@jr2/orchestrator 0.6.0 → 0.7.0

package/src/customize.ts

@@ -9,7 +9,7 @@
 // `.provide()`, nothing to learn (ADR-0015's rule, restated by ADR-0049 — a `.with()` method and
 // a callable-machine hybrid were both rejected there).
 //
-// Four moves, and each is the smallest one that works:
+// Five moves, and each is the smallest one that works:
 //
 //   - An AGENT override is xstate's own `provide`: `machine.provide({ actors: { coder:
 //     agent({ ...stock, ...override }) } })`. The slot already IS the Agent (ADR-0049), so
@@ -18,6 +18,8 @@
 //     package left `open`, or whose auth, header or env names `secret(open)`, carries a binder,
 //     which builds the Effect again with the composer's parts, so the bound slot is checked as a
 //     written one is. Once — a bound part is fixed from then on.
+//   - A GATE binding is the same substitution (ADR-0011, ADR-0054): a Gate slot is built again from
+//     its parts, with the look bound and the handlers patched by kind and event key.
 //   - A CHILD override is the same call one level down, recursing. Each level is exactly the
 //     one-level reach ADR-0015 found `provide` has — held by the composer who owns the child
 //     object, never host-side injection into somebody else's Machine.
@@ -80,6 +82,18 @@ import { isEffect, type Arg } from "./effect.ts";
 import { attachLent, copyOpenBody, lentIn, openBodiesOf, openBodyDeclarationOf } from "./open-body.ts";
 import { effectChecks } from "./effect-checks.ts";
 import type { NamedSecret, Text } from "./http-effect.ts";
+import type { EventsOf, HookKinds, NoWildcardKeys } from "./hook-kinds/index.ts";
+import {
+  gateSlotOf,
+  hooksTableFault,
+  isGateSlot,
+  lookFault,
+  type AnyHandler,
+  type GateIn,
+  type GateLook,
+  type GateSlot,
+  type GateSlotParts,
+} from "./gate.ts";
 import {
   binderOf,
   effectBindingShape,
@@ -141,6 +155,45 @@ type AgentSlots<M extends AnyStateMachine> = Extract<
  */
 type OpenEffectSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: OpenEffect<OpenEffectPart> }>["src"];
 
+/** The Gate slots (`gate({ … })`, ADR-0011) — told by their brand.
+ *
+ * @internal
+ */
+type GateSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: GateSlot<any, any> }>["src"];
+/**
+ * The meta and the event type of the Gate slot under one key.
+ *
+ * @internal
+ */
+type GateTypesAt<M extends AnyStateMachine, K extends string> =
+  LogicAt<M, K> extends GateSlot<infer Meta, infer Ev> ? { meta: Meta; ev: Ev } : never;
+
+/**
+ * A patch of a Gate slot's handlers (ADR-0011, ADR-0054): by Hook kind id and event key, a handler
+ * that adds or replaces the one there, or `null` to remove it. A key that the kind's payloads do not
+ * name does not compile.
+ *
+ * @internal
+ */
+export type GateHooksPatch<Meta, Ev> = {
+  readonly [Id in keyof HookKinds as HookKinds[Id] extends { readonly id: Id } ? Id : never]?: {
+    readonly [Key in keyof EventsOf<HookKinds[Id]>]?:
+      | ((d: GateIn<Meta> & { readonly payload: EventsOf<HookKinds[Id]>[Key] }) => Ev | undefined)
+      | null;
+  } & NoWildcardKeys<HookKinds[Id]>;
+};
+
+/**
+ * What `customize()` binds on one Gate slot: its look, and a patch of its handlers.
+ *
+ * @internal
+ */
+export type GateBinding<Meta, Ev> = {
+  /** The look, bound once: the package left it `open`, or the composer replaces it. Or `"none"`. */
+  readonly look?: GateLook<Meta, Ev> | "none";
+  readonly hooks?: GateHooksPatch<Meta, Ev>;
+};
+
 /** What one Open part binds to: a url, an argv, a secret's name, a dispatch's target — another
  * Orchestrator's origin and the secret that holds its Instance token, together (ADR-0071). */
 type PartBinding<P> = P extends "url"
@@ -151,7 +204,11 @@ type PartBinding<P> = P extends "url"
       ? { secret: string }
       : P extends "target"
         ? { target: { url: string; token: NamedSecret } }
-        : never;
+        : P extends "server"
+          ? { server: string }
+          : P extends "tool"
+            ? { tool: string }
+            : never;
 
 /** A union of object types as their intersection: one binding object with every key. */
 type Intersected<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
@@ -275,6 +332,19 @@ export type Customize<M extends AnyStateMachine> = {
   effects?: [OpenEffectSlots<Reached<M>>] extends [never]
     ? never
     : { [K in OpenEffectSlots<Reached<M>>]?: BindingOf<LogicAt<Reached<M>, K>> };
+  /** Bind the look of a Gate slot (`gate({ … })`) that a package left `open`, and add, replace or
+   * remove its handlers by Hook kind id and event key (`null` removes one), by slot name:
+   * `{ review: { look, hooks: { gitlab: { "note.MergeRequest": null } } } }`. At run time,
+   * `customize()` refuses a slot that holds no Gate slot: `customize(): machine "<id>" carries no
+   * Gate slot "<slot>" — its Gate slots are: <slots>`. */
+  gates?: [GateSlots<Reached<M>>] extends [never]
+    ? never
+    : {
+        [K in GateSlots<Reached<M>>]?: GateBinding<
+          GateTypesAt<Reached<M>, K>["meta"],
+          GateTypesAt<Reached<M>, K>["ev"]
+        >;
+      };
   /** Retune a Machine that this Machine composes, by slot name. The value has the same shape as
    * these parts, one level down. At run time, `customize()` refuses a slot that holds no Machine:
    * `customize(): machine "<id>" composes no Machine under "<slot>"`. */
@@ -326,6 +396,7 @@ export type Customize<M extends AnyStateMachine> = {
 type LooseParts = {
   agents?: Record<string, Partial<AgentDefinition> | undefined>;
   effects?: Record<string, EffectBinding | undefined>;
+  gates?: Record<string, { look?: unknown; hooks?: Record<string, Record<string, AnyHandler | null>> } | undefined>;
   actors?: Record<string, LooseParts | undefined>;
   image?: string;
   user?: string | UserContainer;
@@ -350,6 +421,9 @@ type LooseParts = {
  * - `customize(): machine "<id>" carries no Agent slot "<slot>" — its Agents are: <slots>`
  * - `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots>`
  * - `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots>`
+ * - `customize(): machine "<id>" carries no Gate slot "<slot>" — its Gate slots are: <slots>`
+ * - `` customize(): Gate slot "<slot>"'s look is bound once, to a look or "none" — not `open` again ``, and the
+ *   refusals of a look that `gate()` makes
  * - `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots>`
  * - `customize(): machine "<id>" declares its Repo Slots open as a map — name at least one`
  * - `` customize(): `repos` say what a SANDBOX is made of, how big it is and which Repos it
@@ -384,11 +458,11 @@ type LooseParts = {
  * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
  */
 export function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M {
-  const { agents, effects, actors, image, user, repos, resources } = parts as LooseParts;
+  const { agents, effects, gates, actors, image, user, repos, resources } = parts as LooseParts;
   let out: AnyStateMachine = machine;
   // Order matters in one direction only: the Sandbox seats and slots REBUILD the wrapper, so they
   // go last and carry the retuned implementations with them.
-  if (agents || effects || actors) out = retune(out, { agents, effects, actors });
+  if (agents || effects || gates || actors) out = retune(out, { agents, effects, gates, actors });
   const seats: Seats = {
     ...(image !== undefined ? { image } : {}),
     ...(user !== undefined ? { user } : {}),
@@ -458,6 +532,9 @@ function retune(machine: AnyStateMachine, parts: LooseParts): AnyStateMachine {
   }
   const bound = Object.entries(parts.effects ?? {}).filter(([, b]) => b !== undefined);
   for (const [name, binding] of bound) actors[name] = bindEffect(machine, name, binding!);
+  for (const [name, binding] of Object.entries(parts.gates ?? {})) {
+    if (binding) actors[name] = bindGate(machine, name, binding);
+  }
   for (const [name, childParts] of Object.entries(parts.actors ?? {})) {
     if (!childParts) continue;
     const child = asMachine((machine.implementations.actors as Record<string, unknown>)[name]);
@@ -547,6 +624,12 @@ function bindEffect(machine: AnyStateMachine, name: string, binding: EffectBindi
         );
       }
     }
+    if ((part === "server" || part === "tool") && (typeof value !== "string" || value === "")) {
+      throw new Error(
+        `customize(): the mcp Effect "${name}"'s ${part} is bound to a name, a string: ` +
+          `${effectBindingShape(part)} (ADR-0054, ADR-0079)`,
+      );
+    }
     if (part === "secret" && typeof value !== "string") {
       throw new Error(
         `customize(): the ${logic.effect.kind} Effect "${name}"'s secret is bound to a secret's name, a string — ` +
@@ -557,6 +640,62 @@ function bindEffect(machine: AnyStateMachine, name: string, binding: EffectBindi
   return binder(binding);
 }
 
+/**
+ * Bind a Gate slot's look and patch its handlers (ADR-0011, ADR-0054). The slot is built again from
+ * its parts, with the same `meta`, `delivers` and `reply`, so a run of the import and a run of the
+ * bound Machine each have their own. A look is bound to a value once: `open` again is refused, and
+ * the bound look meets the checks that `gate()` runs.
+ */
+function bindGate(
+  machine: AnyStateMachine,
+  name: string,
+  binding: NonNullable<NonNullable<LooseParts["gates"]>[string]>,
+): unknown {
+  const logic = (machine.implementations.actors as Record<string, unknown>)[name];
+  if (!isGateSlot(logic)) {
+    throw new Error(
+      `customize(): machine "${machine.id}" carries no Gate slot "${name}" — its Gate slots are: ` +
+        `${listed(slotsWhere(machine, isGateSlot))} (ADR-0011). Only declared parts can be bound.`,
+    );
+  }
+  const parts: GateSlotParts = logic.gateSlot;
+  let look = parts.look;
+  if (binding.look !== undefined) {
+    if (binding.look === open) {
+      throw new Error(
+        `customize(): Gate slot "${name}"'s look is bound once, to a look or "none" — not \`open\` again (ADR-0054)`,
+      );
+    }
+    const fault = lookFault(binding.look);
+    if (fault) throw new Error(`customize(): Gate slot "${name}": ${fault} (ADR-0011)`);
+    look = binding.look as GateSlotParts["look"];
+  }
+  const hooks: Record<string, Record<string, AnyHandler>> = {};
+  for (const [kind, keys] of Object.entries(parts.hooks)) hooks[kind] = { ...keys };
+  for (const [kind, keys] of Object.entries(binding.hooks ?? {})) {
+    if (typeof keys !== "object" || keys === null) {
+      throw new Error(`customize(): Gate slot "${name}": hooks.${kind} is { <event key>: handler | null } (ADR-0011)`);
+    }
+    const into = (hooks[kind] ??= {});
+    for (const [key, handler] of Object.entries(keys)) {
+      if (handler === null) delete into[key];
+      else if (handler !== undefined) into[key] = handler;
+    }
+    if (Object.keys(into).length === 0) delete hooks[kind];
+  }
+  const fault = hooksTableFault(hooks);
+  if (fault) throw new Error(`customize(): Gate slot "${name}": ${fault} (ADR-0011)`);
+  const frozen: Record<string, Readonly<Record<string, AnyHandler>>> = {};
+  for (const [kind, keys] of Object.entries(hooks)) frozen[kind] = Object.freeze(keys);
+  return gateSlotOf(
+    Object.freeze({
+      ...parts,
+      hooks: Object.freeze(frozen),
+      ...(look !== undefined ? { look } : {}),
+    }),
+  );
+}
+
 const isSecret = (value: unknown): boolean =>
   typeof value === "object" && value !== null && typeof (value as { secret?: unknown }).secret === "string";
 

package/src/dispatch-effect.ts

@@ -19,6 +19,9 @@
 //     through the binding, foreign in the `jr2-dispatched-by` header), and the door answers a
 //     repeat with the run the key already started. So a dispatch is idempotent by construction: a
 //     restore that cannot tell whether its start arrived sends it again, and gets the same run.
+//     The key is asked before the slot's schema reads the body: in-process through the run host's
+//     lookup, foreign as a key-only ask (no body) when the slot's schema refuses the body. With no
+//     run under the key, the schema's refusal is the invoke's error, and nothing starts.
 //   - THE RUN ON THE ROW. Once the start's answer names the run, the intent row is written again
 //     with it, saved at the write: a restore with it settles `started` at once, or resumes the
 //     wait on that run, and never starts another.
@@ -78,9 +81,10 @@ export type DispatchDefinition<S extends z.ZodObject | undefined = undefined> =
   wait?: boolean;
   /** How long the Effect waits: by default 30s for the start, and 10m with `wait`. */
   timeout?: Duration;
-  /** A different Orchestrator: `url` is its origin, and `token` is the secret that holds its
-   * Instance token. Or `open`, which the composer binds with `customize(<import>, { effects: {
-   * <slot>: { target: { url, token } } } })`. Without it, the run starts in this Orchestrator. */
+  /** A different Orchestrator: `url` is its origin, and `token` is the secret that holds the token
+   * of a Caller of it with `start` for the Workflow, and `read` too when `wait` is true. Or `open`,
+   * which the composer binds with `customize(<import>, { effects: { <slot>: { target: { url, token
+   * } } } })`. Without it, the run starts in this Orchestrator. */
   target?: { url: string; token: NamedSecret } | typeof open;
 };
 
@@ -208,7 +212,9 @@ function targetOf(workflow: string, target: unknown): { url: string; token: stri
     );
   }
   if (typeof token !== "object" || token === null || typeof (token as { secret?: unknown }).secret !== "string") {
-    throw new Error(`${where}: the token is a secret("<name>") holding the target's Instance token (ADR-0071)`);
+    throw new Error(
+      `${where}: the token is a secret("<name>") holding a Caller token of the target with start for the Workflow (ADR-0071)`,
+    );
   }
   const name = (token as { secret: string }).secret;
   if (name === OPEN_SECRET) {
@@ -255,23 +261,75 @@ export function openDispatchOf<S extends z.ZodObject | undefined>(
 }
 
 /** The wire request for one foreign start (ADR-0071): the target's origin, the Workflow, the body,
- * the token by name, and who dispatched it. */
+ * the token by name, who dispatched it, and the party it acts for. With no body (`undefined`), the
+ * start is a key-only ask: the door answers the run under the key, and starts nothing. */
 export function dispatchStartOf(
   parts: DispatchParts,
-  input: Record<string, unknown>,
+  input: Record<string, unknown> | undefined,
   dispatchedBy: DispatchedBy & { instance: string },
+  onBehalfOf?: string,
 ): DispatchStartRequest {
   if (parts.target === undefined) throw new Error("dispatchStartOf: an in-process dispatch has no wire request");
   return {
     kind: "dispatch",
     url: [{ text: parts.target.url }],
     workflow: parts.workflow,
-    input,
+    ...(input !== undefined ? { input } : { keyOnly: true as const }),
     auth: { bearer: { secret: parts.target.token } },
     dispatchedBy,
     wait: parts.wait,
     timeoutMs: parts.timeoutMs,
+    ...(onBehalfOf !== undefined ? { onBehalfOf } : {}),
+  };
+}
+
+/**
+ * What a foreign start sends as `onBehalfOf` for the first Caller of the calling run's chain
+ * (ADR-0071, ADR-0078): the party that Caller says it acts for, else the name that jr2 shows, else
+ * `<via>/<name>`. Undefined when jr2 started the chain, or the text is not printable ASCII of at
+ * most 256 characters, which a header cannot carry: the start then goes with no claim.
+ */
+export function onBehalfOfFor(
+  caller: { via: string; name: string; shown?: string; onBehalfOf?: string } | undefined,
+): string | undefined {
+  if (!caller) return undefined;
+  const text = caller.onBehalfOf ?? caller.shown ?? `${caller.via}/${caller.name}`;
+  return /^[\x20-\x7e]{1,256}$/.test(text) ? text : undefined;
+}
+
+// --- A Pool's worker ------------------------------------------------------------------------------
+
+/** What a Pool of runs gives its `dispatch` worker (ADR-0017): the run's body, and the Hook delivery
+ * that carried the item, when one did. The key is the worker's own spawn id: the item's id. */
+export type PoolWorkerInput = { body: unknown; hook?: DispatchedBy["hook"] };
+
+/** A dispatch's snapshot as a Pool's worker holds it: the key and the Hook delivery ride the
+ * persisted snapshot, so a restore sends the same key again. */
+type KeyedSnapshot<O, I> = EffectSnapshot<O, I> & { key?: string; hook?: DispatchedBy["hook"] };
+
+/**
+ * The `dispatch` slot of a Pool of runs, as the Pool spawns it (ADR-0017): the same Effect, whose
+ * idempotency key is the item's id — the spawn id — and not its ledger row id. So every Pool, every
+ * hand-over and every restore that gives the same item to the callee Workflow gets the same run
+ * (ADR-0071). The input is {@link PoolWorkerInput}.
+ *
+ * @internal
+ */
+export function poolWorker(logic: EffectLogic<any, DispatchOutput>): EffectLogic<PoolWorkerInput, DispatchOutput> {
+  const keyed = Object.create(
+    Object.getPrototypeOf(logic) as object,
+    Object.getOwnPropertyDescriptors(logic),
+  ) as EffectLogic<PoolWorkerInput, DispatchOutput>;
+  const initial = logic.getInitialSnapshot.bind(logic);
+  keyed.getInitialSnapshot = (scope, input) => {
+    const given = (input ?? { body: undefined }) as PoolWorkerInput;
+    return {
+      ...initial(scope, given.body),
+      key: scope.self.id,
+      ...(given.hook !== undefined ? { hook: given.hook } : {}),
+    } as KeyedSnapshot<DispatchOutput, PoolWorkerInput> as never;
   };
+  return keyed;
 }
 
 // --- The actor logic -----------------------------------------------------------------------------
@@ -418,6 +476,9 @@ async function drive<I, O>(
     mark({ stage: "output", text: `${named}: run ${runId}${existing ? " (the key found it: started before)" : ""}` });
   };
   const deadline = Date.parse(at) + parts.timeoutMs;
+  // A Pool's worker carries the item's id as its key, and the delivery that carried the item
+  // (ADR-0017). Any other dispatch's key is its ledger row id.
+  const { key, hook } = snapshot as KeyedSnapshot<O, I>;
 
   if (prior?.run !== undefined && !parts.wait) {
     // Started before the restart, and the answer is the run: nothing to send.
@@ -440,22 +501,58 @@ async function drive<I, O>(
       await waitIn(prior.run);
       return;
     }
-    // Fresh, or in flight with no run on the row: the key makes a second start the same run.
-    const input = inputOf();
+    // The key first, as the door asks it (ADR-0071): a run of the callee that carries it is
+    // answered before the input is read, so a re-send across a change of the slot's schema answers
+    // `existing`, never an error. The slot's bound holds the lookup as it holds the start.
+    const startBound = prior ? Math.max(deadline, Date.now() + START_FLOOR_MS) : deadline;
+    const asked = host.lookup
+      ? await beforeDeadline(
+          host.lookup(parts.workflow, key ?? id).then((run) => ({ run })),
+          startBound,
+          signal,
+        )
+      : { run: undefined };
+    if (signal.aborted) return;
+    if (asked === undefined) {
+      settle(
+        unknown(
+          `the run host did not answer the start of ${parts.workflow} within the slot's timeout; a run may have started`,
+        ),
+      );
+      return;
+    }
+    const found = asked.run;
+    if (found) {
+      if (!prior) binding.recordEffect?.(id, intent());
+      pin(found.runId, true);
+      if (!parts.wait) {
+        settle({ outcome: "started", run: found.runId });
+        return;
+      }
+      await waitIn(found.runId);
+      return;
+    }
+    // Fresh, or in flight with no run on the row: the key makes a second start the same run. With
+    // the key asked above and no run under it, the body is a first send's, and the slot's schema
+    // refuses it as the invoke's error (ADR-0071). A host with no lookup asks the key at its start.
+    const input = inputOf(prior !== undefined && !host.lookup);
     if (!prior) binding.recordEffect?.(id, intent());
     mark({
       stage: "started",
       text: prior ? `${named} (sent again under its key: a run it started is answered)` : named,
     });
     // The depth is the callee's: one below this run, which the host records as sent (ADR-0071).
-    const by: DispatchedBy = { run: binding.runId, slot, effect: id, depth: (binding.depth ?? 0) + 1 };
+    const by: DispatchedBy = {
+      run: binding.runId,
+      slot,
+      effect: id,
+      depth: (binding.depth ?? 0) + 1,
+      ...(key !== undefined ? { key } : {}),
+      ...(hook !== undefined ? { hook } : {}),
+    };
     // The slot's bound holds the start too (ADR-0071): a run host that does not answer in it is
     // `unknown` — the start may have been taken, and a restore's re-send under the key would find it.
-    const answer = await beforeDeadline(
-      host.start(parts.workflow, input, by),
-      prior ? Math.max(deadline, Date.now() + START_FLOOR_MS) : deadline,
-      signal,
-    );
+    const answer = await beforeDeadline(host.start(parts.workflow, input, by), startBound, signal);
     if (signal.aborted) return;
     if (answer === undefined) {
       settle(
@@ -489,8 +586,13 @@ async function drive<I, O>(
   const port = portFactory(target);
   // The wait's stop goes through this port when its state exits (ADR-0071).
   run.port = port;
+  // The party the start acts for: the first Caller of this run's chain, read once (ADR-0071).
+  const onBehalfOf = onBehalfOfFor(await binding?.firstCaller?.());
+  if (signal.aborted) return;
   // Fresh: nothing was sent. The body is checked before the intent row, so a defect in the input is
-  // the Machine's error and sends nothing.
+  // the Machine's error and sends nothing. A body the slot's schema refuses is sent as a key-only
+  // ask (ADR-0071): the door answers a run under the key, and with none the schema's refusal is the
+  // invoke's error.
   const req = prior ? undefined : requestFor(false);
   const big = req && tooLarge(req);
   if (big) {
@@ -567,18 +669,27 @@ async function drive<I, O>(
     expired();
   }
 
-  /** The run's body: the invoke's input, parsed by the slot's schema when it has one. */
-  function inputOf(): Record<string, unknown> {
+  /** Why the slot's schema refuses the invoke's input, or undefined when it takes it (or the slot
+   * has no schema). */
+  function refusedBody(): string | undefined {
+    if (def.input === undefined) return undefined;
+    const parsed = def.input.safeParse(snapshot.input ?? {});
+    if (parsed.success) return undefined;
+    return (
+      `dispatch "${slot}": its input does not match the slot's input schema — ` +
+      parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")
+    );
+  }
+
+  /** The run's body: the invoke's input, parsed by the slot's schema when it has one. `again`: an
+   * in-process re-send to a run host that asks the key only at its start; a body the slot's schema
+   * refuses then goes as it is, and the run host answers the run under the key (ADR-0071). */
+  function inputOf(again = false): Record<string, unknown> {
     let input: unknown = snapshot.input ?? {};
     if (def.input !== undefined) {
       const parsed = def.input.safeParse(input);
-      if (!parsed.success) {
-        throw new Error(
-          `dispatch "${slot}": its input does not match the slot's input schema — ` +
-            parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "),
-        );
-      }
-      input = parsed.data;
+      if (parsed.success) input = parsed.data;
+      else if (!again) throw new Error(refusedBody());
     }
     if (typeof input !== "object" || input === null || Array.isArray(input)) {
       throw new Error(`dispatch "${slot}": its input is the run's body, a JSON object (ADR-0071)`);
@@ -600,7 +711,9 @@ async function drive<I, O>(
       instance: binding?.orchestratorName ?? "an Orchestrator with no name",
     };
     const timeoutMs = again ? Math.max(1, Math.floor(deadline - Date.now())) : parts.timeoutMs;
-    return dispatchStartOf({ ...parts, timeoutMs }, inputOf(), by);
+    // A body the slot's schema refuses is never sent: the start asks the key alone (ADR-0071).
+    const body = refusedBody() === undefined ? inputOf() : undefined;
+    return dispatchStartOf({ ...parts, timeoutMs }, body, by, onBehalfOf);
   }
 
   /** The in-process wait (ADR-0071): the run host tells when the run leaves `live`; the slot's
@@ -677,6 +790,9 @@ async function drive<I, O>(
       if (state.state === "settled" && state.output) {
         const parsed = DispatchOutputShape.safeParse(state.output);
         if (!parsed.success) throw new EffectorMalformed("the Effector's output for a dispatch is not a dispatch's");
+        // A key-only ask, and no run has the key: nothing was started, and the slot's schema refusal
+        // is the invoke's error (ADR-0071).
+        if (parsed.data.outcome === "absent") throw new Error(refusedBody() ?? "the door found no run under the key");
         const output = parsed.data as DispatchOutput;
         if (output.outcome === "started" || output.outcome === "settled") pin(output.run, false);
         settle(output);

package/src/durability.ts

@@ -18,6 +18,8 @@ export type StoredSnapshot = {
   status: string;
   snapshot: unknown;
   reason?: string;
+  /** When the run started (ADR-0009): the row's `started_at`. */
+  startedAt?: string;
 };
 
 type ChildEntry = { snapshot?: { input?: unknown; [k: string]: unknown }; [k: string]: unknown };

package/src/duration.ts

@@ -0,0 +1,20 @@
+// A duration as a person writes it in config or a query: a number and one unit, such as `"90m"`,
+// `"36h"`, `"30d"` or `"2w"`. `runs.retain` (ADR-0065) and the `since` of `GET /runs` (ADR-0009)
+// read it.
+
+const DURATION = /^(\d+(?:\.\d+)?)(s|m|h|d|w)$/;
+const UNIT_MS: Record<string, number> = {
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 7 * 86_400_000,
+};
+
+/** The duration in milliseconds, or undefined when `text` is not a positive duration. */
+export function periodMs(text: string): number | undefined {
+  const m = DURATION.exec(text.trim());
+  if (!m) return undefined;
+  const ms = Number(m[1]) * UNIT_MS[m[2]!]!;
+  return ms > 0 && Number.isFinite(ms) ? ms : undefined;
+}

package/src/effect-checks.ts

@@ -39,6 +39,7 @@
 import type { AnyStateMachine, UnknownActorLogic } from "xstate";
 import type { EventDef } from "@jr2/agent-protocol";
 import { isAgent } from "./agent.ts";
+import { isGateInvoke } from "./gate-brand.ts";
 import { inputKeysOf, inputShapeOf, isEffect } from "./effect.ts";
 import { mayTake, partiesAt } from "./party.ts";
 import { isAnswer, isPickMapper } from "./pick.ts";
@@ -389,7 +390,7 @@ export function effectChecks(
     const below: Node[] = [];
     const descend = (p: Node): void => {
       for (const child of Object.values(p.states)) {
-        if (invokesAgent(child) !== undefined || child.invoke.some((inv) => inv.src === "gate")) continue;
+        if (invokesAgent(child) !== undefined || child.invoke.some((inv) => isGateInvoke(inv, actors))) continue;
         below.push(child);
         descend(child);
       }