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:

Session manifest producer-stage outputs (if readable/valid).
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.

3.3 KiB Raw Blame History