narratio/docs/internal/artifacts.md

Internal: Artifacts

Purpose

Explain the artifact registry, runtime catalog, resolver, previous-input requirements, and shared remote current-state mechanics implemented by internal/artifacts. Configuration fields that accept source IDs belong in Configuration; physical placement belongs in Operations.

Built-in Source IDs

The internal registry recognizes these stable built-in source IDs:

• narratio.transcript.base
• narratio.transcript.polished
• narratio.transcript.final
• narratio.transcript.final_trimmed
• narratio.transcript.final_markdown
• narratio.transcript.final_trimmed_markdown
• narratio.bounds.session

Registry entries bind each ID to its producer, output kind, canonical fallback, and content validator. The focused stage documents own their input/output flow; Configuration owns where operators may select these IDs.

Configured, Extraction, And Previous-Session Sources

• configured source ID format: narratio.artifact.<artifact_key>
• extraction source ID format: narratio.extraction.<output_key>
• previous-session source ID format: narratio.previous_session.artifact.<artifact_key>

All formats are validated by strict source-policy rules. Configured artifact and extraction keys use ^[a-z][a-z0-9_]*$; source parsers never normalize an unrecognized token into a valid source. Extraction sources are registered only from pipeline.notarius.outputs; the Notarius index has no selectable source ID.

Runtime Catalog

ArtifactCatalog tracks:

• planned: source registered for run context;
• executable: selected and enabled for analyze execution;
• available: local file exists and validates;
• provenance: availability source.

Current provenance values:

• generated.current_analyze_run
• filesystem.disabled_artifact_output
• manifest.inputs.previous_cache
• current_session.previous_cache

Resolution Rules

Built-ins:

1. manifest producer outputs (when present)
2. canonical session-path fallback

Configured sources (narratio.artifact.*):

• resolve only through runtime catalog availability.

Extraction sources (narratio.extraction.*):

• use the shared registration and manifest hydration path in extraction_catalog.go;
• require a current successful extract record with the exact configured source, compatible contract and Notarius provenance, a confined regular durable payload, and matching checksum; and
• are never inferred by scanning the Notarius bundle directory.

Previous-session sources (narratio.previous_session.artifact.*):

• resolve only from local previous/ cache state;
• prefer manifest-backed previous-input paths;
• fallback to existing previous-cache filesystem paths.

Validation by content type:

• transcript JSON built-ins: JSON with top-level segments array;
• transcript Markdown built-ins: non-empty text file;
• bounds built-in: valid JSON;
• configured/previous-session artifact files: non-empty text file.

Previous Requirement Collection

CollectPreviousArtifactRequirements:

• scans enabled configured artifacts only;
• extracts only canonical previous-session sources;
• deduplicates by artifact key;
• merges required and optional references (required wins);
• returns deterministic ordering and source locations.

Current-State Helpers

Artifacts package owns shared remote current-state loading mechanics used by restore, status and validation checks, and previous-cache planning.

Core helpers:

• LoadCurrentState
• ValidateCurrentStateIdentity
• RemoteCommitManifest and CurrentCommitPointer

Typed missing-state errors:

• CurrentRunPointerMissingError (ErrCurrentRunPointerMissing)
• CurrentManifestMissingError (ErrCurrentManifestMissing)

Identity validation supports caller-provided expectations:

• expected campaign;
• expected session ID;
• expected run ID, or pointer/manifest run-ID consistency check.

Caller policy is intentionally outside artifacts helpers:

• some callers fail on missing current state;
• some callers downgrade missing state to status/findings;
• some callers skip optional behavior when state is missing.

Key Path Helpers

internal/artifacts/paths.go and S3-key helpers define canonical helpers for:

• session/work/run paths;
• previous-cache paths;
• spool/cache paths;
• S3 session/run/current-state key layout.

New publication creates run-scoped immutable objects, including runs/{run_id}/commit.json and runs/{run_id}/session-manifest.json. The sole mutable selector is current/commit-pointer.json; readers verify its selected commit and declared object generations/checksums. Legacy current-pair loading is confined to current_state_legacy.go for migration only.

Campaign, session, and Narratio run IDs are validated as portable opaque segments at configuration and artifact boundaries before they can be used in a workspace or S3 namespace. Previous-artifact destinations remain typed, multi-segment relative paths and are confined beneath previous/artifacts; they are not treated as opaque identifiers.

See Workspace Internals for how callers consume local helpers and Operations for the authoritative physical layout.

Invariants

• source ID formats are stable contracts;
• artifact resolution is deterministic and manifest-aware;
• extraction sources are available only from a compatible successful manifest record;
• previous-session source resolution in analyze is local-only;
• remote current-state key construction remains centralized in artifacts helpers.

Implementation And Tests

• Registry and resolution: internal/artifacts/artifact_resolver.go, internal/artifacts/catalog.go, internal/artifacts/transcripts.go, internal/artifacts/extraction_catalog.go
• Current state: internal/artifacts/current_state.go
• Paths and keys: internal/artifacts/paths.go, internal/artifacts/s3_keys.go
• Previous requirements: internal/artifacts/previous_requirements.go
• Tests: internal/artifacts/artifact_resolver_test.go, internal/artifacts/catalog_test.go, internal/artifacts/extraction_catalog_test.go, internal/artifacts/current_state_test.go, internal/artifacts/paths_model_test.go, internal/artifacts/previous_requirements_test.go