Rewrite internal documentation for current stage and state contracts

docs/internal/artifacts.md

@@ -1,106 +1,68 @@
 # Internal: Artifacts
 
 ## Purpose
-Define Narratio artifact identity, catalog, and source-resolution behavior for:
-- built-in session artifacts;
-- configured analyze artifacts;
-- canonical previous-session artifact sources.
+Define canonical artifact IDs, runtime catalog behavior, and source resolution rules for stage execution and publish output selection.
 
-## Inputs and outputs
-Inputs:
-- configured input sources (`pipeline.scriptorium.artifacts.*.inputs.*.source`);
-- session paths and manifest inputs/outputs;
-- runtime catalog state.
+## Built-in Source IDs
+- `narratio.transcript.base` -> `transcripts/base.json` (`merge`)
+- `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`)
+- `narratio.transcript.final` -> `transcripts/final.json` (`normalize`)
+- `narratio.transcript.final_trimmed` -> `transcripts/final.trimmed.json` (`trim`)
+- `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)
 
-Outputs:
-- resolved artifact path + provenance (`ResolvedSessionArtifact`);
-- runtime catalog entries for built-ins and configured artifacts;
-- requirement sets for canonical previous-session inputs;
-- canonical S3 session, run, current, session config, session locks, audio, and published output keys.
+## Configured and Previous-Session Sources
+- Configured artifact source ID: `narratio.artifact.<artifact_key>`
+- Previous-session source ID: `narratio.previous_session.artifact.<artifact_key>`
 
-## Boundaries
-Owns:
-- 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`).
+Configured and previous-session source IDs are validated by strict regex rules.
 
-Does not own:
-- prepare-stage remote hydration;
-- stage success/skip transitions;
-- publish upload orchestration.
+## Runtime Catalog
+`ArtifactCatalog` tracks:
+- `planned`: source registered for run context.
+- `executable`: selected and enabled for analyze execution.
+- `available`: local file exists and validated.
+- `provenance`: availability source.
 
-## Built-in IDs
-| Artifact ID | Canonical file | Producer stage | Output kind |
-| --- | --- | --- | --- |
-| `narratio.transcript.base` | `transcripts/base.json` | `merge` | `transcript_base` |
-| `narratio.transcript.polished` | `transcripts/polished.json` | `polish` | `transcript_polished` |
-| `narratio.transcript.final` | `transcripts/final.json` | `normalize` | `transcript_final` |
-| `narratio.transcript.final_trimmed` | `transcripts/final.trimmed.json` | `trim` | `transcript_final_trimmed` |
-| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
-
-## 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>`
-
-## S3 key helpers
-- session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
-- session config: `{session_prefix}/session.yml`
-- session lock store: `{session_prefix}/locks.yml`
-- run prefix: `{session_prefix}/runs/{run_id}/`
-- audio prefix: `{session_prefix}/{session.inputs.audio_s3.prefix}`
-- current manifest: `{session_prefix}/current/manifest.json`
-- current run pointer: `{session_prefix}/current/run_id.txt`
-
-## 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).
-
-Configured artifact provenance values include:
+Current provenance values:
 - `generated.current_analyze_run`
 - `filesystem.disabled_artifact_output`
-
-Previous-session canonical provenance values include:
 - `manifest.inputs.previous_cache`
 - `current_session.previous_cache`
 
-## 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.
-- Publish-relative configured artifact paths under `artifacts/` are cached without a redundant nested `artifacts/` segment.
-- Previous-session canonical resolution prefers manifest-recorded input paths when present, then filesystem fallback under `previous/artifacts/**`.
+## Resolution Rules
+Built-ins:
+1. manifest producer outputs (when present)
+2. canonical session path fallback
 
-## Previous-session requirement scanning
+Configured sources (`narratio.artifact.*`):
+- resolve only through runtime catalog availability.
+
+Previous-session sources (`narratio.previous_session.artifact.*`):
+- resolve only from local `previous/` cache state.
+- prefer manifest-backed previous input paths.
+- fallback to existing previous-cache filesystem paths.
+
+Validation by content type:
+- transcript built-ins: JSON with top-level `segments` array.
+- bounds built-in: valid JSON.
+- configured/previous-session artifact files: non-empty text file.
+
+## Previous Requirement Collection
 `CollectPreviousArtifactRequirements`:
 - scans enabled configured artifacts only;
-- includes canonical previous-session sources only;
+- extracts only canonical previous-session sources;
 - deduplicates by artifact key;
-- merges required/optional references (`required` wins);
-- records deterministic sorted source locations for diagnostics.
+- merges required/optional (required wins);
+- returns deterministic ordering and source locations.
 
-## 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.
+## Key Path Helpers
+`internal/artifacts/paths.go` defines canonical helpers for:
+- session/work/run paths;
+- previous-cache paths;
+- spool/cache paths;
+- S3 key layout helpers for session/run/current pointers.
 
-## Failure behavior
-- 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`
-
-## Architectural invariants
-- 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.
+## Invariants
+- Source ID formats are stable contracts.
+- Resolution is deterministic and manifest-aware.
+- Previous-session source resolution does not call remote storage in `analyze`; remote hydration is `prepare` responsibility.