Record ConfigKit migration review findings

This commit is contained in:
2026-11-17 23:57:45 +00:00
parent 39a958675d
commit bccf03a99f

162
docs/roadmap/remediation.md Normal file
View File

@@ -0,0 +1,162 @@
# 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.
The native configuration architecture is substantially implemented. The items
below are the remaining required corrections; this review does not implement
their fixes.
## 1. P2: Distinguish effective resource origins from superseded history
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
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
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
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.
## 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. |
| 5: Party imports | Imported rosters, source-aware ordering, canonical rendering, players, and family resolution are present. |
| 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; remote-session round-trip coverage is present. |
| 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; effective/history attribution needs item 1. |
| 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 and source-role corrections above. |
| 12: Final verification | Checks exercised; full race validation remains unreliable because of item 2. |
The approved discovery, bootstrap, relative-resource, and secondary-import
changes are deliberate contract changes. No additional production prohibition
or stronger runtime guarantee was identified. Item 2 concerns an incidental
test-time performance assumption, not a requested startup guarantee.
## 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.