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, backendFields and presence capture, effective backend construction, and Backend.QueueCapacitySet.

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. 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 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.

2. Retire Legacy Fields In The Captured Prompt Representation

Relevant code: PromptDefinition.OutputFormat, PromptMessageTemplate.ContentFile, prompt materialization, resolveOutputContract, and definition hashing.

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, HTTP report assembly, fileSource, and SetSchemaFile.

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 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 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 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.

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; 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 and runner documentation. This audit does not classify them as dead functionality or recommend deleting them. Audit 11 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. 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:

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:

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.

13 KiB Raw Blame History