175 lines
9.2 KiB
Markdown
175 lines
9.2 KiB
Markdown
# Codebase Audit
|
||
|
||
## Audit Metadata
|
||
|
||
- **Production target:** `92e89076a268089e703978fb9d7176200e93344c`
|
||
- **Branch at target:** `main`
|
||
- **Audit date:** 2026-08-08
|
||
- **Go version:** `go1.26.5 linux/amd64`
|
||
- **PromptKit version:** `gitea.maximumdirect.net/eric/promptkit v0.5.0`
|
||
- **Knowledge-graph project:** `notarius-audit-92e8907`
|
||
- **Knowledge-graph target:** branch `main`, head
|
||
`92e89076a268089e703978fb9d7176200e93344c`
|
||
- **Initial worktree:** Clean. There were no pre-existing production or roadmap
|
||
changes to record.
|
||
|
||
The commit above is the production snapshot under audit. Later commits that
|
||
change only roadmap audit documents do not change that production target.
|
||
|
||
## Executive Summary
|
||
|
||
Pending final synthesis. The initial baseline is healthy, and the architecture
|
||
and dependency-boundary review found one Low documentation finding and no
|
||
production dependency inversion.
|
||
|
||
## Finding Index
|
||
|
||
Final cross-area ordering is pending synthesis.
|
||
|
||
| ID | Severity | Category | Title |
|
||
| --- | --- | --- | --- |
|
||
| ARCH-001 | Low | Documentation/Comments | Repair broken ADR cross-references |
|
||
|
||
## Findings
|
||
|
||
### Architecture And Dependency Boundaries
|
||
|
||
### ARCH-001 — Repair broken ADR cross-references
|
||
|
||
- **Severity:** Low
|
||
- **Category:** Documentation/Comments
|
||
- **Evidence:**
|
||
`docs/adr/0012-resolve-opaque-entity-identifiers-deterministically.md:15`
|
||
links ADR-0003 as `0003-strongly-typed-stage-interfaces.md`, and line 17
|
||
links ADR-0009 as
|
||
`0009-prefer-minimal-evidence-grounded-extraction-artifacts.md`. Neither file
|
||
exists. The maintained files are
|
||
`0003-typed-interfaces-with-two-zone-data-model.md` and
|
||
`0009-minimal-evidence-grounded-extraction-artifacts.md`.
|
||
- **Impact:** Readers and documentation tooling cannot follow ADR-0012 to the
|
||
two architectural decisions it explicitly relies on. Runtime behavior is
|
||
unaffected.
|
||
- **Recommendation:** Correct only the two relative link targets in ADR-0012.
|
||
- **Preserve:** Keep the accepted decision text and its intended references to
|
||
ADR-0003 and ADR-0009 unchanged.
|
||
- **Validation:** Run a relative Markdown-link check across `docs/adr/` and
|
||
confirm both targets resolve; verify the change contains no decision-text
|
||
edits.
|
||
- **Grouping:** Independent.
|
||
|
||
<!--
|
||
Finding template for later audit stages:
|
||
|
||
### AREA-001 — Concise title
|
||
|
||
- **Severity:** High, Medium, or Low
|
||
- **Category:** Correctness, Efficiency, Duplication, Simplicity, Test Quality,
|
||
or Documentation/Comments
|
||
- **Evidence:** Exact files, symbols, call paths, and observed behavior
|
||
- **Impact:** The concrete risk or cost
|
||
- **Recommendation:** A bounded implementation direction
|
||
- **Preserve:** Invariants and contracts that remediation must retain
|
||
- **Validation:** Focused checks that would demonstrate success
|
||
- **Grouping:** Independent, or the IDs with which this should be implemented
|
||
-->
|
||
|
||
## Intentional Complexity And Duplication To Preserve
|
||
|
||
- `internal/modules/generic/register.Register`,
|
||
`internal/modules/seriatim/register.Register`, and
|
||
`internal/modules/dnd/register.Register` deliberately expose the same small
|
||
registrar shape while retaining family-local registration policy and
|
||
diagnostics. Combining them would move extension ownership out of the domain
|
||
registrars and weaken the composition boundary established by ADR-0004.
|
||
- `internal/modules/dnd/register.registerModules`, `registerEvidence`,
|
||
`registerValidators`, and `registerDefaultChains` use explicit typed
|
||
registration lists. At this architectural pass, that repetition preserves
|
||
artifact Go types, module-specific validator order, and registrar-owned
|
||
production policy. Later D&D stages may evaluate individual shared
|
||
mechanics, but should not replace these lists with a dynamically typed
|
||
registration engine.
|
||
- `internal/framework/pipeline.RegisterArtifactCodec` and
|
||
`exactTypedValue` perform apparently repetitive exact-type checks around
|
||
private erasure. The checks deliberately turn incompatible values into
|
||
errors at each erased boundary rather than permitting a panic or accepting a
|
||
near-matching type, preserving ADR-0003.
|
||
|
||
## Areas Reviewed Without Findings
|
||
|
||
### Architecture And Dependency Boundaries
|
||
|
||
- **Composition root:** `internal/cli.newProductionComponents` constructs the
|
||
complete registry set and asset registry, then invokes only the generic,
|
||
Seriatim, and D&D family registrars. Direct production imports confirm that
|
||
`internal/cli` is the only layer importing those registrar packages.
|
||
- **Dependency direction:** A direct production import map found no core or
|
||
framework package importing `internal/modules`, no module importing
|
||
`internal/cli`, no concrete generic or Seriatim module importing D&D, and no
|
||
module importing the file-backed checkpoint, chunk-plan, debug, file-I/O, or
|
||
debug-bundle implementations. PromptKit is imported directly only by
|
||
`internal/framework/llm`.
|
||
- **Graph cross-layer calls:** The refreshed graph reported one
|
||
framework-to-module edge from `pipeline.Prepare` to a symbol named `request`
|
||
in a D&D validator test. Tracing it showed a confidence `0.06` suffix match
|
||
from the local closure call in `Prepare`; `trace_path` classified the target
|
||
as test-only, and the production import map disproved a dependency. The graph
|
||
reported no module-to-CLI calls.
|
||
- **Assets leaf:** `assets/package.go` imports only `embed` and `io/fs`, embeds
|
||
content, and exposes the read-only `FS() fs.FS` accessor. It contains no
|
||
business logic and has no `internal` or PromptKit dependency.
|
||
- **Fixed pipeline shape:** `pipeline.ResolvePipeline` resolves input and
|
||
chunk once, fixed extract/merge/normalize bindings per artifact lane, and one
|
||
output binding. Ordered steps are barriers around those fixed lanes rather
|
||
than arbitrary graph topology. `pipeline.Prepare`, `Runner.Run`,
|
||
`runPreparedSteps`, and `runLanes` retain that shape through construction and
|
||
execution.
|
||
- **Typed artifact boundary:** Typed registrations retain the exact Go type for
|
||
codecs and lane operations. Private erasure in `RegisterArtifactCodec` and
|
||
`exactTypedValue` verifies exact types and returns contextual errors;
|
||
normalized values cross into output through serialized artifacts.
|
||
- **Physical-state ownership:** The CLI owns root selection, store factories,
|
||
and durable file placement (`chunkPlanStoreForRun`, checkpoint/debug setup,
|
||
and `writeOutputFiles`). The framework receives collaborator interfaces and
|
||
returns logical output files. The generic JSON output module's direct import
|
||
of `internal/framework/chunkmap` validates and republishes the accepted
|
||
serialized chunk-map contract; it neither chooses a physical root nor writes
|
||
files.
|
||
- **Accepted architectural decisions:** ADRs 0001–0005 and 0007–0012 were read
|
||
against the current high-level composition. Apart from ARCH-001, the
|
||
composition root, fixed ordered pipeline, typed boundary, domain packaging,
|
||
canonical chunk-plan policy, separate state surfaces, checkpoint policy,
|
||
evidence rules, workload profile ownership, centralized asset leaf, and
|
||
deterministic entity identity boundary have corresponding current owners.
|
||
|
||
## Validation Record
|
||
|
||
| Date | Scope | Command or check | Result |
|
||
| --- | --- | --- | --- |
|
||
| 2026-08-08 | Initial worktree | `git status --short` | Pass; no output |
|
||
| 2026-08-08 | Knowledge graph | Full index as `notarius-audit-92e8907` | Pass; 8,322 nodes and 47,887 edges; branch/head matched the production target |
|
||
| 2026-08-08 | Baseline tests | `go test ./...` | Pass |
|
||
| 2026-08-08 | Baseline static analysis | `go vet ./...` | Pass |
|
||
| 2026-08-08 | Baseline build | `go build ./cmd/notarius` | Pass |
|
||
| 2026-08-08 | Baseline whitespace | `git diff --check` | Pass |
|
||
| 2026-08-08 | Production imports | Direct `go list` import-edge audit plus graph call tracing | Pass; no production dependency inversion found |
|
||
| 2026-08-08 | Accepted ADR links | Relative Markdown-link target scan under `docs/adr/` | Two unresolved targets recorded as ARCH-001 |
|
||
|
||
## Coverage Matrix
|
||
|
||
| Audit area | Status | Packages and documents inspected | Validation run | Finding IDs |
|
||
| --- | --- | --- | --- | --- |
|
||
| Architecture and dependency boundaries | Reviewed | Architecture, documentation, and testing policies; internal overview; accepted ADRs; `internal/cli/catalog.go`; production registrars; root `assets` package; representative pipeline, typed-codec, output, and state-owner symbols | Full baseline, fresh graph, direct import map, cross-layer call traces, ADR link scan | ARCH-001 |
|
||
| Configuration and CLI composition | Pending | — | — | — |
|
||
| Pipeline resolution, preparation, and typed registries | Pending | — | — | — |
|
||
| References and ordered handoffs | Pending | — | — | — |
|
||
| Execution, validation, retry, and concurrency | Pending | — | — | — |
|
||
| State, checkpoints, debugging, and file safety | Pending | — | — | — |
|
||
| LLM runtime, prompt filesystems, and assets | Pending | — | — | — |
|
||
| Generic and Seriatim modules | Pending | — | — | — |
|
||
| Shared D&D types, codecs, and family mechanics | Pending | — | — | — |
|
||
| NPC, item, and location registries | Pending | — | — | — |
|
||
| NPC, item, and location occurrences | Pending | — | — | — |
|
||
| Spells, scene chunking, and scene descriptions | Pending | — | — | — |
|
||
| Combat turns and enemy events | Pending | — | — | — |
|
||
| Test ownership, comments, and final synthesis | Pending | — | — | — |
|