From 74ab9218ff6cec4d5a05f8c387ebb7cb65411f2b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 4 Sep 2026 18:38:11 +0000 Subject: [PATCH] Close analyze checkpointing documentation --- docs/internal/stage-analyze.md | 34 ++++++++++++++++++------------ docs/roadmap/implementation.md | 8 +++---- internal/manifest/analyze_state.go | 4 ++-- 3 files changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index 5f27f62..640e8b8 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -31,12 +31,14 @@ Supported source families: ## Key Behavior - when `pipeline.scriptorium` is absent or no configured artifact is - executable, completes successfully with no outputs and records explanatory - metadata. This is not an explicit self-skip: the session manifest records success, - satisfy publish's prerequisite, and an ordinary later run reuses the result - while the effective set remains empty. Enabling or selecting an artifact - later makes missing versioned evidence non-resumable and schedules it without - requiring force. + executable, completes successfully and records explanatory metadata. Before + returning, it reconciles and checkpoints the complete session collection: + records removed from configuration are dropped, while valid records for + configured but unselected artifacts remain authoritative. This is not an + explicit self-skip: the session manifest records success, satisfies publish's + prerequisite, and an ordinary later run reuses the result while the effective + set remains empty. Enabling or selecting an artifact later makes missing + versioned evidence non-resumable and schedules it without requiring force. - builds a runtime artifact catalog containing built-ins, configured artifacts, and configured extraction lanes. Extraction availability is hydrated only from compatible successful extraction evidence. @@ -95,7 +97,8 @@ Supported source families: - 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 - artifact work; stale unrelated records do not block a partial selection. + artifact work and no removed configuration records require a checkpoint; + stale unrelated records do not block a partial selection. - exposes the typed artifact decision to `session plan`. Planning applies it to a cloned manifest after modeling earlier selected stage transitions, so aggregate run/skip and artifact execute/reuse decisions match the ordinary @@ -184,13 +187,18 @@ Supported source families: - [CLI](../cli.md) owns user-visible artifact selection. - [Scriptorium](../integrations/scriptorium.md) owns the subprocess contract. - Implementation and tests: `internal/stage/analyze.go`, - `internal/stage/analyze_input_identity.go`, `internal/stage/analyze_test.go`, - `internal/stage/analyze_input_identity_test.go`, + `internal/stage/analyze_artifact_execution.go`, + `internal/stage/analyze_execution_state.go`, + `internal/stage/analyze_input_identity.go`, `internal/stage/analyze_fingerprint.go`, + `internal/stage/analyze_reconciliation.go`, `internal/stage/analyze_plan.go`, + `internal/stage/analyze_resume.go`, `internal/stage/analyze_test.go`, + `internal/stage/analyze_checkpoint_test.go`, + `internal/stage/analyze_input_identity_test.go`, `internal/stage/analyze_fingerprint_test.go`, - `internal/stage/analyze_reconciliation.go`, and `internal/stage/analyze_reconciliation_test.go`, - `internal/stage/analyze_plan.go`, `internal/stage/analyze_plan_test.go`, and - `internal/stage/analyze_incremental_execution_test.go`, and + `internal/stage/analyze_plan_test.go`, + `internal/stage/analyze_incremental_execution_test.go`, `internal/stage/analyze_failure_test.go`, - `internal/stage/analyze_resume.go`, and `internal/stage/analyze_resume_test.go` + `internal/stage/analyze_resume_test.go`, and + `internal/app/analyze_checkpoint_recovery_test.go`. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 60db712..45d9769 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -2,10 +2,10 @@ ## Status -Planning document for Workstream 6, **Per-artifact analyze checkpointing and -recovery**, in [`refactoring.md`](refactoring.md). Workstreams 1 through 5 are -complete and are prerequisites for this plan. All stages below are pending and -must be implemented in numerical order. +Completed implementation record for Workstream 6, **Per-artifact analyze +checkpointing and recovery**, in [`refactoring.md`](refactoring.md). Workstreams +1 through 6 and all stages below are complete. Workstream 7 is the next pending +workstream; its implementation is outside this plan. The purpose of this workstream is to make analyze a deterministic resumable artifact queue backed only by the session manifest. If artifacts A and B diff --git a/internal/manifest/analyze_state.go b/internal/manifest/analyze_state.go index 1d7b541..f1b9cda 100644 --- a/internal/manifest/analyze_state.go +++ b/internal/manifest/analyze_state.go @@ -72,8 +72,8 @@ func (s *StageRecord) HasVersionedAnalyzeState() bool { return s != nil && s.Name == "analyze" && s.AnalyzeStateVersion == AnalyzeStateContractVersion } -// ValidateAnalyzeArtifactCollection validates one complete session or -// invocation collection independently of its containing manifest. +// ValidateAnalyzeArtifactCollection validates one complete session collection +// independently of its containing manifest. func ValidateAnalyzeArtifactCollection(version int, records map[string]AnalyzeArtifactRecord) error { if version != AnalyzeStateContractVersion { return fmt.Errorf("unsupported analyze state version %d", version)