@jr2/orchestrator 0.4.1 → 0.5.1

package/src/effector-wire.ts

@@ -21,11 +21,14 @@ import { z } from "zod";
 
 export const HTTP_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] as const;
 export const HttpMethodShape = z.enum(HTTP_METHODS);
+/** The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`. */
 export type HttpMethod = z.infer<typeof HttpMethodShape>;
 
 /** One part of a string the Effector builds: literal text, or a secret it holds, by name. A
  * secret's value is never on the wire. */
 export const TextPartShape = z.union([z.strictObject({ text: z.string() }), z.strictObject({ secret: z.string() })]);
+/** One part of a {@link Text}: `{ text }`, literal text, or `{ secret }`, the name of an Effect
+ * secret. The `text` template makes the parts. */
 export type TextPart = z.infer<typeof TextPartShape>;
 
 export const WireAuthShape = z.union([
@@ -71,7 +74,8 @@ const HEADER_NAME = /^[a-z0-9!#$%&'*+.^_`|~-]+$/;
 export const isEffectHeader = (name: string): boolean =>
   HEADER_NAME.test(name) && !FRAMING_HEADERS.has(name) && !name.startsWith("proxy-");
 
-/** An `http` start; its body may be a Worktree file (ADR-0067), which only a Sandbox Effector serves. */
+/** An `http` start; its body may be a Worktree file (ADR-0067), which only a Sandbox Effector
+ * serves. */
 export const HttpStartShape = z.strictObject({
   kind: z.literal("http"),
   method: HttpMethodShape,
@@ -103,7 +107,8 @@ export type Pair = z.infer<typeof PairShape>;
 /** A `push` start: the Workspace's branch to the Repo Slot's Binding, with the push credential of
  * the `git.credentials` entry the url falls under — the Effector's config holds the entries, and
  * matches the url as the fence does (`credential` names one by its `match` instead). `pin` is the
- * commit; absent, the Effector reads the Agent's branch tip and its answer carries it (`pinned`). */
+ * commit; absent, the Effector reads the Agent's branch tip and its answer carries it (`pinned`).
+ */
 export const PushStartShape = z.strictObject({
   kind: z.literal("push"),
   push: z.strictObject({
@@ -142,8 +147,71 @@ export const CommandStartShape = z.strictObject({
 });
 export type CommandStartRequest = z.infer<typeof CommandStartShape>;
 
-/** Every start: the http kinds, a push, a credentialed command. */
-export const StartRequestShape = z.union([HttpStartShape, PushStartShape, CommandStartShape]);
+/** A string the Effector builds, as parts (the `text` template's wire form). */
+export const TextShape = z.array(TextPartShape);
+
+/** A secret the Effector holds, by name. */
+export const SecretRefShape = z.strictObject({ secret: z.string() });
+
+/** A Workflow's name as `jr2 run` names it (ADR-0071): a Machine's filename stem, or
+ * `<wrapper>/<name>` for a named Chart. The Go side's `Validate` holds the same rule. */
+export const WORKFLOW_NAME = /^[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)?$/;
+
+/** A dispatch target's origin: a scheme and a host — a DNS name or IPv4 address, or a bracketed
+ * IPv6 address — a port when it is not the scheme's, and no path, query, fragment, userinfo or any
+ * other character no origin has — the Effector appends the door's path (ADR-0071). The Go side's
+ * `origin` is the same rule. */
+export const ORIGIN = /^https?:\/\/(\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9.-]+)(:[0-9]{1,5})?$/;
+
+/**
+ * Which run started a run, and its place in the chain (ADR-0071): the caller's run and slot, the
+ * caller's ledger row id (`effect`, the door's idempotency key), the dispatched run's depth — one
+ * below its caller, stated by the caller and recorded as sent, so at least 1 — and, for a caller
+ * on another Orchestrator, that Instance as opaque text.
+ */
+export const DispatchedByShape = z.strictObject({
+  run: z.string(),
+  slot: z.string(),
+  effect: z.string(),
+  depth: z.number().int().positive(),
+  instance: z.string().optional(),
+});
+
+/**
+ * A `dispatch` start (ADR-0071), which only the Instance Effector serves: a run of `workflow` on the
+ * Orchestrator at `url` (its origin, one text part), the body `input` whole, the Instance token as a
+ * bearer by name, `dispatchedBy` as the `jr2-dispatched-by` header — `instance` set, since the
+ * caller is foreign by construction — and, with `wait`, a poll of `GET /runs/<id>` until the run
+ * ends or `timeoutMs` passes.
+ */
+export const DispatchStartShape = z.strictObject({
+  kind: z.literal("dispatch"),
+  url: TextShape.refine(
+    (parts) => parts.length === 1 && "text" in parts[0]! && ORIGIN.test(parts[0].text),
+    "a dispatch url is one text part, an origin: http(s)://host[:port]",
+  ),
+  workflow: z.string().regex(WORKFLOW_NAME),
+  input: z.record(z.string(), z.unknown()),
+  auth: z.strictObject({ bearer: SecretRefShape }),
+  // Every id non-empty, as the door's header shape requires (http.ts): an empty one would be the
+  // door's 400, which reads as a defect of the input. The effect is a ledger row id, the key. The Go
+  // side's `validateDispatch` holds the same rule.
+  dispatchedBy: DispatchedByShape.extend({
+    run: z.string().min(1),
+    slot: z.string().min(1),
+    effect: z
+      .string()
+      .regex(/^[A-Za-z0-9._-]{1,128}$/)
+      .refine((id) => id !== "." && id !== ".."),
+    instance: z.string().min(1),
+  }),
+  wait: z.boolean(),
+  timeoutMs: z.number().int().positive(),
+});
+export type DispatchStartRequest = z.infer<typeof DispatchStartShape>;
+
+/** Every start: the http kinds, a push, a credentialed command, a dispatch. */
+export const StartRequestShape = z.union([HttpStartShape, PushStartShape, CommandStartShape, DispatchStartShape]);
 export type StartRequest = z.infer<typeof StartRequestShape>;
 
 /** The most bytes of a start's body the Effector reads (its `maxRequestBody`). A longer body
@@ -175,17 +243,68 @@ export const HttpOutputShape = z.union([
   HttpResponseShape,
   z.strictObject({ outcome: z.enum(["unreachable", "refused", "unknown"]), reason: z.string() }),
 ]);
+/**
+ * The output of an `http` Effect: what the `onDone` of its state gets as `event.output`. Every
+ * outcome is output. A 4xx or 5xx status is output too. Route on `outcome`:
+ *
+ * - `response`: an answer came back. `status` is its HTTP status. `headers`, `contentType` and
+ *   `size` tell about the body. `body` is there when the body is text: at most `maxBody` bytes
+ *   (`truncated` is `true` when jr2 cut it). A body that is not text gives only its size and
+ *   content type. jr2 replaces each value of an Effect secret that the Effector holds, and its
+ *   usual encodings, with `[secret:<name>]`, in the body and the headers.
+ * - `unreachable`: the call did not go out, for example because the name did not resolve, or the
+ *   connection or TLS failed. `reason` tells why.
+ * - `refused`: jr2 or the Effector refused the call, and nothing was sent. For example, a path
+ *   segment that is `.`, `..` or empty, or a request that is too large. `reason` tells why.
+ * - `unknown`: the call can have gone out, but no answer came, or jr2 cannot tell after a restart.
+ *   `reason` tells why. jr2 does not send it again unless it is marked `idempotent`.
+ *
+ * @example
+ * ```ts
+ * import { fail, http, jr2Setup, type HttpOutput } from "@jr2/orchestrator";
+ *
+ * const ok = (output: HttpOutput): boolean => output.outcome === "response" && output.status < 300;
+ *
+ * export const machine = jr2Setup({
+ *   actors: { health: http({ method: "GET", url: "https://app.example.com/healthz" }), fail: fail() },
+ * }).createMachine({
+ *   id: "health",
+ *   initial: "checking",
+ *   states: {
+ *     checking: {
+ *       invoke: {
+ *         src: "health",
+ *         onDone: [
+ *           { guard: ({ event }) => ok(event.output), target: "healthy" },
+ *           { target: "unhealthy" },
+ *         ],
+ *       },
+ *     },
+ *     healthy: { type: "final" },
+ *     // Not a final state: the run ends `failed`, and `jr2 run` exits 1.
+ *     unhealthy: { invoke: { src: "fail", input: { reason: "the app is not healthy" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/concepts/effects.md
+ * @see docs/guides/run-a-command-or-call-a-url.md
+ * @see docs/reference/decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md
+ */
 export type HttpOutput = z.infer<typeof HttpOutputShape>;
 
 /**
  * A `push` Effect's output (ADR-0067). `pushed`: the published commit, its source (the Agent's
  * commit), what the remote held before, how the new commits were found after a signed push
- * (`ancestry | pair | cherry | force`), `unchanged` when the remote held it already, `squashed`
- * when the published commit is one squashed commit (`signed | unsigned`; absent for signed
- * copies; what the published commit is, an earlier push's included, never only this push's
- * options), and — when the published commit is not the Agent's own — the published commits as a
- * bundle for the sync. `rejected`: a stage and git's words. `diverged`: the
- * published commit is not in the Agent's history and nothing paired it; nothing was pushed.
+ * (`ancestry | pair | cherry | force`), `unchanged` when the remote held it already, `newCommits`
+ * (how many commits the published commit adds to what jr2 found held, the remote's branch and the
+ * Repo cache; 0 when jr2 found the published commit already held, which the Agent reads in words,
+ * menu.ts), `squashed` when the published
+ * commit is one squashed commit (`signed | unsigned`; absent for signed copies; what the published
+ * commit is, an earlier push's included, never only this push's options), and — when the published
+ * commit is not the Agent's own — the published commits as a bundle for the sync. `rejected`: a
+ * stage and git's words. `diverged`: the published commit is not in the Agent's history and
+ * nothing paired it; nothing was pushed.
  */
 export const PushOutputShape = z.union([
   z.strictObject({
@@ -195,6 +314,9 @@ export const PushOutputShape = z.union([
     previous: z.string().optional(),
     via: z.string().optional(),
     unchanged: z.boolean().optional(),
+    // Optional: a live Sandbox keeps the runtime it started with (ADR-0037), so its older Effector
+    // sends no count after `jr2 up`. With no count the Harness makes no claim (menu.ts).
+    newCommits: z.number().int().nonnegative().optional(),
     squashed: z.enum(["signed", "unsigned"]).optional(),
     bundle: z.string().optional(),
   }),
@@ -207,6 +329,7 @@ export const PushOutputShape = z.union([
   z.strictObject({ outcome: z.literal("diverged"), reason: z.string(), published: z.string(), source: z.string() }),
   z.strictObject({ outcome: z.literal("unknown"), reason: z.string() }),
 ]);
+/** @internal */
 export type PushWireOutput = z.infer<typeof PushOutputShape>;
 
 /** A credentialed command's output, as the command kind's (ADR-0067), and `dirty` when the
@@ -233,6 +356,29 @@ export const CommandOutputShape = z.union([
 ]);
 export type CommandWireOutput = z.infer<typeof CommandOutputShape>;
 
+/**
+ * A `dispatch` Effect's output on the wire (ADR-0071): its own outcome set. `settled.status` is the
+ * callee's status as the door served it, in the store's words, and `output` the callee Machine's,
+ * passed through scrubbed; `refused` is the door's status and its report, told from an http
+ * `refused` (which has a `reason`) by its fields.
+ */
+export const DispatchOutputShape = z.discriminatedUnion("outcome", [
+  z.strictObject({ outcome: z.literal("started"), run: z.string() }),
+  z.strictObject({
+    outcome: z.literal("settled"),
+    run: z.string(),
+    // The store's words (ADR-0025) and the timeout's `live`, as `DispatchOutput` types them for the
+    // Machine: a door that serves another word (another Kit version) is a malformed answer, the
+    // invoke's error, never a status the Machine's type does not name (ADR-0071).
+    status: z.enum(["done", "failed", "error", "cancelled", "lost", "drifted", "live"]),
+    output: z.unknown().optional(),
+  }),
+  z.strictObject({ outcome: z.literal("refused"), status: z.number().int(), report: z.array(z.string()) }),
+  z.strictObject({ outcome: z.literal("unreachable"), reason: z.string() }),
+  z.strictObject({ outcome: z.literal("unknown"), reason: z.string() }),
+]);
+export type DispatchWireOutput = z.infer<typeof DispatchOutputShape>;
+
 /** The replica that holds an Effect, and where to poll it. */
 export const ReplicaShape = z.strictObject({ name: z.string(), address: z.string() });
 export type Replica = z.infer<typeof ReplicaShape>;
@@ -245,7 +391,10 @@ export const EffectStateShape = z.strictObject({
   /** The commit a push or a credentialed command runs against, read when it started: the
    * Orchestrator writes it to the ledger's intent row. */
   pinned: z.string().optional(),
-  output: z.union([HttpOutputShape, PushOutputShape, CommandOutputShape]).optional(),
+  /** The run a dispatch started, once the door answered and while its wait runs: the Orchestrator
+   * writes it to the ledger's intent row, so the caller names its callee during the wait (ADR-0071). */
+  run: z.string().optional(),
+  output: z.union([HttpOutputShape, PushOutputShape, CommandOutputShape, DispatchOutputShape]).optional(),
 });
 export type EffectState = z.infer<typeof EffectStateShape>;
 

package/src/fail.ts

@@ -0,0 +1,209 @@
+// The `fail()` Part (ADR-0073): the end that a Machine chooses for work that did not succeed — a
+// Failure (GLOSSARY.md). It is a Part and not an Effect, because it does no work outside the
+// Machine: its actor throws an error that carries a brand, and xstate sends that error up through
+// each parent Machine by its own rules. An `onError` on the way catches it; `isFailure` tells it
+// from a defect. When no state catches it, the run host ends the run `failed`.
+//
+// The brand is a registry symbol (`Symbol.for`), not a module symbol, for the reason the walk is
+// structural (parts.ts): an Instance resolves its OWN `@jr2/orchestrator`, so the copy that throws
+// and the copy that reads the error (the run host, the CLI's walk) can be two module instances. The
+// brand is not exported: an author makes a Failure only with `fail()`.
+
+import { fromPromise, type PromiseActorLogic } from "xstate";
+
+const FAILURE: unique symbol = Symbol.for("jr2.failure") as never;
+const FAIL_SLOT: unique symbol = Symbol.for("jr2.fail.slot") as never;
+
+/** What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine
+ * reader. The input of `fail()` and the output of a run that ends `failed`. */
+export type FailureInput = { reason: string; detail?: unknown };
+
+/** A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself. */
+export type Failure = { readonly reason: string; readonly detail?: unknown };
+
+/** Make the branded error. Only this module makes one. */
+function failure(input: FailureInput): Error & Failure {
+  const error = new Error(input.reason) as Error & Failure & { [FAILURE]: true };
+  error.name = "Failure";
+  Object.defineProperty(error, "reason", { value: input.reason, enumerable: true });
+  if (input.detail !== undefined) Object.defineProperty(error, "detail", { value: input.detail, enumerable: true });
+  Object.defineProperty(error, FAILURE, { value: true });
+  return error;
+}
+
+/** Refuse an input that is not a Failure's. A defect of the Machine, not a Failure: it ends the run
+ * `error`, with this text as the fault. */
+function checked(raw: unknown): FailureInput {
+  const input = raw as Partial<FailureInput> | undefined;
+  if (typeof input !== "object" || input === null || typeof input.reason !== "string" || input.reason === "") {
+    throw new Error(
+      `fail: the input must be { reason: string; detail?: unknown } with a reason that is not empty (got ${describe(raw)}) — ` +
+        `invoke: { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)`,
+    );
+  }
+  return input.detail === undefined ? { reason: input.reason } : { reason: input.reason, detail: input.detail };
+}
+
+function describe(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** The actor logic that throws. Unbranded: what `workspace()` invokes to send a caught Failure up
+ * again, which is the wrapper's mechanism and no state of the author's that fails the run. */
+export const failLogic: PromiseActorLogic<never, FailureInput> = fromPromise<never, FailureInput>(async ({ input }) => {
+  throw failure(checked(input));
+});
+
+/** The logic `fail()` returns: {@link failLogic} with the brand the walk reads. */
+export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL_SLOT]: true };
+
+/**
+ * Fail the run: the Part a Machine invokes to end work that did not succeed. Put it in `actors`
+ * under a name, and invoke it from any state, at any depth: `actors: { fail: fail() }`, then
+ * `invoke: { src: "fail", input: { reason } }`.
+ *
+ * The input is `{ reason: string; detail?: unknown }`. `reason` is text for a person, and it must
+ * not be empty. `detail` is optional JSON for a machine reader.
+ *
+ * The Failure goes up from the state that invokes `fail`, through each parent Machine, as an error
+ * does. An `onError` on the way catches it; {@link isFailure} tells it from a defect. When no state
+ * catches it, the run ends `failed`: its output is `{ reason, detail }`, and `jr2 run` exits 1. A
+ * `workspace()` that a Failure goes through deletes its Sandbox first.
+ *
+ * To fail, invoke `fail`. Do not throw from a promise to fail: a throw is a defect, and the run
+ * ends `error`. A final state means `done`: do not use one for work that did not succeed. To keep
+ * the work for a person to read, wait at a Gate before the state that fails.
+ *
+ * It refuses an input that is not a Failure's, and the run ends `error`: ``fail: the input must be
+ * { reason: string; detail?: unknown } with a reason that is not empty (got <value>) — invoke:
+ * { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)``.
+ *
+ * @returns The actor logic of the slot.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ branch: z.string() });
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+ *   actors: {
+ *     tests: command(["npm", "test"], { timeout: "15m" }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "check",
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "testing",
+ *   states: {
+ *     testing: {
+ *       invoke: {
+ *         src: "tests",
+ *         onDone: [
+ *           {
+ *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+ *             target: "passed",
+ *           },
+ *           { target: "failing" },
+ *         ],
+ *       },
+ *     },
+ *     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
+ *     failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+ *     passed: { type: "final" },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   input: runInput,
+ *   repos: { app: "https://github.com/you/app.git" },
+ *   spec: ({ input }) => ({ branch: input.branch }),
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md
+ */
+export function fail(): FailSlot {
+  // Logic of its own per slot, so the brand is on this slot's logic and on no other's.
+  const logic = fromPromise<never, FailureInput>(async ({ input }) => {
+    throw failure(checked(input));
+  });
+  return Object.defineProperty(logic, FAIL_SLOT, { value: true }) as FailSlot;
+}
+
+/** Is this actor logic a `fail()` slot? A test on the brand, like `isAgent`: what the walk reads to
+ * list each state that can fail the run (ADR-0073). */
+export function isFailSlot(logic: unknown): logic is FailSlot {
+  return typeof logic === "object" && logic !== null && (logic as { [FAIL_SLOT]?: unknown })[FAIL_SLOT] === true;
+}
+
+/**
+ * Is this error a Failure, which a state invoked `fail` to make? A defect — any other error — is
+ * not. Use it in the guard of an `onError` to catch a Failure and let a defect go up, and read the
+ * Failure's `reason` and `detail` from the error it narrows.
+ *
+ * @param error - The error of an error event: `event.error` in an `onError`.
+ * @returns True for a Failure, with `error` narrowed to `{ reason, detail? }`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { defineEvent, fail, isFailure, jr2Setup } from "@jr2/orchestrator";
+ *
+ * const retry = defineEvent({ name: "retry", description: "Try the plan again.", input: z.object({}) });
+ *
+ * const attempt = jr2Setup({ actors: { fail: fail() } }).createMachine({
+ *   id: "attempt",
+ *   initial: "stuck",
+ *   states: { stuck: { invoke: { src: "fail", input: { reason: "no plan fits the ticket" } } } },
+ * });
+ *
+ * export const machine = jr2Setup({ events: [retry], actors: { attempt } }).createMachine({
+ *   id: "planner",
+ *   initial: "planning",
+ *   states: {
+ *     planning: {
+ *       invoke: {
+ *         src: "attempt",
+ *         onDone: "planned",
+ *         // A Failure waits for a person; a defect has no route, so it goes up and the run ends `error`.
+ *         onError: { guard: ({ event }) => isFailure(event.error), target: "asking" },
+ *       },
+ *     },
+ *     asking: { invoke: { src: "gate" }, on: { retry: "planning" } },
+ *     planned: { type: "final" },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md
+ */
+export function isFailure(error: unknown): error is Failure {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { [FAILURE]?: unknown })[FAILURE] === true &&
+    typeof (error as { reason?: unknown }).reason === "string"
+  );
+}
+
+/** The name of the guard that every Chart has (ADR-0070, ADR-0073): {@link isFailure} on the
+ * event's `error`, so a Chart's `onError` can tell a Failure from a defect. It is a predicate and
+ * gives no capability, so it is never lent, as `jr2.sentBy` is not. */
+export const FAILURE_GUARD = "jr2.failure";
+
+/** The implementation of {@link FAILURE_GUARD}: true when the event's `error` is a Failure. */
+export const failureGuard = ({ event }: { event: { error?: unknown } }): boolean => isFailure(event.error);
+
+/** A Failure's payload as plain JSON data: what a failed run's output is, and what `workspace()`
+ * keeps to send it up again. */
+export function failurePayload(error: Failure): FailureInput {
+  return error.detail === undefined ? { reason: error.reason } : { reason: error.reason, detail: error.detail };
+}