107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# Internal: Artifacts
|
|
|
|
## Purpose
|
|
Define Narratio artifact identity, catalog, and source-resolution behavior for:
|
|
- built-in session artifacts;
|
|
- configured analyze artifacts;
|
|
- canonical previous-session artifact sources.
|
|
|
|
## Inputs and outputs
|
|
Inputs:
|
|
- configured input sources (`pipeline.scriptorium.artifacts.*.inputs.*.source`);
|
|
- session paths and manifest inputs/outputs;
|
|
- runtime catalog state.
|
|
|
|
Outputs:
|
|
- resolved artifact path + provenance (`ResolvedSessionArtifact`);
|
|
- runtime catalog entries for built-ins and configured artifacts;
|
|
- requirement sets for canonical previous-session inputs.
|
|
- canonical S3 session, run, current, session config, session locks, audio, and promoted artifact keys.
|
|
|
|
## Boundaries
|
|
Owns:
|
|
- built-in source registry and validation;
|
|
- configured artifact catalog identity (`narratio.artifact.<name>`);
|
|
- canonical previous-session source parsing and resolution;
|
|
- previous-session requirement collection (`CollectPreviousArtifactRequirements`).
|
|
|
|
Does not own:
|
|
- prepare-stage remote hydration;
|
|
- stage success/skip transitions;
|
|
- archive upload orchestration.
|
|
|
|
## Built-in IDs
|
|
| Artifact ID | Canonical file | Producer stage | Output kind |
|
|
| --- | --- | --- | --- |
|
|
| `narratio.transcript.merged` | `transcripts/merged.json` | `merge` | `transcript_merged` |
|
|
| `narratio.transcript.polished` | `transcripts/processed.json` | `polish` | `transcript_processed` |
|
|
| `narratio.transcript.full` | `transcripts/normalized.json` | `normalize` | `transcript_normalized` |
|
|
| `narratio.transcript.trimmed` | `transcripts/trimmed.json` | `trim` | `transcript_trimmed` |
|
|
| `narratio.bounds.session` | `artifacts/session_bounds.json` | `trim` | `session_bounds` |
|
|
|
|
## Source families
|
|
- built-in: `narratio.transcript.*`, `narratio.bounds.session`
|
|
- configured artifact: `narratio.artifact.<artifact_key>`
|
|
- canonical previous-session artifact: `narratio.previous_session.artifact.<artifact_key>`
|
|
|
|
## S3 key helpers
|
|
- session prefix: `{root_prefix}/campaigns/{campaign}/sessions/{session_id}/`
|
|
- session config: `{session_prefix}/session.yml`
|
|
- session lock store: `{session_prefix}/locks.yml`
|
|
- run prefix: `{session_prefix}/runs/{run_id}/`
|
|
- audio prefix: `{session_prefix}/{session.inputs.audio_s3.prefix}`
|
|
- current manifest: `{session_prefix}/current/manifest.json`
|
|
- current run pointer: `{session_prefix}/current/run_id.txt`
|
|
|
|
## Runtime catalog model
|
|
Catalog entries track:
|
|
- `planned`: source is registered for this run;
|
|
- `executable`: configured artifact is selected for analyze execution;
|
|
- `available`: usable local file exists (generated this run or reused from disk).
|
|
|
|
Configured artifact provenance values include:
|
|
- `generated.current_analyze_run`
|
|
- `filesystem.disabled_artifact_output`
|
|
|
|
Previous-session canonical provenance values include:
|
|
- `manifest.inputs.previous_cache`
|
|
- `current_session.previous_cache`
|
|
|
|
## Resolution behavior
|
|
- Built-ins resolve via manifest producer outputs first, then canonical fallback paths.
|
|
- Configured `narratio.artifact.<name>` sources resolve through catalog availability.
|
|
- Canonical previous-session sources resolve to current-session `previous/` cache candidates derived from configured artifact canonical output paths.
|
|
- Archive-relative configured artifact paths under `artifacts/` are cached without a redundant nested `artifacts/` segment.
|
|
- Previous-session canonical resolution prefers manifest-recorded input paths when present, then filesystem fallback under `previous/artifacts/**`.
|
|
|
|
## Previous-session requirement scanning
|
|
`CollectPreviousArtifactRequirements`:
|
|
- scans enabled configured artifacts only;
|
|
- includes canonical previous-session sources only;
|
|
- deduplicates by artifact key;
|
|
- merges required/optional references (`required` wins);
|
|
- records deterministic sorted source locations for diagnostics.
|
|
|
|
## Validation behavior
|
|
- transcript built-ins: JSON with top-level `segments` array;
|
|
- bounds built-in: valid JSON;
|
|
- configured and previous-session artifact files: non-empty text content.
|
|
|
|
## Failure behavior
|
|
- unsupported source or malformed canonical previous source: validation/resolution error;
|
|
- known source unavailable: `ErrSessionArtifactNotFound`;
|
|
- configured/previous canonical source without catalog: error;
|
|
- resolved invalid file content: validation error.
|
|
|
|
## Tests to inspect before changing
|
|
- `internal/artifacts/artifact_resolver_test.go`
|
|
- `internal/artifacts/catalog_test.go`
|
|
- `internal/artifacts/previous_requirements_test.go`
|
|
- `internal/stage/prepare_previous_test.go`
|
|
- `internal/stage/analyze_test.go`
|
|
|
|
## Architectural invariants
|
|
- Built-in source IDs are static.
|
|
- Configured and previous-session source IDs are artifact-key based and validation-gated.
|
|
- Resolution behavior remains deterministic and manifest-aware.
|