@jr2/orchestrator 0.1.0

package/src/snapshot-store.ts

@@ -0,0 +1,150 @@
+// Persistence for durable Machine snapshots (ADR-0007). A `SnapshotStore` is keyed by `runId`;
+// `SqliteSnapshotStore` is the default backing for a deployed Orchestrator, with `:memory:` for
+// tests. `markLost` records a run whose live state could not be re-hydrated (e.g. its flue
+// handle is gone) without deleting its history.
+
+import { DatabaseSync } from "node:sqlite";
+import type { StoredSnapshot } from "./durability.ts";
+
+export interface SnapshotStore {
+  init(): Promise<void>;
+  load(runId: string): Promise<StoredSnapshot | null>;
+  /** Every persisted run, in insertion order. The host filters by `status` on restore. */
+  list(): Promise<StoredSnapshot[]>;
+  /**
+   * Persisted run ids sharing a prefix, sorted, capped at `limit` — the store half of abbreviated
+   * run ids (ADR-0009). Includes `lost` rows: the ambiguity set is the ids that EXIST, not the ones
+   * that are readable. Skipping a lost row would let a prefix it shares with a live run resolve
+   * silently to the live one, which makes resolution unsound.
+   */
+  findIdsByPrefix(prefix: string, limit: number): Promise<string[]>;
+  save(runId: string, snapshot: unknown, status?: string): Promise<void>;
+  markLost(runId: string, reason: string): Promise<void>;
+  /**
+   * Record a run whose Machine changed shape underneath it (ADR-0030) — refused, not resumed.
+   *
+   * Unlike {@link markLost} this KEEPS the snapshot. A lost run has nothing left to look at, so
+   * nulling it costs nothing; a drifted run is intact and merely unreadable by the Machine now
+   * loaded, and it is the one a human most needs to inspect. Nulling it would also hide the run
+   * entirely: `read()` returns undefined for a null blob, so `jr2 status <id>` would answer
+   * `no run` — a refusal indistinguishable from a run that never existed.
+   */
+  markDrifted(runId: string, reason: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+type Row = {
+  run_id: string;
+  status: string;
+  snapshot: string | null;
+  reason: string | null;
+  updated_at: string;
+};
+
+export class SqliteSnapshotStore implements SnapshotStore {
+  private readonly db: DatabaseSync;
+
+  constructor(path: string) {
+    this.db = new DatabaseSync(path);
+  }
+
+  async init(): Promise<void> {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS machine_snapshots (
+        run_id TEXT PRIMARY KEY,
+        status TEXT NOT NULL DEFAULT 'live',
+        snapshot TEXT,
+        reason TEXT,
+        updated_at TEXT
+      )
+    `);
+  }
+
+  async load(runId: string): Promise<StoredSnapshot | null> {
+    const row = this.db
+      .prepare(`SELECT run_id, status, snapshot, reason, updated_at FROM machine_snapshots WHERE run_id = ?`)
+      .get(runId) as Row | undefined;
+    if (!row) return null;
+
+    const stored: StoredSnapshot = {
+      runId: row.run_id,
+      status: row.status,
+      snapshot: row.snapshot === null ? null : JSON.parse(row.snapshot),
+    };
+    if (row.reason !== null) stored.reason = row.reason;
+    return stored;
+  }
+
+  async list(): Promise<StoredSnapshot[]> {
+    const rows = this.db
+      .prepare(`SELECT run_id, status, snapshot, reason, updated_at FROM machine_snapshots ORDER BY rowid`)
+      .all() as Row[];
+    return rows.map((row) => {
+      const stored: StoredSnapshot = {
+        runId: row.run_id,
+        status: row.status,
+        snapshot: row.snapshot === null ? null : JSON.parse(row.snapshot),
+      };
+      if (row.reason !== null) stored.reason = row.reason;
+      return stored;
+    });
+  }
+
+  /**
+   * A range scan rather than `LIKE`/`GLOB`. `run_id` is the BINARY-collated PRIMARY KEY, but
+   * SQLite's `LIKE` is ASCII-case-insensitive by default, so the planner declines the index range
+   * and falls back to a full scan. `GLOB` would seek correctly but obliges every caller to escape
+   * `*?[]` first — a store shouldn't have to trust that. The `CHAR(0x10FFFF)` sentinel as the upper
+   * bound also avoids incrementing the prefix's last character, which has edge cases. `>=`/`<`
+   * carries to Postgres unchanged, where `LIKE 'x%'` would need `text_pattern_ops` to use an index.
+   */
+  async findIdsByPrefix(prefix: string, limit: number): Promise<string[]> {
+    const rows = this.db
+      .prepare(
+        `SELECT run_id FROM machine_snapshots
+         WHERE run_id >= ? AND run_id < ? || CHAR(0x10FFFF)
+         ORDER BY run_id LIMIT ?`,
+      )
+      .all(prefix, prefix, limit) as Array<{ run_id: string }>;
+    return rows.map((row) => row.run_id);
+  }
+
+  async save(runId: string, snapshot: unknown, status = "live"): Promise<void> {
+    this.db
+      .prepare(
+        `INSERT INTO machine_snapshots (run_id, status, snapshot, reason, updated_at)
+         VALUES (?, ?, ?, NULL, ?)
+         ON CONFLICT(run_id) DO UPDATE SET
+           status = excluded.status,
+           snapshot = excluded.snapshot,
+           reason = NULL,
+           updated_at = excluded.updated_at`,
+      )
+      .run(runId, status, JSON.stringify(snapshot), new Date().toISOString());
+  }
+
+  async markLost(runId: string, reason: string): Promise<void> {
+    this.db
+      .prepare(
+        `INSERT INTO machine_snapshots (run_id, status, snapshot, reason, updated_at)
+         VALUES (?, 'lost', NULL, ?, ?)
+         ON CONFLICT(run_id) DO UPDATE SET
+           status = 'lost',
+           reason = excluded.reason,
+           updated_at = excluded.updated_at`,
+      )
+      .run(runId, reason, new Date().toISOString());
+  }
+
+  /** An UPDATE, not an upsert: a drifted run is one we already have a snapshot for, and the whole
+   * point is to keep it. A row that is not there is not a drifted run — nothing to record. */
+  async markDrifted(runId: string, reason: string): Promise<void> {
+    this.db
+      .prepare(`UPDATE machine_snapshots SET status = 'drifted', reason = ?, updated_at = ? WHERE run_id = ?`)
+      .run(reason, new Date().toISOString(), runId);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/stub-harness.ts

@@ -0,0 +1,217 @@
+// The wire-compatible stub Harness (ADR-0011: dev stubbing happens at the wire, not in the
+// actor). The e2e world hosts this on localhost so workspace-less test workflows can run without a
+// data plane: an endpoint is just a URL, so the Agent actor keeps ONE code path and cannot tell it is
+// talking to a fake. Semantics: ADMIT the agent (accept the prompt, mint an admission), hold
+// the durable stream open, and never act — the Machine parks exactly as it would against a
+// silent real Harness, and e2e drives it by playing the agent against `/mcp/<iid>` instead.
+//
+// Wire (ADR-0027 — the normative model of the five endpoints; `@jr2/harness` serves it for real):
+//   POST /agents/:name/:id  {message, definition, model?, thinkingLevel?} → 200 { streamUrl, offset, submissionId }
+//   GET  /agents/:name/:id?offset=…[&view=updates] → 200 `[]` + Stream-Next-Offset/Up-To-Date
+//   GET  /agents/:name/:id?…&live=long-poll        → parked; 204 + same headers on timeout
+//   POST /agents/:name/:id/abort                   → 200 { aborted }
+//   GET  /agents/:name/:id?view=history            → 200 { …, settlements }
+// (the client's `wait(admission)` long-polls `streamUrl?view=updates` from the admission offset;
+// an empty stream parks it — exactly the "admitted, never settles" semantics the mechanics tier
+// needs.) The client then re-polls calmly at the long-poll cadence. `close()` severs parked polls.
+//
+// A stub submission therefore ends exactly one way: ABORTED, when the state that asked for the
+// turn stops waiting (ADR-0024). That is what `history`'s `settlements` carries, and it is the
+// only place a black-box test can see a turn end — the run itself is untouched by an abort.
+//
+// This can later grow scriptable behavior or be swapped for a real local Harness without
+// touching actor code — it is only a different URL.
+//
+// The stub is INERT, with no seam for an agent to act through, and that is now the whole of it.
+// The `onAdmit` hook this once carried had exactly one consumer — the containerized dev Harness
+// image — and that image is gone (ADR-0038): the @kind tier runs the REAL `@jr2/harness` in the pod
+// against a scripted model, so nothing needs the stub to originate tool calls any more. What
+// survives is this tier's job (ADR-0031): the socket-free mechanics tier reaches the stub by
+// explicit run-input `endpoint`, the Machine parks, and e2e plays the agent from outside.
+
+import { createServer } from "node:http";
+import type { AddressInfo, Socket } from "node:net";
+
+/** One admission of an Agent: which slot, which durable exchange, the prompt, the DEFINITION the
+ * Machine's slot carried here (ADR-0049), and this Submission's dials (ADR-0018) — captured so a
+ * mechanics-tier test can assert which Agent a state ran and at what settings, exactly as it
+ * asserts the prompt. The stub is inert and never READS the definition: a real Harness runs it,
+ * this one only proves it rode the wire. */
+export type Admission = {
+  agentName: string;
+  instanceId: string;
+  message?: string;
+  definition?: Record<string, unknown>;
+  model?: string;
+  thinkingLevel?: string;
+};
+
+/** One settled submission, in the shape `history()` reports it. The stub settles submissions for
+ * exactly one reason — an abort (ADR-0024) — so `outcome` has exactly one value here. */
+export type StubSettlement = { submissionId: string; outcome: "aborted" };
+
+export type StubHarnessOptions = {
+  /** Listen port. Default 0 → ephemeral (read back from `url`). */
+  port?: number;
+  /** Listen hostname. Default `127.0.0.1`. */
+  hostname?: string;
+  /** How long a live long-poll parks before answering "nothing yet". Default 25s. */
+  longPollMs?: number;
+};
+
+export type RunningStubHarness = {
+  /** The base URL — what a test workflow passes as its run-input `endpoint`. */
+  url: string;
+  /** Admissions seen so far (assertable in tests: which agents were admitted, with what). */
+  admissions: Admission[];
+  close: () => Promise<void>;
+};
+
+const AGENT_PATH = /^\/agents\/([^/]+)\/([^/]+)$/;
+const ABORT_PATH = /^\/agents\/([^/]+)\/([^/]+)\/abort$/;
+
+/** Start the stub Harness. Never acts: admit → hold the stream open → answer polls "empty". */
+export async function startStubHarness(opts: StubHarnessOptions = {}): Promise<RunningStubHarness> {
+  const hostname = opts.hostname ?? "127.0.0.1";
+  const longPollMs = opts.longPollMs ?? 25_000;
+  const admissions: RunningStubHarness["admissions"] = [];
+  let submissionSeq = 0;
+
+  // Per-instance submission bookkeeping — the little that abort needs to mean anything (ADR-0024).
+  // A stub submission never settles on its own (that IS its semantics), so "unsettled" is simply
+  // "admitted and not yet aborted", and an abort sweeps ALL of them: the running Submission AND
+  // everything queued behind it (ADR-0024/0027).
+  const unsettled = new Map<string, string[]>();
+  const settlements = new Map<string, StubSettlement[]>();
+  const key = (agentName: string, instanceId: string) => `${agentName}/${instanceId}`;
+
+  // Parked long-polls hold sockets open; close() must sever them or it hangs on graceful close.
+  const sockets = new Set<Socket>();
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://stub");
+
+    // End every in-flight and queued submission for one instance (`agents.abort` — ADR-0024).
+    // Answers `{ aborted }`: whether there was anything to end, exactly as the real Harness
+    // does for an idle instance. Settlement is recorded here rather than pushed on the stream, because nothing is
+    // listening — the actor that asked for the turn is already stopped.
+    const aborting = req.method === "POST" && ABORT_PATH.exec(url.pathname);
+    if (aborting) {
+      const [, agentName, instanceId] = aborting as unknown as [string, string, string];
+      const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
+      const ended = unsettled.get(k)?.splice(0) ?? [];
+      const settled = settlements.get(k) ?? [];
+      settled.push(...ended.map((submissionId) => ({ submissionId, outcome: "aborted" as const })));
+      settlements.set(k, settled);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ aborted: ended.length > 0 }));
+      return;
+    }
+
+    const match = AGENT_PATH.exec(url.pathname);
+    if (!match) {
+      res.writeHead(404, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: `stub harness: no route ${url.pathname}` }));
+      return;
+    }
+    const [, agentName, instanceId] = match as unknown as [string, string, string];
+
+    if (req.method === "POST") {
+      // Admission: accept the prompt and mint the durable handle. That is all — nothing acts.
+      let body = "";
+      req.on("data", (chunk: Buffer) => (body += chunk));
+      req.on("end", () => {
+        const sent = safeParse(body) as
+          | { message?: string; definition?: Record<string, unknown>; model?: string; thinkingLevel?: string }
+          | undefined;
+        const admission: Admission = {
+          agentName: decodeURIComponent(agentName),
+          instanceId: decodeURIComponent(instanceId),
+          message: sent?.message,
+          ...(sent?.definition ? { definition: sent.definition } : {}),
+          ...(sent?.model ? { model: sent.model } : {}),
+          ...(sent?.thinkingLevel ? { thinkingLevel: sent.thinkingLevel } : {}),
+        };
+        admissions.push(admission);
+        const submissionId = `stub-${++submissionSeq}`;
+        const k = key(admission.agentName, admission.instanceId);
+        unsettled.set(k, [...(unsettled.get(k) ?? []), submissionId]);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(
+          JSON.stringify({
+            streamUrl: `http://${hostname}:${port}${url.pathname}`,
+            offset: "0_0",
+            submissionId,
+          }),
+        );
+      });
+      return;
+    }
+
+    if (req.method === "GET" && url.searchParams.get("view") === "history") {
+      // The conversation snapshot (`agents.history`). Messages are not modeled — the stub has no
+      // model — but SETTLEMENTS are, because `settlements[].outcome` is how a turn's end is
+      // observed from outside (ADR-0024) and what the @kind tier asserts.
+      const k = key(decodeURIComponent(agentName), decodeURIComponent(instanceId));
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          v: 1,
+          conversationId: decodeURIComponent(instanceId),
+          offset: "0_0",
+          messages: [],
+          settlements: settlements.get(k) ?? [],
+        }),
+      );
+      return;
+    }
+
+    if (req.method === "GET") {
+      // Durable-stream read. The stream never carries anything: a catch-up read answers
+      // "empty, up to date" immediately; a live long-poll parks until timeout, then 204s.
+      const offset = url.searchParams.get("offset") ?? "0_0";
+      const headers = { "stream-next-offset": offset, "stream-up-to-date": "true" };
+      if (url.searchParams.get("live") === "long-poll") {
+        const timer = setTimeout(() => {
+          res.writeHead(204, headers);
+          res.end();
+        }, longPollMs);
+        req.on("close", () => clearTimeout(timer));
+        return;
+      }
+      res.writeHead(200, { "content-type": "application/json", ...headers });
+      res.end("[]");
+      return;
+    }
+
+    res.writeHead(405, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: `stub harness: ${req.method} not supported` }));
+  });
+
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+  });
+
+  const port = await new Promise<number>((resolve) => {
+    server.listen(opts.port ?? 0, hostname, () => resolve((server.address() as AddressInfo).port));
+  });
+
+  return {
+    url: `http://${hostname}:${port}`,
+    admissions,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+        for (const socket of sockets) socket.destroy(); // sever parked long-polls
+      }),
+  };
+}
+
+function safeParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,126 @@
+// Bearer tokens (ADR-0013), because the Sandbox boundary is otherwise theater. The Harness
+// container shares the pod's network namespace, so an Agent can reach the Orchestrator directly;
+// a per-pod NetworkPolicy cannot distinguish its packets from the Adapter's. Only authentication
+// closes this, and only the token bounds what a caller may DO (as opposed to where it may talk).
+//
+// Two principals, and the asymmetry between them is the whole design:
+//
+//   Instance token  the human/CLI credential. Full trust: gates, run control, agent surfaces.
+//                   From the instance Secret (`JR2_INSTANCE_TOKEN`); minted per boot when absent,
+//                   announced once on stdout (fixtures capture it). An Agent never has it — it
+//                   never enters a Sandbox.
+//
+//   Sandbox token   the Adapter's credential. Authorizes exactly: deliver to `kind: "agent"`
+//                   registrations whose Sandbox is THIS one. Never a Gate (a compromised Agent
+//                   must not approve its own review), never another Sandbox (`coding.ts`'s iids
+//                   are derivable and feature ids are readable from the Work Source, so a merely
+//                   run-scoped token would let one feature's coder inject a verdict into another
+//                   feature's reviewer). Delivered as a Secret via the CR's `envFrom` into the
+//                   Adapter container ALONE, which is the one place the Agent cannot read.
+//                   The signed name is a POD hosting Turns, not a Sandbox CR per se: the Instance
+//                   Harness's Adapter bears one signed for that placement's Service name
+//                   (ADR-0031), scoping it to the Menu-only registrations placed there.
+//
+// The Sandbox token is a SIGNED NAME, not a random string in a table: `<sandbox>.<hmac(key, name)>`,
+// verified by recomputing. Three things fall out that a token table would have to work for — the
+// Orchestrator holds no per-Sandbox state, `provision` stays idempotent (re-minting yields the same
+// token, so a re-applied Secret is a no-op), and a token minted before a restart still verifies
+// after one, which is exactly what ADR-0012's re-attach promises the still-running Adapter.
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Who a request is, once its bearer token checks out. */
+export type Principal =
+  /** The instance's own operator: the CLI, a human, a webhook translator holding the token. */
+  | { kind: "instance" }
+  /** One Sandbox's Adapter, speaking for the Agent in that pod — and for no one else. */
+  | { kind: "sandbox"; sandbox: string };
+
+/** Resolve a bearer token to a principal; undefined = not a token we minted (→ 401). */
+export type Authenticator = (bearer: string | undefined) => Principal | undefined;
+
+/** The Sandbox token for one Sandbox: its name, signed. Same name + key → same token, always. */
+export function sandboxToken(key: Buffer, sandbox: string): string {
+  return `${sandbox}.${sign(key, sandbox)}`;
+}
+
+/** Mint the per-boot Instance token (opaque and random — it names nothing, it just IS the trust). */
+export function mintInstanceToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+/**
+ * The instance's HMAC signing key, at `<dir>/.jr2/secret` (0600), created on first use.
+ *
+ * It MUST outlive the process: an Orchestrator restart leaves live Sandboxes running (ADR-0012 re-attach),
+ * and their Adapters still hold tokens minted by the process that died. A fresh key would reject
+ * every one of them — the Agent would silently lose its only route to its Machine.
+ */
+export async function loadSigningKey(dir: string): Promise<Buffer> {
+  const path = join(dir, ".jr2", "secret");
+  try {
+    const existing = Buffer.from(await readFile(path, "utf8"), "base64");
+    if (existing.length >= 32) return existing;
+  } catch {
+    // absent (or unreadable) → mint below
+  }
+  const key = randomBytes(32);
+  await mkdir(join(dir, ".jr2"), { recursive: true });
+  await writeFile(path, key.toString("base64"), { mode: 0o600 });
+  await chmod(path, 0o600); // an existing file keeps its old mode through writeFile
+  return key;
+}
+
+/**
+ * The instance's authenticator: the Instance token, plus any Sandbox token this key signed.
+ * A token we did not mint resolves to nothing, and the caller is refused — there is no anonymous
+ * principal, and no route decides for itself whether it needs one.
+ */
+export function createAuthenticator(opts: { instanceToken: string; signingKey: Buffer }): Authenticator {
+  return (bearer) => {
+    if (!bearer) return undefined;
+    if (constantTimeEqual(bearer, opts.instanceToken)) return { kind: "instance" };
+    const cut = bearer.lastIndexOf(".");
+    if (cut <= 0) return undefined;
+    const sandbox = bearer.slice(0, cut);
+    if (!constantTimeEqual(bearer.slice(cut + 1), sign(opts.signingKey, sandbox))) return undefined;
+    return { kind: "sandbox", sandbox };
+  };
+}
+
+/**
+ * May this principal deliver to this agent registration? The Instance token may (it is the
+ * operator). A Sandbox token may only when the registration records ITS name — which is why
+ * an Agent registration carries `sandbox` at all (ADR-0013). The recorded name is the pod hosting the Turn:
+ * a Workspace's Sandbox, or `jr2-instance-harness` for a Menu-only registration (ADR-0031). An
+ * agent registration with NO name at all is an explicit-`endpoint` run (the stub Harness on the
+ * host, in no pod): no Sandbox token can claim it.
+ */
+export function mayDeliverToAgent(principal: Principal, registrationSandbox: string | undefined): boolean {
+  if (principal.kind === "instance") return true;
+  return registrationSandbox !== undefined && registrationSandbox === principal.sandbox;
+}
+
+/**
+ * May this principal ask for a fetch on this Sandbox (ADR-0053)? A Sandbox token may ask for its
+ * OWN pod and no other — the scope is the caches that pod mounts, and the route refuses a Repo it
+ * does not. The Instance token may, on the same grounds it may deliver to any agent surface: it is
+ * the operator. Nothing else can hold either, so there is no third case.
+ */
+export function mayAskForSandbox(principal: Principal, sandbox: string): boolean {
+  if (principal.kind === "instance") return true;
+  return principal.sandbox === sandbox;
+}
+
+function sign(key: Buffer, value: string): string {
+  return createHmac("sha256", key).update(value).digest("base64url");
+}
+
+/** Compare without leaking the answer through timing. Unequal lengths are unequal, cheaply. */
+function constantTimeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}

package/src/vocabulary.ts

@@ -0,0 +1,99 @@
+// Vocabulary-on-the-machine (ADR-0011, ADR-0015): a Machine's event defs ride the machine, not a
+// module export — and they are scoped to THAT Machine alone. `jr2Setup.createMachine` attaches
+// them here; `gate` and the Agent slots read them back off the Machine that invoked them, and nothing ever
+// merges two Machines' sets. That is what makes a Machine composable by plain `invoke`
+// (ADR-0049): the importing Machine neither re-declares nor sees the nested one's events, so
+// `coding`'s `approve` and `release`'s `approve` may differ and one run may hold both.
+//
+// The attachment is keyed on `machine.config` — the raw config object xstate's `.provide()`
+// passes through unchanged (`new StateMachine(this.config, …)`, verified against the pinned
+// xstate 5.32.2). So the host's per-run `provide` and a test's `.provide()` both keep the
+// vocabulary, which is ADR-0049's rule that parts resolve at invoke time THROUGH THE LIVE ACTOR'S
+// LOGIC rather than a build-time closure: whatever machine object an actor was invoked as, its
+// config is the one the defs were attached to.
+//
+// A WeakMap (rather than a field) keeps the returned machine bit-identical — Stately-inspectable,
+// constructible with no jr2 runtime — and preserves ADR-0011's anti-global-registry argument:
+// attribution flows through the machine object, per-Machine by construction (a shared defs module
+// can feed two machines; a dev reload's fresh machine gets a fresh entry).
+//
+// This module is a pure leaf (no wire client, no actors) so `run-host.ts` and `registration.ts`
+// can read vocabularies without dragging the Harness wire client onto their test load path — the
+// same isolation actor.ts keeps.
+
+import type { AnyActorRef, AnyStateMachine } from "xstate";
+import type { z } from "zod";
+import type { EventDef } from "@jr2/agent-protocol";
+
+/** The key both attachments use: the machine's raw config, which survives `.provide()`. */
+type MachineKey = AnyStateMachine["config"];
+
+const vocabularies = new WeakMap<MachineKey, Map<string, EventDef>>();
+
+/** Attach a Machine's resolved vocabulary. jr2-internal: `jr2Setup` calls it, and `pool()` calls it
+ * for the one def it owns (its wake event). The machine factories do NOT propagate their body's
+ * or worker's defs onto the wrapper (ADR-0011): those belong to the nested Machine, which is
+ * where the actors that use them resolve. */
+export function attachVocabulary(machine: AnyStateMachine, defs: Map<string, EventDef>): void {
+  vocabularies.set(machine.config, defs);
+}
+
+/** The vocabulary a Machine was built with — undefined for a Machine not built by `jr2Setup`
+ * (a plain `setup()` machine declares no workflow events and resolves to an empty scope). */
+export function vocabularyOf(machine: AnyStateMachine): Map<string, EventDef> | undefined {
+  return vocabularies.get(machine.config);
+}
+
+/**
+ * The Machine that invoked this actor — `self._parent.logic`, public xstate API (ADR-0011). This
+ * is the resolution scope for `gate`'s `accepts` and an Agent turn's menu: the derived set came from
+ * THIS Machine's transitions, so its defs are the only ones a delivery may be validated against.
+ *
+ * Undefined for a rootless actor (`createActor(gate)` directly) and for a parent that is not a
+ * state machine — both read as an empty vocabulary, which fails the invoke loudly rather than
+ * silently accepting a name nobody declared.
+ */
+export function invokingMachine(self: AnyActorRef): AnyStateMachine | undefined {
+  const logic = (self._parent as { logic?: unknown } | undefined)?.logic as AnyStateMachine | undefined;
+  return logic?.root ? logic : undefined;
+}
+
+// The declared run input (ADR-0033): the one piece of a machine's vocabulary the event defs
+// missed — what a run of it is STARTED with. Same key choice as the vocabulary above, for the
+// same reasons (per-machine attribution, no global registry, transparent across `.provide()`).
+
+const inputSchemas = new WeakMap<MachineKey, z.ZodObject>();
+
+/** Attach a machine's declared run-input schema. jr2-internal: `jr2Setup.createMachine({ input })`
+ * attaches it, and the machine factories (`workspace`, `pool`) attach their OWN — the `input` in
+ * their options. Like the vocabulary, the door does NOT propagate up from a body or a worker
+ * (ADR-0033): a wrapper feeds its child something other than the run input (the injected
+ * `workspace` handles; a source item), so the child's contract is not the door's. */
+export function attachInputSchema(machine: AnyStateMachine, schema: z.ZodObject): void {
+  inputSchemas.set(machine.config, schema);
+}
+
+/** The run-input schema a machine declared — undefined for a machine that declared none, which
+ * is PERMISSIVE (ADR-0033): a run of it starts with anything, today's behavior. */
+export function inputSchemaOf(machine: AnyStateMachine): z.ZodObject | undefined {
+  return inputSchemas.get(machine.config);
+}
+
+/**
+ * What the HOST adds to the input of the machine a run STARTS with, beside the door
+ * (`RunHost.start`). One field today: the run's seed Instance ID, minted with the run and
+ * reported by `jr2 status`, so an external caller can address the run's first conversation.
+ *
+ * It is deliberately NOT door material (ADR-0033): no caller sends it — `start` overwrites
+ * whatever arrived, after the parse — and it is never served as JSON Schema, so putting it in a
+ * door schema would publish it and demand of every caller a field the host supplies anyway.
+ *
+ * It is also PLACEMENT-DEPENDENT: only the ROOT machine is started with it. A machine invoked
+ * further down is fed by its parent, which passes what it chooses. No type can see where a machine
+ * sits, so the one contract that must reason about this — `workspace()`'s body guard — takes the
+ * permissive answer and counts these keys as PROVIDED, which lets a body declare the field
+ * honestly. Counting them as provided (rather than subtracting them from what the body demands)
+ * is what keeps their TYPE checked: `instanceId` is a string, and a body asking for anything else
+ * is still rejected.
+ */
+export type HostInjectedInput = { instanceId: string };