@studio-foundation/contracts 0.3.0-beta.6 → 0.5.2

package/README.md

@@ -1,18 +1,56 @@
 # @studio-foundation/contracts
 
-Shared TypeScript types and interfaces for the Studio monorepo. Zero dependencies, zero logic.
+**Studio** is a declarative YAML runtime for AI agents. It orchestrates multi-stage agent workflows with structured output validation and automatic retry. This package is **contracts**: the shared TypeScript types and interfaces that every other Studio package imports. Zero dependencies, zero logic.
 
-## Role
+`contracts` is the leaf of the dependency graph. It defines the language all Studio packages speak: `PipelineDefinition`, `StageRun`, `OutputContract`, `AgentConfig`, `LLMRequest`, and the rest. Install it if you're writing tooling that reads or produces Studio configs, or if you're embedding Studio packages into your own code and need the types.
 
-`contracts` is the leaf package — every other Studio package imports from it, nothing imports it back. It defines the language that all packages speak.
+- Homepage: https://github.com/studio-foundation/studio
+- Full docs: [README](https://github.com/studio-foundation/studio#readme) · [INVARIANTS](https://github.com/studio-foundation/studio/blob/main/INVARIANTS.md)
+- Use via the CLI: [`@studio-foundation/cli`](https://www.npmjs.com/package/@studio-foundation/cli)
+
+## Install
+
+```bash
+npm install @studio-foundation/contracts
+# or
+pnpm add @studio-foundation/contracts
+```
+
+## Usage
+
+```typescript
+import type {
+  PipelineDefinition,
+  StageDefinition,
+  OutputContract,
+  AgentConfig,
+  StageStatus,
+} from '@studio-foundation/contracts';
+
+import { isStageGroup } from '@studio-foundation/contracts'; // the only runtime export
+
+for (const stage of pipeline.stages) {
+  if (isStageGroup(stage)) {
+    // handle a group
+  } else {
+    // handle a plain stage
+  }
+}
+```
+
+## Dependency position
 
 ```
 contracts ← ralph
 contracts ← runner
+contracts ← anonymizer
 contracts ← engine
 contracts ← cli
+contracts ← api
 ```
 
+Nothing imports upward. If you find yourself adding a dep here, you're solving the wrong problem.
+
 ## What's in here
 
 | Module | Purpose |
@@ -98,9 +136,15 @@ interface SpawnConfig {
 
 Used by the `studio_run` builtin tool to spawn sub-pipelines from within an agent run.
 
-## Rules
+## For contributors
 
-- **Zero dependencies** — no imports from other `@studio/*` packages, ever.
-- **Zero logic** — types and interfaces only. The one exception: `isStageGroup()` in `pipeline.ts` is a pure type guard function (no side effects, no state).
+Internal rules that govern this package:
+
+- **Zero dependencies**: no imports from other `@studio-foundation/*` packages, ever.
+- **Zero logic**: types and interfaces only. The one exception: `isStageGroup()` in `pipeline.ts` is a pure type guard function (no side effects, no state).
 - If you need to add a type used by two packages, put it here.
 - If you're adding logic, you're in the wrong package.
+
+## License
+
+AGPL-3.0-only

package/dist/pipeline.d.ts

@@ -67,7 +67,7 @@ export interface StageDefinition {
     };
     hooks?: StageHooks;
 }
-export type PipelineEntry = StageDefinition | StageGroup;
+export type PipelineEntry = StageDefinition | StageGroup | MapStage | CallStage;
 export interface StageGroup {
     group: string;
     max_iterations: number;
@@ -75,5 +75,50 @@ export interface StageGroup {
     on_failure?: 'fail-fast' | 'collect-all';
     stages: StageDefinition[];
 }
+/**
+ * A fan-out / map stage: run a sub-pipeline once per item of a list, then
+ * collect the structured outputs. Replaces the "shell `studio run` per item +
+ * scrape the log" glue — the child runs are spawned in-process via the engine's
+ * RunSpawner and their last-stage output is returned directly (no scraping).
+ */
+export interface MapStage {
+    map: string;
+    condition?: string;
+    over: string;
+    pipeline: string;
+    /**
+     * Per-item input template. Each value may reference the current item and the
+     * pipeline input via {{item}}, {{item.<path>}}, {{index}}, {{input.<path>}}.
+     * A value that is exactly "{{item}}" (or "{{input.x}}") keeps the resolved
+     * value's native type; mixed strings interpolate to text.
+     */
+    input?: Record<string, unknown>;
+    as?: string;
+    concurrency?: number;
+    on_item_failure?: 'fail-fast' | 'collect-all';
+}
+/**
+ * A call stage: run a named pipeline once, inline, and expose its output to
+ * later parent stages under the stage name. This is `map` with the iteration
+ * removed — same RunSpawner machinery, structured output, no log scraping — for
+ * when the shape is a sequence, not a fan-out (e.g. chaining wiki-extraction →
+ * wiki-resolution → wiki-preparation → pages-export in one top-level pipeline).
+ */
+export interface CallStage {
+    call: string;
+    condition?: string;
+    pipeline?: string;
+    /**
+     * Input for the child run. Each value may reference the parent context via
+     * {{input}}, {{input.<path>}}, {{stages.<name>.output.<path>}} — the same
+     * substitution as `map`'s `input`, minus the per-item {{item}}/{{index}}. A
+     * value that is exactly one {{ref}} keeps the resolved value's native type;
+     * any other string interpolates to text. Omitted → the parent input is
+     * forwarded to the child unchanged.
+     */
+    input?: Record<string, unknown>;
+}
 export declare function isStageGroup(entry: PipelineEntry): entry is StageGroup;
+export declare function isMapStage(entry: PipelineEntry): entry is MapStage;
+export declare function isCallStage(entry: PipelineEntry): entry is CallStage;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js

@@ -2,4 +2,10 @@
 export function isStageGroup(entry) {
     return 'group' in entry && 'stages' in entry;
 }
+export function isMapStage(entry) {
+    return 'map' in entry && 'over' in entry;
+}
+export function isCallStage(entry) {
+    return 'call' in entry;
+}
 //# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,iCAAiC;AA8FjC,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,iCAAiC;AA4IjC,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC"}

package/dist/task.d.ts

@@ -1,2 +1,27 @@
 export type TaskStatus = 'pending' | 'running' | 'success' | 'failed';
+/**
+ * Input contract for a single agent run, carried from the engine to the runner.
+ *
+ * `description` is the default flat task text — most pipelines have only this.
+ * `fields`, when present, SUPERSEDES `description`: named fields are preserved
+ * structurally so anonymization can tokenize each independently (run-level
+ * shared keymap) BEFORE the prompt is assembled, and prompt assembly renders
+ * the fields. Field names are OPAQUE to the kernel — it imposes no domain
+ * meaning on them; an input opts into field-addressing, the kernel never
+ * requires it. One documented branch: `fields` present → field path; absent →
+ * flat-description path unchanged.
+ */
+export interface TaskInput {
+    description: string;
+    fields?: Record<string, string>;
+    /**
+     * Opaque scope: names of `fields` to anonymize. Treated as opaque strings —
+     * the kernel imposes no domain meaning (INV-04). Undefined → anonymize all
+     * fields (fail-safe); [] → anonymize none; ['a'] → only field `a`. Ignored
+     * when `fields` is absent.
+     */
+    anonymize_fields?: string[];
+    expected_output?: string;
+    contract_name?: string;
+}
 //# sourceMappingURL=task.d.ts.map

package/dist/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/validation.d.ts

@@ -5,14 +5,85 @@ export interface ToolCallRequirements {
     required_tool_groups?: string[][];
     counted_tools?: string[];
 }
+/**
+ * An external validator: a shell command that receives the stage output as JSON
+ * on stdin and prints `{ "valid": boolean, "errors": string[] }` to stdout.
+ *
+ * This is the escape hatch for validation the declarative schema cannot express
+ * (cross-field rules, computed constraints) and for validators written in another
+ * language. Field-level shape — types, enums, nested required fields — now lives
+ * declaratively in `schema.fields` (see FieldSpec); reach for an external validator
+ * only when a rule spans multiple fields or needs real code. Unlike a required tool,
+ * it runs against the ACTUAL stage output, so the agent cannot satisfy it by
+ * reporting different arguments than it emits.
+ */
+export interface ExternalValidator {
+    name: string;
+    /** Shell command. Receives the output JSON on stdin; prints {valid, errors} on stdout. */
+    command: string;
+    /** Optional timeout in milliseconds (default 30000). */
+    timeout_ms?: number;
+}
+/**
+ * Post-execution filesystem check: the files/artifacts a stage MUST leave on
+ * disk to be considered done. A "success" return code doesn't prove the agent
+ * actually produced its outputs — this closes that gap. Each entry is a path or
+ * glob (relative to the repo workspace); a stage fails if any entry matches no
+ * existing file. Runs inside the RALPH loop, so a miss enriches the retry
+ * feedback before the stage is finally failed.
+ */
+export interface ExpectedOutputs {
+    /** Paths or glob patterns (relative to the repo workspace). Each must match ≥1 existing file. */
+    files: string[];
+}
+/**
+ * The JSON type a field is expected to hold. `integer` is `number` narrowed to
+ * whole values; `object` excludes arrays and null (use `array` for lists).
+ */
+export type FieldType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+/**
+ * Declarative shape of a single field — the piece that lifts contract validation
+ * beyond "the key is present" (required_fields) to "the value is the right type,
+ * one of the allowed values, and structurally sound".
+ *
+ * Every check is optional and only fires when the field is actually present;
+ * presence is still governed by `required_fields`. This keeps the two orthogonal:
+ * `required_fields` says a field must exist, `fields` says what it must look like.
+ *
+ * Recursion covers nested structures the PoC contracts need:
+ *   - `type: object` + `required_fields`/`fields` validates a sub-object
+ *   - `type: array` + `items` validates every element (e.g. each `pages[]` entry)
+ */
+export interface FieldSpec {
+    /** Expected JSON type. On mismatch the field fails and nested checks are skipped. */
+    type?: FieldType;
+    /** Allowed values (enumeration), compared with strict equality. */
+    enum?: Array<string | number | boolean>;
+    /** For objects: names of nested fields that must be present. */
+    required_fields?: string[];
+    /** For objects: per-field specs applied to nested fields that are present. */
+    fields?: Record<string, FieldSpec>;
+    /** For arrays: the spec every element must satisfy. */
+    items?: FieldSpec;
+}
+/**
+ * A stage's output schema. `required_fields` checks top-level presence; `fields`
+ * adds declarative type/enum/nested validation for the fields it names. Both are
+ * optional and compose — a contract can use either, both, or neither.
+ */
+export interface OutputSchema {
+    required_fields?: string[];
+    fields?: Record<string, FieldSpec>;
+}
 export interface OutputContract {
     name: string;
     version: number;
-    schema?: {
-        required_fields?: string[];
-        [key: string]: unknown;
-    };
+    schema?: OutputSchema;
     tool_calls?: ToolCallRequirements;
+    /** External validators run against the real output inside the RALPH loop. */
+    validators?: ExternalValidator[];
+    /** Files/artifacts the stage must leave on disk. Checked post-execution. */
+    expected_outputs?: ExpectedOutputs;
     custom_rules?: ValidationRule[];
     post_validation?: {
         rejection_detection: {

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE;QAChB,mBAAmB,EAAE;YACnB,KAAK,EAAE,MAAM,CAAC;YACd,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE;QAChB,mBAAmB,EAAE;YACnB,KAAK,EAAE,MAAM,CAAC;YACd,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@studio-foundation/contracts",
-  "version": "0.3.0-beta.6",
-  "description": "Shared TypeScript types and interfaces for Studio v7",
+  "version": "0.5.2",
+  "description": "Shared TypeScript types and interfaces for Studio packages",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",