Record configuration integration audit findings

This commit is contained in:
2026-11-18 00:30:09 +00:00
parent bccf03a99f
commit 583c5bdf1b

View File

@@ -7,6 +7,11 @@ against [the approved target](configkit.md), the implementation diff from
`65d0e51` through `39a958675d68e940799f4cb8c8e6748830d1483a`, current code, `65d0e51` through `39a958675d68e940799f4cb8c8e6748830d1483a`, current code,
documentation, focused diagnostic reproductions, and repository checks. 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.
The native configuration architecture is substantially implemented. The items The native configuration architecture is substantially implemented. The items
below are the remaining required corrections; this review does not implement below are the remaining required corrections; this review does not implement
their fixes. their fixes.
@@ -121,6 +126,78 @@ license texts, factual notice wording, and Go version identification.
Verification: confirm the links identify that source revision and run the Verification: confirm the links identify that source revision and run the
documentation checks. This requires no licensing change or new release gate. documentation checks. This requires no licensing change or new release gate.
## 5. P2: Give session initialization the correct authoring context
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.
## Stage-by-stage disposition ## Stage-by-stage disposition
| Stage | Review result | | Stage | Review result |
@@ -128,22 +205,22 @@ documentation checks. This requires no licensing change or new release gate.
| 1: Dependency/toolchain | ConfigKit v1.2.1 and Go 1.27.0/1.27.4 selected; remaining notice pinning in item 4. | | 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. | | 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. | | 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. | | 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. | | 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. | | 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. | | 7: Publish/restore | Prepared documents flow through immutable committed run objects and restore; remote initialization and committed selection conflict in item 6. |
| 8: Final-domain snapshots | Defaults-backed native snapshots, safe credential identities, rendering, and digest integration are 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. | | 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. | | 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. | | 11: Documentation/policy | Current references cover the migration; finish attribution, source-role, and initialization/selection corrections above. |
| 12: Final verification | Checks exercised; full race validation remains unreliable because of item 2. | | 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 The approved discovery, bootstrap, relative-resource, and secondary-import
changes are deliberate contract changes. No additional production prohibition changes are deliberate contract changes. Items 5–6 describe implementation
or stronger runtime guarantee was identified. Item 2 concerns an incidental inconsistencies in existing workflows. Item 2 concerns an incidental test-time
test-time performance assumption, not a requested startup guarantee. performance assumption, not a requested startup guarantee.
## Validation ## Initial review validation
Using Go 1.27.4: Using Go 1.27.4:
@@ -160,3 +237,21 @@ Using Go 1.27.4:
Review execution made no application changes and invoked no live subprocess Review execution made no application changes and invoked no live subprocess
services or release publication. 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.