|
|
|
|
@@ -121,23 +121,10 @@ The incremental executor constructs this restricted projection at each
|
|
|
|
|
scheduled artifact boundary. The active record is failed without output,
|
|
|
|
|
current transitive dependents are stale, unrelated current records survive, and
|
|
|
|
|
only earlier validated and materialized completions remain current in the
|
|
|
|
|
invocation subset. Session failure state is persisted before invocation failure
|
|
|
|
|
state. If either terminal save fails, its persistence error is joined with the
|
|
|
|
|
original adapter, validation, or filesystem cause; a failed projection save
|
|
|
|
|
reconciled session collection. A terminal session-save failure is joined with
|
|
|
|
|
the original adapter, validation, or filesystem cause; a failed projection save
|
|
|
|
|
does not turn incidental canonical bytes into manifest authority.
|
|
|
|
|
|
|
|
|
|
## Run Manifest
|
|
|
|
|
|
|
|
|
|
`manifest.RunManifest` is created for each invocation and records:
|
|
|
|
|
|
|
|
|
|
- required `schema_version: narratio.run-manifest.v1`
|
|
|
|
|
- invocation identity and `force` flag
|
|
|
|
|
- the selected profile (when any) and secret-free effective configuration digest
|
|
|
|
|
- requested stages
|
|
|
|
|
- per-stage action (`run` or `skip`)
|
|
|
|
|
- per-stage status
|
|
|
|
|
- overall run status (`running`, `succeeded`, `failed`)
|
|
|
|
|
|
|
|
|
|
## Remote Commit Manifest
|
|
|
|
|
|
|
|
|
|
`artifacts.RemoteCommitManifest` is a separate, versioned remote snapshot
|
|
|
|
|
@@ -173,7 +160,7 @@ durability guarantee. Callers reload after a returned save error before retrying
|
|
|
|
|
## Execution Semantics
|
|
|
|
|
|
|
|
|
|
The application runner marks an executing stage running and then succeeded or
|
|
|
|
|
failed in both manifests, persisting each transition. On success it records
|
|
|
|
|
failed in the session manifest, persisting each transition. On success it records
|
|
|
|
|
outputs, logs, generated configuration references, metadata, and—when the
|
|
|
|
|
stage implements the optional contract—a versioned semantic-configuration
|
|
|
|
|
fingerprint. Artifact
|
|
|
|
|
@@ -190,8 +177,7 @@ Failed and skipped
|
|
|
|
|
transitions enforce the same clearing rule directly, while success repopulates
|
|
|
|
|
only fields returned by the new result. Marking a record stale does not clear
|
|
|
|
|
those details because resume validation and diagnosis may still require them
|
|
|
|
|
before execution begins. Invocation run manifests remain immutable audit
|
|
|
|
|
records of their own outcomes.
|
|
|
|
|
before execution begins.
|
|
|
|
|
|
|
|
|
|
Aggregate lifecycle clearing deliberately preserves the analyze-owned
|
|
|
|
|
per-artifact collection. This lets later reconciliation replace only evaluated
|
|
|
|
|
@@ -200,24 +186,21 @@ existing aggregate-only lifecycle behavior and are forbidden from carrying the
|
|
|
|
|
analyze-specific fields.
|
|
|
|
|
|
|
|
|
|
A stage may explicitly return a skipped disposition and stable reason. The
|
|
|
|
|
runner persists that outcome in both manifests, clears older outputs for the
|
|
|
|
|
session-stage record along with older logs, generated configuration references,
|
|
|
|
|
and metadata, then applies any bounded details from the current skip and
|
|
|
|
|
continues. This self-skip is distinct from deciding not to execute an
|
|
|
|
|
runner persists that outcome in the session manifest, clears older outputs,
|
|
|
|
|
logs, generated configuration references, and metadata, then applies any
|
|
|
|
|
bounded details from the current skip and continues. This self-skip is distinct from deciding not to execute an
|
|
|
|
|
already-succeeded stage and is reconsidered on later runs. Skipped results
|
|
|
|
|
cannot contain outputs. An intentional self-skip records the current semantic
|
|
|
|
|
fingerprint because it is a completed, reusable stage result; failed or
|
|
|
|
|
interrupted work never promotes one.
|
|
|
|
|
|
|
|
|
|
When an already-succeeded stage is skipped, the invocation run manifest records
|
|
|
|
|
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
|
|
|
|
|
When an already-succeeded stage is skipped, 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 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
|
|
|
|
|
stale. The existing stage-specific resume
|
|
|
|
|
validator runs only after this semantic check succeeds; both checks are
|
|
|
|
|
required. Extraction and analyze have resume validators and may reject an
|
|
|
|
|
otherwise eligible skip when their selected durable evidence is obsolete; the
|
|
|
|
|
@@ -248,10 +231,8 @@ contents that a tool privately loads remain outside the contract when their
|
|
|
|
|
configured identifier is unchanged; operators must force the affected work
|
|
|
|
|
after such a private content change.
|
|
|
|
|
|
|
|
|
|
Session manifest is the authoritative stage-progress ledger across invocations.
|
|
|
|
|
Run manifest is invocation-scoped audit state.
|
|
|
|
|
|
|
|
|
|
Both manifests retain the most recently resolved invocation's bounded
|
|
|
|
|
The session manifest is the authoritative stage-progress ledger across
|
|
|
|
|
invocations. It retains the most recently resolved invocation's bounded
|
|
|
|
|
configuration provenance. It identifies the selected profile name and source
|
|
|
|
|
(`default` or `cli`) plus the effective configuration digest, but never a raw
|
|
|
|
|
secret or profile content. This provenance is informational: it does not
|
|
|
|
|
@@ -262,7 +243,7 @@ configured identifier, use `--force` for the affected work.
|
|
|
|
|
|
|
|
|
|
`session plan` computes the same current fingerprint and applies the same
|
|
|
|
|
comparison and invalidation rules to a cloned manifest. It predicts the runner
|
|
|
|
|
decision without persisting session or invocation state. The shared helper
|
|
|
|
|
decision without persisting session state. The shared helper
|
|
|
|
|
hashes deterministic JSON from stage-owned typed structs; stage providers must
|
|
|
|
|
exclude secrets, complete effective-configuration dumps, and operational
|
|
|
|
|
values that cannot affect canonical results. Concrete coverage is owned by the
|
|
|
|
|
@@ -272,7 +253,7 @@ Before an explicitly bounded execution starts after `prepare`, the application
|
|
|
|
|
reads the session manifest and accepts only `succeeded` or `skipped` for every
|
|
|
|
|
excluded canonical prefix stage. The first other status or absent record fails
|
|
|
|
|
the request before layout mutation, adapter initialization, session-manifest
|
|
|
|
|
writes, or run-manifest creation. Excluded prefix records are not passed to
|
|
|
|
|
writes, or run-directory creation. Excluded prefix records are not passed to
|
|
|
|
|
resume validators. Records after the selected end are not prerequisites and
|
|
|
|
|
may be made stale by selected work without being scheduled.
|
|
|
|
|
|
|
|
|
|
@@ -289,30 +270,28 @@ session manifest must agree on campaign and session identity before execution;
|
|
|
|
|
the current projection is refreshed for every invocation while stage progress,
|
|
|
|
|
inputs, and durable artifacts remain session history.
|
|
|
|
|
|
|
|
|
|
For handled failures after an invocation record is created, the runner records
|
|
|
|
|
the failure on the session ledger and persists it before persisting the failed
|
|
|
|
|
run audit record. This preserves the resume authority while making a partial
|
|
|
|
|
persistence disagreement visible. Abrupt process death remains an accepted case
|
|
|
|
|
where a durable running record can require operator interpretation.
|
|
|
|
|
For handled failures after the session identity transition, the runner records
|
|
|
|
|
the failure on the session ledger and atomically attempts its save while
|
|
|
|
|
preserving the originating error. Abrupt process death remains an accepted case
|
|
|
|
|
where the last session transition can require operator interpretation.
|
|
|
|
|
|
|
|
|
|
## Invariants
|
|
|
|
|
|
|
|
|
|
- stage resume/skip decisions are session-manifest driven.
|
|
|
|
|
- semantic fingerprint comparison precedes stage-specific resume validation.
|
|
|
|
|
- only successful and intentional-skipped results promote current semantic
|
|
|
|
|
evidence; invocation reuse copies evidence without replacing session state.
|
|
|
|
|
evidence.
|
|
|
|
|
- running, failed, and self-skipped stages do not retain result payloads from
|
|
|
|
|
an earlier success.
|
|
|
|
|
- stale stages retain prior details until replacement execution starts.
|
|
|
|
|
- force reruns stale succeeded stages in the fixed dependency relation.
|
|
|
|
|
- run manifest does not replace session manifest as progress authority.
|
|
|
|
|
- the session manifest is the only durable local progress ledger.
|
|
|
|
|
- remote commitment is established by a verified current pointer and remote
|
|
|
|
|
commit relationship, never by a mutable session-manifest boolean.
|
|
|
|
|
|
|
|
|
|
## Implementation And Tests
|
|
|
|
|
|
|
|
|
|
- Models and transitions: `internal/manifest/manifest.go`,
|
|
|
|
|
`internal/manifest/run_manifest.go`
|
|
|
|
|
- Models and transitions: `internal/manifest/manifest.go`
|
|
|
|
|
- Remote commit model and readers: `internal/artifacts/remote_commit.go`,
|
|
|
|
|
`internal/artifacts/current_state_commit.go`,
|
|
|
|
|
- Persistence and validation: `internal/manifest/store.go`
|
|
|
|
|
|
