ScriptContract Appendix

Package: dodil.scriptum.v1 · Service: ScriptumService

The ScriptContract is the canonical, self-describing typed-I/O schema returned for every Script, ScriptVersion, draft (GetDraftInfo), and TemplateInfo. It is the single source of truth for every consumer — UI form generators, K3 pre-validators / ingest routers, and LLM agents all read it once and have everything needed to validate inputs, render forms, and produce well-typed values without re-parsing the DSL source. This is the same typed contract that the Scriptum Language input / output / stream / env blocks compile into.

`ScriptContract`


message ScriptContract {
  repeated TypedField inputs  = 1;
  repeated TypedField outputs = 2;
  repeated TypedField stream  = 3;     // fields a `yield` emits
  repeated TypedField env     = 4;     // declared env keys
  repeated EnumDef    enums   = 5;     // the enum catalog the fields reference
  repeated string accepted_content_types = 6;  // MIME types accepted as input data
  repeated string accepted_extensions    = 7;  // file extensions accepted
}

Field	Type	Notes
`inputs`	`repeated TypedField`	The script’s input parameters.
`outputs`	`repeated TypedField`	The script’s outputs.
`stream`	`repeated TypedField`	The shape of values a `yield` emits during a thread.
`env`	`repeated TypedField`	Environment keys the script declares.
`enums`	`repeated EnumDef`	The enum catalog any `TypeRef.enum_name` resolves against.
`accepted_content_types`	`repeated string`	MIME types this script accepts as input data, declared via `-- @accepts_content_type`. Globs like `image/*` allowed. Empty = unrestricted.
`accepted_extensions`	`repeated string`	Accepted file extensions (canonical lowercase, no leading dot), declared via `-- @accepts_extension`. Empty = unrestricted.

`TypedField`

A named, typed field in inputs / outputs / stream / env.


message TypedField {
  string  name               = 1;
  TypeRef type               = 2;
  string  default_value_json = 3;   // JSON literal; "" means no default
  bool    required           = 4;
  string  description        = 5;   // from the `-- comment` after the field
}

Field	Type	Notes
`name`	`string`	Field name.
`type`	`TypeRef`	The field’s type.
`default_value_json`	`string`	Default as a JSON-encoded literal — `"hi"`, `42`, `0.5`, `true`, `null`, `[1,2]`, `{"k":"v"}`. Empty string means “no default”.
`required`	`bool`	Explicit required flag (redundant with an empty `default_value_json`, but clearer over the wire).
`description`	`string`	From the trailing `-- comment` on the field.

`TypeRef`

A type reference. Exactly one of the kind oneof is populated; the constraint blocks apply only to the matching kind.


message TypeRef {
  oneof kind {
    TypeRefPrimitive primitive = 1;   // text, number, integer, boolean, object, binary, date, timestamp, any
    string           enum_name = 2;   // refers to an entry in ScriptContract.enums
    ListType         list      = 3;   // list<T>
    ObjectShape      object    = 4;   // anonymous record with named typed fields
  }
  NumericConstraints number_constraints = 10;   // when numeric
  StringConstraints  string_constraints = 11;   // when text
  ListConstraints    list_constraints   = 12;   // when list
}
 
message ListType    { TypeRef item = 1; }
message ObjectShape { repeated TypedField fields = 1; }

`kind`	Payload	Meaning
`primitive`	`TypeRefPrimitive`	A built-in scalar/blob type.
`enum_name`	`string`	Name of an `EnumDef` in `ScriptContract.enums`.
`list`	`ListType { TypeRef item }`	`list<T>` — element type on `list.item`; element constraints live on that inner `TypeRef`.
`object`	`ObjectShape { repeated TypedField fields }`	An anonymous record of named typed fields.

`TypeRefPrimitive`


enum TypeRefPrimitive {
  TYPE_REF_PRIMITIVE_UNSPECIFIED = 0;
  TYPE_REF_PRIMITIVE_TEXT        = 1;
  TYPE_REF_PRIMITIVE_NUMBER      = 2;  // float / double
  TYPE_REF_PRIMITIVE_INTEGER     = 3;
  TYPE_REF_PRIMITIVE_BOOLEAN     = 4;
  TYPE_REF_PRIMITIVE_OBJECT      = 5;  // untyped object — escape hatch
  TYPE_REF_PRIMITIVE_BINARY      = 6;
  TYPE_REF_PRIMITIVE_DATE        = 7;
  TYPE_REF_PRIMITIVE_TIMESTAMP   = 8;
  TYPE_REF_PRIMITIVE_ANY         = 9;  // unspecified / value
}

Constraints

Constraint blocks are optional and populated only where they apply for the TypeRef’s kind. Bounds use optional so “unset” is distinguishable from a zero bound.


// Applied when the underlying type is numeric (integer or number).
message NumericConstraints {
  optional double minimum       = 1;
  optional double maximum       = 2;
  bool            exclusive_min = 3;
  bool            exclusive_max = 4;
  optional double multiple_of   = 5;
}
 
// Applied when the underlying type is text.
message StringConstraints {
  optional uint32 min_length = 1;
  optional uint32 max_length = 2;
  optional string pattern    = 3;   // ECMA-262 regex syntax
}
 
// Applied when the underlying type is a list (element constraints live on list.item).
message ListConstraints {
  optional uint32 min_items    = 1;
  optional uint32 max_items    = 2;
  bool            unique_items = 3;
}

`EnumDef`

The declared enum catalog. base controls how a variant’s value serializes on the wire; each EnumVariant populates exactly one value_* matching the base.


enum EnumBase {
  ENUM_BASE_UNSPECIFIED = 0;
  ENUM_BASE_TEXT        = 1;   // wire values are strings
  ENUM_BASE_INTEGER     = 2;   // wire values are signed 64-bit integers
  ENUM_BASE_NUMBER      = 3;   // wire values are doubles
}
 
message EnumDef {
  string               name     = 1;
  EnumBase             base     = 2;
  repeated EnumVariant variants = 3;
}
 
message EnumVariant {
  oneof value {
    string value_text    = 1;
    int64  value_integer = 2;
    double value_number  = 3;
  }
  string description = 4;       // optional per-variant docs
}

A field is an enum when its TypeRef.kind is enum_name, pointing at one of these EnumDef.names.

Service enums

These enums appear across the request/response messages on the other pages.

`ScriptStatus`

Script lifecycle. Appears on Script.status.


enum ScriptStatus {
  SCRIPT_STATUS_UNSPECIFIED = 0;
  SCRIPT_STATUS_CREATED = 1;    // metadata only, no versions yet
  SCRIPT_STATUS_DRAFT = 2;      // has a draft in progress, no published version
  SCRIPT_STATUS_ACTIVE = 3;     // at least one published version
  SCRIPT_STATUS_DISABLED = 4;   // paused by user — no new threads can be created
  SCRIPT_STATUS_ARCHIVED = 5;   // long idle, kept for history
}

`ScriptVersionStatus`

Version / draft state. Appears on Script.draft_status, ScriptVersion.status, SaveScriptDraftResponse, GetScriptCodeResponse, and GetDraftInfoResponse.


enum ScriptVersionStatus {
  SCRIPT_VERSION_STATUS_UNSPECIFIED = 0;
  SCRIPT_VERSION_STATUS_DRAFT = 1;
  SCRIPT_VERSION_STATUS_COMPILING = 2;
  SCRIPT_VERSION_STATUS_COMPILED = 3;
  SCRIPT_VERSION_STATUS_ACTIVE = 4;
  SCRIPT_VERSION_STATUS_SUPERSEDED = 5;
  SCRIPT_VERSION_STATUS_FAILED = 6;
}

`ThreadStatus`

Thread lifecycle. Appears on Thread, CreateThreadResponse, TestScriptDraftResponse, CancelThreadResponse, ResumeThreadResponse, ThreadResult, ThreadOutputMeta, and as the status_filter on ListThreads.


enum ThreadStatus {
  THREAD_STATUS_UNSPECIFIED = 0;
  THREAD_STATUS_PENDING = 1;
  THREAD_STATUS_RUNNING = 2;
  THREAD_STATUS_PAUSED = 3;
  THREAD_STATUS_COMPLETED = 4;
  THREAD_STATUS_FAILED = 5;
  THREAD_STATUS_CANCELLED = 6;
}

`StepStatus`

Per-step status. Appears on StepSummary, StepDetail, and StepSnapshot.


enum StepStatus {
  STEP_STATUS_UNSPECIFIED = 0;
  STEP_STATUS_PENDING = 1;
  STEP_STATUS_RUNNING = 2;
  STEP_STATUS_COMPLETED = 3;
  STEP_STATUS_FAILED = 4;
  STEP_STATUS_SKIPPED = 5;
}

ScriptContract Appendix

ScriptContract

TypedField

TypeRef

TypeRefPrimitive

Constraints

EnumDef

Service enums

ScriptStatus

ScriptVersionStatus

ThreadStatus

StepStatus

See also