From c98b4ef4ef2513a24f06e88e851bee1516147904 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 2 Sep 2026 14:38:51 +0000 Subject: [PATCH] Align compatibility documentation --- docs/config.md | 2 +- docs/internal/artifacts.md | 7 ++++--- docs/internal/manifest.md | 2 +- docs/internal/stage-analyze.md | 6 +++--- docs/internal/stage-prepare.md | 5 ++--- docs/operations.md | 2 +- docs/roadmap/implementation.md | 9 ++++----- docs/troubleshooting.md | 33 +++++++++++++++++---------------- 8 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/config.md b/docs/config.md index b7bf61b..2208e81 100644 --- a/docs/config.md +++ b/docs/config.md @@ -450,7 +450,7 @@ Without `--artifacts`, analyze executes enabled configured artifacts. With an explicit `--artifacts` list, the exact named configured artifacts are the one-invocation targets even if their `enabled` values are false. Analyze closes those targets over `depends_on`: a current prerequisite is reused, while a -stale, missing, failed, or legacy prerequisite is rebuilt before its dependent. +stale, missing, or failed prerequisite is rebuilt before its dependent. Unrelated artifacts are not executed. Named targets and any prerequisite that may require rebuilding must therefore have valid executable fields. This override affects analyze planning only; publish uses the list only to filter diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index cdc69ec..409ea58 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -69,8 +69,9 @@ publish rules during configuration resolution. Configured outputs, including non-executable prerequisites, become available only when the versioned analyze state identifies a current result whose source, contract, canonical configured path, size, and checksum match a confined -no-follow regular file. An incidental canonical file and a legacy aggregate -analyze output are unavailable. +no-follow regular file. An incidental canonical file is unavailable, and a +manifest with an unsupported aggregate-only representation is rejected before +catalog construction. Extraction entries are registered from configuration and become available only after compatible extraction evidence is hydrated. @@ -108,7 +109,7 @@ Configured sources (`narratio.artifact.*`): record for the exact configured key and source ID, a complete contract, the configured canonical relative path, positive stored size, and stored checksum matching bytes read from a confined no-follow regular file; and -- treat non-current statuses, legacy or malformed records, removed keys, +- treat non-current statuses, malformed records, removed keys, unsafe or missing files, and size/checksum mismatches as unavailable without rewriting manifest state. Catalog construction iterates current configuration, so removed or renamed records are not advertised. diff --git a/docs/internal/manifest.md b/docs/internal/manifest.md index d99a4b2..75cb635 100644 --- a/docs/internal/manifest.md +++ b/docs/internal/manifest.md @@ -214,7 +214,7 @@ the `skip` action and reason. The session manifest deliberately retains its existing succeeded record because it remains the cross-invocation progress authority. If a stage supplies semantic configuration evidence, reuse first requires the persisted positive schema version and lowercase SHA-256 digest to -match the current resolved stage semantics. Missing legacy evidence, malformed +match the current resolved stage semantics. Missing semantic evidence, malformed evidence, or a mismatch makes the stage and its fixed transitive dependents stale. The invocation skip copies the matched fingerprint for provenance but does not rewrite session authority. The existing stage-specific resume diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index de74a42..94665c8 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -75,7 +75,7 @@ Supported source families: validated current dependency-output identities, and sorted effective Scriptorium variables (including Narratio's sticky session variable). - provides read-only reconciliation that classifies each configured record as - current, stale, missing, failed, legacy, or otherwise non-resumable, and + current, stale, missing, failed, or otherwise non-resumable, and separately identifies manifest records removed from current configuration. A record is current only when its fingerprint version and value match and its configured output still passes manifest-authoritative evidence validation. @@ -90,8 +90,8 @@ Supported source families: - the work plan carries explicit targets, prerequisite-only work, deterministic execution and reuse lists, invalidated and removed records, and a cloned projected record collection. Valid unrelated configured records survive the - projection, removed records are omitted, and legacy files never become - current without regeneration. + projection, removed records are omitted, and incidental files never become + current without manifest-backed regeneration. - implements aggregate resume validation by running the same read-only catalog, fingerprint reconciliation, and work planner used by execution. A succeeded aggregate record is reusable exactly when the selected closure schedules no diff --git a/docs/internal/stage-prepare.md b/docs/internal/stage-prepare.md index 9eeff42..e642c00 100644 --- a/docs/internal/stage-prepare.md +++ b/docs/internal/stage-prepare.md @@ -39,9 +39,8 @@ Materialize canonical current-session inputs before processing stages. - materializes a configured spell catalog with checksum and provenance, or safely removes an obsolete canonical spell catalog and its manifest record when the effective input is omitted. -- in canonical party mode, copies the validated raw party bytes unchanged and - deterministically generates the prepared players projection; legacy mode - continues to copy its opaque party and explicit players sources. +- copies the validated canonical party bytes unchanged and deterministically + generates the prepared players projection. - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements. - clears managed `previous/` state on every invocation, then, when requirements exist: - resolves the pointer-selected previous source through the shared resolver; diff --git a/docs/operations.md b/docs/operations.md index e9e8bdf..07c5695 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -205,7 +205,7 @@ narratio session artifacts 2026-04-04 narratio publish 2026-04-04 ``` -If planning or execution reports stale, missing, failed, legacy, or tampered +If planning or execution reports stale, missing, failed, or tampered analysis evidence, regenerate the affected target instead of copying an older canonical file into place or editing the manifest. See [Troubleshooting: Analysis artifact evidence is not current](./troubleshooting.md#analysis-artifact-evidence-is-not-current). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index e886b0a..a7eb5a3 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -7,11 +7,10 @@ This is the executable plan for [`refactoring.md`](refactoring.md), Workstream [`contract-audit.md`](contract-audit.md) and rows C01/H43 of [`audit-decisions.md`](audit-decisions.md) own the approved decisions. -All seven stages are pending and must be implemented in order. Each is bounded -for one `gpt-5.6-terra` prompt. Workstreams 1 and 2 are complete. Workstreams -4 and later are out of scope: do not remove the run manifest, redesign runner -lifecycle, change analyze checkpoint timing, replace locks, decompose publish, -or add cleanup while following this plan. +All seven stages are complete. Workstreams 1 through 3 are complete. +Workstreams 4 and later remain out of scope for this completed plan: it did not +remove the run manifest, redesign runner lifecycle, change analyze checkpoint +timing, replace locks, decompose publish, or add cleanup. ## Settled Implementation Decisions diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 47b339f..719fb6e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -398,8 +398,7 @@ Symptom: Likely causes: -- the per-artifact record is stale, missing, failed, unselected, malformed, or - from the legacy aggregate-only manifest contract; +- the per-artifact record is stale, missing, failed, unselected, or malformed; - a configured prompt/profile, dependency, input identity, output path, or effective variable changed; or - the recorded output is missing, unsafe, empty, or has a size/checksum that no @@ -447,33 +446,35 @@ Safe fix: stage to regenerate both the bytes and current manifest evidence, then retry the consumer. -## Legacy aggregate analysis requires regeneration +## An older manifest schema is rejected Symptom: -- a manifest from an older Narratio version reports aggregate analyze success - and the old files are present, but configured artifact sources remain - unavailable. +- Narratio rejects a local session manifest because `schema_version` is missing + or unsupported; or +- restore rejects a committed remote session manifest for the same reason. Likely cause: -- the manifest has no supported per-artifact analyze state. Aggregate output - lists do not establish current configured-artifact authority. +- the manifest predates the supported canonical state contract. Narratio + rejects it at the schema boundary rather than interpreting aggregate output + lists or incidental files as current authority. Safe fix: -- regenerate the required artifacts. A partial selection makes only its - targets and prerequisites eligible for current state; unselected legacy - files intentionally remain unavailable. Run full analysis later when every - enabled configured artifact must become current. +- for unsupported local state, move the old manifest aside and regenerate, or + restore a verified current committed snapshot when one is authoritative; +- for unsupported committed remote state, regenerate healthy local state as + needed and republish the session. ```bash -narratio analyze 2026-04-04 --artifacts session_recap -narratio analyze 2026-04-04 +narratio run 2026-04-04 +narratio publish 2026-04-04 ``` -After current records exist, inspect them and publish explicitly. Do not delete -the legacy files merely to influence selection; availability is manifest-owned. +After current records exist, inspect them and publish explicitly. Do not copy +old files into canonical paths merely to influence selection; availability is +manifest-owned. Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior) and [Manifest Internals](./internal/manifest.md#analyze-owned-artifact-state).