@jr2/orchestrator 0.4.1 → 0.5.1

package/src/http.ts

@@ -5,17 +5,14 @@
 // TWO dialects, one primitive (ADR-0013). The Orchestrator does not speak MCP — nothing does: the
 // Harness presents the Menu to its model itself, and reaches these routes through the Custodian in
 // its pod, which holds the Sandbox token. What is left here are two thin adapters over the same
-// registration table:
+// registration table: the Gate resource of ADR-0011, for a human, a webhook or CI
+// (`GET /runs/:id`, `POST /runs/:id/gates/:gate/events`), and the Agent's surface, for the Agent's
+// Harness through its Custodian and nothing else (`/agents/:iid/*`). `/sandboxes/:name/fetch` also
+// serves the Harness's pod, but it is not an adapter over the registration table.
 //
-//   # human / webhook / CI — the Gate resource of ADR-0011
-//   GET  /runs/:id                     open gates: accepts + schemas + meta      [Instance token]
-//   POST /runs/:id/gates/:gate/events  validate + deliver                        [Instance token]
-//
-//   # the Agent's Harness, through its Custodian, and nothing else
-//   GET  /agents/:iid/surface          accepts + schemas + semantics             [Sandbox token]
-//   POST /agents/:iid/events           validate + deliver → the turn receipt      [Sandbox token]
-//   GET  /agents/:iid/deliveries/:id   long-poll an outstanding pick's answer    [Sandbox token]
-//   POST /sandboxes/:name/fetch        ask the node cache to fetch one Repo      [Sandbox token]
+// Every route, with its band, is a row of `HTTP_ROUTES` below. That table is data: the HTTP API
+// Reference is generated from it (ADR-0072), and http-routes.test.ts holds it to the routes
+// `createApp` registers, both ways.
 //
 //   # named Charts (ADR-0070): a Chart under a name is a Workflow `<wrapper>/<name>`
 //   GET    /workflows/:wrapper/chart-schema           the grammar, narrowed to the Open body    [open]
@@ -53,16 +50,379 @@ import { Hono } from "hono";
 import type { Context, MiddlewareHandler } from "hono";
 import { accepts } from "hono/accepts";
 import { streamSSE } from "hono/streaming";
-import { EventValidationError, NotTakenError, OutstandingError, UnknownAddressError } from "./registration.ts";
+import { z } from "zod";
+import {
+  DISPATCHED_BY_HEADER,
+  EventValidationError,
+  NotTakenError,
+  OutstandingError,
+  UnknownAddressError,
+  type DispatchedBy,
+} from "./registration.ts";
 import type { RepoStatus } from "./repos.ts";
 import { UnmountedRepoError, type FetchAnswer } from "./repo-fetch.ts";
 import { mayAskForSandbox, mayDeliverToAgent, type Authenticator, type Principal } from "./tokens.ts";
-import { observe, type RunFeedEvent, type RunHost, type RunStatus, type WorkflowFeedEvent } from "./run-host.ts";
+import {
+  DispatchKeyConflictError,
+  keyAnswer,
+  keyConflict,
+  observe,
+  UnknownWorkflowError,
+  type RunFeedEvent,
+  type RunHost,
+  type RunStatus,
+  type WorkflowFeedEvent,
+} from "./run-host.ts";
 import { KIT_VERSION } from "./config.ts";
 import type { AssemblyDoor } from "./assembly.ts";
 import { ChartRefusal } from "./chart.ts";
 import { chartName, NamedChartError, splitChartName, type NamedCharts } from "./charts.ts";
 
+// ---- The route table (ADR-0072) -------------------------------------------------------------
+// The routes `createApp` registers, as data. It is the source of the HTTP API Reference page, so a
+// row says what a CALLER needs: the address, the credential, the body, the answer. Why a route is
+// in its band stays in the comment above its handler. http-routes.test.ts compares the rows with
+// the app's own registrations both ways and checks each row's band on the wire, so the table
+// cannot drift from the code by forgetting.
+
+/** The access bands of ADR-0014, named for the credential each requires, and the publish door's
+ * band (ADR-0069): the publish token alone. */
+export type HttpBand = "open" | "authenticated" | "instanceOnly" | "publishOnly";
+
+/** One route of the Orchestrator's HTTP API (ADR-0072). */
+export type HttpRoute = {
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /** In Hono syntax, exactly as registered: `:param`, and `:param{regex}` for a constrained one. */
+  path: string;
+  band: HttpBand;
+  /** One line: what the route does. */
+  summary: string;
+  /** The request body, as a type name or in short; absent when the route reads none. */
+  body?: string;
+  /** The success answer, in short. Errors are `{ error }` with the status the handler says. */
+  response: string;
+  /** `true` when the answer is a Server-Sent Events stream. */
+  stream: boolean;
+  /** The decisions that shape the route, as bare ADR numbers: `"0014"`. */
+  adrs: readonly string[];
+};
+
+/** Every route of the Orchestrator's HTTP API, in the order `createApp` registers them. */
+export const HTTP_ROUTES: readonly HttpRoute[] = [
+  {
+    method: "GET",
+    path: "/healthz",
+    band: "open",
+    summary: "Liveness, and what this instance is: its Kit version and image content hash.",
+    response: "{ ok: true, version, hash? }",
+    stream: false,
+    adrs: ["0009", "0019"],
+  },
+  {
+    method: "GET",
+    path: "/readyz",
+    band: "open",
+    summary: "Readiness.",
+    response: "{ ready: true }",
+    stream: false,
+    adrs: ["0009"],
+  },
+  {
+    method: "GET",
+    path: "/workflows",
+    band: "open",
+    summary:
+      "The Workflows a run can start, each with its origin, and each Chart wrapper's named Charts in its entry. A named Chart that cannot run now says why.",
+    response: "WorkflowListing[]",
+    stream: false,
+    adrs: ["0014", "0070"],
+  },
+  {
+    method: "GET",
+    path: "/assembly",
+    band: "open",
+    summary: "The current Assembly and the Assemblies that live runs hold.",
+    response: "AssemblyView",
+    stream: false,
+    adrs: ["0069"],
+  },
+  {
+    method: "PUT",
+    path: "/assembly",
+    band: "publishOnly",
+    summary:
+      "Publish the next Assembly. `jr2 up` calls it, and nothing else. A refused Assembly leaves the current one current.",
+    body: "the Assembly as a tar stream, with the headers `jr2-kit-version` and `jr2-assembly-hash`",
+    response:
+      "200 with the Assembly, its Workflows, the held Assemblies and the ones collected; 400, 409 or 422 with the reason",
+    stream: false,
+    adrs: ["0069"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:wrapper/chart-schema",
+    band: "open",
+    summary: "The Chart grammar, narrowed to the Open body of one Chart wrapper.",
+    response: "JSON Schema",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "PUT",
+    path: "/workflows/:wrapper/charts/:name",
+    band: "instanceOnly",
+    summary: "Admit and keep a runtime Chart under a name. Its Workflow is `<wrapper>/<name>`.",
+    body: "the Chart text alone",
+    response: "201 { name, origin, hash } when new, 200 when it replaced one; 422 { error, report } when refused",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "DELETE",
+    path: "/workflows/:wrapper/charts/:name",
+    band: "instanceOnly",
+    summary: "Remove a runtime Chart. A live run of it keeps its own text.",
+    response: "204",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "POST",
+    path: "/workflows/:wrapper/charts/:name/runs",
+    band: "instanceOnly",
+    summary: "Start a run of a named Chart, as `POST /workflows/<wrapper>%2F<name>/runs` does.",
+    body: "the Chart wrapper's input, without the Chart",
+    response: "201 { runId, instanceId }; 409 when the named Chart cannot run now",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs/:runId/machine",
+    band: "open",
+    summary: "The Machine that a run binds, with each bound Chart compiled in, which the Console draws.",
+    response: "MachineDoc",
+    stream: false,
+    adrs: ["0070"],
+  },
+  {
+    method: "GET",
+    path: "/",
+    band: "open",
+    summary: "The Console page to a browser; a 404 to a JSON caller.",
+    response: "text/html (the Console shell)",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name",
+    band: "open",
+    summary: "The Console page to a browser; to a JSON caller, the workflow and its declared input schema.",
+    response: "{ name, machineId, input: JSON Schema | null }, or text/html",
+    stream: false,
+    adrs: ["0032", "0033"],
+  },
+  {
+    method: "POST",
+    path: "/workflows/:name/runs",
+    band: "instanceOnly",
+    summary:
+      "Start a run of a registered workflow. A `dispatch` from another Orchestrator sends the header `jr2-dispatched-by`, and a repeated start with its key answers the run that it started.",
+    body: "the workflow's input, checked against its declared input schema",
+    response:
+      "201 { runId, instanceId }; 200 { runId, instanceId, existing: true } for a repeated dispatch; 422 { error, report } when the door refuses a Chart in the input",
+    stream: false,
+    adrs: ["0033", "0058", "0070", "0071"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/machine",
+    band: "open",
+    summary: "The registered template Machine's structure, which the Console draws.",
+    response: "MachineDoc",
+    stream: false,
+    adrs: ["0014"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs",
+    band: "open",
+    summary: "The live runs of one workflow, as observations: identity and state value, no context.",
+    response: "RunObservation[]",
+    stream: false,
+    adrs: ["0014"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/events",
+    band: "open",
+    summary: "The activity of every run of one workflow, as observations, on one connection.",
+    response: "SSE: runs, status, emit (type only), retry, gone",
+    stream: true,
+    adrs: ["0014", "0022"],
+  },
+  {
+    method: "GET",
+    path: "/workflows/:name/runs/:runId/events",
+    band: "open",
+    summary: "One live run's activity, as observations, until it settles.",
+    response: "SSE: status, emit (type only), retry",
+    stream: true,
+    adrs: ["0014", "0022"],
+  },
+  {
+    method: "GET",
+    path: "/assets/style.css",
+    band: "open",
+    summary: "The Console's stylesheet.",
+    response: "text/css",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/assets/elk.js",
+    band: "open",
+    summary: "The Console's graph layout library (the elkjs bundle).",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0032"],
+  },
+  {
+    method: "GET",
+    path: "/assets/:file{[\\w.-]+\\.ts}",
+    band: "open",
+    summary: "A Console source module, with its types erased.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/assets/components/:file{[\\w.-]+\\.ts}",
+    band: "open",
+    summary: "A Console view module, with its types erased.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/assets/vendor/:file",
+    band: "open",
+    summary: "Preact's browser ESM, which the Console's import map names.",
+    response: "text/javascript",
+    stream: false,
+    adrs: ["0034"],
+  },
+  {
+    method: "GET",
+    path: "/runs",
+    band: "instanceOnly",
+    summary: "The live runs, with their full status.",
+    response: "RunStatus[]",
+    stream: false,
+    adrs: ["0009", "0014"],
+  },
+  {
+    method: "GET",
+    path: "/repos",
+    band: "instanceOnly",
+    summary: "The Repos as the cluster reports them.",
+    response: "{ dataPlane, repos: RepoStatus[] }",
+    stream: false,
+    adrs: ["0048", "0051"],
+  },
+  {
+    method: "GET",
+    path: "/runs/resolve",
+    band: "instanceOnly",
+    summary: "The run ids that start with a prefix (`?prefix=`, at least 4 characters).",
+    response: "{ prefix, runIds: string[], truncated }",
+    stream: false,
+    adrs: ["0009"],
+  },
+  {
+    method: "GET",
+    path: "/runs/:runId",
+    band: "instanceOnly",
+    summary: "One run's status, live or settled, with its open Gates.",
+    response: "RunStatus & { gates: GateView[] }",
+    stream: false,
+    adrs: ["0009", "0011"],
+  },
+  {
+    // `authenticated` in the code, and the handler refuses a Sandbox token itself (ADR-0013): the
+    // credential the route requires is the Instance token's, so this is its band.
+    method: "POST",
+    path: "/runs/:runId/gates/:gate/events",
+    band: "instanceOnly",
+    summary: "Deliver an event to an open Gate of a run.",
+    body: "{ type, ...payload }, checked against the Gate's schema for that event",
+    response: "{ ok: true }; 409 { error, acceptsNow } when the run does not take it now",
+    stream: false,
+    adrs: ["0011", "0013"],
+  },
+  {
+    method: "GET",
+    path: "/runs/:runId/events",
+    band: "instanceOnly",
+    summary: "One run's full activity until it settles; a settled run's final status, once.",
+    response: "SSE: status, emit, retry, admission, pick, placing, placed, child-error, effect, gone",
+    stream: true,
+    adrs: ["0022", "0023", "0064", "0067"],
+  },
+  {
+    method: "POST",
+    path: "/runs/:runId/events",
+    band: "instanceOnly",
+    summary: "Cancel a run: it ends, and its Workspaces go unless `keep` is true.",
+    body: '{ type: "CANCEL", keep?: boolean }',
+    response: "{ ok: true }",
+    stream: false,
+    adrs: ["0002", "0025"],
+  },
+  {
+    method: "GET",
+    path: "/agents/:instanceId/surface",
+    band: "authenticated",
+    summary: "An Agent's Menu and this Turn's Allowed picks. A Sandbox token reads only its own Sandbox's.",
+    response: "AgentSurfaceView",
+    stream: false,
+    adrs: ["0013", "0029"],
+  },
+  {
+    method: "POST",
+    path: "/agents/:instanceId/events",
+    band: "authenticated",
+    summary: "Deliver an Agent's pick into the state that invoked it.",
+    body: "{ type, ...payload }, checked against the pick's input schema",
+    response: 'AgentDeliveryReceipt; 409 { refused: "outstanding", outstanding?, allowed }',
+    stream: false,
+    adrs: ["0013", "0024", "0029"],
+  },
+  {
+    method: "GET",
+    path: "/agents/:instanceId/deliveries/:deliveryId",
+    band: "authenticated",
+    summary: "Long-poll the answer to an outstanding pick; 503 means ask again.",
+    response: "AgentDeliveryReceipt",
+    stream: false,
+    adrs: ["0013", "0024"],
+  },
+  {
+    method: "POST",
+    path: "/sandboxes/:name/fetch",
+    band: "authenticated",
+    summary: "Ask the node cache to fetch one Repo that this Sandbox mounts. A Sandbox token asks only for its own.",
+    body: "{ identity }",
+    response: "FetchAnswer: { fetched } | { stale, asOf }",
+    stream: false,
+    adrs: ["0053"],
+  },
+];
+
 /** A `POST /runs/:id/events` body: the down-channel event. CANCEL is all that is left of it
  * (ADR-0013): APPROVE and STEER rode the deferred/poll machinery: `deferred`
  * is retired (ADR-0006), `poll` reserved but not built.
@@ -89,6 +449,40 @@ async function readJson(text: Promise<string>): Promise<Record<string, unknown>>
   }
 }
 
+/**
+ * The `jr2-dispatched-by` header a foreign `dispatch` sends (ADR-0071). `instance` is required: a
+ * start that comes over the door with a key comes from another Orchestrator by construction (an
+ * in-process dispatch never reaches the door). Unknown fields are dropped, as a door drops them: a
+ * caller at a later Kit version may send more.
+ */
+const DispatchedByHeader = z.object({
+  run: z.string().min(1),
+  slot: z.string().min(1),
+  effect: z.string().min(1),
+  depth: z.number().int().positive(),
+  instance: z.string().min(1),
+});
+
+/** The header's {@link DispatchedBy}, absent when no header was sent, or why it is refused. */
+function dispatchedByOf(raw: string | undefined): { by?: DispatchedBy } | { error: string } {
+  if (raw === undefined) return {};
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return { error: `the ${DISPATCHED_BY_HEADER} header is not JSON: ${errMessage(err)} (ADR-0071)` };
+  }
+  const parsed = DispatchedByHeader.safeParse(json);
+  if (!parsed.success) {
+    return {
+      error:
+        `the ${DISPATCHED_BY_HEADER} header must be { run, slot, effect, depth, instance }: ` +
+        `${parsed.error.issues.map((i) => `${i.path.join(".") || "(header)"}: ${i.message}`).join("; ")} (ADR-0071)`,
+    };
+  }
+  return { by: parsed.data };
+}
+
 /** The message of a thrown error, for the `{ error }` 404 body. */
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
@@ -581,18 +975,35 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
    * Start a run of a Workflow (ADR-0009). A named Chart that cannot run now is 409 with why
    * (ADR-0070); a Chart in the input that the door refuses is 422 with the report; input failing
    * the door schema is 400 (ADR-0033); an unknown Workflow is 404.
+   *
+   * A foreign `dispatch` sends `jr2-dispatched-by` (ADR-0071): its key makes a repeated start one
+   * run, answered `200 { runId, instanceId, existing: true }` where a new one is `201`. The key is
+   * asked first, so a re-send answers its run even when the name would be refused now; a key a
+   * run of another Workflow carries is 409. A header that does not parse is 400. `jr2 run` and the
+   * Console send none. Any throw that is not a refusal is a defect, 500: a foreign caller reads a
+   * 404 as "nothing was started", and a defect may come after a start.
    */
   const startRun = async (c: Context<JR2Env>, name: string): Promise<Response> => {
+    const header = dispatchedByOf(c.req.header(DISPATCHED_BY_HEADER));
+    if ("error" in header) return c.json({ error: header.error }, 400);
+    const { by } = header;
+    if (by) {
+      const found = await host.dispatched(by.effect);
+      if (found && found.workflow !== name) return c.json({ error: keyConflict(found, name, by.effect) }, 409);
+      if (found) return c.json({ ...keyAnswer(found, name, by.effect), existing: true }, 200);
+    }
     const unrunnable = opts.charts?.get(name)?.unrunnable;
     if (unrunnable !== undefined) return c.json({ error: `named Chart "${name}" cannot run: ${unrunnable}` }, 409);
     const input = await readJson(c.req.text());
     try {
-      const { runId, instanceId } = await host.start(name, input);
-      return c.json({ runId, instanceId }, 201);
+      const { runId, instanceId, existing } = await host.start(name, input, by ? { dispatchedBy: by } : {});
+      return existing ? c.json({ runId, instanceId, existing }, 200) : c.json({ runId, instanceId }, 201);
     } catch (err) {
       if (err instanceof ChartRefusal) return c.json({ error: "refused", report: err.report }, 422);
       if (err instanceof EventValidationError) return c.json({ error: errMessage(err) }, 400);
-      return c.json({ error: errMessage(err) }, 404);
+      if (err instanceof DispatchKeyConflictError) return c.json({ error: errMessage(err) }, 409);
+      if (err instanceof UnknownWorkflowError) return c.json({ error: errMessage(err) }, 404);
+      return c.json({ error: errMessage(err) }, 500);
     }
   };
 
@@ -660,7 +1071,7 @@ export function createApp(host: RunHost, auth?: Authenticator, opts: CreateAppOp
     });
   });
 
-  // Push work: start a run of a registered workflow. Unknown workflow → host.start throws → 404.
+  // Push work: start a run of a registered workflow. Unknown workflow → UnknownWorkflowError → 404.
   // A body failing the machine's declared input schema (ADR-0033) → 400 naming the accepted
   // shape — the same error class, and the same wire mapping, as a gate delivery failing its
   // schema (`POST /runs/:id/gates/:gate/events` below). Instance-band (ADR-0058): starting work is

package/src/index.ts

@@ -1,85 +1,63 @@
-// @jr2/orchestrator — the deployed app that runs Machines: workflow config, the agent + gate
-// delivery surfaces, the duplex Actor over the Harness wire, and durable snapshot persistence
-// (ADR-0002/0006/0007). Builds on the `@jr2/agent-protocol` wire contract.
+// @jr2/orchestrator — the Authoring surface (GLOSSARY.md): the names an author writes in a
+// workflow module or in `jr2.config.ts`, and no other name. A name is here when an author writes
+// it; a name an author only meets through inference (a jr2Setup event union, a gate's input, a
+// pick's Frame) stays internal. A workflow authors against ONE package — `defineEvent`,
+// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" (ADR-0015) — and an Assistant that
+// reads this file reads the whole of what it may write.
 //
-// It does NOT speak MCP (ADR-0013): the Harness presents the Menu to its model itself, and reaches
-// the surface here through the Custodian in its pod. What lives here is the registration table and
-// two thin HTTP adapters over it — plus what composes a Custodian (ADR-0059).
+// Named re-exports only, never `export *`: each name below is a decision, and
+// test/authoring-surface.test.ts pins the list. The kit's own packages (the CLI, the e2e suite,
+// the Harness's tests) import "@jr2/orchestrator/internal", which holds everything here and the
+// runtime besides.
 
-// The wire contract, re-exported: a workflow authors against ONE package (`defineEvent`,
-// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" — ADR-0015).
-export * from "@jr2/agent-protocol";
-export * from "./agent.ts";
-// The Effect surface (ADR-0067): `command` itself is the wire-bound one, from harness-client.ts;
-// `fromPick`, `paramsOf` and `answer` are what an author writes between a pick and its work.
-export * from "./effect.ts";
-// The http kind (ADR-0068): `http`, `secret`, `bearer`, `basic`, `text`, and the Effector's wire.
-export * from "./http-effect.ts";
-export * from "./sandbox-effect.ts";
-// An Effect's Open parts (ADR-0054): the types `customize({ effects })` reads.
-export type { EffectBinding, OpenEffect, OpenEffectPart } from "./open-effect.ts";
-export { openPartsText } from "./open-effect.ts";
-export * from "./effector-wire.ts";
-export * from "./pick.ts";
-// The Chart (ADR-0070): its grammar (`chartSchema`, which a Chart wrapper's door and a planner's pick
-// import), the door that admits one, and the resolver of its references.
-export * from "./chart.ts";
-// The Open body a Chart binds (`openBody`, the slot constructor a Chart wrapper places in `actors`)
-// and the named Charts of an Instance: Chart files and runtime Charts (ADR-0070).
-export * from "./open-body.ts";
-export * from "./charts.ts";
-export * from "./parts.ts";
-export * from "./size.ts";
-export * from "./customize.ts";
-export * from "./ambient.ts";
-export * from "./config.ts";
-export * from "./repo-identity.ts";
-export * from "./pool.ts";
-export * from "./setup.ts";
-// The author's routing guard (ADR-0015).
+// Machine and events: the setup a workflow writes its Machine with, the events its parties send,
+// and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+export { defineEvent } from "@jr2/agent-protocol";
+export { jr2Setup } from "./setup.ts";
 export { sentBy } from "./party.ts";
-export * from "./vocabulary.ts";
-export * from "./tokens.ts";
-export * from "./durability.ts";
-export * from "./snapshot-store.ts";
-export * from "./actor.ts";
-export * from "./gate.ts";
-export * from "./workspace.ts";
-export * from "./images.ts";
-// The Assembly's content address and wire form (ADR-0069): `jr2 up` and the door share both.
-export * from "./content-hash.ts";
-export * from "./assembly-tar.ts";
-// The current Assembly and the publish door (ADR-0069), and the walk's refusal listing that
-// `jr2 up` and the door both run.
-export * from "./assembly.ts";
-export * from "./assembly-checks.ts";
-export * from "./mount-digest.ts";
-export * from "./model-keys.ts";
-export * from "./held-secrets.ts";
-export * from "./secret-placement.ts";
-export * from "./git-push.ts";
-export * from "./git-clone.ts";
-export * from "./custodian.ts";
-export * from "./sandbox-kube.ts";
-export {
-  effectorManifestKey,
-  LABEL_EFFECTOR_POD,
-  readSandboxEffectorManifest,
-  sandboxEffectorKeySecret,
-  sandboxEffectorObjectsOf,
-  type ProjectedSecret,
-  type SandboxEffectorManifest,
-} from "./sandbox-effector.ts";
-export * from "./repos.ts";
-export * from "./repo-fetch.ts";
-// Type-only: what a workflow event delivery looks like (the registration TABLE stays internal —
-// ADR-0011: workflows speak only defineEvent/agent/gate).
-export type { ChildErrorMarker, DeliveredEvent, PlacingMarker, RunMarker, TurnMarker } from "./registration.ts";
-export * from "./machine-doc.ts";
-export * from "./run-host.ts";
-export * from "./http.ts";
-export * from "./harness-client.ts";
-export * from "./stub-harness.ts";
-export * from "./instance.ts";
-export * from "./server.ts";
-export * from "./names.ts";
+export type { HostInjectedInput } from "./vocabulary.ts";
+
+// Failure: the Part a Machine invokes to fail its run, and the guard that tells a Failure from a
+// defect in an `onError` (ADR-0073).
+export { fail, isFailure } from "./fail.ts";
+
+// Agents: an Agent slot and the definition it carries (ADR-0028, ADR-0049).
+export { agent } from "./harness-client.ts";
+export type { AgentDefinition, ThinkingLevel } from "./agent.ts";
+
+// Workspaces and Repos: a Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+export { workspace } from "./workspace.ts";
+export type { Workspaced } from "./workspace.ts";
+export type { Binding, RepoSlot } from "./parts.ts";
+
+// Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071),
+// and what an author writes between a pick and that work.
+export { arg } from "./effect.ts";
+export type { CommandOutput } from "./effect.ts";
+export { command } from "./harness-client.ts";
+export { basic, bearer, file, http, secret, text } from "./http-effect.ts";
+export type { HttpOutput } from "./effector-wire.ts";
+export { push } from "./sandbox-effect.ts";
+export type { PushOutput } from "./sandbox-effect.ts";
+export { dispatch } from "./dispatch-effect.ts";
+export type { DispatchOutput } from "./effect.ts";
+export { answer, fromPick, paramsOf } from "./pick.ts";
+
+// Composition: a part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017,
+// ADR-0049, ADR-0054, ADR-0060).
+export { open } from "./parts.ts";
+export { customize } from "./customize.ts";
+export type { Customize } from "./customize.ts";
+export type { EffectBinding } from "./open-effect.ts";
+export type { Size, UserContainer } from "./size.ts";
+export { pool, source } from "./pool.ts";
+
+// Charts: the Open body a Chart wrapper places in `actors`, and the grammar a planner's pick
+// declares, whole or narrowed to one wrapper (ADR-0070).
+export { openBody } from "./open-body.ts";
+export type { OpenBodyDeclaration, OpenBodyOutput } from "./open-body.ts";
+export { chartSchema, chartSchemaFor } from "./chart.ts";
+
+// Config: `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
+export { defineConfig } from "./config.ts";
+export type { JR2Config } from "./config.ts";