narratio/docs/internal/artifacts.md

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

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.