65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
# Integration: scriptorium
|
|
|
|
## Purpose
|
|
Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations.
|
|
|
|
## Inputs and Outputs
|
|
Inputs:
|
|
- `RunArtifactRequest`: binary, config path, prompt/profile IDs, input map, vars map, timeout, output path, logs/config paths, optional API env and working dir
|
|
- `RenderArtifactRequest`: same core fields for render mode
|
|
|
|
Outputs (`ArtifactResult`):
|
|
- output path
|
|
- stdout/stderr log paths
|
|
- generated config path
|
|
- exit code and duration
|
|
- command mode (`run` or `render`)
|
|
- prompt/profile provenance
|
|
- validation failure signal
|
|
- adapter metadata
|
|
|
|
## Boundaries
|
|
Owns:
|
|
- Deterministic CLI arg construction for `scriptorium run` and `scriptorium render`
|
|
- Common request validation
|
|
- Invocation config emission
|
|
- Output existence/non-empty checks
|
|
- Validation-failure mapping for run exit code 2
|
|
|
|
Does not own:
|
|
- Artifact selection policy (`analyze` stage)
|
|
- Bounds semantic validation (`trim` stage)
|
|
|
|
## Config Fields Used
|
|
Via `pipeline.scriptorium.*` and stage-level artifact config:
|
|
- `binary`, `config_path`, `timeout`, `render_debug`
|
|
- artifact-level `prompt_id`, `profile_id`, `timeout`, `inputs`, `vars`, `output_path`
|
|
|
|
## External Adapters Used
|
|
- Shared subprocess helper (`internal/adapters/subprocess`).
|
|
|
|
## State and Manifest Behavior
|
|
- No direct manifest writes.
|
|
- Stage metadata records adapter outputs and command mode.
|
|
- Generated invocation YAML is written when requested.
|
|
|
|
## Skip and Resume Behavior
|
|
- Adapter has no skip/resume logic. Stage/runner controls execution.
|
|
|
|
## Failure Behavior
|
|
- Request validation fails for missing binary/prompt/output, invalid timeout, invalid input/var names, or missing required API env var.
|
|
- Subprocess errors bubble with command context.
|
|
- `run` exit code 2 is treated as `ValidationFailed=true` and surfaced as error by calling stage.
|
|
- Successful subprocess still fails if output file is missing/empty.
|
|
|
|
## Tests to Inspect Before Changing
|
|
- `internal/adapters/scriptorium/subprocess_test.go`
|
|
- `internal/adapters/scriptorium/fake_test.go`
|
|
- `internal/stage/analyze_test.go`
|
|
- `internal/stage/trim_test.go`
|
|
|
|
## Architectural Invariants
|
|
- Both modes require explicit timeout > 0.
|
|
- Input/var maps are sorted into deterministic CLI argument order.
|
|
- Run-mode validation failures are represented explicitly, not silently skipped.
|