narratio/docs/integrations/scriptorium.md

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.