@jr2/orchestrator 0.4.1 → 0.5.1

package/src/setup.ts

@@ -51,33 +51,59 @@ import { gate } from "./gate.ts";
 import { attachLent, isOpenBody, openBodyDeclarationOf, type LentParts } from "./open-body.ts";
 import { refuseInlineParts } from "./parts.ts";
 import { partyWarnings, refuseUnknownSentBy, SENT_BY, sentByGuard } from "./party.ts";
+import { refuseLostOutput } from "./run-output.ts";
+import { refuseUnroutedAgentFault } from "./mechanism-routes.ts";
 import { boundEpoch, boundRunId, continuedIid } from "./registration.ts";
 import { attachInputSchema, attachLoadWarnings, attachSeats, attachVocabulary } from "./vocabulary.ts";
 
 /**
- * The events jr2's own mechanism delivers into any workflow machine, injected into every jr2Setup
- * union. Dotted names by construction (`NAME_RE` forbids dots in workflow event names), so they
- * can never collide with a def.
+ * The marker that `compileChart` puts on the config of a Chart's Machine (ADR-0070). In a Chart the
+ * `agent.fault` route is optional: the Open body sends an `agent.fault` that no transition takes to
+ * the Machine that invoked it, so `createMachine` does not refuse a Chart state with no route. Not on the Authoring
+ * surface (index.ts). The load walk (`partsOf`) refuses an author's Machine with no route, with or
+ * without the marker (ADR-0074).
  */
+export const COMPILED_CHART: unique symbol = Symbol("jr2.compiledChart");
+
+// Injected into every jr2Setup union. Dotted names by construction (`NAME_RE` forbids dots in
+// workflow event names), so they can never collide with a def.
+/** The events that jr2 itself sends into each Machine that `jr2Setup` makes. A Mechanism event's
+ * name has a dot, and a workflow event's name cannot, so the two never collide. */
 export type MechanismEvent = FaultTelemetry | WorkspaceLost;
 
+// A Workspace's Continuity broke (ADR-0021): its Sandbox is gone, or Lost. `reason` and `message`
+// are for a body whose policy tells the causes apart, or only reports them; no policy needs them.
 /**
- * A Workspace's Continuity broke (ADR-0021): its Sandbox is gone, or Lost. `reason` and `message`
- * say why — the pod's own reason (`Evicted`, `NodeShutdown`, ...) or the operator's (`PodDeleted`,
- * `NodeLost`), or `Deleted` for a Sandbox that is gone — for a body whose policy tells them apart,
- * or only reports them. Optional: the body's policy never needs them to act.
+ * jr2 sends `workspace.lost` to the body of a `workspace()` when its Sandbox is gone: its pod was
+ * evicted or deleted, or its node went. jr2 does not make the Sandbox again, and the commits that
+ * were not pushed go with it. The body decides what to do next: route the event with
+ * `on: { "workspace.lost": … }`, usually once, on the body's root. `workspace()` refuses a body
+ * with a state that is not final and has no route for it on itself or on a state above. When the
+ * event comes and no transition takes it (the route's guard is false), the run ends `error`, with
+ * the event, the state and the reason in its fault.
  */
-export type WorkspaceLost = { type: "workspace.lost"; reason?: string; message?: string };
+export type WorkspaceLost = {
+  type: "workspace.lost";
+  /** Why the Sandbox is gone, for a person or a log: the pod's reason (`Evicted`, `NodeShutdown`),
+   * the operator's (`PodDeleted`, `NodeLost`), or `Deleted`. A body can act without it. */
+  reason?: string;
+  /** More text about the loss, when jr2 has it. */
+  message?: string;
+};
 
-/** The full event union a jr2Setup machine sees: the defs' derived types plus the mechanism's. A
- * workflow event a party delivered carries its `sender` (ADR-0015); the Machine's own events
- * (`raise`, `sendTo` itself) carry none. */
+// The defs' derived types plus the mechanism's (ADR-0015).
+/** The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`,
+ * and each Mechanism event. A workflow event that an Agent or a Gate sent has `event.sender`. An
+ * event that the Machine sent to itself (`raise`, `sendTo`) has no `sender`. */
 export type WorkflowEvent<TDefs extends readonly EventDef[]> =
   | (EventFrom<TDefs[number]> & { readonly sender?: Sender })
   | MechanismEvent;
 
 /** The guard jr2Setup registers for every Machine — `sentBy(id)` (ADR-0015) — in the typed guard
- * map, so `sentBy("coder")` and `and([sentBy("coder"), "ready"])` type-check with no cast. */
+ * map, so `sentBy("coder")` and `and([sentBy("coder"), "ready"])` type-check with no cast.
+ *
+ * @internal
+ */
 type SentByGuards = { [SENT_BY]: { id: string } };
 
 /** The jr2 actor every workflow can invoke by name without listing it (ADR-0015). `gate` is the
@@ -86,25 +112,154 @@ type SentByGuards = { [SENT_BY]: { id: string } };
 const jr2Actors = { gate };
 type JR2Actors = typeof jr2Actors;
 
-/** Consumer actors merge OVER the pre-registered set: same name → the consumer's logic wins. */
+/**
+ * Consumer actors merge OVER the pre-registered set: same name → the consumer's logic wins.
+ *
+ * @internal
+ */
 type MergedActors<TActors extends Record<string, UnknownActorLogic>> = Omit<JR2Actors, keyof TActors> & TActors;
 
 // Local equivalents of xstate's non-exported setup() mapped helpers (setup.d.ts) — same shapes,
 // so the declared signature below composes with the public `ActionFunction`/`GuardPredicate`.
+/** @internal */
 type ToParameterizedObject<T extends Record<string, ParameterizedObject["params"] | undefined>> = {
   [K in keyof T & string]: { type: K; params: T[K] };
 }[keyof T & string];
+/** @internal */
 type ToProvidedActor<TActors extends Record<string, UnknownActorLogic>> = {
   [K in keyof TActors & string]: { src: K; logic: TActors[K]; id: string | undefined };
 }[keyof TActors & string];
 
 /**
- * Author a workflow machine (ADR-0015). Like `setup()`, but `types.events` is gone: the event
- * union derives from `events` (defineEvent defs, taken as values) plus the mechanism events.
+ * Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`. Write a Machine
+ * with it when an Agent or a Gate sends events into the Machine, or when the Machine declares a
+ * door. Call `.createMachine(config)` on the result, as with `setup()`. The Machine you get is a
+ * plain xstate Machine.
+ *
+ * What it adds to `setup()`:
+ * - `events` replaces `types.events`. The event type of the Machine comes from the
+ *   `defineEvent` events you list, plus the events jr2 itself sends (`agent.fault`,
+ *   `workspace.lost`). An event that a party sent has `event.sender`. A Machine that takes no
+ *   workflow event leaves out `events`.
+ * - The `gate` actor is ready to invoke by name: `invoke: { src: "gate" }`.
+ * - Each Agent slot (`actors: { coder: agent(…) }`) gets its Menu from the states that invoke it.
+ * - The `sentBy(id)` guard is ready to use.
+ * - `createMachine` also takes `input`: a zod object for the input that starts a run. jr2 checks
+ *   each start against it. Without it, a run can start with any input. The `setup()` of xstate
+ *   does not read this `input`, so a Machine with a door uses `jr2Setup`, also when it takes no
+ *   workflow event. `jr2 up` and the publish door refuse a registered Machine that has a zod
+ *   `input` if `jr2Setup` did not make the Machine: ``workflow "<name>": machine "<id>" has a zod `input` on
+ *   createMachine, but jr2Setup did not make this Machine, so no door reads that input …``
+ *
+ * The output of a run is the root `output` of `createMachine`, beside `id` and `states`, as in
+ * xstate v5. xstate does not read the `output` of a final state as the output of the Machine. It
+ * gives that output to the root `output` as `event.output`. Write
+ * `output: ({ event }) => event.output as Output` at the root, or make the output from `context`
+ * there. `createMachine` refuses an `output` on a final state directly below the root when the root
+ * has no `output` (see the list below).
+ *
+ * `createMachine` refuses a Machine that it cannot run as written. Among the refusals:
+ * - an `on` key that no listed event has: ``machine "<id>" handles event "<key>", which no def in
+ *   jr2Setup({ events }) declares (declared: <names>) — a typo, or a missing defineEvent``
+ * - a listed event that no state takes: ``machine "<id>" declares "<name>", which no state handles
+ *   — a pick no state takes is on no Menu and no Gate: handle it, or drop it from
+ *   jr2Setup({ events })``
+ * - an entry of `events` that `defineEvent` did not make, or one name listed twice:
+ *   ``machine "<id>": `events` entry is not a defineEvent() def: <entry>``,
+ *   ``machine "<id>": duplicate event "<name>" in `events` ``
+ * - an `agent()`, an Effect or a `workspace()` written on `invoke.src` instead of under `actors`:
+ *   ``machine "<id>": state "<state>" invokes <part> inline — a Part is a key of actors, so it has
+ *   a name that the ledger, the report and customize() share: actors: { <name>: <factory>(...) },
+ *   then invoke: { src: "<name>" }``. `<part>` is `an Agent`, `an Effect` or `a Workspace`.
+ *   `<factory>` is `agent`, the Effect's kind (such as `command`), or `workspace`.
+ * - an `output` on a final state directly below the root, when the root has no `output`:
+ *   ``machine "<id>": final state "<state>" declares an output, and the root has no output — xstate
+ *   v5 gives a run only its root output, so this output reaches nothing and the run ends with none:
+ *   write it at the root, as output: ({ context }) => ..., or keep it on the final state and pass it
+ *   on with output: ({ event }) => event.output at the root``. With more than one such final state,
+ *   it names each one and puts the words in the plural: ``final states "<state>", "<state>"
+ *   declare an output``, ``these outputs reach nothing``, ``write one at the root`` and ``keep
+ *   them on the final states and pass them on``. An `output` on a
+ *   final state inside a compound state is legal: the `onDone` of that compound state gets it as
+ *   `event.output`.
+ * - a parallel state at or below a state that invokes an Agent: ``machine "<id>": state "<state>"
+ *   is parallel, at or below Agent "<slot>"'s state "<state>" — a parallel region below an Agent's
+ *   state is reserved for picks the Agent does not wait for, which jr2 does not build; background
+ *   work goes above the Agent's state``
+ * - a state below an Agent's state that invokes something and that nothing enters: ``machine
+ *   "<id>": state "<state>" below Agent "<slot>"'s state "<state>" is entered by nothing, so what
+ *   it invokes (<src>) never runs — target it from a pick or a route, or delete it``
+ * - a state that invokes an Agent when that state and each state above it have no `agent.fault`
+ *   route: ``machine "<id>": state "<state>" invokes an Agent, and no route for "agent.fault" is
+ *   on it or on a state above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with
+ *   no route the run faults: route it on that state or on a state above it, as on: {
+ *   "agent.fault": "<the state that handles it>" } (ADR-0074)``. A state that invokes an Open body
+ *   that lends an Agent or allows a model gets the same line, with `invokes an Open body that can
+ *   run an Agent`: the body sends it a Chart's unrouted `agent.fault`. When both kinds have no route,
+ *   one line names both, joined by `, and`. One route on the root is a route for each state. A
+ *   Chart's Machine does not get this refusal: in a Chart the route is optional (ADR-0070).
+ *
+ * It also refuses a `sentBy` that names no party (see `sentBy`). It refuses a pick param that
+ * nothing reads, where the pick enters a state that invokes an Effect (see `fromPick`). Shapes that
+ * are legal but probably not what you mean, such as a mode that nothing enters, are warnings that
+ * `jr2 up` prints.
+ *
+ * @param def - What `setup()` takes, with `events` in place of `types.events`. A Machine that
+ *   needs none of it calls `jr2Setup()`.
+ * @returns What `setup()` returns. Call `.createMachine(config)` on it.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+ *
+ * const proposed = defineEvent({
+ *   name: "proposed",
+ *   description: "Call this with your plan.",
+ *   input: z.object({ plan: z.string() }),
+ * });
+ * const approve = defineEvent({ name: "approve", input: z.object({}) });
+ * const reject = defineEvent({ name: "reject", input: z.object({ reason: z.string() }) });
+ *
+ * export const machine = jr2Setup({
+ *   types: {} as { input: { goal: string }; context: { goal: string } },
+ *   events: [proposed, approve, reject],
+ *   actors: {
+ *     planner: agent({
+ *       model: "anthropic/claude-haiku-5-5",
+ *       instructions: "You plan small releases.",
+ *       workspace: "none",
+ *     }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "plan",
+ *   input: z.object({ goal: z.string() }),
+ *   context: ({ input }) => ({ goal: input.goal }),
+ *   on: { "agent.fault": ".failed" },
+ *   initial: "planning",
+ *   states: {
+ *     planning: {
+ *       invoke: { src: "planner", input: ({ context }) => ({ prompt: `Plan this: ${context.goal}` }) },
+ *       on: { proposed: "review" },
+ *     },
+ *     review: {
+ *       invoke: { src: "gate" },
+ *       on: { approve: "approved", reject: "planning" },
+ *     },
+ *     approved: { type: "final" },
+ *     failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/guides/write-a-workflow.md
+ * @see docs/concepts/machines-and-workflows.md
+ * @see docs/reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md
  */
 export function jr2Setup<
   TContext extends MachineContext = MachineContext,
-  const TDefs extends readonly EventDef[] = readonly EventDef[],
+  const TDefs extends readonly EventDef[] = readonly [],
   TActors extends Record<string, UnknownActorLogic> = {},
   TActions extends Record<string, ParameterizedObject["params"] | undefined> = {},
   TGuards extends Record<string, ParameterizedObject["params"] | undefined> = {},
@@ -114,44 +269,56 @@ export function jr2Setup<
   TOutput extends NonReducibleUnknown = NonReducibleUnknown,
   TEmitted extends EventObject = EventObject,
   TMeta extends MetaObject = MetaObject,
->(def: {
-  /** context/input/output/tags/emitted/meta — never `events`; the union is derived. */
-  types?: {
-    context?: TContext;
-    input?: TInput;
-    output?: TOutput;
-    tags?: TTag;
-    emitted?: TEmitted;
-    meta?: TMeta;
-  };
-  /** This Machine's vocabulary, as values — the single source for types, validation, delivery. */
-  events: TDefs;
-  actors?: TActors;
-  actions?: {
-    [K in keyof TActions]: ActionFunction<
-      TContext,
-      WorkflowEvent<TDefs>,
-      WorkflowEvent<TDefs>,
-      TActions[K],
-      ToProvidedActor<MergedActors<TActors>>,
-      ToParameterizedObject<TActions>,
-      ToParameterizedObject<TGuards>,
-      TDelay,
-      TEmitted
-    >;
-  };
-  guards?: {
-    [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
-  };
-  delays?: {
-    [K in TDelay]: DelayConfig<
-      TContext,
-      WorkflowEvent<TDefs>,
-      ToParameterizedObject<TActions>["params"],
-      WorkflowEvent<TDefs>
-    >;
-  };
-}): SetupReturn<
+>(
+  def: {
+    /** The types of the Machine, as in `setup()`: `context`, `input`, `output`, `tags`, `emitted`
+     * and `meta`. Not `events`: the event type comes from `events`. */
+    types?: {
+      context?: TContext;
+      input?: TInput;
+      output?: TOutput;
+      tags?: TTag;
+      emitted?: TEmitted;
+      meta?: TMeta;
+    };
+    // The single source for types, validation and delivery.
+    /** The workflow events this Machine takes: each one made by `defineEvent`. Leave it out when the
+     * Machine takes none. Each listed event must be the name of an `on` key. Each `on` key must be
+     * listed, if it is not a jr2 or xstate event (an event with a `.` in its name). */
+    events?: TDefs;
+    /** The actors the states invoke by name, as in `setup()`: Agent slots (`agent(…)`), Effects
+     * (`command(…)`, `http(…)`, `push(…)`), child Machines, `workspace(…)` and plain xstate logic.
+     * The key is the slot's name. An actor named `gate` replaces jr2's Gate. */
+    actors?: TActors;
+    /** Named actions, as in `setup()`. Their `event` has the type of this Machine's events. */
+    actions?: {
+      [K in keyof TActions]: ActionFunction<
+        TContext,
+        WorkflowEvent<TDefs>,
+        WorkflowEvent<TDefs>,
+        TActions[K],
+        ToProvidedActor<MergedActors<TActors>>,
+        ToParameterizedObject<TActions>,
+        ToParameterizedObject<TGuards>,
+        TDelay,
+        TEmitted
+      >;
+    };
+    /** Named guards, as in `setup()`. `sentBy` is there already; do not name a guard `jr2.sentBy`. */
+    guards?: {
+      [K in keyof TGuards]: GuardPredicate<TContext, WorkflowEvent<TDefs>, TGuards[K], ToParameterizedObject<TGuards>>;
+    };
+    /** Named delays, as in `setup()`. */
+    delays?: {
+      [K in TDelay]: DelayConfig<
+        TContext,
+        WorkflowEvent<TDefs>,
+        ToParameterizedObject<TActions>["params"],
+        WorkflowEvent<TDefs>
+      >;
+    };
+  } = {},
+): SetupReturn<
   TContext,
   WorkflowEvent<TDefs>,
   MergedActors<TActors>,
@@ -165,6 +332,8 @@ export function jr2Setup<
   TEmitted,
   TMeta
 > {
+  // Like `setup()`, but `types.events` is gone (ADR-0015): the event union derives from `events`
+  // (defineEvent defs, taken as values) plus the mechanism events.
   const inner = setup({
     types: def.types,
     actors: { ...jr2Actors, ...(def.actors ?? {}) },
@@ -179,11 +348,16 @@ export function jr2Setup<
     // machine receives at creation — and is pulled OFF before xstate sees it: a zod schema is
     // not machine structure, and it must never reach the fingerprint/serialization paths that
     // read `machine.config`. It is attached beside the vocabulary below.
-    const { input: inputSchema, ...machineConfig } = config as { input?: z.ZodObject } & Record<string, unknown>;
+    // A compiled Chart (ADR-0070) is marked, and the marker is pulled off as `input` is.
+    const {
+      input: inputSchema,
+      [COMPILED_CHART]: compiledChart,
+      ...machineConfig
+    } = config as { input?: z.ZodObject; [COMPILED_CHART]?: true } & Record<string, unknown>;
 
     // Resolve the defs first (duplicates and reserved semantics fail HERE, naming the machine —
     // the same loud failure `eventMap` gave the manifest, moved to machine-build time)…
-    const defs = eventMap((machineConfig as { id?: string }).id ?? "(machine)", def.events);
+    const defs = eventMap((machineConfig as { id?: string }).id ?? "(machine)", def.events ?? []);
 
     // Every Open body slot (ADR-0070), found by its brand: each name it lends resolves against THIS
     // setup's own parts, or the Machine is refused naming it. The resolved set is stamped on the slot,
@@ -231,6 +405,12 @@ export function jr2Setup<
 
     // A Part written inline has no name (ADR-0049, ADR-0067): refused, with the slot form.
     refuseInlineParts(machine);
+    // A final state's output with no root output (ADR-0015): the run would end with none.
+    refuseLostOutput(machine);
+    // A state that invokes an Agent, or an Open body that can run one, with no `agent.fault` route
+    // (ADR-0074): the run would wait for ever. Not in a compiled Chart: there the route is optional,
+    // and the Open body sends the event that no transition takes to the Machine that invoked it (ADR-0070).
+    if (compiledChart !== true) refuseUnroutedAgentFault(machine);
     refuseParallelBelowAgents(machine, def.actors ?? {});
     refuseUnknownSentBy(machine);
     // Before the Effect checks: they ask who may send a writing (`mayTake`), which reads its audience.
@@ -894,6 +1074,9 @@ function wrapAgentInput(orig: unknown, derived: string[], agentName: string, men
       // jr2 mints every id (ADR-0016, ADR-0057): the Turn's input carries no id to honor, so
       // nothing a Machine writes can address a conversation jr2 did not derive.
       instanceId: mintIid(consumer, agentName, args.self),
+      // One per invocation (ADR-0016): two Turns that continue one conversation share the iid, the
+      // admission ledger's key, and a restore must not re-attach one Turn to the other's admission.
+      turnId: randomUUID(),
       endpoint: consumer.endpoint,
       sandbox: consumer.sandbox,
       prompt: consumer.prompt,

package/src/size.ts

@@ -23,15 +23,73 @@
 /** A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory). */
 export type Quantity = string | number;
 
+// A Size (ADR-0060, GLOSSARY.md "Size"): `limits.memory` and `limits.cpu`, nothing else. A field
+// left out resolves down the chain (`resolveSize`) — the Instance's `sandbox.resources`, then the
+// kit default (`KIT_SIZE`). The same shape is the User Container's split (`userSeatOf`,
+// `splitSize`), where a field left out means the seat has no limit of its own for it and shares
+// the pod's budget.
 /**
- * A Size (ADR-0060, GLOSSARY.md "Size"): `limits.memory` and `limits.cpu`, nothing else. A field
- * left out resolves down the chain (`resolveSize`) — the Instance's `sandbox.resources`, then the
- * kit default of 2Gi and 1 cpu.
+ * The Size of a Workspace: the most memory and cpu that its whole Sandbox can use. jr2 reserves
+ * all of it on the node. Thus a Sandbox never gets less than its Size and never uses more.
  *
- * The same shape is the User Container's split (`user: { image, resources }`), where a field left
- * out means the seat has no limit of its own for it and shares the pod's budget.
+ * Write it as `{ limits: { memory, cpu } }`. You can write it in three places: the `resources`
+ * option of `workspace()`, `customize(machine, { resources })`, and `sandbox.resources` in
+ * `jr2.config.ts`. The Size is a fact of the Machine. The Instance's `sandbox.resources` applies
+ * only to a Workspace that states no Size. A field that neither states comes from the kit default:
+ * memory `2Gi`, cpu `1`.
+ *
+ * The same shape is the User Container's part of the Size, in `user: { image, resources }`. There,
+ * a field you leave out gives the User Container no limit of its own: it shares the pod's budget.
+ *
+ * It refuses any key but `limits.memory` and `limits.cpu`, where you write it. The message names
+ * the field: `<where>` is where you wrote the Size, for example `workspace(): resources`.
+ *
+ * - `<where>.requests is not accepted — jr2 reserves the whole Size, so every request equals its
+ *   limit — a Size is { limits: { memory?, cpu? } } and nothing else — Agent Substrate's template
+ *   size (ADR-0060)`
+ * - `<where>.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing else —
+ *   Agent Substrate's template size (ADR-0060)`
+ * - `<where>.limits.<key> is not accepted — a Size is { limits: { memory?, cpu? } } and nothing
+ *   else — Agent Substrate's template size (ADR-0060)`
+ * - `<where>.limits.memory: <value> is not a positive quantity (e.g. "2Gi", "512Mi")`, and for
+ *   cpu, `<where>.limits.cpu: <value> is not a positive quantity (e.g. "2", "1500m")`
+ *
+ * `jr2 up` also refuses a Size that leaves the Harness container less than its floor. The message
+ * starts with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or
+ * with `the Size leaves the Harness container no cpu:`. The text that follows names each number
+ * and where it came from.
+ *
+ * @example
+ * ```ts
+ * import { customize, type Size } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * const size: Size = { limits: { memory: "4Gi", cpu: "2" } };
+ *
+ * export const machine = customize(task, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ *   resources: size,
+ * });
+ * ```
+ *
+ * @see docs/guides/size-a-workspace.md
+ * @see docs/concepts/workspaces.md
+ * @see docs/reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md
  */
-export type Size = { limits: { memory?: Quantity; cpu?: Quantity } };
+export type Size = {
+  /** The two limits. Write `limits: {}` to state no field: each field then comes from the next
+   * source. */
+  limits: {
+    /** The memory limit, as a Kubernetes quantity: `"4Gi"`, `"512Mi"`, or a number of bytes.
+     * It must be more than zero. When you leave it out, it comes from the next source, as above. */
+    memory?: Quantity;
+    /** The cpu limit, as a Kubernetes quantity: `"2"`, `"1500m"`, or a number of cpus. It must be
+     * more than zero. jr2 enforces it. When you leave it out, it comes from the next source, as
+     * above. */
+    cpu?: Quantity;
+  };
+};
 
 /** The kit's default Size (ADR-0060). Node gives each process a V8 heap of about 55% of its
  * container limit, and `tsc` on a mid-size repo aborted below about 1.1Gi, so 1Gi fails a common
@@ -303,11 +361,65 @@ export function splitSize(size: ResolvedSize, user?: Size): SizeSplit {
 
 // --- the User Container seat -------------------------------------------------------------------
 
+// The User Container as a Machine states it (ADR-0005, ADR-0060): an image in ADR-0037's two
+// shapes, and optionally its split of the Size. The object form exists for the split alone.
 /**
- * The User Container as a Machine states it (ADR-0005, ADR-0060): an image in ADR-0037's two
- * shapes, and optionally its split of the Size. The object form exists for the split alone.
+ * The User Container in its object form: its image, and its part of the Workspace's Size. The User
+ * Container is an optional container of your own in the Sandbox pod. It runs its own entrypoint
+ * with `/work` mounted, and jr2 never builds into it, probes it or sends it commands. Use it for a
+ * service that must run without an Agent, such as an sshd.
+ *
+ * Write it in the `user` option of `workspace()` or of `customize()`. That option also takes the
+ * image as a string; use this object form only to give the User Container a part of the Size. A
+ * `customize()` that names `user` replaces the whole User Container, its part of the Size
+ * included.
+ *
+ * It refuses, where you write it. `<where>` is `workspace()` or `customize()`:
+ *
+ * - an image that is not a non-empty string. The message starts with
+ *   `` <where>: `user` must be a non-empty string (an image), or { image, resources? } ``.
+ * - `<where>: user.<key> is not accepted — the User Container is { image, resources? } (ADR-0005,
+ *   ADR-0060)`
+ *
+ * `resources` is checked as a {@link Size}, with the same refusals.
+ *
+ * `jr2 up` refuses a part that leaves the Harness container less than its floor. The message starts
+ * with `the Size leaves the Harness container <memory> memory, below its 256Mi floor:` or with
+ * `the Size leaves the Harness container no cpu:`. The text that follows names each number and
+ * where it came from.
+ *
+ * @example
+ * ```ts
+ * import { customize, type UserContainer } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * const sshd: UserContainer = {
+ *   image: "registry.example.com/sshd:1.0",
+ *   resources: { limits: { memory: "256Mi", cpu: "250m" } },
+ * };
+ *
+ * export const machine = customize(task, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ *   user: sshd,
+ * });
+ * ```
+ *
+ * @see docs/concepts/workspaces.md
+ * @see docs/guides/size-a-workspace.md
+ * @see docs/reference/decisions/0005-sandbox-pod-composition.md
+ * @see docs/reference/decisions/0060-a-workspace-states-its-size-and-jr2-reserves-all-of-it.md
  */
-export type UserContainer = { image: string; resources?: Size };
+export type UserContainer = {
+  /** The image: a `file:` URL to a docker context that your module ships
+   * (`import.meta.resolve("./sshd")`), which `jr2 up` builds, or a registry ref. It must not be
+   * empty. */
+  image: string;
+  /** This container's part of the Workspace's Size, as a Size. jr2 takes it from the Harness
+   * container's part. A field you leave out gives this container no limit of its own for it: it
+   * shares the pod's budget. Default: no part. */
+  resources?: Size;
+};
 
 /** The `user` option in either shape, read as its two halves. */
 export function userSeatOf(user: string | UserContainer | undefined): { image?: string; resources?: Size } {

package/src/snapshot-store.ts

@@ -4,7 +4,8 @@
 // store is owed — with `:memory:` for tests. A persist survives a process crash, not a power loss
 // (WAL, `synchronous=NORMAL`), and the write stays synchronous so the row is on disk before the
 // Machine's next side effect runs. `markLost` records a run whose live state could not be
-// re-hydrated (e.g. its flue handle is gone); a non-live row lives a week, then `sweep` deletes it.
+// re-hydrated (e.g. its flue handle is gone), keeping any snapshot the row had; a non-live row
+// lives a week, then `sweep` deletes it.
 
 import { DatabaseSync } from "node:sqlite";
 import type { StoredSnapshot } from "./durability.ts";
@@ -37,18 +38,31 @@ export interface SnapshotStore {
    * silently to the live one, which makes resolution unsound.
    */
   findIdsByPrefix(prefix: string, limit: number): Promise<string[]>;
+  /**
+   * The run whose blob carries the idempotency key `effect` (`dispatchedBy.effect`, ADR-0071), in
+   * any status, or undefined: what answers a re-sent dispatch with the run it already started. A
+   * row `markLost` wrote with no save before it has no snapshot, and so no key; a swept row is gone
+   * with its key.
+   */
+  findByDispatch(effect: string): Promise<string | undefined>;
   save(runId: string, snapshot: unknown, status?: string): Promise<void>;
+  /**
+   * Record a run whose live state could not be re-hydrated. An upsert: a row that was saved KEEPS
+   * its snapshot and its idempotency key, because a lost dispatched run must keep answering its
+   * key — a re-send from its caller would otherwise start a second run (ADR-0071). Only a run with
+   * no row before gets a row with no snapshot.
+   */
   markLost(runId: string, reason: string): Promise<void>;
   /**
    * Record a run this Orchestrator can no longer read (ADR-0030, ADR-0069) — refused, not resumed:
    * the Assembly its snapshot names is not on the volume, was published for another Kit version or
    * does not load, or its Machine's shape does not match the snapshot's stamp.
    *
-   * 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 only unreadable by this Orchestrator,
-   * 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.
+   * An UPDATE of a row that is there, and it KEEPS the snapshot: a drifted run is intact and only
+   * unreadable by this Orchestrator, 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. It keeps the row's idempotency key too (ADR-0071).
    */
   markDrifted(runId: string, reason: string): Promise<void>;
   close(): Promise<void>;
@@ -62,6 +76,20 @@ type Row = {
   updated_at: string;
 };
 
+/** The lookup `findByDispatch` runs, exported so a test can ask the planner about THIS statement,
+ * not a copy of it: the column is indexed, so the plan is a seek. */
+export const FIND_BY_DISPATCH_SQL = `SELECT run_id FROM machine_snapshots
+  WHERE dispatch_effect = ? ORDER BY rowid LIMIT 1`;
+
+/** The idempotency key a blob carries at `dispatchedBy.effect` (ADR-0071), or null. */
+function dispatchEffectOf(snapshot: unknown): string | null {
+  if (typeof snapshot !== "object" || snapshot === null) return null;
+  const by = (snapshot as { dispatchedBy?: unknown }).dispatchedBy;
+  if (typeof by !== "object" || by === null) return null;
+  const effect = (by as { effect?: unknown }).effect;
+  return typeof effect === "string" ? effect : null;
+}
+
 export class SqliteSnapshotStore implements SnapshotStore {
   private readonly db: DatabaseSync;
 
@@ -83,6 +111,16 @@ export class SqliteSnapshotStore implements SnapshotStore {
         updated_at TEXT
       )
     `);
+    // The idempotency key of a dispatched run (ADR-0071) is copied out of its blob into a column of
+    // its own when `save` writes the row, and the column is indexed. Not an expression index over
+    // `json_extract(snapshot, …)`: that runs on every row and THROWS on a blob SQLite's JSON parser
+    // refuses (nested about a thousand deep), so one such row would fail its own save and every
+    // later `init()` over the volume. A column also costs no JSON parse a save.
+    const columns = this.db.prepare(`PRAGMA table_info(machine_snapshots)`).all() as Array<{ name: string }>;
+    if (!columns.some((c) => c.name === "dispatch_effect")) {
+      this.db.exec(`ALTER TABLE machine_snapshots ADD COLUMN dispatch_effect TEXT`);
+    }
+    this.db.exec(`CREATE INDEX IF NOT EXISTS machine_snapshots_dispatch_effect ON machine_snapshots(dispatch_effect)`);
   }
 
   async load(runId: string): Promise<StoredSnapshot | null> {
@@ -151,18 +189,24 @@ export class SqliteSnapshotStore implements SnapshotStore {
     return rows.map((row) => row.run_id);
   }
 
+  async findByDispatch(effect: string): Promise<string | undefined> {
+    const row = this.db.prepare(FIND_BY_DISPATCH_SQL).get(effect) as { run_id: string } | undefined;
+    return 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, ?)
+        `INSERT INTO machine_snapshots (run_id, status, snapshot, reason, updated_at, dispatch_effect)
+         VALUES (?, ?, ?, NULL, ?, ?)
          ON CONFLICT(run_id) DO UPDATE SET
            status = excluded.status,
            snapshot = excluded.snapshot,
            reason = NULL,
-           updated_at = excluded.updated_at`,
+           updated_at = excluded.updated_at,
+           dispatch_effect = excluded.dispatch_effect`,
       )
-      .run(runId, status, JSON.stringify(snapshot), new Date().toISOString());
+      .run(runId, status, JSON.stringify(snapshot), new Date().toISOString(), dispatchEffectOf(snapshot));
   }
 
   async markLost(runId: string, reason: string): Promise<void> {