Record CommandKit algorithm audit findings

This commit is contained in:
2026-11-20 13:12:32 +00:00
parent 65d24fb88f
commit 38866110a7

View File

@@ -12,8 +12,10 @@ The native command boundary, actual ConfigKit inspection results, separate domai
catalogs, independent selections, reporting, and cancellation architecture are catalogs, independent selections, reporting, and cancellation architecture are
substantially implemented. The initial pass identified findings 1–3. An substantially implemented. The initial pass identified findings 1–3. An
integration-focused follow-up at `8be65fd` adds finding 4; the application source integration-focused follow-up at `8be65fd` adds finding 4; the application source
is unchanged from the initial review. All four P2 findings remain open. is unchanged from the initial review. An algorithm-focused follow-up at
These reviews make no application changes. `65d24fb` adds findings 5–8: two P2 findings and two P3 optimization
opportunities. Findings 1–4 remain open. These reviews make no application
changes.
## 1. P2: Preserve campaign inheritance when materializing session documents ## 1. P2: Preserve campaign inheritance when materializing session documents
@@ -175,6 +177,154 @@ Required remediation:
bytes, and retained downstream success. Include changed roster contents as a bytes, and retained downstream success. Include changed roster contents as a
counterexample that must invalidate affected work. counterexample that must invalidate affected work.
## 5. P2: Capture pipeline provenance once per catalog derivation
Stages: 2 and 4; catalog consumers in Stages 5, 7, and 11.
Locations: `internal/config/artifact_catalog.go:49–65,127–143`,
`internal/config/artifact_families.go:78`, and
`internal/config/pipeline_configkit.go:291–307`.
Every authored concrete-artifact provenance lookup calls
`cfg.ConfigKitResult().Metadata()`. Family derivation calls the same accessor
once per family. In the selected ConfigKit v1.2.1, this accessor calls
`Inspection.Metadata`, which clones the complete effective-path and field-info
maps. It is a detached snapshot operation, rather than a constant-time handle
lookup. The immutable history model is shared; the effective metadata maps and
their nested records are copied.
Let `D` be the number of authored artifact and family declarations, and `M` the
size of the metadata copied by one snapshot. Snapshot acquisition alone costs
`O(D * M)` work and cumulative allocation per catalog derivation, in addition to
the actual history queries. With bounded-size declarations and `M = Θ(D)`, this
is quadratic work. Family lookups also rebuild the complete source-path index
per family. The prior implementation reused its retained metadata snapshot;
the repeated full-snapshot acquisition is introduced by this migration.
Refactoring opportunity:
- Acquire one native metadata snapshot and one source-ID/path index inside a
catalog derivation. Share them across authored-artifact and family provenance
queries through a small local resolver or explicit helper parameters.
- This reduces snapshot work to `O(M)` plus the existing per-declaration native
queries and output processing. Build the source index once as well. The
existing `partyCharacterSourceLookup` already demonstrates an invocation-local
snapshot and lookup cache.
- Retain native history, inheritance, and source semantics, with no global
cache or replacement inspection result. Verify equivalent provenance for
concrete definitions, families, imports, and overlays; preserve the completed
ConfigKit values.
This opportunity concerns how Narratio calls the public API. It does not require
changing ConfigKit's detached-snapshot contract or reviewing its selected
configuration algorithms.
## 6. P3: Avoid cloning the complete family catalog for individual origins
Stages: 5 and 11; artifact evidence in Stage 15.
Locations: `internal/stage/analyze_resume.go:88–103`,
`internal/stage/analyze.go:179–185`, `internal/config/config.go:71–76`, and
`internal/config/artifact_families.go:395–418`.
`exportAnalyzeResumeItems` calls `config.ArtifactFamilies(catalog)` inside its
per-item loop, then reads one member's family and character ID. That accessor
deep-copies every family and member, including dependency slices and input maps.
`analyzeArtifactOrigin` performs the same whole-catalog copy for individual
artifact checkpoint and diagnostic records.
Let `L` be the number of origin lookups and `K` the total family/member catalog
payload. These lookups cost `O(L * K)` work and cumulative allocation. When a
plan reports a catalog-sized set of bounded-size members, `L` and `K` both grow
with member count, producing quadratic copy work for a linear-sized report.
This inefficiency predates the migration and remains in the rewired domain
consumers; it is an optimization opportunity, rather than a new regression.
Refactoring opportunity:
- Capture one detached family catalog outside a batch and reuse its member
index across all three resume-summary lists. Copy work becomes `O(K + L)`.
- For execution's individual lookups, read the already-derived member index
through a narrow accessor that returns the needed identity fields by value.
If a caller needs mutable dependency/input records, copy that member only.
- Preserve family identities, deterministic report ordering, and detached
records where callers need them. A new defensive-copy framework or global
cache is unnecessary.
## 7. P3: Build publication-report lookup tables once
Stage: 12.
Locations: `internal/app/session_state_command.go:256–270`,
`internal/app/artifact_inspection.go:79–131`, and
`internal/artifacts/catalog.go:255–289`.
For every publication rule, `inspectPublishedOutputs` calls
`helperPublishedOutputDest`, which rebuilds the configured-output map and
extraction-output set. Building each map first enumerates, sorts, and copies
the entire corresponding runtime catalog. The same loop calls
`committedPublishedOutput`, scanning all commit declarations to find one source.
Let `R` be publication-rule count, `A` configured-artifact count, `X`
extraction-artifact count, and `K` commit-declaration count. With bounded-size
catalog records, the repeated local work is
`O(R * (A log A + X log X + K))`, plus copying any variable-sized entry payloads.
When `R`, `A`, and `K` grow together, this includes quadratic-logarithmic sorting
work and quadratic declaration scans. Required remote existence checks are
separate from this CPU/allocation cost. These helpers and repeated lookups
predate the migration and remain in the new structured-report collector.
Refactoring opportunity:
- Build configured/extraction lookup tables once per report and pass them to
destination resolution, or share the existing publication-action planner
where its selection and failure behavior fit inspection.
- Index published commit declarations once by source, preserving the existing
declaration-selection behavior. Resolve each report row through that index.
- Reusing the existing catalog enumeration APIs reduces this local lookup work
to `O(A log A + X log X + K + R)`, plus entry-payload copying. Keep configured
report ordering, partial error reporting, pointer-selected authority, exact
declared object keys, and the existing remote checks.
There is no need to add remote concurrency, caching across invocations, or a new
publication protocol to obtain this improvement.
## 8. P2: Use canonical publication sources in session reports
Stage: 12; assembled correctness verification in Stage 21.
Location: `internal/app/session_state_command.go:256–270`.
Publication validation and execution accept a source with surrounding whitespace
and resolve it to its trimmed artifact identity. The new report collector uses
the authored `rule.Source` unchanged for lock, outcome, and committed-declaration
lookups, although its destination helper trims the same source.
A focused diagnostic loads and validates `source:
" narratio.transcript.final_trimmed "` through the actual configuration loaders.
The shared publication planner produces `narratio.transcript.final_trimmed`.
Given a matching committed artifact and lock, inspection reports `missing`,
`unlocked`, an empty outcome, and no declared key. The otherwise identical
unspaced case reports `published`, `locked`, and `carried_locked`, with the
declared object identity. The previous collector normalized the source before
these lookups, making this a migration regression.
Required remediation:
- Use the same canonical source identity as publication for every report
lookup and the report's source field. Derive this identity locally or consume
the shared publication-action representation; keep completed ConfigKit values
unchanged.
- Preserve accepted configuration, rather than adding a whitespace prohibition.
Retain exact committed destination and origin-run reporting, including carried
outputs.
- Add a collector/native-report regression with an accepted spaced source,
committed output, lock, and outcome, alongside an unspaced control.
Canonicalizing once per row is linear in the source's string length and adds no
catalog-wide traversal. This correctness fix is independent of the repeated
sorting/scanning optimization in finding 7.
## Stage-by-stage coverage ## Stage-by-stage coverage
| Stage | Evidence reviewed and result | | Stage | Evidence reviewed and result |
@@ -260,3 +410,49 @@ all passed on Go 1.27.4. A new native-invocation Go-overlay diagnostic reproduce
finding 4 under `-race` and verified unchanged prepared input checksums. Its finding 4 under `-race` and verified unchanged prepared input checksums. Its
files remained under `/tmp`. Documentation checks and whitespace validation files remained under `/tmp`. Documentation checks and whitespace validation
were repeated for this document update. were repeated for this document update.
## Algorithmic follow-up coverage and validation
The algorithmic pass reviewed the completed stages in order, using the same
application source and the exact pinned dependency implementations. Findings 5–8
add three scaling opportunities and one correctness regression. It preserves the
algorithms and consequential behavior expressly selected in the plan.
| Stage | Algorithmic review |
| --- | --- |
| 1 | Fixed command declarations and native outcome adaptation; parser/reporting algorithms remain upstream-owned. |
| 2 | Native-result and source-metadata access; repeated catalog snapshots are covered by finding 5. |
| 3 | Presence-based defaults and fixed stable-input fields; no additional scaling finding. |
| 4 | Family expansion is output-sensitive in families × characters; maps support collision checks. Finding 5 covers avoidable metadata copies beyond that output work. |
| 5 | Concrete dependency/input consumers and family-origin access; finding 6 covers whole-catalog copies per lookup. |
| 6 | Safe materialization and semantic projections; retained checkpoint and publication algorithms were not reopened. |
| 7 | Invocation-local lazy acquisition reuses acquired products and keeps comparison sides separate. |
| 8 | Native scope dispatch and actual-result inspection; no replacement traversal algorithm is introduced. |
| 9 | Independent side acquisition and upstream comparison/override semantics; no additional scaling finding. |
| 10 | Artifact-name token processing uses a set and sorting; family selection expands the selected members, and stage selection operates on the fixed inventory. |
| 11 | Planning and catalog reporting use derived products; findings 5 and 6 apply before/during report construction. |
| 12 | Artifact/publication report collection; findings 7 and 8 cover repeated lookup construction and inconsistent source normalization. |
| 13 | Initialization and lock commands retain shared operations; no additional scaling finding. |
| 14 | Restore/cleanup action reports retain their existing planners and safety rules; no additional scaling finding in the conversion. |
| 15 | Durable summary collection traverses recorded outputs/checkpoints with per-stage sets and sorted keys; finding 6 also affects individual analysis records. |
| 16 | Cancellation propagation and worker settlement retain selected execution/checkpoint behavior. |
| 17 | Native diagnostic adaptation adds no growing history or extra durable progress collection. |
| 18 | Per-unit progress attaches to existing audio, speaker, and artifact completion/reuse events. |
| 19 | Static completion and legacy deletion add no campaign/artifact enumeration algorithm. |
| 20 | Documentation-only stage; no runtime algorithm to reassess. |
| 21 | Cross-checked assembled paths, selected dependency source, and focused correctness reproduction. |
Complexity statements are derived from loops, call paths, and copied payloads;
they are not benchmark results or predictions of measured operator latency.
The pass did not reconsider upstream configuration algorithms, fixed pipeline
ordering/invalidation, immediate durable checkpoints, or the selected publication
and restore protocols.
The focused Go-overlay diagnostic used real configuration loading/validation and
the shared publication planner with in-memory remote state. Its canonical-source
control passed; its spaced-source case failed the expected-state assertions as
described in finding 8. Diagnostic files remained under `/tmp`, with no repository
test or application changes. Earlier full application verification remains
applicable to the unchanged source. Documentation checks and `git diff --check`
were repeated for this update. No live services or performance measurements were
used.