Internal: Artifacts

Purpose

Define Narratio's artifact identity and resolution model for built-in transcript/bounds artifacts and runtime-configured analyze artifacts.

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

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

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

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:

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`

Runtime catalog entries include built-ins and configured narratio.artifact.<name> sources.

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)

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:

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

Skip and resume behavior

resolver and catalog have no direct skip/resume decisions
stage/runner skip-resume behavior consumes catalog/resolver results

Failure behavior

unsupported source -> source validation error
known source unavailable -> ErrSessionArtifactNotFound
configured source without catalog -> resolution error
resolved file with invalid content -> validation error

Tests to inspect before changing

internal/artifacts/artifact_resolver_test.go
internal/artifacts/catalog_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

3.5 KiB Raw Blame History