narratio/docs/internal/artifacts.md

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.

Inputs and outputs

Inputs:

• configured input sources (pipeline.scriptorium.artifacts.*.inputs.*.source);
• session paths and manifest inputs/outputs;
• runtime catalog state.

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 promoted artifact keys.

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).

Does not own:

• prepare-stage remote hydration;
• stage success/skip transitions;
• archive upload orchestration.

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:

• 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.
• Archive-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/**.

Previous-session requirement scanning

CollectPreviousArtifactRequirements:

• scans enabled configured artifacts only;
• includes canonical previous-session sources only;
• deduplicates by artifact key;
• merges required/optional references (required wins);
• records deterministic sorted source locations for diagnostics.

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.

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.