@jr2/orchestrator 0.1.0

package/src/machine-doc.ts

@@ -0,0 +1,334 @@
+// Serialize a workflow's Machine for the Console (`GET /workflows/:name/machine`). Walks the
+// live StateNode tree (`machine.root`) rather than `machine.definition`/`toJSON()` — those carry
+// entry/exit actions and output mappers as functions, which don't survive JSON. The DTO here is
+// pure data: the nested state tree drives the renderer's containment, the flat transition list its
+// edges. Structure doesn't depend on which actors fill the named slots, so the registered Machine
+// (before any test-seam `.provide()` — ADR-0015) is the right thing to serialize.
+//
+// A workflow's real work usually happens in CHILD machines (`coding`'s whole feature pipeline is a
+// `spawnChild`), so the walk descends into them too — one `MachineBodyDoc` per child, attached to
+// the state that runs it. Each carries the `src` a live child actor reports, which is how the page
+// hangs run state under the right subgraph.
+//
+// Vocabulary is attributed the same way: each `MachineBodyDoc` carries the events ITS Machine
+// declares (ADR-0011, ADR-0049), never one flattened root list. Two Machines in one doc may
+// declare the same name with different payloads — that is legal, and only a per-Machine listing
+// can report it honestly.
+
+import type { AnyStateMachine, StateNode, TransitionDefinition } from "xstate";
+import { z } from "zod";
+import type { EventAudience } from "@jr2/agent-protocol";
+import { vocabularyOf } from "./vocabulary.ts";
+
+/** One transition of the Machine, id-addressed at both ends. */
+export type MachineTransitionDoc = {
+  /** Source state id. */
+  source: string;
+  /** Target state ids; empty = targetless (self/internal) transition. */
+  targets: string[];
+  /** The raw event descriptor (`""` for always/eventless). */
+  event: string;
+  /** Display label, precomputed here so the renderer stays dumb. */
+  label: string;
+  /** Normalized guard name, if guarded. */
+  guard?: string;
+  kind: "event" | "always" | "after" | "done" | "error";
+};
+
+/** One state of the Machine; `states` nests in document order. */
+export type MachineStateDoc = {
+  /** Unique state id (custom `id:` respected). */
+  id: string;
+  /** Relative key — the segment that appears in a run's `status.value`. */
+  key: string;
+  type: "atomic" | "compound" | "parallel" | "final" | "history";
+  /** Initial child state id (compound only). */
+  initial?: string;
+  invoke: Array<{ id: string; src: string }>;
+  tags: string[];
+  description?: string;
+  states: MachineStateDoc[];
+  /** The child MACHINES this state runs — invoked ones (a subset of `invoke`, which stays the
+   * complete invocation list) plus spawned ones (which appear nowhere else). See
+   * {@link ChildMachineDoc}. A promise/callback actor has no state tree, so it is never here. */
+  children: ChildMachineDoc[];
+  /**
+   * This state runs an `enqueueActions` closure, so THIS STATE'S `children` MAY BE INCOMPLETE.
+   *
+   * Spawning is an action, and `spawnChild` is the only static trace it leaves (see
+   * {@link spawnedSrcs}). A spawn issued as `enqueue.spawnChild(...)` inside a closure resolves at
+   * runtime — it can be conditional, looped, or have a computed `src` — so no amount of static
+   * analysis recovers it, and the subgraph beneath it would simply be absent from the diagram while
+   * the machine ran correctly. That silence is the hazard, not the omission: it once erased the
+   * whole feature pipeline of a multi-stage Machine with no signal at all. So the doc carries the
+   * fact it cannot see, and callers say so out loud (`opaqueStates`, surfaced on the page).
+   */
+  opaqueActions?: boolean;
+};
+
+/**
+ * A child Machine reached from a state — the pipeline a workflow delegates to, which is most of
+ * what it DOES. Attached to the state that runs it, so the renderer nests it where it belongs.
+ *
+ * `src` is the JOIN KEY: it is exactly the `src` a live child actor reports (`RunChild.src`), for
+ * both kinds — a named actor keeps its name (`"body"`, `"worker"`, `"featureWorkspace"`), an inline
+ * machine object gets xstate's generated key (`"xstate.invoke.0.wrapper.running"`) on both sides.
+ * That is what lets the page hang a run's live child state under the right subgraph without the two
+ * halves agreeing on anything but this string. Since ADR-0049 every kit wrapper names its child, so
+ * the generated key is an author's shape only.
+ */
+export type ChildMachineDoc = {
+  /** The join key — matches a live `RunChild.src` exactly. */
+  src: string;
+  /** Display name: the invoke id (`"body"`) or the spawned actor's name (`"featureWorkspace"`). */
+  label: string;
+  /** How the state reaches it: `invoke` binds it to the state's lifetime, `spawn` outlives it. */
+  via: "invoke" | "spawn";
+  /** The child's own structure. Absent iff `recursive`. */
+  machine?: MachineBodyDoc;
+  /** The machine is already an ancestor of this point — the body is up there, not repeated here. */
+  recursive?: true;
+};
+
+/**
+ * One event a Machine declares — its Vocabulary entry (ADR-0011), as the doc carries it. Same
+ * shape a Gate's `accepts` serves, because it is the same thing seen statically: the name, what a
+ * caller sends (JSON Schema), and who may send it.
+ */
+export type MachineEventDoc = {
+  name: string;
+  description?: string;
+  audience: EventAudience;
+  /** The def's input schema as JSON Schema — what a form or a `jr2 send` prompt generates from. */
+  input: unknown;
+};
+
+/** One Machine's structure, independent of what NAMES it (a `workflow` at the root, a `src` below). */
+export type MachineBodyDoc = {
+  /** Machine id. */
+  id: string;
+  root: MachineStateDoc;
+  transitions: MachineTransitionDoc[];
+  /** The events THIS Machine declares, and only this one (ADR-0049): a nested Machine's ride its
+   * own `MachineBodyDoc`. Empty for a Machine not built by `jr2Setup`. */
+  events: MachineEventDoc[];
+};
+
+/** The serialized structure of a workflow's Machine. */
+export type MachineDoc = MachineBodyDoc & {
+  workflow: string;
+  /** States whose child list may be incomplete — see {@link opaqueStates}. Computed once here, on
+   * the server, so the notice reaches whoever renders the doc without every consumer re-walking it
+   * to discover the diagram is lying. Absent on the nested `MachineBodyDoc`s: it is a whole-doc
+   * question, and the root's walk already covers them. */
+  opaqueStates?: string[];
+};
+
+/** Normalize a guard to a display name: setup() name, parameterized type, or `"inline"`. */
+function guardName(guard: unknown): string | undefined {
+  if (guard === undefined) return undefined;
+  if (typeof guard === "string") return guard;
+  // An inline arrow gets the property-inferred name "guard" — meaningless, so report "inline";
+  // a deliberately named function (`guard: function isValid() {…}`) keeps its name.
+  if (typeof guard === "function") return guard.name && guard.name !== "guard" ? guard.name : "inline";
+  return (guard as { type?: string }).type ?? "inline";
+}
+
+/** Normalize an invoke `src` to a display name: setup() actor name or `"inline"`. */
+function srcName(src: unknown): string {
+  if (typeof src === "string") return src;
+  return ((src as { id?: string })?.id ?? "inline") as string;
+}
+
+/**
+ * The tail of a done/error descriptor's id. xstate names an ANONYMOUS invoke after its own position
+ * (`0.body.working.claimTask`), so the raw descriptor spells out the whole path down to the state
+ * the edge already leaves from. Only the last segment says anything new — and a label is not free:
+ * in a layered graph an edge label's WIDTH becomes spacing between layers, so the path is paid for
+ * in diagram width. The full descriptor stays on `event`, so nothing is lost.
+ */
+const shortId = (id = "") => id.slice(id.lastIndexOf(".") + 1);
+
+/** Classify an event descriptor and derive its display label. */
+function eventLabel(eventType: string): { kind: MachineTransitionDoc["kind"]; label: string } {
+  if (eventType === "") return { kind: "always", label: "always" };
+  const done = /^xstate\.done\.(?:actor|state)\.(.*)$/.exec(eventType);
+  if (done) return { kind: "done", label: `done: ${shortId(done[1])}` };
+  const error = /^xstate\.error\.actor\.(.*)$/.exec(eventType);
+  if (error) return { kind: "error", label: `error: ${shortId(error[1])}` };
+  const after = /^xstate\.after\.([^.]+)\./.exec(eventType);
+  if (after) return { kind: "after", label: `after ${after[1]}` };
+  return { kind: "event", label: eventType };
+}
+
+function serializeTransition(t: TransitionDefinition<any, any>): MachineTransitionDoc {
+  const { kind, label } = eventLabel(t.eventType);
+  const guard = guardName(t.guard);
+  const doc: MachineTransitionDoc = {
+    source: t.source.id,
+    targets: (t.target ?? []).map((s) => s.id),
+    event: t.eventType,
+    label,
+    kind,
+  };
+  if (guard !== undefined) doc.guard = guard;
+  return doc;
+}
+
+/** The registry a `src` name resolves against, plus the cycle guard. One per machine level. */
+type Scope = {
+  /** The machine's `setup({ actors })` registry — where a named `src` is bound. */
+  actors: Record<string, unknown>;
+  /** The machines on the path from the root down to here. A machine already on it does not recurse. */
+  path: Set<AnyStateMachine>;
+};
+
+/** A machine actor, told apart from a promise/callback/observable one by having a state tree. */
+function asMachine(logic: unknown): AnyStateMachine | undefined {
+  return (logic as AnyStateMachine | undefined)?.root ? (logic as AnyStateMachine) : undefined;
+}
+
+/** The machine behind `node.invoke[index]`, if it is one. Named actors resolve through the registry;
+ * an INLINE machine object survives only on the raw config node — xstate rewrites
+ * `StateNode.invoke[].src` to a generated key (which is exactly the key the live child reports, so
+ * the doc keeps it as the join `src` and looks the logic up here instead). */
+function invokedMachine(node: StateNode<any, any>, index: number, scope: Scope): AnyStateMachine | undefined {
+  const src = node.invoke[index]?.src;
+  if (typeof src === "string") {
+    const named = asMachine(scope.actors[src]);
+    if (named) return named;
+  }
+  const config = [node.config.invoke ?? []].flat()[index] as { src?: unknown } | undefined;
+  return asMachine(config?.src);
+}
+
+/** Walk every action list a state can carry: its entry, and all of its transitions'. */
+function eachAction(node: StateNode<any, any>, visit: (action: { type?: unknown; src?: unknown }) => void): void {
+  const scan = (actions: readonly unknown[] | undefined) => {
+    for (const action of actions ?? []) visit(action as { type?: unknown; src?: unknown });
+  };
+  scan(node.entry);
+  for (const defs of node.transitions.values()) for (const t of defs) scan(t.actions);
+  for (const t of node.always ?? []) scan(t.actions);
+}
+
+/**
+ * Does this state run an `enqueueActions` closure? If so its {@link MachineStateDoc.children} may be
+ * incomplete — the closure is opaque, and a spawn inside it leaves no static trace at all.
+ *
+ * We cannot see through it (the body resolves at runtime against a live context and event), so the
+ * honest move is to REPORT that we cannot, rather than emit a confidently wrong diagram. xstate
+ * gives us exactly enough to do that: the action's `type` is `"xstate.enqueueActions"`, visible even
+ * though its contents are not.
+ */
+function hasOpaqueActions(node: StateNode<any, any>): boolean {
+  let opaque = false;
+  eachAction(node, (a) => {
+    if (a?.type === "xstate.enqueueActions") opaque = true;
+  });
+  return opaque;
+}
+
+/** Every actor name this state `spawnChild`s — from its entry actions or any of its transitions'.
+ * A spawned child is an ACTION, so it appears nowhere in the state tree; this is its only trace.
+ * Only a TOP-LEVEL `spawnChild` is visible; one issued inside an `enqueueActions` closure is not,
+ * which is what {@link hasOpaqueActions} exists to flag. */
+function spawnedSrcs(node: StateNode<any, any>): string[] {
+  const srcs = new Set<string>();
+  eachAction(node, (a) => {
+    if (a?.type === "xstate.spawnChild" && typeof a.src === "string") srcs.add(a.src);
+  });
+  return [...srcs];
+}
+
+/** The child machines a state runs, invoked and spawned. */
+function childMachines(node: StateNode<any, any>, scope: Scope): ChildMachineDoc[] {
+  const docs: ChildMachineDoc[] = [];
+  const attach = (src: string, label: string, via: ChildMachineDoc["via"], machine: AnyStateMachine) => {
+    // Recursion is legal (a machine that spawns itself); serializing it is not. Name it and stop.
+    if (scope.path.has(machine)) docs.push({ src, label, via, recursive: true });
+    // A fresh path per branch, not a shared visited-set: two SIBLINGS may run the same machine, and
+    // both should carry its body — only an ANCESTOR is a cycle.
+    else docs.push({ src, label, via, machine: serializeBody(machine, new Set(scope.path)) });
+  };
+
+  node.invoke.forEach((inv, i) => {
+    const machine = invokedMachine(node, i, scope);
+    if (machine) attach(srcName(inv.src), inv.id, "invoke", machine);
+  });
+  for (const src of spawnedSrcs(node)) {
+    const machine = asMachine(scope.actors[src]);
+    if (machine) attach(src, src, "spawn", machine);
+  }
+  return docs;
+}
+
+function serializeState(node: StateNode<any, any>, into: MachineTransitionDoc[], scope: Scope): MachineStateDoc {
+  // `node.always` entries are already in the transitions map under the eventless descriptor, so the
+  // map alone is the complete edge set; a reference-set dedupe guards against either representation.
+  const seen = new Set<TransitionDefinition<any, any>>();
+  for (const defs of node.transitions.values()) {
+    for (const t of defs) {
+      if (!seen.has(t)) {
+        seen.add(t);
+        into.push(serializeTransition(t));
+      }
+    }
+  }
+  for (const t of node.always ?? []) {
+    if (!seen.has(t)) {
+      seen.add(t);
+      into.push(serializeTransition(t));
+    }
+  }
+
+  const children = Object.values(node.states as Record<string, StateNode<any, any>>).sort((a, b) => a.order - b.order);
+  const doc: MachineStateDoc = {
+    id: node.id,
+    key: node.key,
+    type: node.type,
+    invoke: node.invoke.map((inv) => ({ id: inv.id, src: srcName(inv.src) })),
+    tags: [...node.tags],
+    states: children.map((child) => serializeState(child, into, scope)),
+    children: childMachines(node, scope),
+  };
+  if (node.type === "compound") doc.initial = node.initial.target[0]?.id;
+  if (node.description !== undefined) doc.description = node.description;
+  if (hasOpaqueActions(node)) doc.opaqueActions = true;
+  return doc;
+}
+
+/** Every state whose `children` may be incomplete, by id — what a caller warns about. Walks the
+ * whole doc, child machines included, since an opaque spawn hides just as well one level down. */
+export function opaqueStates(doc: MachineDoc): string[] {
+  const ids: string[] = [];
+  const walk = (state: MachineStateDoc): void => {
+    if (state.opaqueActions) ids.push(state.id);
+    for (const child of state.children) if (child.machine) walk(child.machine.root);
+    for (const nested of state.states) walk(nested);
+  };
+  walk(doc.root);
+  return ids;
+}
+
+/** Serialize one Machine — its own state tree and its own transitions. Each level carries its own
+ * actor registry (a child machine resolves `src` names against ITS `setup`, not its parent's). */
+function serializeBody(machine: AnyStateMachine, path: Set<AnyStateMachine>): MachineBodyDoc {
+  path.add(machine);
+  const transitions: MachineTransitionDoc[] = [];
+  const scope: Scope = { actors: machine.implementations.actors as Record<string, unknown>, path };
+  const root = serializeState(machine.root, transitions, scope);
+  const events = [...(vocabularyOf(machine)?.values() ?? [])].map((def) => ({
+    name: def.name,
+    ...(def.description !== undefined ? { description: def.description } : {}),
+    audience: def.audience,
+    input: z.toJSONSchema(def.input),
+  }));
+  return { id: machine.id, root, transitions, events };
+}
+
+/** Serialize a workflow's template Machine into the Console's DTO, child machines and all. */
+export function serializeMachine(workflow: string, machine: AnyStateMachine): MachineDoc {
+  const doc: MachineDoc = { workflow, ...serializeBody(machine, new Set()) };
+  return { ...doc, opaqueStates: opaqueStates(doc) };
+}

package/src/names.ts

@@ -0,0 +1,78 @@
+// The fixed in-namespace object names of a deployed instance (ADR-0019). The namespace is the
+// instance's IDENTITY, so names inside it are constants — shared by `jr2 up` (which creates them),
+// the CLI transport (which dials them), and the server entrypoint (which consumes them).
+
+/** The orchestrator's Deployment + Service name; the Service targets `ORCHESTRATOR_PORT`. */
+export const ORCHESTRATOR_SERVICE = "jr2-orchestrator";
+export const ORCHESTRATOR_PORT = 4000;
+
+/** The instance-owned Secret: Instance token + signing key (+ orchestrator-side creds). */
+export const INSTANCE_SECRET = "jr2-instance";
+
+/** The Instance Harness's Deployment + Service name (ADR-0031): converged by `jr2 up` whenever any
+ * Agent definition declares `workspace: "none"`, and the deterministic Service DNS the Agent actor
+ * resolves such a Turn to. Doubles as the delivery scope a Menu-only registration records — the
+ * name the placement's Adapter token is signed for (tokens.ts, ADR-0013). The port is the
+ * Harness's own listen port (`PORT` default). */
+export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
+export const INSTANCE_HARNESS_PORT = 8080;
+
+/** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
+ * REACH — the custom model provider, minus its key. No Agents ride it: a Machine carries its own
+ * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
+ * (ADR-0050). */
+export const HARNESS_CONFIGMAP = "jr2-harness";
+/** Its one key, hence the env var's value — `JR2_HARNESS_JSON` on every Harness container. */
+export const HARNESS_CONFIG_KEY = "harness.json";
+
+/** The resolved image map `jr2 up` writes and every provision reads (ADR-0037/0038): key → ref for
+ * the Harness, the Adapter, and every Sandbox Image context the registered Machines carry — keyed
+ * by content digest, plus the reserved `default` (ADR-0049).
+ *
+ * MOUNTED, never projected into env — the load-bearing part. A mount updates in place through
+ * kubelet propagation, so adding a CLI to a Dockerfile costs one propagation window; the same map
+ * as Deployment env would be a pod-template change, rolling the Orchestrator and putting every
+ * live run through snapshot restore (ADR-0007) for a change that affects only FUTURE Sandboxes. */
+export const IMAGES_CONFIGMAP = "jr2-images";
+export const IMAGES_MOUNT = "/etc/jr2/images";
+/** The ConfigMap key, hence the filename under the mount — the two-sided contract's other half. */
+export const IMAGES_KEY = "images.json";
+
+/** The HARNESS containers' env Secret — Agent creds only, never the Instance token (ADR-0013). */
+export const HARNESS_ENV_SECRET = "jr2-harness-env";
+
+/** The instance's private-CA bundle ConfigMap (`harness.caBundle`, ADR-0020) — mounted into the
+ * Harness container (and only it) so Agent egress trusts an internal CA. Public data by nature. */
+export const CA_CONFIGMAP = "jr2-ca";
+
+/** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
+ * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when
+ * an entry names it. Only a default — an entry may name any Secret. */
+export const GIT_SSH_SECRET = "jr2-git-ssh";
+
+/** The snapshot store's PVC (sqlite lives on it — ADR-0019). */
+export const STATE_PVC = "jr2-state";
+
+/** The cache agent (ADR-0051): the per-Instance DaemonSet that clones each Repo onto its node and
+ * fetches it in place, plus its ServiceAccount/Role/RoleBinding, all by this name. */
+export const REPO_CACHE = "jr2-repo-cache";
+/** The node directory the cache agent owns — `<REPO_CACHE_HOSTPATH>/<namespace>/repos/<key>` is one
+ * Repo's bare clone on one node, mounted read-only into every Sandbox there that names it. */
+export const REPO_CACHE_HOSTPATH = "/var/lib/jr2";
+/** Where a Sandbox sees the node's caches: `/repos/<key>`, one mount per Repo the CR names. */
+export const REPOS_MOUNT = "/repos";
+
+/** Metadata the Orchestrator writes on a `Repo` resource (ADR-0051). `bound` is set when a
+ * registered Machine binds the Repo, so `jr2 gc` never evicts it; the identity is what every
+ * spelling of the url normalizes to (repo-identity.ts); `last-attached` is the eviction clock for
+ * a Repo nothing binds. */
+export const LABEL_REPO_BOUND = "jr2.dev/bound";
+export const ANNOTATION_REPO_IDENTITY = "jr2.dev/identity";
+export const ANNOTATION_REPO_LAST_ATTACHED = "jr2.dev/last-attached";
+
+/** The mark one ask leaves on a Sandbox CR, per Repo key (ADR-0053): a timestamp the Orchestrator
+ * writes when something inside the pod asks for a fetch. The operator copies it onto the pod, and
+ * the node's cache agent takes `asked` as the later of the pod's creation and this — so a fetch
+ * that started before the ask does not satisfy it. The Lease's shape: an annotation, written by
+ * the Orchestrator, read by the operator. */
+export const askedAnnotation = (key: string): string => `jr2.dev/asked-${key}`;

package/src/open.ts

@@ -0,0 +1,17 @@
+// The OPEN sentinel (ADR-0051, widened by ADR-0054) — one value, its own module.
+//
+// It lives alone here because both of the parts it marks must read it and they sit on opposite
+// sides of the package: `agent()`'s declaration (agent.ts, a pure leaf that pulls no wire client)
+// and a `workspace()`'s Repo Slots (parts.ts, which already imports agent.ts). A module with
+// nothing but the sentinel in it is what lets both import it and neither import the other.
+
+/**
+ * Open (CONTEXT.md): this part is a composer's to bind, with `customize()` — a Repo Slot with no
+ * url, an Agent with no model. The shape a packaged Machine ships in, because a package cannot
+ * know the repository or pay for the model. `jr2 up` refuses an Open part nobody bound and names
+ * the line that binds it; a run never sees one.
+ *
+ * `Symbol.for`, so an Instance's own copy of this module and the CLI's walk agree on it — a
+ * packaged Machine may be built against one and walked by the other.
+ */
+export const open: unique symbol = Symbol.for("jr2.open");