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 and Previous-Session Sources

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

Both formats are validated by strict source-policy rules.

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.

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:

• LoadCurrentRunPointer
• LoadCurrentManifest
• LoadCurrentState
• ValidateCurrentStateIdentity

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.

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;
• 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
• 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/current_state_test.go, internal/artifacts/paths_model_test.go, internal/artifacts/previous_requirements_test.go