116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# 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.transcript.final_markdown` -> `transcripts/final.md` (`render`)
|
|
- `narratio.transcript.final_trimmed_markdown` -> `transcripts/final.trimmed.md` (`render`)
|
|
- `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 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/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.
|