2026-05-18 22:03:59 -05:00
|
|
|
# Stage: analyze
|
|
|
|
|
|
|
|
|
|
## Purpose
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
Execute selected configured Scriptorium artifacts in dependency order and materialize outputs.
|
|
|
|
|
|
|
|
|
|
## Inputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- configured artifacts from `pipeline.scriptorium.artifacts`
|
2026-08-09 21:50:21 +00:00
|
|
|
- optional selected artifact keys supplied through the stage environment
|
2026-05-23 12:57:59 +00:00
|
|
|
- built-in/configured/previous-session source references in artifact inputs
|
|
|
|
|
|
|
|
|
|
Supported source families:
|
|
|
|
|
- built-ins: `narratio.transcript.*`, `narratio.bounds.session`
|
2026-08-09 21:50:21 +00:00
|
|
|
- prepared stable inputs: `narratio.input.players`, `narratio.input.party`,
|
|
|
|
|
`narratio.input.glossary`
|
2026-05-23 12:57:59 +00:00
|
|
|
- configured artifacts: `narratio.artifact.<key>`
|
|
|
|
|
- previous-session cache: `narratio.previous_session.artifact.<key>`
|
|
|
|
|
|
|
|
|
|
## Outputs
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- one materialized output per executed configured artifact (`output_path`)
|
|
|
|
|
- stage metadata describing selected/generated/reused artifacts
|
|
|
|
|
|
|
|
|
|
## Key Behavior
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- skips with metadata when Scriptorium config is missing or no executable artifacts remain.
|
|
|
|
|
- builds runtime artifact catalog (built-ins + configured artifacts).
|
|
|
|
|
- marks non-executable configured artifacts as reusable when output files already exist.
|
|
|
|
|
- validates selected artifact dependency order (cycle-safe topo ordering).
|
|
|
|
|
- resolves required/optional inputs per artifact source definition.
|
2026-05-27 09:34:05 -05:00
|
|
|
- resolves prepared stable input sources from `inputs/*.yml` materialized by `prepare`.
|
2026-05-23 12:57:59 +00:00
|
|
|
- resolves previous-session sources from local `previous/` cache only.
|
|
|
|
|
- runs optional render-debug, then artifact execution.
|
|
|
|
|
- validates non-empty output files and materializes canonical outputs.
|
|
|
|
|
|
|
|
|
|
## Failure Semantics
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- required missing configured/previous-session inputs fail.
|
2026-05-27 09:34:05 -05:00
|
|
|
- missing required prepared stable input source includes prepare rerun guidance.
|
2026-05-23 12:57:59 +00:00
|
|
|
- missing required previous-session source includes prepare rerun guidance.
|
2026-08-09 21:50:21 +00:00
|
|
|
- missing required `narratio.transcript.final_markdown` or
|
|
|
|
|
`narratio.transcript.final_trimmed_markdown` inputs includes render rerun
|
|
|
|
|
guidance.
|
2026-05-23 12:57:59 +00:00
|
|
|
- dependency cycles or unavailable required dependencies fail.
|
|
|
|
|
- adapter validation failures fail stage.
|
|
|
|
|
|
|
|
|
|
## Invariants
|
2026-08-09 21:50:21 +00:00
|
|
|
|
2026-05-23 12:57:59 +00:00
|
|
|
- `analyze` performs no remote storage calls for previous-session source resolution.
|
|
|
|
|
- output provenance and metadata are deterministic per execution.
|
2026-08-09 21:50:21 +00:00
|
|
|
|
|
|
|
|
## Related Contracts And Tests
|
|
|
|
|
|
|
|
|
|
- [Configuration](../config.md#scriptorium-artifact-entries) owns artifact
|
|
|
|
|
fields and source-selection rules.
|
|
|
|
|
- [CLI](../cli.md) owns user-visible artifact selection.
|
|
|
|
|
- [Scriptorium](../integrations/scriptorium.md) owns the subprocess contract.
|
|
|
|
|
- Implementation and tests: `internal/stage/analyze.go`,
|
|
|
|
|
`internal/stage/analyze_test.go`
|
