Files
narratio/docs/roadmap/remediation.md

263 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CommandKit migration review
## Scope
Reviewed all 21 stages of [implementation.md](implementation.md) against the
[approved roadmap](commandkit.md), the implementation from `86692d5` through
`0117f3f35d73b3025a0222d25b6924ef455592e1`, current source and documentation,
behavioral tests, and focused diagnostic reproductions. Completion annotations
were treated as claims to verify rather than proof of completion.
The native command boundary, actual ConfigKit inspection results, separate domain
catalogs, independent selections, reporting, and cancellation architecture are
substantially implemented. The initial pass identified findings 1–3. An
integration-focused follow-up at `8be65fd` adds finding 4; the application source
is unchanged from the initial review. All four P2 findings remain open.
These reviews make no application changes.
## 1. P2: Preserve campaign inheritance when materializing session documents
Stages: 3, 6, and 13; preservation checks in Stage 21.
Locations: `internal/config/load.go:254–255`,
`internal/config/document_render.go:52–62`, and
`internal/app/prepared_session_roundtrip_test.go:88`.
`SessionDocument` now points to the completed session, which already contains
campaign defaults. `RenderSessionDocument` writes those inherited stable input
paths as explicit session fields. Reloading generated session YAML or the
published prepared-session fallback therefore replaces inheritance with fixed
paths from the producing campaign. The optional spell-catalog default is also
written whenever nonempty.
Reproduction: load a session whose authored inputs contain only audio; render its
prepared session; change the selected campaign's `speakers_file`; reload the
prepared bytes with that campaign. The received session still selects the old
speaker file. Its native metadata now calls this a session override. The
round-trip test was changed to expect `session_config` ownership for the formerly
inherited speaker path, so it accepts the regression rather than protecting the
prior behavior.
The [configuration contract](../config.md#pipeline-imports-and-overlays) says
omitted session fields remain eligible to inherit the receiving campaign's
values. Preserving materialization/authoring semantics was part of the plan.
Freezing inherited resource paths is an additional semantic commitment, not a
requirement of completing defaults before the ConfigKit handoff. It can select
obsolete resources after campaign updates and retain paths unavailable on a
receiving host.
Required remediation:
- Keep the actual completed ConfigKit result authoritative for inspection and
execution. Use native explicitness metadata when serializing session-owned
fields so inherited campaign input defaults remain omitted in materialized
session YAML. Retain explicit session overrides and explicit optional-input
clearing. Preserve import flattening and source-relative resolution.
- Apply the distinction to preparation, local/remote initialization, and
committed-session fallback through their shared renderer. Do not introduce a
replacement configuration result or reparse authoring files for inspection.
- Restore coverage that materializes an omitted default, changes the receiving
campaign, and observes the new default. Include an explicit override and an
explicit empty optional spell catalog to establish the difference. Update the
existing round-trip expectation rather than preserving the newly frozen
behavior as a contract.
## 2. P2: Classify identifiable Narratio input errors consistently
Stages: 1, 7–10, and 12; native outcome verification in Stage 21.
Locations: `internal/app/configuration_commands.go:75–96`,
`internal/app/configuration_acquisition.go:294–297`, and
`internal/app/command_outcome.go:30–55`.
Two integration paths return operational status 1 for identifiable input errors:
1. Native configuration acquisition/comparison returns
`config.SessionIdentityError` for a supplied campaign/session identity that
differs from the selected file. The scope wrapper adds explanatory text but
passes the same error to ckconfig, whose classifier does not know Narratio's
type. For example, `config show --scope campaign --campaign-file FILE
--campaign WRONG` returns status 1. Session assertions and comparison-side
assertions have the same problem. The application outcome adapter recognizes
the type for domain commands, but native config commands do not use it.
2. Catalog derivation returns plain errors for invalid configuration relations.
A configured artifact with `depends_on: [missing]` reaches domain derivation,
then `artifacts list` and `run --stage analyze` return status 1. The error
unambiguously identifies invalid supplied configuration, not a service failure.
Such relational validation belongs in domain derivation; moving family
expansion into native app inspection is not the remedy.
The roadmap and [CLI outcome contract](../cli.md#cancellation-and-exit-status)
reserve status 2 for invalid invocation or identifiable configuration input.
Current identity tests check only a nonzero status and explanatory text, leaving
this integration mismatch undetected.
Required remediation:
- Preserve the agreed status 2 classification for post-resolution identity
assertions in native config acquisition and comparison, including the right
side. Use genuine native resolution/validation or a supported classification
integration point while preserving the underlying typed cause. If the released
API lacks the necessary integration point, address that narrow capability
upstream rather than forking native commands or matching error strings.
- Give Narratio-owned invalid domain-configuration relations typed input
classification at their existing boundary. Keep cancellation, storage/access
failures, shutdown/persistence errors, and mixed operational causes at status 1.
Do not classify every acquisition or catalog error as user input indiscriminately.
- Add native invocation regressions asserting exact status classification for
campaign/session mismatch, comparison-side mismatch, and an unknown artifact
dependency, alongside an operational or joined-cause counterexample.
## 3. P2: Correct the documented empty spell-catalog behavior
Stage: 20.
Location: `docs/config.md:706`, the `inputs.spell_catalog_file` session field row.
The field table says an empty or omitted value inherits the campaign value.
The implemented native-default behavior distinguishes them: omission inherits;
an explicit empty string clears the optional input. This behavior is exercised
by `TestSessionDefaultsCompleteBeforeNativeHandoff` and is consistent with the
agreed explicit-presence rules. The table contradicts both implementation and
the reference's general defaults section.
Required remediation: update the field row and any equivalent current guidance
to state the implemented distinction. Retain optional-input clearing behavior;
do not change it to satisfy the obsolete wording. This is a documentation-only
correction, separate from preserving inherited versus explicit fields during
materialization in finding 1.
## 4. P2: Keep party-selection provenance out of prepare resume identity
Stages: 4–7, 10–11, and 21.
Locations: `internal/config/party_resolution.go:70–81`,
`internal/stage/semantic_contracts_initial.go:151–171`,
`internal/app/semantic_resume.go:44–45`, and
`internal/app/run_control.go:78–83`.
The new explicit party selector labels its source `party_file`; campaign-default
selection labels the same roster `campaign_config`. Existing prepare semantic
evidence hashes that source label in `prepareStableInputSelection.Source`.
Selecting the very same file explicitly changes the semantic fingerprint even
when the canonical roster, players projection, derived catalog, and all prepared
file contents are unchanged.
An end-to-end native-invocation diagnostic reproduced this sequence:
1. Run `prepare` successfully using the campaign-default roster and record a
succeeded downstream `transcribe` stage.
2. Plan the same session with `--party-file` pointing to that same roster. The
planner reports `result-affecting configuration changed; rerun the stage`.
3. Execute that bounded prepare request without force. Prepare executes again,
and the previously succeeded transcription stage becomes stale. Every
prepared input path/checksum pair remains identical.
The normal invalidation relation also applies to other succeeded downstream
stages. A subsequent full run can therefore schedule unnecessary downstream
processing solely because the operator made the source selection explicit.
The selector and existing semantic-resume implementation work independently,
but their integration turns provenance into result identity, contrary to the
roadmap's result-affecting evidence boundary. This is separate from finding 1:
the reproduction requires no serialization/reload or campaign-default change.
Required remediation:
- Keep the selected source label in appropriate provenance and inspection
records. Exclude or semantically normalize the provenance-only distinction in
prepare's reuse fingerprint. Review equivalent stable-input source labels
under the same result-affecting rule without weakening content validation.
- Continue detecting actual roster/players/input changes through existing
canonical payload checksums and stage/artifact evidence. Preserve the fixed
downstream invalidation relation when inputs really change.
- Add an integration regression covering native planning and execution with
default versus explicit selection of the same roster, unchanged prepared
bytes, and retained downstream success. Include changed roster contents as a
counterexample that must invalidate affected work.
## Stage-by-stage coverage
| Stage | Evidence reviewed and result |
| --- | --- |
| 1 | Released module selection, native application/process boundary, lazy construction, and outcome adapter; finding 2 covers classification gaps. |
| 2 | Retained pipeline/campaign results, lifecycle normalization/validation, native metadata, and absence of replacement inspection results. |
| 3 | Campaign defaults, explicit presence, session assertions, and resource bases; findings 1 and 2 cover materialization and native assertion outcomes. |
| 4 | Selected-party results/players, pure family expansion, collision/dependency checks, and separate publication rules; finding 4 covers resume integration. |
| 5 | Concrete-catalog consumers in planning, analysis, semantic fingerprints, adapter composition, and runtime registration. |
| 6 | Preparation, publication, restore round trips, and semantic evidence; findings 1 and 4 cover serialization and provenance-sensitive reuse. |
| 7 | Exact-file/local/remote acquisition, source labels, one-time bootstrap, retained errors, and resource cleanup; finding 2 covers typed input classification. |
| 8 | Four native scopes, path/history/findings capabilities, aggregate behavior, and lazy acquisition. |
| 9 | Independent comparison inputs/defaults, app-only overrides, native difference reports and status 3; finding 2 covers assertion failures. |
| 10 | Native bounded run/regeneration wiring, force and artifact selection, and shared execution; finding 2 covers invalid domain configuration. |
| 11 | Shared read-only planning, publication actions, and configured artifact catalog reporting; finding 4 affects planned reuse. |
| 12 | Structured validation/status/artifact inspection, partial findings, local/remote evidence, and read-only behavior. |
| 13 | Initialization targets, authoring contexts, generated YAML, explicit lock commands, and conditional lock mutations; finding 1 covers inherited defaults. |
| 14 | Restore and cleanup declarations, dry-run behavior, exact action reports, confinement, conflicts, and partial failure handling. |
| 15 | Failed-attempt accounting, partial run results, checkpoint evidence, terminal persistence, cause retention, and lock release. |
| 16 | Interrupt/termination wiring, context propagation, worker settlement, detached terminal local persistence, and resumability. |
| 17 | Narratio-owned reporting seam, native visibility/channels, stage progress, and isolation from downstream debug capture. |
| 18 | Audio transfers/cache reuse, speaker/artifact durable completions, checkpoint reuse, and progress-only integration tests. |
| 19 | Native completion/static/path hints, lazy discovery tests, and retirement of handwritten routing/parsing/rendering. |
| 20 | Canonical references, workflows, migration table, attribution, supported platforms, and preserved release history; findings 1 and 3 cover remaining documentation divergence. |
| 21 | Full test/race suites, vet/build, assembled workflows, focused review reproductions, and remaining verification recorded below. |
The initial pass identified no other actionable requirement strengthening.
The removed CLI aliases, native flag conventions, inspection-only overrides, domain/native-view
separation, and deferred workspace/downstream changes follow the agreed scope.
## Review validation
Using official Go 1.27.4 against the reviewed application source:
- `go test ./...` passed.
- `go test -race ./...` passed.
- `go vet ./...` and `go build ./...` passed.
- Focused Go-overlay diagnostics reproduced both cases in finding 2 and the
campaign-default freezing in finding 1. Diagnostic files remained under
`/tmp`; application source and tests were unchanged.
- `go mod tidy -diff` passed.
- The nonpublishing asset builder passed with `v0.0.0-test`, producing Linux
amd64/arm64 and macOS arm64 binaries under `/tmp` and verifying the host
binary's embedded version. macOS evidence is compilation-only.
- Documentation-link checks and `git diff --check` passed with this review
document present.
Only this remediation document changes the repository. No release, tag, push,
CI polling, or live downstream service invocation was performed.
## Integration follow-up coverage and validation
The follow-up traversed the stages in order, emphasizing existing consumers:
- Stages 1–3: process/CLI inputs into existing loaders, validation callers,
authoring-context initialization, and materialized input consumers.
- Stage 4: selected-party provenance and canonical roster/players derivation.
- Stage 5: concrete catalog/dependency consumers in planning, execution,
adapter composition, previous-session requirements, and runtime registration.
- Stage 6: semantic fingerprints, preparation comparisons, publication actions,
and restored input records. Finding 4 is an additional resume-integration gap.
- Stage 7: explicit/default source selection into existing identity checks,
local/remote acquisition, storage, and temporary-resource cleanup.
- Stages 8–9: native scope acquisition, independent comparison state, and
invocation-local overrides against the retained load results.
- Stages 10–11: bounded run/regeneration and plan decisions against existing
resume validation, analysis target closure, and dependent invalidation.
- Stages 12–14: inspection, initialization, locks, restore, and cleanup against
local manifests, pointer-selected remote declarations, conditional lock
updates, confinement, and existing action-report persistence.
- Stages 15–16: partial results and cancellation against speaker/artifact
checkpoints, terminal persistence, adapter contexts, and local lock release.
- Stages 17–19: progress/diagnostic delivery across existing concurrent workers
and captured subprocess logs; native lazy discovery and retired routing.
- Stages 20–21: current operator contracts and maintained workflow fixtures
against the assembled boundaries above.
Application source remained unchanged. The initial full tests, race tests, vet,
build, module, and supported-target checks therefore remain applicable. This
pass additionally reran `go test` for `internal/app`, `internal/config`,
`internal/stage`, `internal/artifacts`, `internal/audio`, and `internal/manifest`;
all passed on Go 1.27.4. A new native-invocation Go-overlay diagnostic reproduced
finding 4 under `-race` and verified unchanged prepared input checksums. Its
files remained under `/tmp`. Documentation checks and whitespace validation
were repeated for this document update.