Close analyze checkpointing workstream
This commit is contained in:
@@ -119,6 +119,8 @@ the last committed collection before constructing the active failed record.
|
|||||||
Newly materialized canonical bytes therefore remain incidental and cannot
|
Newly materialized canonical bytes therefore remain incidental and cannot
|
||||||
become current authority. A later ordinary run reconciles the durable records,
|
become current authority. A later ordinary run reconciles the durable records,
|
||||||
reuses earlier current artifacts, and resumes with the failed or stale work.
|
reuses earlier current artifacts, and resumes with the failed or stale work.
|
||||||
|
The same recovery applies after process interruption: the aggregate record may
|
||||||
|
be non-successful, but every completed artifact checkpoint remains reusable.
|
||||||
|
|
||||||
## Remote Commit Manifest
|
## Remote Commit Manifest
|
||||||
|
|
||||||
@@ -151,6 +153,10 @@ establish a current immutable snapshot.
|
|||||||
|
|
||||||
Manifest replacement provides atomic visibility, not a crash- or power-loss
|
Manifest replacement provides atomic visibility, not a crash- or power-loss
|
||||||
durability guarantee. Callers reload after a returned save error before retrying.
|
durability guarantee. Callers reload after a returned save error before retrying.
|
||||||
|
An analyze checkpoint error leaves the prior manifest as per-artifact authority.
|
||||||
|
The runner then attempts to persist the bounded failed/stale retry collection;
|
||||||
|
if that terminal save also fails, its error is joined with the originating
|
||||||
|
failure and the next invocation must reconcile from the last readable manifest.
|
||||||
|
|
||||||
## Execution Semantics
|
## Execution Semantics
|
||||||
|
|
||||||
|
|||||||
@@ -104,6 +104,10 @@ Supported source families:
|
|||||||
prerequisites remain available through the runtime catalog without invoking
|
prerequisites remain available through the runtime catalog without invoking
|
||||||
Scriptorium; newly produced prerequisites enter that catalog with the same
|
Scriptorium; newly produced prerequisites enter that catalog with the same
|
||||||
contract, checksum, and size identity used for persisted current evidence.
|
contract, checksum, and size identity used for persisted current evidence.
|
||||||
|
- before the first adapter call, checkpoints the reconciled starting collection
|
||||||
|
when it removed configuration records or cleared obsolete authority. After
|
||||||
|
each successful artifact, checkpoints the complete collection before making
|
||||||
|
that artifact available to the next scheduled dependent.
|
||||||
- keeps adapter output in the invocation's run-local analyze directory until
|
- keeps adapter output in the invocation's run-local analyze directory until
|
||||||
it is a safe, non-empty, bounded regular file with a calculated checksum and
|
it is a safe, non-empty, bounded regular file with a calculated checksum and
|
||||||
complete output contract. Canonical replacement uses the shared atomic file
|
complete output contract. Canonical replacement uses the shared atomic file
|
||||||
@@ -146,6 +150,10 @@ Supported source families:
|
|||||||
- unrelated current records survive a partial failure. Old canonical bytes for
|
- unrelated current records survive a partial failure. Old canonical bytes for
|
||||||
the failed artifact and newly materialized bytes whose checkpoint fails are
|
the failed artifact and newly materialized bytes whose checkpoint fails are
|
||||||
incidental, not current evidence.
|
incidental, not current evidence.
|
||||||
|
- a checkpoint failure stops the queue immediately. The in-memory retry
|
||||||
|
collection starts from the last successful checkpoint, marks the active
|
||||||
|
artifact failed without output authority, and stales its current transitive
|
||||||
|
dependents.
|
||||||
- the runner's ordinary error path marks aggregate analyze failed, clears its
|
- the runner's ordinary error path marks aggregate analyze failed, clears its
|
||||||
aggregate outputs, invalidates publish and notify through the application
|
aggregate outputs, invalidates publish and notify through the application
|
||||||
dependency relation, and persists the live retry collection. Terminal-save
|
dependency relation, and persists the live retry collection. Terminal-save
|
||||||
@@ -164,6 +172,9 @@ Supported source families:
|
|||||||
- output provenance and metadata are deterministic per execution.
|
- output provenance and metadata are deterministic per execution.
|
||||||
- a canonical file without current per-artifact manifest evidence is never
|
- a canonical file without current per-artifact manifest evidence is never
|
||||||
promoted to current state.
|
promoted to current state.
|
||||||
|
- an ordinary retry after interruption or partial failure reuses every valid
|
||||||
|
earlier checkpoint and schedules only failed, stale, missing, or otherwise
|
||||||
|
non-current work in dependency order.
|
||||||
|
|
||||||
## Related Contracts And Tests
|
## Related Contracts And Tests
|
||||||
|
|
||||||
|
|||||||
@@ -210,6 +210,12 @@ analysis evidence, regenerate the affected target instead of copying an older
|
|||||||
canonical file into place or editing the manifest. See
|
canonical file into place or editing the manifest. See
|
||||||
[Troubleshooting: Analysis artifact evidence is not current](./troubleshooting.md#analysis-artifact-evidence-is-not-current).
|
[Troubleshooting: Analysis artifact evidence is not current](./troubleshooting.md#analysis-artifact-evidence-is-not-current).
|
||||||
|
|
||||||
|
Analyze checkpoints each completed configured artifact before starting later
|
||||||
|
artifact work. After a partial failure or interruption, retry normally: valid
|
||||||
|
earlier checkpoints are reused and execution resumes with failed, stale, or
|
||||||
|
missing work in dependency order. `--force` is unnecessary unless the operator
|
||||||
|
intends to replace otherwise-current artifacts.
|
||||||
|
|
||||||
## Artifact Selection
|
## Artifact Selection
|
||||||
|
|
||||||
For a configured artifact family, selecting its family key expands to every
|
For a configured artifact family, selecting its family key expands to every
|
||||||
|
|||||||
@@ -383,7 +383,7 @@ validation, application, and rollback paths.
|
|||||||
|
|
||||||
## Stage 5 — Verify Force Semantics, Align Documentation, And Close Workstream 6
|
## Stage 5 — Verify Force Semantics, Align Documentation, And Close Workstream 6
|
||||||
|
|
||||||
**Status:** Pending
|
**Status:** Completed
|
||||||
|
|
||||||
### Goal
|
### Goal
|
||||||
|
|
||||||
|
|||||||
@@ -264,7 +264,7 @@ do not require process-global substitution.
|
|||||||
|
|
||||||
### Workstream 6 — Per-artifact analyze checkpointing and recovery
|
### Workstream 6 — Per-artifact analyze checkpointing and recovery
|
||||||
|
|
||||||
**Status:** Pending
|
**Status:** Complete
|
||||||
|
|
||||||
**Audit sources:** H04, H14, H15, H36, H37, C02, and C03.
|
**Audit sources:** H04, H14, H15, H36, H37, C02, and C03.
|
||||||
|
|
||||||
|
|||||||
@@ -428,6 +428,34 @@ narratio analyze 2026-04-04 --artifacts session_recap
|
|||||||
Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
|
Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
|
||||||
and [Artifact Internals](./internal/artifacts.md#resolution-rules).
|
and [Artifact Internals](./internal/artifacts.md#resolution-rules).
|
||||||
|
|
||||||
|
## Analysis manifest checkpoint failed
|
||||||
|
|
||||||
|
Symptom:
|
||||||
|
|
||||||
|
- analyze reports that it could not save the session manifest after completing
|
||||||
|
an artifact.
|
||||||
|
|
||||||
|
Likely causes:
|
||||||
|
|
||||||
|
- the workspace is unwritable or out of space;
|
||||||
|
- the manifest path or its parent directory has unsafe permissions or type; or
|
||||||
|
- a transient local filesystem error interrupted atomic manifest replacement.
|
||||||
|
|
||||||
|
Safe fix:
|
||||||
|
|
||||||
|
- correct the reported filesystem or permission problem;
|
||||||
|
- inspect `session artifacts` to identify the last durable current records; and
|
||||||
|
- rerun analyze normally. Narratio reuses earlier successful checkpoints and
|
||||||
|
retries the failed or non-current artifact and its required dependents.
|
||||||
|
|
||||||
|
Do not treat a newly created canonical artifact file as current when its
|
||||||
|
checkpoint failed, and do not edit the manifest to advertise it. If the error
|
||||||
|
recurs, preserve the manifest and run-local diagnostics before repairing the
|
||||||
|
workspace.
|
||||||
|
|
||||||
|
Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
|
||||||
|
and [Manifest Internals](./internal/manifest.md#persistence-semantics).
|
||||||
|
|
||||||
## Built-in transcript or bounds source is unavailable
|
## Built-in transcript or bounds source is unavailable
|
||||||
|
|
||||||
Symptom:
|
Symptom:
|
||||||
|
|||||||
@@ -62,6 +62,30 @@ func TestPlanAnalyzeWorkSelectionAndDependencyClosure(t *testing.T) {
|
|||||||
},
|
},
|
||||||
wantTargets: []string{"alpha", "zeta"}, wantExecution: []string{"alpha", "zeta"},
|
wantTargets: []string{"alpha", "zeta"}, wantExecution: []string{"alpha", "zeta"},
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
name: "ordinary default selection reuses every current artifact",
|
||||||
|
configured: map[string]config.ScriptoriumArtifactConfig{
|
||||||
|
"alpha": {Enabled: true}, "zeta": {Enabled: true}, "disabled": {Enabled: false},
|
||||||
|
},
|
||||||
|
reasons: map[string]analyzeReconciliationReason{
|
||||||
|
"alpha": analyzeReconciliationCurrent, "zeta": analyzeReconciliationCurrent,
|
||||||
|
"disabled": analyzeReconciliationCurrent,
|
||||||
|
},
|
||||||
|
wantTargets: []string{"alpha", "zeta"}, wantReused: []string{"alpha", "zeta"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "unqualified force reruns every enabled artifact",
|
||||||
|
configured: map[string]config.ScriptoriumArtifactConfig{
|
||||||
|
"alpha": {Enabled: true}, "zeta": {Enabled: true}, "disabled": {Enabled: false},
|
||||||
|
},
|
||||||
|
force: true,
|
||||||
|
reasons: map[string]analyzeReconciliationReason{
|
||||||
|
"alpha": analyzeReconciliationCurrent, "zeta": analyzeReconciliationCurrent,
|
||||||
|
"disabled": analyzeReconciliationCurrent,
|
||||||
|
},
|
||||||
|
wantTargets: []string{"alpha", "zeta"}, wantExecution: []string{"alpha", "zeta"},
|
||||||
|
wantForced: []string{"alpha", "zeta"},
|
||||||
|
},
|
||||||
{
|
{
|
||||||
name: "partial selection closes over nested dependencies",
|
name: "partial selection closes over nested dependencies",
|
||||||
configured: map[string]config.ScriptoriumArtifactConfig{
|
configured: map[string]config.ScriptoriumArtifactConfig{
|
||||||
|
|||||||
Reference in New Issue
Block a user