narratio/docs/internal/artifacts.md

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.