422 lines
23 KiB
Markdown
422 lines
23 KiB
Markdown
# 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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
The native configuration architecture is substantially implemented. The items
|
||
below record the six required corrections and four additional algorithmic
|
||
opportunities. This document implements none of their fixes.
|
||
|
||
## 1. P2: Distinguish effective resource origins from superseded history
|
||
|
||
Status: Complete. Native pre-resolution Previous evidence supplies current
|
||
contributors; regression coverage includes overlay replacement and inheritance.
|
||
|
||
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
|
||
|
||
Status: Complete. Cancellation is synchronized after discovery with the session
|
||
lock held. Ten focused race repetitions and the full repository race suite pass.
|
||
|
||
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
|
||
|
||
Status: Complete. Field-only defaults and destinations retain precise native
|
||
history. Publish and authored append/upsert/replace regression checks pass.
|
||
|
||
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
|
||
|
||
Status: Complete. Go license, patent, and source links identify the verified
|
||
Go 1.27.4 source commit; documentation checks pass.
|
||
|
||
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.
|
||
|
||
## 5. P2: Give session initialization the correct authoring context
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
## 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.
|
||
|
||
## 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. |
|
||
| 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. |
|
||
| 5: Party imports | Imported rosters, source-aware ordering, canonical rendering, players, and family resolution are present; the planned roster sort is retained. |
|
||
| 6: Prepared inputs/resume | Canonical document materialization and matching resume evidence are present. |
|
||
| 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. |
|
||
| 8: Final-domain snapshots | Defaults-backed native snapshots, safe credential identities, rendering, and digest integration are present. |
|
||
| 9: Diff/provenance | Native diff and pointer paths are present; item 1 concerns attribution correctness and items 7–8 concern avoidable provenance work. |
|
||
| 10: Examples | Destination-based definitions, directory imports, list operations, split roster, and secondary imports are demonstrated. |
|
||
| 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. |
|
||
|
||
The approved discovery, bootstrap, relative-resource, and secondary-import
|
||
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.
|
||
|
||
## Initial review validation
|
||
|
||
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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|