Record ConfigKit migration review findings
This commit is contained in:
162
docs/roadmap/remediation.md
Normal file
162
docs/roadmap/remediation.md
Normal 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.
|
||||||
Reference in New Issue
Block a user