Finalize previous-session artifact documentation and restore-analyze continuity coverage

docs/internal/artifacts.md

@@ -1,41 +1,35 @@
 # Internal: Artifacts
 
 ## Purpose
-Define Narratio's artifact identity and resolution model for built-in transcript/bounds artifacts and runtime-configured analyze artifacts.
+Define Narratio artifact identity, catalog, and source-resolution behavior for:
+- built-in session artifacts;
+- configured analyze artifacts;
+- canonical previous-session artifact sources.
 
 ## Inputs and outputs
 Inputs:
-- artifact sources from config/runtime (`pipeline.scriptorium.artifacts.*.inputs.*.source`)
-- session paths and optional session manifest stage outputs
-- runtime artifact catalog state for configured artifact sources
+- configured input sources (`pipeline.scriptorium.artifacts.*.inputs.*.source`);
+- session paths and manifest inputs/outputs;
+- runtime catalog state.
 
 Outputs:
-- resolved local artifact path and provenance (`ResolvedSessionArtifact`)
-- runtime catalog entries for planned/executable/available artifacts
-- validation errors for unsupported, missing, or invalid artifact sources
+- resolved artifact path + provenance (`ResolvedSessionArtifact`);
+- runtime catalog entries for built-ins and configured artifacts;
+- requirement sets for canonical previous-session inputs.
 
 ## Boundaries
 Owns:
-- built-in artifact registry and content validation rules
-- runtime artifact catalog for configured artifact source IDs
-- source resolution behavior for built-in and configured artifact sources
+- built-in source registry and validation;
+- configured artifact catalog identity (`narratio.artifact.<name>`);
+- canonical previous-session source parsing and resolution;
+- previous-session requirement collection (`CollectPreviousArtifactRequirements`).
 
 Does not own:
-- artifact generation (stages produce files)
-- manifest transition policy
-- archive promotion behavior
-
-## Config fields used
-- `pipeline.scriptorium.artifacts.<name>.enabled`
-- `pipeline.scriptorium.artifacts.<name>.output_path`
-- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
-
-## External adapters used
-- none
-
-## State and manifest behavior
-Built-in registry entries:
+- prepare-stage remote hydration;
+- stage success/skip transitions;
+- archive upload orchestration.
 
+## Built-in IDs
 | Artifact ID | Canonical file | Producer stage | Output kind |
 | --- | --- | --- | --- |
 | `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
@@ -44,44 +38,58 @@ Built-in registry entries:
 | `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
 | `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
 
-Runtime catalog entries include built-ins and configured `narratio.artifact.<name>` sources.
+## Source families
+- built-in: `narratio.transcript.*`, `narratio.bounds.session`
+- configured artifact: `narratio.artifact.<artifact_key>`
+- canonical previous-session artifact: `narratio.previous_session.artifact.<artifact_key>`
 
-Catalog states:
-- `planned`: source is registered and known for this run
-- `executable`: configured artifact is selected for analyze execution
-- `available`: artifact has a usable file path (generated this run or reused from disk)
+## Runtime catalog model
+Catalog entries track:
+- `planned`: source is registered for this run;
+- `executable`: configured artifact is selected for analyze execution;
+- `available`: usable local file exists (generated this run or reused from disk).
 
-Resolution behavior:
-- built-in sources resolve via manifest producer outputs first, then canonical fallback path
-- configured `narratio.artifact.<name>` sources resolve through runtime catalog availability
-- configured source lookup requires catalog context
-
-Configured artifact provenance values:
+Configured artifact provenance values include:
 - `generated.current_analyze_run`
 - `filesystem.disabled_artifact_output`
 
-Content validation:
-- transcript built-ins: JSON with top-level `segments` array
-- bounds built-in: valid JSON
-- configured artifacts: non-empty text file
+Previous-session canonical provenance values include:
+- `manifest.inputs.previous_cache`
+- `current_session.previous_cache`
 
-## Skip and resume behavior
-- resolver and catalog have no direct skip/resume decisions
-- stage/runner skip-resume behavior consumes catalog/resolver results
+## Resolution behavior
+- Built-ins resolve via manifest producer outputs first, then canonical fallback paths.
+- Configured `narratio.artifact.<name>` sources resolve through catalog availability.
+- Canonical previous-session sources resolve to current-session `previous/` cache candidates derived from configured artifact canonical output paths.
+- Previous-session canonical resolution prefers manifest-recorded input paths when present, then filesystem fallback under `previous/artifacts/**`.
+
+## Previous-session requirement scanning
+`CollectPreviousArtifactRequirements`:
+- scans enabled configured artifacts only;
+- includes canonical previous-session sources only;
+- deduplicates by artifact key;
+- merges required/optional references (`required` wins);
+- records deterministic sorted source locations for diagnostics.
+
+## Validation behavior
+- transcript built-ins: JSON with top-level `segments` array;
+- bounds built-in: valid JSON;
+- configured and previous-session artifact files: non-empty text content.
 
 ## Failure behavior
-- unsupported source -> source validation error
-- known source unavailable -> `ErrSessionArtifactNotFound`
-- configured source without catalog -> resolution error
-- resolved file with invalid content -> validation error
+- unsupported source or malformed canonical previous source: validation/resolution error;
+- known source unavailable: `ErrSessionArtifactNotFound`;
+- configured/previous canonical source without catalog: error;
+- resolved invalid file content: validation error.
 
 ## Tests to inspect before changing
 - `internal/artifacts/artifact_resolver_test.go`
 - `internal/artifacts/catalog_test.go`
+- `internal/artifacts/previous_requirements_test.go`
+- `internal/stage/prepare_previous_test.go`
 - `internal/stage/analyze_test.go`
-- `internal/config/scriptorium_test.go`
 
 ## Architectural invariants
-- built-in IDs are static and registry-backed
-- configured artifact IDs are runtime-derived (`narratio.artifact.<name>`) and catalog-backed
-- built-in/source resolution remains deterministic and validation-gated
+- Built-in source IDs are static.
+- Configured and previous-session source IDs are artifact-key based and validation-gated.
+- Resolution behavior remains deterministic and manifest-aware.