# Internal: Artifacts

## Purpose
Define canonical artifact IDs, runtime catalog behavior, and source resolution rules for stage execution and publish output selection.

## Built-in Source IDs
- `narratio.transcript.base` -> `transcripts/base.json` (`merge`)
- `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`)
- `narratio.transcript.final` -> `transcripts/final.json` (`normalize`)
- `narratio.transcript.final_trimmed` -> `transcripts/final.trimmed.json` (`trim`)
- `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`)

## Configured and Previous-Session Sources
- Configured artifact source ID: `narratio.artifact.<artifact_key>`
- Previous-session source ID: `narratio.previous_session.artifact.<artifact_key>`

Configured and previous-session source IDs are validated by strict regex rules.

## Runtime Catalog
`ArtifactCatalog` tracks:
- `planned`: source registered for run context.
- `executable`: selected and enabled for analyze execution.
- `available`: local file exists and validated.
- `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 built-ins: JSON with top-level `segments` array.
- 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/optional (required wins);
- returns deterministic ordering and source locations.

## Key Path Helpers
`internal/artifacts/paths.go` defines canonical helpers for:
- session/work/run paths;
- previous-cache paths;
- spool/cache paths;
- S3 key layout helpers for session/run/current pointers.

## Invariants
- Source ID formats are stable contracts.
- Resolution is deterministic and manifest-aware.
- Previous-session source resolution does not call remote storage in `analyze`; remote hydration is `prepare` responsibility.