promptkit/docs/roadmap/audit/12-deadcode.md

# Dead Code And Obsolete Functionality Audit

Reviewed 2026-11-04 against commit `3b76031` and the current worktree. Existing
audit-document moves were preserved. No production code, tests, dependencies,
or functionality were changed.

## Scope And Assessment

Reviewed repository-owned Go packages, public entry points, configuration and
runtime values, collaborator interfaces, default/optional paths, embedded
resources, build constraints, and the release launchers and their wiring test.
The architecture remains a public facade over captured configuration, use-case
orchestration, generation/capacity, and focused internal adapters. The former
standalone configuration repositories have already been retired; this review
found smaller residues rather than another abandoned subsystem.

The review combined Rapid Type Analysis, Staticcheck unused/data-flow checks,
graph caller discovery, source inspection, and the format, internal, policy,
and roadmap documents. Tests count as real callers, but a helper's self-test
does not by itself establish a production need. Conversely, absence from the
examples or default execution path is not evidence that an optional public
feature is obsolete.

Four cleanup areas warrant consideration. These are low-priority reductions in
state and maintenance surface, not newly demonstrated runtime bugs. None calls
for deleting a supported public feature or imposing a new release gate.

## 1. Remove Backend Presence Bookkeeping With No Runtime Consumer

**Relevant code:** [loaded.backends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L122),
[backendFields and presence capture](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L215),
[effective backend construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/targets.go#L14),
and [Backend.QueueCapacitySet](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L187).

**Evidence:** Construction allocates a per-backend field-state map and fills it
through `captureFields(..., state.backends)`. No production code reads the
recorded backend states. The only lookup of the captured queue state is in
[TestLoadDefaultsAbsentQueueCapacity](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load_test.go#L755).
Unlike profile presence, backend presence is not consumed while constructing
effective execution targets.

`QueueCapacitySet` is also assigned during target construction and asserted in
tests, but never read to select a production behavior. The current assignment
is simply whether concurrency is positive; it no longer distinguishes an
explicit queue setting from a derived default. The registry's capacity-policy
projection uses `ConcurrencyLimit` and `QueueCapacity`, not this flag.

**Why obsolete:** Queue defaulting and its provenance are already handled by
[resolveBackends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/resolve_targets.go#L11) and
ConfigKit's derived-default record. Typed final values drive runtime capacity;
the retained side map and Boolean do not contribute to that behavior or to the
public inspection view. No documented compatibility or planned-feature need for
these extra records was found.

**Potential remediation:** Remove the backend-only presence capture, its field
list and retained map, and the unused runtime Boolean/assignment. Adjust tests
to assert effective queue behavior and, where relevant, the existing ConfigKit
inspection/provenance result. Keep `captureFields`, profile field-state
tracking, and prompt-input metadata presence: those have actual consumers and
preserve required absent/null/explicit-value distinctions. Retain explicit
zero queue capacity, derived defaulting, and operator history unchanged.

This removes unnecessary construction work and retained per-backend maps; it
does not justify dropping configuration provenance or changing its ownership
under the [configuration-boundary ADR](../../adr/0001-configuration-boundary.md).

## 2. Retire Legacy Fields In The Captured Prompt Representation

**Relevant code:** [PromptDefinition.OutputFormat](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L148),
[PromptMessageTemplate.ContentFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L173),
[prompt materialization](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/prompts.go#L58),
[resolveOutputContract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner.go#L639), and
[definition hashing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/promptdef/hash.go#L12).

**Evidence:** Supported engine construction requires and validates a complete
output contract. Materialization sets `definition.Validation` to that contract
and duplicates its format into `definition.OutputFormat`. The runner reads
the duplicate only when `Validation.Format` is empty, a condition that the
captured definitions supplied by engine construction cannot have. The standard
runner test-definition helper fills both fields with the same value; no
supported public repository-injection path supplies an alternative definition.

For messages, materialization resolves the real source `content_file` into
captured `Content` and does not populate the domain `ContentFile` field. The
renderer uses `Content`/captured templates, not that path field. Its one
nonempty assignment is a renderer fixture demonstrating that already-loaded
content is rendered without opening a file. The source-format
`promptMessageConfig.ContentFile` remains actively used and is a different
field.

**Why obsolete:** The runtime representation still carries source-era message
path data and a second output-format source after configuration loading became
the authoritative materialization boundary. The empty-format fallback is
disconnected from supported engine definitions. No current documentation or
roadmap records a compatibility requirement for these internal duplicate fields.

**Potential remediation:** Use `PromptDefinition.Validation.Format` as the one
captured format and remove the legacy duplicate/fallback. Remove only the
runtime message path field, adjusting its fixture to exercise captured text.
Preserve the actual YAML `content_file` feature, source-relative resource
resolution, ConfigKit origin inspection, and construction-time capture. Also
preserve the separate, supported request-override rule that an empty replacement
`OutputContract.Format` defaults to text.

**Serialization caveat:** These fields are included indirectly by
`HashDefinition`'s `json.Marshal`, even when a message path is empty. They are
therefore not completely inert bytes: removing them changes current prompt
hash values. Account for that effect explicitly and protect the documented
opaque-equality relationships between inspection and preparation. Do not claim
bit-identical hashes after changing the hash input, or invent a permanent hash
encoding guarantee merely to perform this cleanup. The fields are internal
representation, not part of the public stable DTO shapes.

## 3. Remove Unused Diagnostic State And A Discarded Helper Result

**Relevant code:** [reachabilityProbeOutcome.initialEndpoint](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_reachability.go#L24),
[HTTP report assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_tester.go#L376),
[fileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L211), and
[SetSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L75).

**Evidence:** The reachability probe assigns its private outcome's
`initialEndpoint`, but the smoke tester never reads that member. It records
the real public attempt's `InitialEndpoint` from the resolved report target.
Only `TestReachabilityProbeRemovesURLCredentials` inspects the private echo.
Actual sanitized request/evidence and report behavior are established through
other values.

Separately, `fileSource` returns a filesystem, file name, source-directory
string, and error. Its only caller, `SetSchemaFile`, always discards the
directory result. The directory is still needed internally to construct
`os.DirFS`; exposing it as another return value serves no caller.

**Potential remediation:** Remove the unused probe-outcome member and its
assignment; retain credential-removal assertions against the actual request,
evidence, or public diagnostic report. Reduce `fileSource`'s private signature
to the consumed results. Keep its directory calculation, file checks, selected
filesystem/root, and the public `WithSchemaFile` option intact.

Neither cleanup removes `SmokeTestAttempt.InitialEndpoint`, destination
evidence, or single-schema-file support. Those public features are live even
though an extra private field/result is unnecessary.

## 4. Remove Orphan Helpers Whose Only Callers Are Their Own Tests

**Relevant code and evidence:**

- [filecatalog.RelativePath](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/filecatalog/catalog.go#L71) is
  called only by `TestRelativePathNested`. Current source discovery and
  source-relative resource resolution use other helpers; no production or
  public-facade caller uses this wrapper around `filepath.Rel`.
- [resourceNamespaceFromID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/resource_identity.go#L34)
  is called only by `TestResourceNamespaceFromID`. Actual namespace inventory
  and filtering paths do not call it. The exported identity-validation and
  qualification operations remain active and are not candidates for removal.
- [runner_test.go:stringPtr](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner_test.go#L2592)
  has no callers, including in tests. Both reachability analysis and
  Staticcheck `U1000` report it.

Caller searches found no reflection, registration, build-constrained caller,
or supported external API exposing these helpers. The first two belong to
internal packages and have only their direct self-tests; no documented future
or compatibility purpose was found. The third is already test-only and unused.

**Potential remediation:** Remove the orphan helpers and their now-irrelevant
self-tests, keeping behavioral coverage of real discovery, namespace
inventory/filtering, and identity qualification. Remove the unused pointer
helper without replacing it. There is no reason to introduce a new abstraction
or move the self-tests to another layer solely to preserve these unused APIs.

## Intentional Retention And Related Findings

The following distinctions prevent removal based on misleading reachability:

- `WithSchemaFile` and `InlineWithURI` are supported public helpers despite
  being unreachable from the current test executables. The former's missing
  public wiring coverage is already in [audit 08](08-testing.md); it is not
  evidence that the option should be deleted.
- The older capacity client wrapper and no-repair runner constructor are
  expressly retained for focused internal callers/tests in the current
  [capacity](../../internal/capacity.md#fifo-generation-permits) and
  [runner](../../internal/runner.md#collaborators) documentation. This audit
  does not classify them as dead functionality or recommend deleting them.
  [Audit 11](11-boundaries.md) discusses the wrapper's architectural placement;
  altering that deliberate retention is a separate decision.
- Repository capability fallbacks, standalone rendering/validation, injected
  clients' nil usage-presence compatibility, nil-validator/admitter behavior,
  and optional provider settings have meaningful callers or documented
  purposes. Normal engine assembly taking another path does not obsolete them.
- ConfigKit YAML fields and stable JSON DTO fields can be used by reflection;
  formatter methods and interfaces can be invoked indirectly. Embedded
  OpenRouter and smoke-schema assets, the Linux FIFO test, and release scripts
  likewise have consumers outside a simple direct-call list. They were not
  treated as dead. No unused public configuration option or abandoned release
  launcher was established.

The domain smoke-request/full-report cloners have a narrow-or-unused consumer
surface already described in [audit 11, finding 3](11-boundaries.md#3-narrow-smoke-value-copy-helpers-to-their-actual-ownership-boundaries).
That ownership/remediation scope is not counted again here. The schema and
JSON-copy consolidations in prior audits likewise remain their existing work,
not an excuse to delete intentional alternative implementations wholesale.

## Tooling And Validation

The checks used local Go 1.27.0 and pinned audit-tool versions:

```sh
go run golang.org/x/tools/cmd/deadcode@v0.52.0 -test -filter='^go.maximumdirect.net/promptkit(/|$)' ./...
go run honnef.co/go/tools/cmd/staticcheck@v0.8.2 -checks 'U1000,SA4*' ./...
go list -f '{{.ImportPath}} {{join .GoFiles " "}} {{join .IgnoredGoFiles " "}}' ./...
```

`deadcode -test` reported the two public helpers and unused test pointer helper
listed above. Staticcheck reported only `stringPtr` (`U1000`) and exited with
status 1 because of that finding; it reported no additional selected `SA4*`
diagnostics. These are audit observations, not successful lint sign-offs.
Neither tool establishes that all tested or serialized state is necessary,
which is why the write-only and redundant fields required manual review.

Rapid Type Analysis starts from executable roots; tests add roots, and example
programs do not exercise every library consumer path. The analysis is local-build
evidence, not proof about all platforms or downstream programs. In particular,
platform-specific schema handling and optional library operations were retained.

Existing offline race-enabled tests passed:

```sh
go test -race -count=1 ./internal/configuration ./internal/domain ./internal/filecatalog ./internal/prompt ./internal/engine ./internal/usecase
go test -race -count=1 -run 'Test(ConfigurationInspection|PreparedExecution|ValidateRequestMatchesPrepareContract|AppendedMessagesComposeFrozenEffectivePrompt)' .
```

Tool execution left `go.mod` and `go.sum` unchanged. No production changes,
test removals, provider calls, or new validation gates were made during this
review.