# 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](../config.md); physical placement belongs in
[Operations](../operations.md).

## 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](../config.md) 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](workspace.md) for how callers consume local helpers
and [Operations](../operations.md#local-state-layout) 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`