narratio/docs/internal/artifacts.md

Internal: Artifacts

Purpose

Define canonical artifact IDs, runtime catalog behavior, source resolution rules, and shared current-state mechanics used by app and previous-cache code.

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 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 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 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/validate 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.

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.