@operatorstack/yield 0.0.0-canary.20260807110004.5bf4016f3efd

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Operator Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Yield
+
+Yield is an open-source execution runtime for programmable Agent Skill workflows.
+
+**Write one skill workflow. Run it from your coding agents.**
+
+Skill workflows are portable, executable processes that combine agent skills
+with deterministic code, state, and verification.
+
+Write the workflow in TypeScript, Python, Go, or Rust. Combine agent judgment,
+real commands, human input, checks, and saved state. Yield generates the small
+adapter each coding agent expects.
+
+The split is small:
+
+| term | meaning |
+|---|---|
+| **skill** | one reusable capability |
+| **workflow** | order, branches, checks, and saved state |
+| **skill workflow** | an executable composition of skills, code, commands, and human input |
+| **adapter** | a generated `SKILL.md` that lets one coding agent discover the workflow |
+
+The canonical skill workflow stays beside your code. Generated adapters are
+disposable. The model keeps reasoning, exploration, editing, and judgment;
+normal code owns the repeatable control flow.
+
+## Install
+
+Choose one language package. TypeScript and Python include a package-local
+runtime. Go and Rust install the matching runtime under `.yield/bin` in the
+repository. Generated adapters never use a global `yskill` from `PATH`.
+
+```bash
+# TypeScript (public npm)
+npm install --save-exact @operatorstack/yield@0.1.29
+npm exec -- yskill --version
+
+# Python, after creating and activating .venv
+python -m pip install yieldskill==0.1.29 --index-url https://get.operatorstack.systems/pip/simple/
+python -m yieldskill --version
+
+# Go, from the repository root
+mkdir -p .yield/bin
+GOBIN="$PWD/.yield/bin" GOPROXY=https://get.operatorstack.systems/go,direct \
+  go install github.com/operatorstack/yield/cmd/yskill@v0.1.29
+.yield/bin/yskill --version
+
+# Rust, from the repository root
+cargo install yieldskill@0.1.29 --root .yield \
+  --index sparse+https://get.operatorstack.systems/cargo/index/ --locked
+.yield/bin/yskill --version
+```
+
+Yield creates `.yield/.gitignore` when it registers a Go or Rust workflow, so
+the local runtime and run state stay out of Git.
+On Windows, run the local binary as `.\.yield\bin\yskill.exe`.
+
+## Create and register a skill workflow
+
+Keep the canonical workflow beside the language dependencies it uses. Yield writes
+small adapters into each coding agent's project skill directory; it does not
+copy the workflow or install its dependencies again.
+
+```bash
+# TypeScript example
+npm exec -- yskill init skills/review \
+  --language typescript \
+  --description "Review changed code when the user wants a branch checked before shipping."
+
+# Replace the intentionally incomplete starter and fixture, then check it.
+npm exec -- yskill doctor skills/review --test
+
+# Detect installed agents, or pass --agent cursor,codex,claude-code.
+npm exec -- yskill register skills/review
+```
+
+`yskill agents` lists the available agent IDs and project paths. Cursor,
+Codex, and Claude Code are verified. Remaining entries support explicit path
+registration from the pinned open registry; they are not presented as
+end-to-end verified.
+
+## How a skill workflow runs
+
+Deterministic re-execution: on every run/resume, `yskill` re-executes the
+skill workflow from the top, feeding recorded responses back in order. At
+the first unanswered operation the SDK emits a `yield.v1` request envelope
+and the process exits — no daemon. A replayed step that produces a
+different operation than the journal recorded is a divergence and fails
+the run loudly; it never silently forks.
+
+- **`yskill`** owns the append-only run log
+  (`.yield/runs/<id>.jsonl`), sequence and digest binding, response
+  validation, and every refusal (stale, duplicate, wrong-run,
+  schema-invalid, digest-mismatch, completion-unproven).
+- **The skill workflow** is an ordinary program using one Yield SDK; every
+  side effect crosses a yielded primitive.
+
+Five primitives, two exits:
+
+| primitive | who acts |
+|---|---|
+| `AskUser` | the agent asks through its normal interface |
+| `AgentTask` | the model reasons; the result must be schema-valid JSON |
+| `RunCommand` | **yskill executes it itself** — results are observed fact, not transcription |
+| `Require` | a claim bound to evidence; failure makes completion structurally unreachable |
+| `Complete` / `Blocked` / `Refused` | honest terminals, always recorded |
+
+## Four languages, one execution contract
+
+Write the skill workflow in Go, TypeScript, Python, or Rust. Every SDK
+implements the same certified execution contract, and the conformance suite
+(`internal/conformance`) runs the same program in all four languages and
+asserts identical observable behavior. The language-neutral schemas are
+documented in the [runtime reference](docs/reference/sdk-parity.md).
+
+| language | SDK | example |
+|---|---|---|
+| Go | `sdk/yield` | `examples/investigate` — bounded hypothesis loop |
+| TypeScript | `sdk/typescript` (`@operatorstack/yield`) | `examples/release-checklist` — human-gated deploy |
+| Python | `sdk/python` (`yieldskill`) | `examples/env-doctor` — probe, branch, resume after the human |
+| Rust | `sdk/rust` (`yieldskill`) | `examples/data-migration` — dry-run → approve → apply → verify |
+
+Skills declare their language and runner in `skill.json`:
+`{"version": 1, "language": "typescript", "run": ["node", "main.ts"]}`.
+
+## Ten skill workflows, every language
+
+The [example library](examples/library/) implements ten common skill workflows
+independently in all four SDKs: branch review, failure
+investigation, web QA, package release, issue triage, CI repair, dependency
+upgrade, database migration, security audit, and iOS publishing.
+
+Each language has the same skill workflow, a thin adapter, and a scripted
+fixture. Start from the work you already do instead of starting from a
+framework tutorial.
+
+## Documentation
+
+Start with [what a skill workflow is](docs/skill-workflows.md), then build one
+with the [ten-minute TypeScript quickstart](docs/quickstart.md). Continue with
+the documentation for your job:
+
+- [primitive guides](docs/primitives/README.md) — commands, model work,
+  human input, evidence gates, and outcomes;
+- [tutorials](docs/tutorials/README.md) — review, approval, environment
+  repair, bounded debugging, and migration;
+- [examples](docs/examples.md) — working programs in all four languages;
+- [coding-agent setup](docs/agent-setup.md) — register one skill workflow with the
+  agents used by the project;
+- [Agent Plugins and Yield](docs/agent-plugins.md) — where portable packaging ends
+  and workflow execution begins;
+- [test workflow effects](docs/testing-fixtures.md) — deterministic fixture
+  setup, response effects, standard-input JSON, and cleanup;
+- [evaluations](evals/README.md) — first-party workflow conformance and runtime
+  invariant results, including the exact claim boundary;
+- [convert an existing skill](docs/convert-existing-skill.md) — move
+  control flow into code without claiming that fixture execution proves
+  every reading of the original prose;
+- [CLI and runtime reference](docs/reference/cli.md).
+
+## Try it
+
+```
+go build -o yskill ./cmd/yskill
+./yskill test examples/library/typescript/review-branch
+./yskill test examples/library/python/review-branch
+./yskill test examples/library/go/review-branch
+./yskill test examples/library/rust/review-branch
+YSKILL="$PWD/yskill" bash ./examples/library/test-all.sh
+./yskill test examples/investigate        # Go: scripted fixture run to completion
+./yskill test examples/release-checklist  # TypeScript (Node >= 23.6)
+./yskill test examples/env-doctor         # Python 3.10+
+./yskill test examples/data-migration     # Rust (cargo)
+./yskill run  examples/investigate        # prints the first operation envelope
+./yskill init my-skill --description "Run this skill workflow when ..."
+./yskill register my-skill --agent codex # write a thin project adapter
+./yskill doctor my-skill --agent codex   # verify package + adapter wiring
+```
+
+The reference skill, `examples/investigate`, encodes an investigation
+discipline in code: at least three hypotheses, cheapest-to-disprove
+first, at most three failed attempts, completion requires a causal chain
+— or an honest `Blocked` at the frontier.
+
+## What it guarantees — and what it doesn't
+
+Guaranteed: deterministic control flow, typed requests/responses,
+persistent state, replay (divergence fails loudly), stale/duplicate
+rejection, evidence-bound completion.
+
+Not guaranteed: that the agent performed *only* the requested operation,
+or that a schema-valid `agent_task` result is true — schema validity is
+not truth. `RunCommand` is the exception by construction: commands are
+executed by the Yield CLI, so exit codes and output enter the log as
+observed fact. Runtime and conformance tests enforce these guarantees.
+
+## What it is not
+
+Not a daemon, not a hosted runtime, not a workflow DSL, not a
+marketplace, not a new agent loop, not a multi-agent orchestrator, not a
+security sandbox.
+
+---
+
+This is Yield's canonical source repository. Changes, verification, release
+intent, and publishing control all live here. MIT licensed.

package/bin/runtime.mjs

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+
+const packages = new Map([
+  ["darwin:x64", "@operatorstack/yield-darwin-amd64"],
+  ["darwin:arm64", "@operatorstack/yield-darwin-arm64"],
+  ["linux:x64", "@operatorstack/yield-linux-amd64"],
+  ["linux:arm64", "@operatorstack/yield-linux-arm64"],
+  ["win32:x64", "@operatorstack/yield-windows-amd64"],
+  ["win32:arm64", "@operatorstack/yield-windows-arm64"],
+]);
+
+export function runtimePackage(platform = process.platform, arch = process.arch) {
+  const name = packages.get(`${platform}:${arch}`);
+  if (!name) {
+    throw new Error(`Yield does not provide a runtime for ${platform}/${arch}`);
+  }
+  return name;
+}
+
+export function resolveRuntime({
+  platform = process.platform,
+  arch = process.arch,
+  resolve = createRequire(import.meta.url).resolve,
+} = {}) {
+  const name = runtimePackage(platform, arch);
+  try {
+    return resolve(name);
+  } catch (error) {
+    throw new Error(
+      `The runtime package ${name} is missing. Reinstall @operatorstack/yield for ${platform}/${arch}.`,
+      { cause: error },
+    );
+  }
+}

package/bin/runtime.test.mjs

@@ -0,0 +1,30 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveRuntime, runtimePackage } from "./runtime.mjs";
+
+const cases = [
+  ["darwin", "x64", "@operatorstack/yield-darwin-amd64"],
+  ["darwin", "arm64", "@operatorstack/yield-darwin-arm64"],
+  ["linux", "x64", "@operatorstack/yield-linux-amd64"],
+  ["linux", "arm64", "@operatorstack/yield-linux-arm64"],
+  ["win32", "x64", "@operatorstack/yield-windows-amd64"],
+  ["win32", "arm64", "@operatorstack/yield-windows-arm64"],
+];
+
+test("selects the exact runtime package for every supported target", () => {
+  for (const [platform, arch, expected] of cases) {
+    assert.equal(runtimePackage(platform, arch), expected);
+    assert.equal(resolveRuntime({ platform, arch, resolve: (name) => `/packages/${name}` }), `/packages/${expected}`);
+  }
+});
+
+test("rejects unsupported targets", () => {
+  assert.throws(() => runtimePackage("freebsd", "x64"), /does not provide a runtime/);
+});
+
+test("does not fall back when the selected package is missing", () => {
+  assert.throws(
+    () => resolveRuntime({ platform: "linux", arch: "x64", resolve: () => { throw new Error("missing"); } }),
+    /Reinstall @operatorstack\/yield/,
+  );
+});

package/bin/yskill.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { resolveRuntime } from "./runtime.mjs";
+
+let binary;
+try {
+  binary = resolveRuntime();
+} catch (error) {
+  console.error(`yskill: ${error.message}`);
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: "inherit",
+  env: { ...process.env, YIELD_LANGUAGE: process.env.YIELD_LANGUAGE ?? "typescript" },
+});
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    if (!child.killed) child.kill(signal);
+  });
+}
+child.on("error", (error) => {
+  console.error(`yskill: could not start the packaged runtime: ${error.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal && process.platform !== "win32") {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/dist/index.js

@@ -0,0 +1,219 @@
+// Generated from src/index.ts by scripts/build.mjs. Do not edit.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { exit, env, stdout, stderr } from "node:process";
+export class Blocked extends Error {
+    reason;
+    constructor(reason){
+        super(`blocked: ${reason}`);
+        this.reason = reason;
+    }
+}
+export class Refused extends Error {
+    reason;
+    constructor(reason){
+        super(`refused: ${reason}`);
+        this.reason = reason;
+    }
+}
+class EmitSignal {
+    output;
+    constructor(output){
+        this.output = output;
+    }
+}
+const digest = (b)=>"sha256:" + createHash("sha256").update(b).digest("hex");
+const compact = (v)=>v === undefined ? "" : JSON.stringify(v);
+const requestDigest = (r)=>digest(Buffer.concat([
+        Buffer.from(String(r.kind)),
+        Buffer.from([
+            0
+        ]),
+        Buffer.from(r.id),
+        Buffer.from([
+            0
+        ]),
+        Buffer.from(compact(r.payload)),
+        Buffer.from([
+            0
+        ]),
+        Buffer.from(compact(r.output_schema))
+    ]));
+export class Context {
+    idx = 0;
+    requirements = [];
+    journal;
+    constructor(journal){
+        this.journal = journal;
+    }
+    askUser(id, question, options) {
+        const valueSchema = {
+            type: "string"
+        };
+        if (options?.length) valueSchema.enum = options.map((option)=>option.value);
+        const resp = this.step({
+            id,
+            kind: "ask_user",
+            payload: options ? {
+                question,
+                options
+            } : {
+                question
+            },
+            output_schema: {
+                type: "object",
+                required: [
+                    "value"
+                ],
+                additionalProperties: false,
+                properties: {
+                    value: valueSchema
+                }
+            }
+        });
+        return resp.result.value;
+    }
+    agentTask(id, instruction, context, schema) {
+        const resp = this.step({
+            id,
+            kind: "agent_task",
+            payload: context === undefined ? {
+                instruction
+            } : {
+                instruction,
+                context
+            },
+            output_schema: schema
+        });
+        return resp.result;
+    }
+    runCommand(id, command, timeoutSeconds = 0) {
+        const payload = timeoutSeconds > 0 ? {
+            command,
+            timeout_seconds: timeoutSeconds
+        } : {
+            command
+        };
+        const resp = this.step({
+            id,
+            kind: "run_command",
+            payload
+        });
+        return resp.result;
+    }
+    require(ok, claim, evidence) {
+        const req = {
+            claim,
+            passed: ok
+        };
+        if (evidence !== undefined) req.evidence_digest = digest(compact(evidence));
+        this.requirements.push(req);
+        if (!ok) {
+            throw new EmitSignal({
+                type: "terminal",
+                terminal: {
+                    status: "requirement_failed",
+                    reason: claim
+                },
+                requirements: this.requirements
+            });
+        }
+    }
+    blocked(reason) {
+        throw new Blocked(reason);
+    }
+    refused(reason) {
+        throw new Refused(reason);
+    }
+    step(req) {
+        const entries = this.journal.entries ?? [];
+        const seq = this.idx + 1;
+        if (this.idx < entries.length) {
+            const entry = entries[this.idx];
+            const want = requestDigest(entry.request);
+            const got = requestDigest(req);
+            if (want !== got) {
+                throw new EmitSignal({
+                    type: "diverged",
+                    divergence: {
+                        sequence: seq,
+                        expected_digest: want,
+                        got_digest: got,
+                        detail: `replay produced operation "${req.id}" (${req.kind}) where the journal recorded "${entry.request.id}" (${entry.request.kind})`
+                    }
+                });
+            }
+            this.idx++;
+            return entry.response;
+        }
+        this.idx++;
+        throw new EmitSignal({
+            type: "request",
+            envelope: {
+                protocol: "yield.v1",
+                run_id: this.journal.run_id,
+                skill: this.journal.skill,
+                sequence: seq,
+                request: req
+            },
+            requirements: this.requirements
+        });
+    }
+    terminalFor(err) {
+        if (err instanceof EmitSignal) return err.output;
+        if (err instanceof Blocked) return {
+            type: "terminal",
+            terminal: {
+                status: "blocked",
+                reason: err.reason
+            },
+            requirements: this.requirements
+        };
+        if (err instanceof Refused) return {
+            type: "terminal",
+            terminal: {
+                status: "refused",
+                reason: err.reason
+            },
+            requirements: this.requirements
+        };
+        return null;
+    }
+    completed(result) {
+        return {
+            type: "terminal",
+            terminal: {
+                status: "completed",
+                result
+            },
+            requirements: this.requirements
+        };
+    }
+}
+function emit(output) {
+    stdout.write(JSON.stringify(output) + "\n");
+    exit(0);
+}
+export function defineSkill(program) {
+    const path = env.YIELD_JOURNAL;
+    if (!path) {
+        stderr.write("yield: YIELD_JOURNAL is not set; this program is run by yskill, not directly\n");
+        exit(2);
+    }
+    let journal;
+    try {
+        journal = JSON.parse(readFileSync(path, "utf8"));
+    } catch (err) {
+        stderr.write(`yield: cannot read journal: ${String(err)}\n`);
+        exit(2);
+    }
+    const ctx = new Context(journal);
+    try {
+        emit(ctx.completed(program(ctx)));
+    } catch (err) {
+        const out = ctx.terminalFor(err);
+        if (out) emit(out);
+        stderr.write(`yield: program error: ${String(err)}\n`);
+        exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@operatorstack/yield",
+  "version": "0.0.0-canary.20260807110004.5bf4016f3efd",
+  "description": "Yield skill-program SDK for TypeScript: turn SKILL.md workflows into resumable programs.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "bin": {
+    "yskill": "bin/yskill.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=23.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/operatorstack/yield.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/operatorstack/yield#readme",
+  "bugs": {
+    "url": "https://github.com/operatorstack/yield/issues"
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "workflow",
+    "resumable",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "@operatorstack/yield-darwin-amd64": "0.0.0-canary.20260807110004.5bf4016f3efd",
+    "@operatorstack/yield-darwin-arm64": "0.0.0-canary.20260807110004.5bf4016f3efd",
+    "@operatorstack/yield-linux-amd64": "0.0.0-canary.20260807110004.5bf4016f3efd",
+    "@operatorstack/yield-linux-arm64": "0.0.0-canary.20260807110004.5bf4016f3efd",
+    "@operatorstack/yield-windows-amd64": "0.0.0-canary.20260807110004.5bf4016f3efd",
+    "@operatorstack/yield-windows-arm64": "0.0.0-canary.20260807110004.5bf4016f3efd"
+  }
+}

package/src/index.ts

@@ -0,0 +1,328 @@
+// Yield skill-program SDK for TypeScript (yield.v1).
+//
+// Implements the tested SDK execution contract (see ir/README.md):
+// load the journal, replay recorded operations with a digest comparison at
+// EVERY replayed step before consuming its response, emit exactly one
+// program output (request | terminal | diverged) on stdout, then exit.
+//
+// Programs are synchronous and must be deterministic between yields: same
+// journal, same operations, every execution. Wall clocks, RNGs, and
+// filesystem reads are side effects — cross them through a yielded
+// operation or leave them out.
+//
+// Runs under Node >= 23.6 (native type stripping): `node main.ts`.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { exit, env, stdout, stderr } from "node:process";
+
+export type OpKind = "ask_user" | "agent_task" | "run_command";
+
+export interface SkillRef {
+  name: string;
+  version?: string;
+  digest: string;
+}
+
+export interface Request {
+  id: string;
+  kind: OpKind;
+  payload: unknown;
+  output_schema?: unknown;
+}
+
+export interface RequestEnvelope {
+  protocol: "yield.v1";
+  run_id: string;
+  skill: SkillRef;
+  sequence: number;
+  request: Request;
+}
+
+export interface ResponseEnvelope {
+  run_id: string;
+  sequence: number;
+  request_id: string;
+  status: "completed" | "failed";
+  result: unknown;
+}
+
+export interface Option {
+  value: string;
+  label?: string;
+}
+
+export interface CommandResult {
+  exit_code: number;
+  stdout: string;
+  stderr: string;
+  timed_out?: boolean;
+}
+
+export interface Requirement {
+  claim: string;
+  passed: boolean;
+  evidence_digest?: string;
+}
+
+interface Journal {
+  run_id: string;
+  skill: SkillRef;
+  entries?: { request: Request; response: ResponseEnvelope }[];
+}
+
+type ProgramOutput =
+  | { type: "request"; envelope: RequestEnvelope; requirements?: Requirement[] }
+  | {
+      type: "terminal";
+      terminal: {
+        status: "completed" | "blocked" | "refused" | "requirement_failed";
+        result?: unknown;
+        reason?: string;
+      };
+      requirements?: Requirement[];
+    }
+  | {
+      type: "diverged";
+      divergence: {
+        sequence: number;
+        expected_digest: string;
+        got_digest: string;
+        detail?: string;
+      };
+      requirements?: Requirement[];
+    };
+
+/** Terminal exit: a true frontier was reached — say so explicitly. */
+export class Blocked extends Error {
+  reason: string;
+  constructor(reason: string) {
+    super(`blocked: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+/** Terminal exit: the skill declines to proceed, with a stated reason. */
+export class Refused extends Error {
+  reason: string;
+  constructor(reason: string) {
+    super(`refused: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+// Thrown to unwind the program when an output has been decided; defineSkill
+// catches it. Never observable by program code that doesn't catch blindly.
+class EmitSignal {
+  output: ProgramOutput;
+  constructor(output: ProgramOutput) {
+    this.output = output;
+  }
+}
+
+const digest = (b: string | Buffer): string =>
+  "sha256:" + createHash("sha256").update(b).digest("hex");
+
+const compact = (v: unknown): string =>
+  v === undefined ? "" : JSON.stringify(v);
+
+/** sha256 over kind\0id\0compact(payload)\0compact(schema) — the IR digest. */
+const requestDigest = (r: Request): string =>
+  digest(
+    Buffer.concat([
+      Buffer.from(String(r.kind)),
+      Buffer.from([0]),
+      Buffer.from(r.id),
+      Buffer.from([0]),
+      Buffer.from(compact(r.payload)),
+      Buffer.from([0]),
+      Buffer.from(compact(r.output_schema)),
+    ]),
+  );
+
+export class Context {
+  private idx = 0;
+  private requirements: Requirement[] = [];
+  private journal: Journal;
+
+  constructor(journal: Journal) {
+    this.journal = journal;
+  }
+
+  /** Yield a question asked through the host's normal interface. */
+  askUser(id: string, question: string, options?: Option[]): string {
+    const valueSchema: Record<string, unknown> = { type: "string" };
+    if (options?.length) valueSchema.enum = options.map((option) => option.value);
+    const resp = this.step({
+      id,
+      kind: "ask_user",
+      payload: options ? { question, options } : { question },
+      output_schema: {
+        type: "object",
+        required: ["value"],
+        additionalProperties: false,
+        properties: { value: valueSchema },
+      },
+    });
+    return (resp.result as { value: string }).value;
+  }
+
+  /**
+   * Delegate reasoning to the model. `schema` (JSON Schema) is enforced by
+   * the supervisor on resume; the returned value is schema-valid by
+   * construction.
+   */
+  agentTask<T = unknown>(
+    id: string,
+    instruction: string,
+    context?: unknown,
+    schema?: unknown,
+  ): T {
+    const resp = this.step({
+      id,
+      kind: "agent_task",
+      payload: context === undefined ? { instruction } : { instruction, context },
+      output_schema: schema,
+    });
+    return resp.result as T;
+  }
+
+  /**
+   * Yield a command that yskill executes itself — the result is observed
+   * fact, not the agent's account of it.
+   */
+  runCommand(id: string, command: string, timeoutSeconds = 0): CommandResult {
+    const payload =
+      timeoutSeconds > 0
+        ? { command, timeout_seconds: timeoutSeconds }
+        : { command };
+    const resp = this.step({ id, kind: "run_command", payload });
+    return resp.result as CommandResult;
+  }
+
+  /**
+   * Bind a claim to evidence. A failed requirement terminates the program
+   * immediately; completion is structurally unreachable past it.
+   */
+  require(ok: boolean, claim: string, evidence?: unknown): void {
+    const req: Requirement = { claim, passed: ok };
+    if (evidence !== undefined) req.evidence_digest = digest(compact(evidence));
+    this.requirements.push(req);
+    if (!ok) {
+      throw new EmitSignal({
+        type: "terminal",
+        terminal: { status: "requirement_failed", reason: claim },
+        requirements: this.requirements,
+      });
+    }
+  }
+
+  blocked(reason: string): never {
+    throw new Blocked(reason);
+  }
+
+  refused(reason: string): never {
+    throw new Refused(reason);
+  }
+
+  /** @internal replay-or-emit; the certified contract's step. */
+  private step(req: Request): ResponseEnvelope {
+    const entries = this.journal.entries ?? [];
+    const seq = this.idx + 1;
+    if (this.idx < entries.length) {
+      const entry = entries[this.idx];
+      const want = requestDigest(entry.request);
+      const got = requestDigest(req);
+      if (want !== got) {
+        // Mandatory per-step check: consuming a recorded response for a
+        // drifted operation is the forbidden state the rival design fails.
+        throw new EmitSignal({
+          type: "diverged",
+          divergence: {
+            sequence: seq,
+            expected_digest: want,
+            got_digest: got,
+            detail: `replay produced operation "${req.id}" (${req.kind}) where the journal recorded "${entry.request.id}" (${entry.request.kind})`,
+          },
+        });
+      }
+      this.idx++;
+      return entry.response;
+    }
+    this.idx++;
+    throw new EmitSignal({
+      type: "request",
+      envelope: {
+        protocol: "yield.v1",
+        run_id: this.journal.run_id,
+        skill: this.journal.skill,
+        sequence: seq,
+        request: req,
+      },
+      requirements: this.requirements,
+    });
+  }
+
+  /** @internal */
+  terminalFor(err: unknown): ProgramOutput | null {
+    if (err instanceof EmitSignal) return err.output;
+    if (err instanceof Blocked)
+      return {
+        type: "terminal",
+        terminal: { status: "blocked", reason: err.reason },
+        requirements: this.requirements,
+      };
+    if (err instanceof Refused)
+      return {
+        type: "terminal",
+        terminal: { status: "refused", reason: err.reason },
+        requirements: this.requirements,
+      };
+    return null;
+  }
+
+  /** @internal */
+  completed(result: unknown): ProgramOutput {
+    return {
+      type: "terminal",
+      terminal: { status: "completed", result },
+      requirements: this.requirements,
+    };
+  }
+}
+
+function emit(output: ProgramOutput): never {
+  stdout.write(JSON.stringify(output) + "\n");
+  exit(0);
+}
+
+/**
+ * Run a skill program under the supervisor protocol. The program's return
+ * value is the run result; throw `ctx.blocked(...)`/`ctx.refused(...)` for
+ * the honest terminals.
+ */
+export function defineSkill(program: (ctx: Context) => unknown): void {
+  const path = env.YIELD_JOURNAL;
+  if (!path) {
+    stderr.write(
+      "yield: YIELD_JOURNAL is not set; this program is run by yskill, not directly\n",
+    );
+    exit(2);
+  }
+  let journal: Journal;
+  try {
+    journal = JSON.parse(readFileSync(path, "utf8")) as Journal;
+  } catch (err) {
+    stderr.write(`yield: cannot read journal: ${String(err)}\n`);
+    exit(2);
+  }
+  const ctx = new Context(journal!);
+  try {
+    emit(ctx.completed(program(ctx)));
+  } catch (err) {
+    const out = ctx.terminalFor(err);
+    if (out) emit(out);
+    stderr.write(`yield: program error: ${String(err)}\n`);
+    exit(1);
+  }
+}