@jr2/orchestrator 0.4.1 → 0.6.0

package/src/door-compat.ts

@@ -0,0 +1,217 @@
+// A dispatch's slot schema against its callee's door (ADR-0071): the comparison `jr2 up` and the
+// publish door make before any run starts. A match is COMPATIBILITY, one direction: every field the
+// door requires is one the slot's schema always sends, with a compatible type, values and bounds,
+// and every field of the slot's schema is in the door, since a plain zod door strips the rest
+// silently. Equality is not asked: a slot may narrow what the door takes, never widen it.
+//
+// It compares within the JSON Schema subset ADR-0070 names (`PAYLOAD_KEYWORDS`, chart.ts). A schema
+// that uses anything outside it (`oneOf`, `$ref`, `pattern`, `format`) is "not compared", never
+// guessed at: a guess that says "ok" hides the mismatch it was asked for, and one that says
+// "mismatch" refuses a publish that would run.
+//
+// Pure, and over two JSON Schemas only: the slot's is `z.toJSONSchema(input, { io: "output" })`
+// (what the driver sends, its defaults filled), the door's is what `GET /workflows/<name>` serves (run-host.ts `inputSchema`), so a foreign door
+// at another Kit version is compared by the same rules as this Assembly's own.
+
+import { doorSchemaFaults } from "./chart.ts";
+
+/** The comparison's answer: compatible; the faults that make it not, each naming the field; or not
+ * compared, with why. */
+export type DoorCompat = { ok: true } | { ok: false; faults: string[] } | { ok: "not-compared"; why: string };
+
+type Schema = Record<string, unknown>;
+
+/**
+ * Is a slot's input schema compatible with a door (ADR-0071)? `door` null is a door that declares
+ * no input (a run of it starts with anything): every slot is compatible with it.
+ */
+export function doorCompat(slot: unknown, door: unknown): DoorCompat {
+  if (door === null) return { ok: true };
+  slot = withoutDefaults(slot);
+  door = withoutDefaults(door);
+  for (const [whose, schema] of [
+    ["the slot's input schema", slot],
+    ["the door", door],
+  ] as const) {
+    const fault = doorSchemaFaults(schema)[0];
+    if (fault) {
+      const at = fault.path.length ? `${fault.path.map(String).join(".")}: ` : "";
+      return { ok: "not-compared", why: `${whose} is outside the subset jr2 compares — ${at}${fault.message}` };
+    }
+  }
+  const faults: string[] = [];
+  compareValue(slot as Schema, door as Schema, "", faults);
+  return faults.length ? { ok: false, faults } : { ok: true };
+}
+
+/** Compare two object schemas at `at` (a field path, "" at the root), one direction. */
+function compareObject(slot: Schema, door: Schema, at: string, faults: string[]): void {
+  const slotProps = propsOf(slot);
+  const doorProps = propsOf(door);
+  const required = Array.isArray(door.required) ? (door.required as unknown[]).map(String) : [];
+  const sent = new Set(Array.isArray(slot.required) ? (slot.required as unknown[]).map(String) : []);
+  for (const field of required) {
+    if (slotProps[field] === undefined) {
+      faults.push(`the door requires "${join(at, field)}", which the slot's input schema does not have`);
+    } else if (!sent.has(field)) {
+      // The slot's schema is what the driver sends after its parse (`io: "output"`), so a
+      // defaulted field is required there: optional means a body may leave it out.
+      faults.push(`the door requires "${join(at, field)}", which the slot's input schema leaves optional`);
+    }
+  }
+  // Every field both have is compared, the door's required ones among them.
+  const extra = door.additionalProperties;
+  for (const [field, sub] of Object.entries(slotProps)) {
+    const name = join(at, field);
+    const theirs = doorProps[field];
+    if (theirs !== undefined) {
+      compareValue(sub, theirs, name, faults);
+      continue;
+    }
+    // A door that takes any field (`additionalProperties: {}` or `true`) keeps the slot's extra one;
+    // a catchall door (`additionalProperties: <schema>`) keeps it when its value fits.
+    if (isOpen(extra)) continue;
+    if (isSchema(extra)) {
+      compareValue(sub, extra, name, faults);
+      continue;
+    }
+    faults.push(
+      extra === false
+        ? `the slot's field "${name}" is not in the door, which refuses it`
+        : `the slot's field "${name}" is not in the door, which strips it silently`,
+    );
+  }
+}
+
+/** Compare one field's schemas: the type, the values an `enum` or a `const` allows, the bounds,
+ * then `items` and nested `properties`, by the same rules. A door node that states none of these
+ * takes any value (`z.unknown()`, `z.any()`), and every slot is compatible with it. */
+function compareValue(slot: Schema, door: Schema, at: string, faults: string[]): void {
+  const theirs = typesOf(door);
+  const ours = typesOf(slot);
+  if (theirs !== undefined) {
+    if (ours === undefined) {
+      faults.push(`${label(at)}: the door takes ${theirs.join(" or ")}, and the slot's input schema takes any value`);
+      return;
+    }
+    const outside = ours.filter((t) => !theirs.includes(t) && !(t === "integer" && theirs.includes("number")));
+    if (outside.length) {
+      faults.push(`${label(at)}: the slot sends ${ours.join(" or ")}, and the door takes ${theirs.join(" or ")}`);
+      return;
+    }
+  }
+  const allowed = valuesOf(door);
+  const sent = valuesOf(slot);
+  if (allowed !== undefined) {
+    const list = allowed.map((v) => JSON.stringify(v)).join(", ");
+    if (sent === undefined) {
+      faults.push(`${label(at)}: the door takes only ${list}, and the slot's input schema does not narrow to them`);
+    } else {
+      const extra = sent.filter((v) => !allowed.some((a) => same(a, v)));
+      if (extra.length) {
+        faults.push(
+          `${label(at)}: the slot may send ${extra.map((v) => JSON.stringify(v)).join(", ")}, which the door does ` +
+            `not take (it takes ${list})`,
+        );
+      }
+    }
+  }
+  compareBounds(slot, door, at, faults);
+  const may = (type: string): boolean => ours === undefined || ours.includes(type);
+  if (isSchema(door.items) && !isOpen(door.items) && may("array")) {
+    compareValue(isSchema(slot.items) ? slot.items : {}, door.items, `${at}[]`, faults);
+  }
+  const objectDoor =
+    isSchema(door.properties) || (theirs?.includes("object") ?? false) || door.additionalProperties !== undefined;
+  if (objectDoor && may("object")) compareObject(slot, door, at, faults);
+}
+
+/** The bounds, one direction: the slot's range lies inside the door's, so a bound the door sets
+ * and the slot does not is a fault, as is a slot bound wider than the door's. */
+function compareBounds(slot: Schema, door: Schema, at: string, faults: string[]): void {
+  const pairs: Array<[string, string | undefined, "lower" | "upper"]> = [
+    ["minimum", "exclusiveMinimum", "lower"],
+    ["maximum", "exclusiveMaximum", "upper"],
+    ["minLength", undefined, "lower"],
+    ["maxLength", undefined, "upper"],
+    ["minItems", undefined, "lower"],
+    ["maxItems", undefined, "upper"],
+  ];
+  for (const [inclusive, exclusive, side] of pairs) {
+    const theirs = boundOf(door, inclusive, exclusive);
+    if (theirs === undefined) continue;
+    const ours = boundOf(slot, inclusive, exclusive);
+    const fits =
+      ours !== undefined &&
+      (side === "lower"
+        ? ours.value > theirs.value || (ours.value === theirs.value && (ours.exclusive || !theirs.exclusive))
+        : ours.value < theirs.value || (ours.value === theirs.value && (ours.exclusive || !theirs.exclusive)));
+    if (fits) continue;
+    faults.push(
+      `${label(at)}: the door takes ${theirs.keyword} ${theirs.value}, and the slot's input schema ` +
+        (ours === undefined ? "sets no such bound" : `allows ${ours.keyword} ${ours.value}`),
+    );
+  }
+}
+
+type Bound = { value: number; exclusive: boolean; keyword: string };
+
+/** A schema's bound on one side: the tighter of its inclusive and exclusive keyword, if any. */
+function boundOf(schema: Schema, inclusive: string, exclusive: string | undefined): Bound | undefined {
+  const inc = typeof schema[inclusive] === "number" ? (schema[inclusive] as number) : undefined;
+  const exc =
+    exclusive !== undefined && typeof schema[exclusive] === "number" ? (schema[exclusive] as number) : undefined;
+  if (inc === undefined && exc === undefined) return undefined;
+  if (exc === undefined) return { value: inc!, exclusive: false, keyword: inclusive };
+  if (inc === undefined) return { value: exc, exclusive: true, keyword: exclusive! };
+  const lowerSide = inclusive.startsWith("min");
+  const excTighter = lowerSide ? exc >= inc : exc <= inc;
+  return excTighter
+    ? { value: exc, exclusive: true, keyword: exclusive! }
+    : { value: inc, exclusive: false, keyword: inclusive };
+}
+
+function propsOf(schema: Schema): Record<string, Schema> {
+  const props = schema.properties;
+  if (!isSchema(props)) return {};
+  return Object.fromEntries(Object.entries(props).filter(([, v]) => isSchema(v))) as Record<string, Schema>;
+}
+
+/** A schema's types, as a list; undefined when it states none (any value). */
+function typesOf(schema: Schema): string[] | undefined {
+  const t = schema.type;
+  if (typeof t === "string") return [t];
+  if (Array.isArray(t)) return t.map(String);
+  return undefined;
+}
+
+/** The values a schema allows by `enum` or `const`; undefined when it lists none. */
+function valuesOf(schema: Schema): unknown[] | undefined {
+  if (Array.isArray(schema.enum)) return schema.enum as unknown[];
+  if (Object.hasOwn(schema, "const")) return [schema.const];
+  return undefined;
+}
+
+/**
+ * The schema without its `default`s, at every depth. A default is an annotation: it changes no
+ * value a schema takes (a defaulted field is already optional in `io: "input"`), so leaving it out
+ * guesses nothing, and a door with a defaulted field — common — is compared, not skipped.
+ */
+function withoutDefaults(schema: unknown): unknown {
+  if (!isSchema(schema)) return schema;
+  const { default: _default, ...rest } = schema;
+  const out: Schema = { ...rest };
+  // Schema nodes only: a field NAMED "default" under `properties` stays.
+  if (isSchema(rest.properties)) {
+    out.properties = Object.fromEntries(Object.entries(rest.properties).map(([k, v]) => [k, withoutDefaults(v)]));
+  }
+  if (rest.items !== undefined) out.items = withoutDefaults(rest.items);
+  if (rest.additionalProperties !== undefined) out.additionalProperties = withoutDefaults(rest.additionalProperties);
+  return out;
+}
+
+const isSchema = (v: unknown): v is Schema => typeof v === "object" && v !== null && !Array.isArray(v);
+const isOpen = (v: unknown): boolean => v === true || (isSchema(v) && Object.keys(v).length === 0);
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+const join = (at: string, field: string): string => (at ? `${at}.${field}` : field);
+const label = (at: string): string => (at ? `"${at}"` : "the body");

package/src/durability.ts

@@ -84,13 +84,13 @@ export function hydrateSnapshot(
  * twin of `AgentAdmission` — kept import-free so this codec module stays a pure leaf.
  * `instanceId` is the actor's live-conversation stamp (a runaway reroll advances it past the
  * ledger key — ADR-0035); it rides the rewrite verbatim so the restored actor re-addresses the
- * live conversation. */
-type Admission = { streamUrl: string; offset: string; submissionId: string; instanceId?: string };
+ * live conversation. `turnId` is the Turn that ledgered it (see `reattachAgentRuns`). */
+type Admission = { streamUrl: string; offset: string; submissionId: string; instanceId?: string; turnId?: string };
 
 /** A persisted Agent child input: `instanceId` (the durable handle) beside `agentName` —
  * both strings by construction (machine children carry neither at top level; `endpoint` can no
  * longer identify it, being ambient-optional since ADR-0016). */
-function isAgentRunInput(input: unknown): input is { instanceId: string; agentName: string } {
+function isAgentRunInput(input: unknown): input is { instanceId: string; agentName: string; turnId?: string } {
   return (
     !!input &&
     typeof input === "object" &&
@@ -107,6 +107,12 @@ function isAgentRunInput(input: unknown): input is { instanceId: string; agentNa
  * context leg). An instanceId with no recorded admission re-admits its prompt — a run that
  * crashed before its admission was ledgered is the same first-turn at-most-once edge as before
  * (ADR-0007), narrowed to the send→record window.
+ *
+ * The key is not the Turn: two Turns that continue one conversation share the iid, and nothing
+ * removes a Turn's entry when it ends. So an admission re-attaches only the Turn that ledgered it —
+ * its `turnId` equals the input's. A crash after the next Turn's state was saved, and before its
+ * admission was ledgered, finds the earlier Turn's admission under the key; that Turn is not this
+ * one, so the input keeps its prompt and the restore admits it.
  */
 export function reattachAgentRuns(snapshot: unknown, admissions: Record<string, Admission>): unknown {
   const walk = (node: unknown): unknown => {
@@ -114,7 +120,8 @@ export function reattachAgentRuns(snapshot: unknown, admissions: Record<string,
     const src = node as AnySnapshot & { input?: unknown };
     const out: typeof src = { ...src };
 
-    const admission = isAgentRunInput(src.input) ? admissions[src.input.instanceId] : undefined;
+    const ledgered = isAgentRunInput(src.input) ? admissions[src.input.instanceId] : undefined;
+    const admission = isAgentRunInput(src.input) && ledgered?.turnId === src.input.turnId ? ledgered : undefined;
     if (isAgentRunInput(src.input) && admission !== undefined) {
       out.input = { ...src.input, prompt: undefined, attach: admission };
     }

package/src/effect-checks.ts

@@ -27,6 +27,11 @@
 //     Agent reads the Effect's output, not the answer. Everywhere else a settled child with no
 //     `onDone` is Rest, and the one-line form is correct — silent on purpose.
 //
+//   - AN onDone WITH NO LAST ARM (ADR-0075, `refuseUnroutedOutcome`). Each Effect outcome is open,
+//     so an `onDone` that an output can miss holds the run in the state and shows no fault. A type
+//     cannot see the missing arm, so the walk refuses it. No `onDone` at all is Rest, as above: the
+//     author routes nothing, so no outcome can miss a route.
+//
 // The probe reads, it never runs work: a mapper is called with a Proxy event whose reads are
 // recorded, and a context and self that survive any read. A guard and an assign are pure by
 // contract, and only they are probed; any other action may do work, and is never run.
@@ -34,12 +39,43 @@
 import type { AnyStateMachine, UnknownActorLogic } from "xstate";
 import type { EventDef } from "@jr2/agent-protocol";
 import { isAgent } from "./agent.ts";
-import { inputKeysOf, isEffect } from "./effect.ts";
+import { inputKeysOf, inputShapeOf, isEffect } from "./effect.ts";
 import { mayTake, partiesAt } from "./party.ts";
 import { isAnswer, isPickMapper } from "./pick.ts";
 
 type Node = AnyStateMachine["root"];
 
+/**
+ * Refuse a Machine with a state that invokes an Effect when the last arm of that `onDone` has a
+ * guard (ADR-0075). The slots are the Machine's own `actors`. Thrown at build by
+ * `jr2Setup.createMachine`, so also at a Chart's door, and at load by `partsOf`, so a Machine built
+ * with xstate's own `createMachine` is refused where `jr2 check`, `jr2 up` and the Orchestrator read
+ * it. Throws one line that names each state and the arm to write.
+ */
+export function refuseUnroutedOutcome(machine: AnyStateMachine): void {
+  const actors = (machine.implementations.actors ?? {}) as Record<string, unknown>;
+  const unrouted: string[] = [];
+  const visit = (node: Node): void => {
+    for (const inv of node.invoke) {
+      if (typeof inv.src !== "string" || !isEffect(actors[inv.src])) continue;
+      const arms = node.transitions.get(`xstate.done.actor.${inv.id}`);
+      if (arms !== undefined && (arms.length === 0 || arms.at(-1)!.guard !== undefined)) {
+        unrouted.push(`"${node.id}" (Effect "${inv.src}")`);
+      }
+    }
+    for (const child of Object.values(node.states)) visit(child);
+  };
+  visit(machine.root);
+  if (!unrouted.length) return;
+  const many = unrouted.length > 1;
+  throw new Error(
+    `machine "${machine.id}": ${many ? "states" : "state"} ${unrouted.join(", ")} ${many ? "have" : "has"} an ` +
+      `onDone with no unguarded last arm — an Effect's outcomes are open, and an output that no arm matches holds ` +
+      `the run in that state with no fault: add a last arm with no guard, as onDone: [..., { target: "<the state ` +
+      `that handles the rest>" }] (ADR-0075)`,
+  );
+}
+
 /** What the walk found: refusals, and warnings. */
 export type EffectFindings = { errors: string[]; warnings: string[] };
 
@@ -47,6 +83,7 @@ export function effectChecks(
   machine: AnyStateMachine,
   actors: Record<string, UnknownActorLogic>,
   defs: Map<string, EventDef>,
+  chart = false,
 ): EffectFindings {
   const errors: string[] = [];
   const warnings: string[] = [];
@@ -220,6 +257,15 @@ export function effectChecks(
       };
     });
     const effects = invokes.filter((inv) => inv.effect !== undefined);
+    // xstate's `input` is optional for an actor: a kit Effect that takes a key refuses an invoke
+    // with no input when `jr2Setup` or `customize()` builds the Machine.
+    for (const inv of effects) {
+      const shape = inputShapeOf(inv.effect!);
+      const needs = [...(shape?.required ?? []), ...(shape?.oneOf ?? [])];
+      if (inv.mapper === undefined && needs.length > 0) {
+        errors.push(`state "${n.id}": Effect "${inv.slot}" has no \`input\`, and it takes ${needs.join(", ")}`);
+      }
+    }
     if (!effects.length) continue;
     const at = `state "${n.id}" (Effect${effects.length > 1 ? "s" : ""} ${effects.map((e) => `"${e.slot}"`).join(", ")})`;
     for (const [event, { pick, ...reads }] of entering.get(n) ?? []) {
@@ -276,7 +322,8 @@ export function effectChecks(
             });
           } catch (err) {
             probed = false;
-            warnings.push(`${own}: could not probe the input mapper (${messageOf(err)}); its params are unchecked`);
+            if (!chart)
+              warnings.push(`${own}: could not probe the input mapper (${messageOf(err)}); its params are unchecked`);
           }
         }
       }
@@ -289,7 +336,7 @@ export function effectChecks(
       const picked = effects.filter((e) => isPickMapper(e.mapper));
       if (probed && lost.length && probe.unrun.length) {
         // Any other action may do work, so the probe never runs one; it may read the param.
-        warnings.push(unrunWarning(where, lost, probe.unrun));
+        if (!chart) warnings.push(unrunWarning(where, lost, probe.unrun));
       } else if (probed && lost.length && picked.length) {
         const inputs =
           picked.length === 1