Scriptum Service Overview
Last validated: 2026-05-11
Scriptum is a multi-tenant workflow orchestrator for .scriptum DSL programs.
It provides:
- Script authoring lifecycle (draft, compile, test, publish, rollback)
- Durable thread execution with step-level telemetry
- Pause/resume support for human-in-the-loop steps (
ask) - Tool invocation across native tools, Ignite-backed tools, and internal model primitives
Scriptum currently runs as two binaries:
scriptum-api: gRPC control plane and metadata APIsscriptum-worker: async execution worker consuming NATS JetStream jobs
Core Concepts
Script
A named tenant-scoped workflow definition with metadata and version history.
Draft
Mutable in-progress script state (dsl_content, compiled YAML IR, diagnostics, contract).
Version
Immutable published snapshot of a script. One version is active at a time.
Thread
One execution instance of a script version, identified by thread_id.
Step
A single IR primitive execution unit with input/output records and status.
Tenant Env
Tenant-level key-value env store (tenants/{org_id}/env.json).
Script Env Overlay
Per-script env overlay (tenants/{org_id}/scripts/{name}/env.json) merged over tenant env with empty-defers semantics.
Template
Read-only preloaded .scriptum source available through template APIs.
Runtime Surface Areas
| Area | What it does | Current shape |
|---|---|---|
| Script lifecycle | Create/get/list/delete scripts and manage versions | Implemented in API |
| Thread lifecycle | Create/list/get/resume/watch threads | Implemented except cancel |
| Results | Get thread summary/details and stream large payloads | Implemented except artifacts listing |
| Env management | Tenant env CRUD/import plus per-script overlay APIs | Implemented in API |
| Tool catalog | List tools available to tenant | List implemented; register/get unimplemented |
| Templates | List and fetch preloaded templates | Implemented in API |
Script Lifecycle At A Glance
CreateScript: create metadata shell (optionally from template).SaveScriptDraft: store DSL or YAML draft.CompileScriptDraft: compile DSL to YAML IR and contract.TestScriptDraft: schedule a draft test thread.PublishScriptDraft: create immutable active version.CreateThread: execute active or specified version.RollbackScript: switch active version to a superseded one.
Thread Lifecycle At A Glance
- API validates script version, input contract, and required env availability.
- API writes pending thread metadata and publishes a NATS job.
- Worker executes the compiled steps and emits events.
- Worker persists step records and terminal output (inline or spilled to storage).
- API exposes status/events/results through get/list/watch/stream RPCs.
- GC later removes expired terminal threads and related artifacts.
What Scriptum Is Not
- Not a direct REST HTTP app in this repository. Contract has HTTP annotations, but runtime here is gRPC plus health/metrics HTTP endpoints.
- Not a full tool marketplace yet. Tool registration/get APIs are present in contract but not implemented.
- Not complete parity across all declared primitives and contract knobs. Some primitives and request fields have partial behavior (tracked in feature status doc).
Primary Integrations
- NATS JetStream: job dispatch and event stream replay.
- S3-compatible storage: script registry objects, step records, context snapshots, large outputs.
- Ignite: runtime tool/model execution backend.
- IAM (optional but default-enabled in code): script resource registration for authorization flows.
- Service discovery (optional): endpoint registration and IAM endpoint lookup.