2026-11-17 23:57:45 +00:00
# ConfigKit adoption review remediation
## Review scope
Reviewed the twelve completed stages in [implementation.md ](implementation.md )
against [the approved target ](configkit.md ), the implementation diff from
`65d0e51` through `39a958675d68e940799f4cb8c8e6748830d1483a` , current code,
documentation, focused diagnostic reproductions, and repository checks.
2026-11-18 00:30:09 +00:00
An integration-focused follow-up reviewed the same implementation at
`bccf03a99f45c2b9b342412b85f70e356663df61` , tracing each stage into existing
command, preparation, publication, restore, and inspection workflows. Items
5– 6 are additional findings from that pass; items 1– 4 remain outstanding.
2026-11-18 01:10:44 +00:00
An algorithm-focused pass reviewed all twelve stages at
`583c5bdf1bc8f0af8ec2e257bcb03ecccbf283b1` . Items 7– 10 are refactoring
opportunities for consideration. Complexity follows the code and the selected
ConfigKit v1.2.1 implementation; no operational timings or benchmarks were
collected. The pass preserves algorithms expressly chosen by the plan.
2026-11-17 23:57:45 +00:00
The native configuration architecture is substantially implemented. The items
2026-11-18 01:10:44 +00:00
below record the six required corrections and four additional algorithmic
opportunities. This document implements none of their fixes.
2026-11-17 23:57:45 +00:00
## 1. P2: Distinguish effective resource origins from superseded history
2026-11-18 03:59:09 +00:00
Status: Complete. Native pre-resolution Previous evidence supplies current
contributors; regression coverage includes overlay replacement and inheritance.
2026-11-17 23:57:45 +00:00
Stage: 9, with documentation coverage in Stage 11.
Location: `internal/config/effective_pipeline.go:274– 280` ,
`effectivePipelineOwners` .
For a resolution-origin field, the projection adds every main/overlay origin
from native history to the same current source-role records. This conflates
effective ownership with historical definitions. For example, a root containing
`audita: {config_path: original.yml}` and an overlay containing
`audita: {config_path: replacement.yml}` produce `audita.config_path` records
for the root, overlay, and resolution. The root's superseded value did not
supply the effective resource; its record is indistinguishable from an effective
contributor. The error is visible to operators using `config sources` to locate
the definition that controls an integration path.
Required change: use native effective/pre-normalization evidence for effective
input attribution. If historical definitions are also displayed, label them
separately. Preserve historical contributor information in the artifact catalog
where it is explicitly definition evidence. Keep the projection thin; another
provenance reconstruction service is unnecessary.
Verification: cover a normalized resource with a superseded root/import value,
an overlay replacement, and inheritance. The effective overlay and resolution
remain visible, while superseded evidence is either absent from current-owner
records or explicitly identified as history. Update the command reference for
the resulting roles.
## 2. P2: Remove the restore test's incidental startup deadline
2026-11-18 04:02:30 +00:00
Status: Complete. Cancellation is synchronized after discovery with the session
lock held. Ten focused race repetitions and the full repository race suite pass.
2026-11-17 23:57:45 +00:00
Stage: 12; the fragile timing assumption predates this migration.
Location: `internal/app/restore_execution_test.go:383– 387` ,
`TestExecuteRestoreLockConflictFailsAndWritesNothing` .
The test starts a 100 ms context deadline before calling the complete restore
command, then requires an error from session-lock acquisition. With the current
configuration workflow under the full race suite, the deadline can expire
during earlier work. The reproduced failure was:
```text
restore: remote check current commit pointer "dnd/campaigns/sample-campaign/sessions/2026-05-03/current/commit-pointer.json": context deadline exceeded, want lock failure
```
An isolated application-suite run passed, while a subsequent full race run
failed at this assertion. A green isolated run therefore does not establish
Stage 12's repeatable final validation. The test implicitly requires unrelated
startup work to finish within 100 ms, which is not an application requirement.
This is not evidence that production session locking is incorrect.
Required change: make the contention/cancellation test target the intended
lock boundary without timing all preceding configuration and remote discovery.
Use synchronization at an appropriate existing test boundary, or separate
lock-service contention coverage from command-level no-write coverage. A larger
arbitrary startup timeout alone leaves the underlying timing dependence.
Preserve the assertions that restore cannot write protected files while another
invocation owns the session lock.
Verification: repeat the focused test and rerun the complete race suite under
normal package concurrency. Report actual outcomes rather than treating an
isolated pass as full-suite success.
## 3. P3: Finish the planned field-level publish resolution cleanup
2026-11-18 04:03:33 +00:00
Status: Complete. Field-only defaults and destinations retain precise native
history. Publish and authored append/upsert/replace regression checks pass.
2026-11-17 23:57:45 +00:00
Stages: 1 and 3; the roadmap's integration scope requires field-level recording
for field-only changes.
Location: `internal/config/pipeline_configkit.go:202– 215,232– 235` ,
`resolvePipelineConfig` .
Publish requiredness and derived destinations already use field-level native
helpers. The resolver additionally tracks `defaultedOutput` , records the entire
`publish.outputs` list for those field edits, and retains a comment claiming
that child records cannot cover the changes. ConfigKit v1.2.1 supports exactly
this field-level coverage. The ancestor record adds redundant history: querying
an untouched output source also returns a whole-list normalization operation
with publish-default/destination reasons.
Required change: remove the obsolete list-coverage tracking, redundant ancestor
records, and inaccurate comment for these field-only edits. Keep field helpers
and any whole-list records actually needed for structural membership/order
changes. This is completion of the selected simplification, not a new ban on
container-level records.
Verification: a temporary diagnostic overlay removing only the obsolete
workarounds successfully loaded defaulted/derived publish outputs and passed
the append/upsert/replace collection tests. Add suitable behavioral coverage
for effective values and precise field history, without asserting private
helper invocation counts.
## 4. P3: Pin Go attribution links to the selected source commit
2026-11-18 04:03:40 +00:00
Status: Complete. Go license, patent, and source links identify the verified
Go 1.27.4 source commit; documentation checks pass.
2026-11-17 23:57:45 +00:00
Stages: 1 and 11.
Location: `docs/oss/attribution.md:125– 128` .
The updated Go entry uses `go1.27.4` in the LICENSE, PATENTS, and Source URLs.
The adopted OSS policy requires commit-specific upstream source and notice
links. The preceding entry used a source hash; this update replaced it with
tag-based references.
Required change: use the verified Go 1.27.4 source commit
`7b2881024c95a11ddb86663a616340aa3a88b67f` in those three URLs. The hash was
resolved through the official Go repository's release tag. Keep the existing
license texts, factual notice wording, and Go version identification.
Verification: confirm the links identify that source revision and run the
documentation checks. This requires no licensing change or new release gate.
2026-11-18 00:30:09 +00:00
## 5. P2: Give session initialization the correct authoring context
2026-11-18 04:06:29 +00:00
Status: Complete. Rendered templates load with native local context and imports;
local and remote products are standalone effective documents. Relative CLI audio,
import removal, placeholder/identity, and initialization race checks pass.
2026-11-18 00:30:09 +00:00
Stage: 4, interacting with materialization and command validation in Stages
6, 11, and 12.
Locations: `internal/app/operator_session_init.go:78– 102` and
`internal/config/load.go` , `LoadSessionBytesWithOptions` .
The existing initializer validates its rendered document through
`LoadSessionBytesWithOptions` . That loader now deliberately describes a
contextless remote snapshot with imports disabled. A generated local session
is an authored file, so this caller no longer uses the same semantics as the
ordinary file loader.
Two focused reproductions show the mismatch:
- A local template with a required `shared.yml` import containing constant
metadata fails with `import.disabled` , even when the import exists beside
the generated destination and the resulting local session is otherwise valid.
- With `--audio-dir ./audio` and an output in another directory, initialization
validates the invocation-directory audio path, then writes the original
relative text. Loading that generated file selects the output-directory
audio path. The persisted resource differs from the validated resource and
the documented invocation-relative CLI interpretation.
Required change: distinguish authored initialization from contextless snapshot
loading. Use ConfigKit's supported source/context facilities for local
composition, and make persisted resource references reproduce the validated
configuration. Materialize effective values where moving or uploading the
document would leave authoring imports unresolved. Preserve the narrow template
substitution contract and the existing contextless remote-loading boundary.
Verification: initialize a local imported template, load its output through the
ordinary loader, and check the imported values. Cover a destination outside the
invocation directory and relative CLI audio input. Check that remote generation
emits a consumable standalone snapshot and that ordinary placeholder and identity
validation still applies. These cases exercise initialization through the real
configuration owner without adding remote companion retrieval.
## 6. P2: Reconcile remote session updates with committed-session selection
Stage: 7, interacting with the existing initializer and shared command loader
from Stages 2 and 4.
Locations: `internal/app/config_loader.go:194– 223` and
`internal/app/operator_session_init.go:113– 138` .
The new remote loader selects a committed `run:prepare/inputs/session.yml`
whenever the current commit declares one. The existing `session init --remote`
writer continues to update the session-root `session.yml` . After publication,
the writer and reader therefore use different authoritative objects.
A prepare → publish → `session init --remote --force --title "After publication"`
reproduction succeeds and writes the requested title to the root object. A
subsequent ordinary command load still returns the old title from the committed
prepared session. The same selection would ignore changed audio or previous-session
settings. The documented overwrite workflow silently stops affecting later runs
once the session has been published.
Required change: reconcile remote input authoring and selection so successful
operator updates can be used by subsequent runs. Preserve immutable published
snapshots and committed restore authority. Keep an effective remote editing or
override workflow; silently ignoring updates or introducing a blanket ban on
editing published sessions would leave the integration unresolved. Update the
canonical operator guidance for the resulting selection behavior.
Verification: publish a prepared session, update it through the supported remote
workflow, then load it through the ordinary run/plan configuration path and check
the updated values. Include audio or previous-session selection as well as title.
Verify that restore still uses its selected immutable commit and that published
objects are unchanged by the authoring update.
2026-11-18 01:10:44 +00:00
## 7. P3: Reuse enumerated source records and one inspection source index
Stage: 9.
Locations: `internal/config/effective_pipeline.go:57– 75` ,
`internal/config/pipeline_configkit.go:354– 371` , and
`internal/config/artifact_catalog.go` , `declarationDefinitionSources` .
`emptyImportSelections` enumerates `Result.Sources()` and then calls
`Result.Source(id)` for every enumerated record. `pipelineSourcePaths` does the
same lookup for every retained source. In ConfigKit v1.2.1, completed-result
source lookup scans the source slice. Enumerating S sources this way performs
Θ(S²) source-ID comparisons, although the enumerated records already contain
the required information, including empty-import evidence.
The artifact catalog additionally rebuilds this source map for each declaration.
For A entries this introduces O(A S²) source-index work; with one imported file
per artifact, that component can become cubic in A. This is separate from the
native history queries and necessary output construction.
Potential refactoring: consume the complete enumerated records directly. Build
the source-ID/path map once per inspection operation and share it with declaration
projection. This reduces empty-import enumeration to O(S + E), where E is the
returned selection evidence, and source-index work across the catalog to
expected O(S + A). Expanded members can also reuse the family-source lists
already retained in the family catalog. Keep native history and origin queries
as the provenance authority.
Verification: temporary functional checks confirmed that enumerated records and
individual lookups have equal contents, and that direct enumeration preserves
source paths and nested empty-import selections. Preserve operator source/catalog
output, including composite and inherited contributors, when refactoring.
## 8. P3: Reuse party metadata and per-character provenance within inspection
Stage: 9, consuming Stage 5's imported party result.
Locations: `internal/config/artifact_catalog.go:67– 105` and
`internal/config/effective_pipeline.go` , `appendGeneratedArtifactSources` .
`partyCharacterSources` calls `result.Metadata()` separately for Lookup and
History. ConfigKit v1.2.1 returns detached metadata by copying the complete
effective-path and field maps, including their origin records. This helper is
called for each generated artifact in the catalog and for each generated
artifact field in source inspection. The same character's provenance is
therefore repeatedly recomputed across fields and families.
Let M be the copied party-metadata size and P the number of provenance requests.
The avoidable metadata-copy work and cumulative allocation are Θ(P M). Even
with one family and bounded-size character entries, M and P both grow with the
character count C, producing quadratic work. More families and fields multiply
the requests. This describes the provenance pass, not the complexity of the
whole command or unchanged party validation.
Potential refactoring: obtain one native Metadata snapshot and source index per
inspection operation. Resolve each requested character's source list once and
reuse it for that operation. The full-metadata copy term becomes O(M), with
native per-character query costs and required output emission remaining. Keep
the cache local to the projection; a new persistent provenance service is
unnecessary. Apply the same snapshot reuse to campaign provenance helpers where
convenient, although their fixed field count is not a quadratic case.
Verification: a temporary imported/inherited-roster check confirmed equivalent
source lists using shared native metadata and an enumerated source index.
Retain contributor accuracy, ordering, and secret-free inspection output.
## 9. P3: Read the selected remote session without enumerating run history
Stage: 7.
Location: `internal/app/config_loader.go:194– 228` , `findRemoteSessionConfig` .
After selecting the committed prepared-session key, this function lists the
entire session prefix and scans it for that exact key. If H objects are retained
across historical runs, this adds Θ(H) listing/scan work and Θ(H) object-record
memory to every remote session load. The production S3 adapter paginates and
accumulates the complete listing. The scan predates the migration and was
retained in the new committed-object selection path.
Potential refactoring: retrieve the exact selected key through the existing
`ObjectStore.Read` boundary, which returns metadata with the opened body. Use
that metadata for the existing size/generation checks and stream the body into
the command-owned temporary file while retaining checksum verification. The
object lookup/transfer then takes a constant number of requests independent of
H, plus the necessary O(B) work for B session bytes. Current-commit acquisition
and validation costs remain. Apply this after reconciling the selection policy
in item 6; no new backend interface is needed.
Verification: the production S3 Read implementation performs one exact-key
GetObject and returns its size and generation. Preserve fake-store coverage for
missing objects, selected identity, checksum/size/generation mismatches, and
temporary-file cleanup. Confirm that unrelated historical keys are not enumerated.
## 10. P3: Stream prepared-input archival copies
Stage: 7.
Location: `internal/stage/publish_sources.go:29– 64` ,
`collectPublishPreparedInputs` .
After opening and verifying each prepared document, the new archival path reads
the whole file with `io.ReadAll` and passes the byte slice to
`writeBytesIfChanged` . For a document of B bytes this requires Θ(B) auxiliary
transfer memory. Expanded imported party documents can be larger than any one
authoring fragment. A full in-memory document is unnecessary for this file copy.
Potential refactoring: preserve the current confined source opening and checksum
checks, then stream the opened descriptor into the run archive. The existing
`fileops.WriteReaderAtomicWithChecksum` already supplies reader-based atomic
replacement and hashing through `io.Copy` . Preserve unchanged-destination reuse
using the known checksum. Transfer time remains Θ(B), while auxiliary copy
memory becomes O(1) with a fixed-size buffer. This does not alter the plan's
separate canonical YAML rendering algorithm or total in-memory configuration size.
Verification: preserve archived bytes/checksums, workspace file modes, source
validation, failure handling, and immutable publication behavior. Existing
reader-copy and prepared-session publication tests provide suitable behavioral
coverage; allocation or wall-clock thresholds are unnecessary.
2026-11-17 23:57:45 +00:00
## Stage-by-stage disposition
| Stage | Review result |
| --- | --- |
| 1: Dependency/toolchain | ConfigKit v1.2.1 and Go 1.27.0/1.27.4 selected; remaining notice pinning in item 4. |
| 2: Discovery/bootstrap | Native discovery, exclusive explicit selection, independent bootstrap, and shared diff bootstrap are present. |
| 3: Resource bases | Native origin-based resolution and fallbacks are present; field-record cleanup remains in item 3. |
2026-11-18 00:30:09 +00:00
| 4: Campaign/session imports | File contexts, contextless remote snapshots, native optional discovery, and detached document values are present; initialization still uses the snapshot path in item 5. |
2026-11-18 01:10:44 +00:00
| 5: Party imports | Imported rosters, source-aware ordering, canonical rendering, players, and family resolution are present; the planned roster sort is retained. |
2026-11-17 23:57:45 +00:00
| 6: Prepared inputs/resume | Canonical document materialization and matching resume evidence are present. |
2026-11-18 01:10:44 +00:00
| 7: Publish/restore | Prepared documents flow through immutable committed run objects and restore; item 6 is a correctness gap and items 9– 10 are scalability opportunities. |
2026-11-17 23:57:45 +00:00
| 8: Final-domain snapshots | Defaults-backed native snapshots, safe credential identities, rendering, and digest integration are present. |
2026-11-18 01:10:44 +00:00
| 9: Diff/provenance | Native diff and pointer paths are present; item 1 concerns attribution correctness and items 7– 8 concern avoidable provenance work. |
2026-11-17 23:57:45 +00:00
| 10: Examples | Destination-based definitions, directory imports, list operations, split roster, and secondary imports are demonstrated. |
2026-11-18 00:30:09 +00:00
| 11: Documentation/policy | Current references cover the migration; finish attribution, source-role, and initialization/selection corrections above. |
| 12: Final verification | Existing integration checks pass; add coverage for items 5– 6. Full race validation remains unreliable because of item 2. |
2026-11-17 23:57:45 +00:00
The approved discovery, bootstrap, relative-resource, and secondary-import
2026-11-18 00:30:09 +00:00
changes are deliberate contract changes. Items 5– 6 describe implementation
inconsistencies in existing workflows. Item 2 concerns an incidental test-time
performance assumption, not a requested startup guarantee.
2026-11-17 23:57:45 +00:00
2026-11-18 00:30:09 +00:00
## Initial review validation
2026-11-17 23:57:45 +00:00
Using Go 1.27.4:
- `go test ./...` passed.
- `go test -race ./...` failed at item 2. The isolated application race suite
passed, as did five subsequent repetitions of the focused restore test.
- `go vet ./...` , `go build ./...` , and `go mod tidy -diff` passed.
- Release-asset cross-builds passed for Linux amd64, Linux arm64, and macOS
arm64 with the existing `v0.0.0-test` label and temporary output directory.
- Focused diagnostic reproductions confirmed items 1 and 3. Temporary Go
overlays kept those diagnostics and proposed-code experiments outside the
repository.
- Documentation checks and `git diff --check` passed.
Review execution made no application changes and invoked no live subprocess
services or release publication.
2026-11-18 00:30:09 +00:00
## Integration follow-up validation
Using Go 1.27.4 at the follow-up revision:
- `go test ./...` passed with local test-server sockets permitted. The sandboxed
attempt was blocked by `httptest` socket restrictions.
- Focused migration checks across config, stage, and app packages passed both
ordinarily and under `-race` . These exercised native discovery/inspection,
imported inputs, canonical materialization, published-session round trips,
initialization, and command/execution agreement.
- Temporary overlay diagnostics reproduced both aspects of item 5 and the
publication/update conflict in item 6, ordinarily and under `-race` .
- The full race suite was not repeated in this pass; item 2 retains the initial
review's observed failure. Application code is unchanged.
Only this remediation document changed. Diagnostic files remained outside the
repository, and object storage used an in-memory fake.
2026-11-18 01:10:44 +00:00
## Algorithm-focused review coverage and validation
The stage-by-stage pass covered dependency/API substitutions (1), native
discovery/bootstrap (2), resource-base queries (3), secondary loading and
materialization data flow (4), roster ordering/rendering (5), prepare/resume
serialization (6), archive/remote/restore paths (7), finalized snapshots (8),
diff/provenance projection (9), examples (10), documentation (11), and assembled
verification (12).
The chosen roster ordering, defaults-backed snapshot construction, native Diff,
and required content validation remain accepted. Canonical rendering is linear
in emitted data; the planned roster comparison sort is O(C log C) after deriving
ordering keys. Unchanged algorithms such as pairwise party-name validation and
prepare-input matching are not new findings from this migration-focused pass.
Cost analysis followed the released module's public API wrappers through native
source lookup and metadata-copy implementations. Temporary functional Go-overlay
checks validated source-enumeration and shared-metadata equivalence, ordinarily
and under `-race` . Focused configuration, file-reader copy, S3 opened-object
metadata, native inspection, and prepared-session publication checks passed on
Go 1.27.4. No performance data, timing assertions, benchmark gates, or application
changes were introduced.