Added new internal documentation

docs/internal/artifacts.md

@@ -0,0 +1,85 @@
+# Internal: Artifacts
+
+## Purpose
+Describe supported session artifact IDs, transcript tiers, and artifact resolution/provenance behavior used by stage logic and Scriptorium input configuration.
+
+## Inputs and outputs
+Inputs:
+- Artifact source identifiers from stage config/runtime (for example `pipeline.scriptorium.artifacts.*.inputs.*.source`).
+- Session paths and optional session manifest stage outputs.
+
+Outputs:
+- Resolved local artifact path + provenance (`ResolvedSessionArtifact`).
+- Validation errors for unsupported or unreadable artifact sources.
+
+## Boundaries
+Owns:
+- Canonical artifact ID registry and metadata (`internal/artifacts/artifact_resolver.go`).
+- Alias normalization for legacy source names.
+- Resolution order and artifact content validation.
+
+Does not own:
+- Artifact generation (stages produce files).
+- Manifest transition policy.
+- Remote archive publishing behavior.
+
+## Config fields used
+Artifact source usage is driven by:
+- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
+- Optional source-specific fields for previous artifact input (`artifact`, `path`, `required`).
+
+## External adapters used
+- No external service adapters.
+- Resolver relies on local filesystem checks + session manifest state.
+
+## State and manifest behavior
+Supported canonical IDs and current mappings:
+
+| Artifact ID | Canonical file | Producer stage | Output kind |
+| --- | --- | --- | --- |
+| `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
+| `narratio.transcript.polished` | `transcripts/processed.json` | `polish` | `transcript_processed` |
+| `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
+| `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
+| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
+| `narratio.artifact.session_recap` | `artifacts/session_recap.md` | `analyze` | `session_recap` |
+
+Legacy aliases normalized by resolver:
+- `processed_transcript` -> `narratio.transcript.polished`
+- `normalized_transcript` -> `narratio.transcript.full`
+- `trimmed_transcript` -> `narratio.transcript.trimmed`
+
+Resolution order:
+1. Session manifest producer-stage outputs (if readable/valid).
+2. Canonical session path fallback.
+
+Provenance fields:
+- `ProducerStage`
+- `OutputKind`
+- `ProducerRunID` (when resolved from manifest output)
+- `Provenance` (`manifest.<stage>.outputs` or `fallback.canonical_path`)
+
+Content validation by artifact type:
+- Transcript artifacts: JSON with top-level `segments` array.
+- `narratio.bounds.session`: valid JSON.
+- `narratio.artifact.session_recap`: non-empty text.
+
+## Skip and resume behavior
+- Resolver has no direct skip/resume logic.
+- Resolver output influences stage behavior (for example analyze input resolution and required-input failures).
+
+## Failure behavior
+- Unsupported or empty artifact source -> normalization error.
+- Known source not found/readable -> `ErrSessionArtifactNotFound` wrapped error.
+- Found but invalid content -> validation error.
+
+## Tests to inspect before changing
+- `internal/artifacts/artifact_resolver_test.go`
+- `internal/artifacts/resolve_test.go`
+- `internal/stage/analyze_test.go`
+- `internal/config/scriptorium_test.go`
+
+## Architectural invariants
+- Artifact IDs are canonical interface values for stage/config integration.
+- Alias support is compatibility behavior layered on top of canonical IDs.
+- Manifest producer outputs are preferred over canonical fallback when both exist.