81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# Internal: Artifacts
|
|
|
|
## Purpose
|
|
Describe supported session artifact IDs, transcript tiers, and artifact resolution/provenance behavior used by stage logic and Scriptorium input configuration.
|
|
|
|
## Inputs and outputs
|
|
Inputs:
|
|
- Artifact source identifiers from stage config/runtime (for example `pipeline.scriptorium.artifacts.*.inputs.*.source`).
|
|
- Session paths and optional session manifest stage outputs.
|
|
|
|
Outputs:
|
|
- Resolved local artifact path + provenance (`ResolvedSessionArtifact`).
|
|
- Validation errors for unsupported or unreadable artifact sources.
|
|
|
|
## Boundaries
|
|
Owns:
|
|
- Canonical artifact ID registry and metadata (`internal/artifacts/artifact_resolver.go`).
|
|
- Alias normalization for legacy source names.
|
|
- Resolution order and artifact content validation.
|
|
|
|
Does not own:
|
|
- Artifact generation (stages produce files).
|
|
- Manifest transition policy.
|
|
- Remote archive publishing behavior.
|
|
|
|
## Config fields used
|
|
Artifact source usage is driven by:
|
|
- `pipeline.scriptorium.artifacts.<name>.inputs.<key>.source`
|
|
- Optional source-specific fields for previous artifact input (`artifact`, `path`, `required`).
|
|
|
|
## External adapters used
|
|
- No external service adapters.
|
|
- Resolver relies on local filesystem checks + session manifest state.
|
|
|
|
## State and manifest behavior
|
|
Supported canonical IDs and current mappings:
|
|
|
|
| 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` |
|
|
| `narratio.artifact.session_recap` | `artifacts/session_recap.md` | `analyze` | `session_recap` |
|
|
|
|
Resolution order:
|
|
1. Session manifest producer-stage outputs (if readable/valid).
|
|
2. Canonical session path fallback.
|
|
|
|
Provenance fields:
|
|
- `ProducerStage`
|
|
- `OutputKind`
|
|
- `ProducerRunID` (when resolved from manifest output)
|
|
- `Provenance` (`manifest.<stage>.outputs` or `fallback.canonical_path`)
|
|
|
|
Content validation by artifact type:
|
|
- Transcript artifacts: JSON with top-level `segments` array.
|
|
- `narratio.bounds.session`: valid JSON.
|
|
- `narratio.artifact.session_recap`: non-empty text.
|
|
|
|
## Skip and resume behavior
|
|
- Resolver has no direct skip/resume logic.
|
|
- Resolver output influences stage behavior (for example analyze input resolution and required-input failures).
|
|
|
|
## Failure behavior
|
|
- Unsupported or empty artifact source -> normalization error.
|
|
- Known source not found/readable -> `ErrSessionArtifactNotFound` wrapped error.
|
|
- Found but invalid content -> validation error.
|
|
|
|
## Tests to inspect before changing
|
|
- `internal/artifacts/artifact_resolver_test.go`
|
|
- `internal/artifacts/resolve_test.go`
|
|
- `internal/stage/analyze_test.go`
|
|
- `internal/config/scriptorium_test.go`
|
|
|
|
## Architectural invariants
|
|
- Artifact IDs are canonical interface values for stage/config integration.
|
|
- Alias support is compatibility behavior layered on top of canonical IDs.
|
|
- Manifest producer outputs are preferred over canonical fallback when both exist.
|