88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# Internal: Artifacts
|
|
|
|
## Purpose
|
|
Define Narratio's artifact identity and resolution model for built-in transcript/bounds artifacts and runtime-configured analyze artifacts.
|
|
|
|
## Inputs and outputs
|
|
Inputs:
|
|
- artifact sources from config/runtime (`pipeline.scriptorium.artifacts.*.inputs.*.source`)
|
|
- session paths and optional session manifest stage outputs
|
|
- runtime artifact catalog state for configured artifact sources
|
|
|
|
Outputs:
|
|
- resolved local artifact path and provenance (`ResolvedSessionArtifact`)
|
|
- runtime catalog entries for planned/executable/available artifacts
|
|
- validation errors for unsupported, missing, or invalid artifact sources
|
|
|
|
## Boundaries
|
|
Owns:
|
|
- built-in artifact registry and content validation rules
|
|
- runtime artifact catalog for configured artifact source IDs
|
|
- source resolution behavior for built-in and configured artifact sources
|
|
|
|
Does not own:
|
|
- artifact generation (stages produce files)
|
|
- manifest transition policy
|
|
- archive promotion behavior
|
|
|
|
## Config fields used
|
|
- `pipeline.scriptorium.artifacts.<name>.enabled`
|
|
- `pipeline.scriptorium.artifacts.<name>.output_path`
|
|
- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
|
|
|
|
## External adapters used
|
|
- none
|
|
|
|
## State and manifest behavior
|
|
Built-in registry entries:
|
|
|
|
| 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` |
|
|
|
|
Runtime catalog entries include built-ins and configured `narratio.artifact.<name>` sources.
|
|
|
|
Catalog states:
|
|
- `planned`: source is registered and known for this run
|
|
- `executable`: configured artifact is selected for analyze execution
|
|
- `available`: artifact has a usable file path (generated this run or reused from disk)
|
|
|
|
Resolution behavior:
|
|
- built-in sources resolve via manifest producer outputs first, then canonical fallback path
|
|
- configured `narratio.artifact.<name>` sources resolve through runtime catalog availability
|
|
- configured source lookup requires catalog context
|
|
|
|
Configured artifact provenance values:
|
|
- `generated.current_analyze_run`
|
|
- `filesystem.disabled_artifact_output`
|
|
|
|
Content validation:
|
|
- transcript built-ins: JSON with top-level `segments` array
|
|
- bounds built-in: valid JSON
|
|
- configured artifacts: non-empty text file
|
|
|
|
## Skip and resume behavior
|
|
- resolver and catalog have no direct skip/resume decisions
|
|
- stage/runner skip-resume behavior consumes catalog/resolver results
|
|
|
|
## Failure behavior
|
|
- unsupported source -> source validation error
|
|
- known source unavailable -> `ErrSessionArtifactNotFound`
|
|
- configured source without catalog -> resolution error
|
|
- resolved file with invalid content -> validation error
|
|
|
|
## Tests to inspect before changing
|
|
- `internal/artifacts/artifact_resolver_test.go`
|
|
- `internal/artifacts/catalog_test.go`
|
|
- `internal/stage/analyze_test.go`
|
|
- `internal/config/scriptorium_test.go`
|
|
|
|
## Architectural invariants
|
|
- built-in IDs are static and registry-backed
|
|
- configured artifact IDs are runtime-derived (`narratio.artifact.<name>`) and catalog-backed
|
|
- built-in/source resolution remains deterministic and validation-gated
|