@jr2/orchestrator 0.3.0 → 0.4.1

package/src/kube-client.ts

@@ -0,0 +1,333 @@
+// The Orchestrator's Kubernetes client (ADR-0063): plain REST on Node's built-in `fetch`, with no
+// dependency. The Orchestrator is always in-cluster (ADR-0019), so the whole of "configuration" is
+// the ServiceAccount the kubelet mounts and the Service the API server publishes:
+//
+//   base URL   https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT
+//   bearer     the SA token FILE, read on every request (below)
+//   trust      the SA `ca.crt`, through NODE_EXTRA_CA_CERTS on the Deployment (deploy.ts) — so
+//              this module holds no TLS code at all
+//
+// It speaks for jr2's own kinds alone — Sandbox, Repo, Secret — and every call stays behind the
+// Sandbox and Repo ports, so swapping it for a client library is a contained change if jr2 ever
+// needs exec or many more kinds (ADR-0063's considered options).
+//
+// Its rules, each observed on a real cluster (ADR-0063):
+//
+//   - The token is never cached. The kubelet replaced a 10-minute token only about 50 seconds
+//     before it expired, so a cached one fails in production and never in a test. A `401` re-reads
+//     the file and retries ONCE — a rotation between the read and the request.
+//   - Writes are capped (8–16 at once). 200 parallel writes each opened a TLS connection and cost
+//     about 130% CPU; a provision burst queues here instead.
+//   - A watch asks for bookmarks and `timeoutSeconds=240`: built-in `fetch` aborts a body silent
+//     for 300s (`UND_ERR_BODY_TIMEOUT`) and that cannot be changed without undici's dispatcher, so
+//     the server closing first — and bookmarks about every 60s — keep a healthy watch clear of it.
+//     The watch LOOP that reads this stream lives in sandbox-watch.ts.
+
+import { readFile } from "node:fs/promises";
+
+// The API server's CA (`SERVICE_ACCOUNT_CA`, names.ts) is not read here: the Deployment points
+// NODE_EXTRA_CA_CERTS at it, and built-in `fetch` trusts it from there.
+
+/** Where the kubelet mounts the Pod's ServiceAccount. */
+export const SERVICE_ACCOUNT_DIR = "/var/run/secrets/kubernetes.io/serviceaccount";
+/** The bearer — rotated by the kubelet, so read per request. */
+export const SERVICE_ACCOUNT_TOKEN = `${SERVICE_ACCOUNT_DIR}/token`;
+
+/** The field manager every server-side apply names — the Orchestrator's one identity as a writer. */
+export const FIELD_MANAGER = "jr2";
+
+/** The write cap when the caller names none: inside ADR-0063's 8–16. */
+const DEFAULT_MAX_WRITES = 12;
+
+/** One kind, as its REST path spells it. The core group is `""` (`/api/v1`). */
+export type KubeKind = { group: string; version: string; plural: string };
+
+export const SANDBOXES: KubeKind = { group: "core.jr2.dev", version: "v1alpha1", plural: "sandboxes" };
+export const REPOS: KubeKind = { group: "core.jr2.dev", version: "v1alpha1", plural: "repos" };
+export const SECRETS: KubeKind = { group: "", version: "v1", plural: "secrets" };
+export const CONFIGMAPS: KubeKind = { group: "", version: "v1", plural: "configmaps" };
+export const SERVICES: KubeKind = { group: "", version: "v1", plural: "services" };
+
+/** The object fields every kind shares — what the client and the watch read off any of them. */
+export type KubeObject = {
+  apiVersion?: string;
+  kind?: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    uid?: string;
+    resourceVersion?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+  };
+};
+
+/** One event off a watch stream. `ERROR` carries a `Status` (code 410 for a resourceVersion too
+ * old) INSIDE an HTTP 200 — the caller re-lists on any of them. */
+export type WatchEvent<T extends KubeObject = KubeObject> =
+  | { type: "ADDED" | "MODIFIED" | "DELETED" | "BOOKMARK"; object: T }
+  | { type: "ERROR"; object: { kind?: "Status"; code?: number; reason?: string; message?: string } };
+
+/** A refusal from the API server: the HTTP status and the `Status` body's own reason and words. */
+export class KubeError extends Error {
+  readonly status: number;
+  readonly reason: string | undefined;
+  constructor(status: number, reason: string | undefined, message: string) {
+    super(message);
+    this.name = "KubeError";
+    this.status = status;
+    this.reason = reason;
+  }
+}
+
+export type KubeClientOptions = {
+  /** The API server. Default: the in-cluster Service from `KUBERNETES_SERVICE_HOST`/`_PORT`. */
+  baseUrl?: string;
+  /** The environment the default base URL is read from. Default `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** The bearer, asked for on EVERY request — never cached (see the header). Default: the SA
+   * token file. */
+  token?: () => Promise<string>;
+  /** Injectable transport: the tests' fake API server. Default: global `fetch`. */
+  fetch?: typeof fetch;
+  /** How many writes may be in flight at once. Default 12. */
+  maxWrites?: number;
+};
+
+/** The client the Sandbox, Repo and fetch ports share: one process, one write cap. */
+export interface KubeClient {
+  /** The object, or `undefined` when there is none (404). */
+  get<T extends KubeObject>(kind: KubeKind, namespace: string, name: string): Promise<T | undefined>;
+  /** Every object of the kind in the namespace, with the list's resourceVersion — where a watch
+   * starts. A kind the cluster does not serve (no CRD) is a {@link KubeError} with status 404. */
+  list<T extends KubeObject>(
+    kind: KubeKind,
+    namespace: string,
+    opts?: { labelSelector?: string },
+  ): Promise<{ items: T[]; resourceVersion: string }>;
+  /** Create; an existing object is a {@link KubeError} with status 409. */
+  create<T extends KubeObject>(kind: KubeKind, namespace: string, body: T): Promise<T & KubeObject>;
+  /** Delete; true when there was one to delete, false when it was already gone. */
+  delete(kind: KubeKind, namespace: string, name: string): Promise<boolean>;
+  /** A JSON merge patch — `null` removes a key. `status` patches the status subresource. Answers
+   * the object as it stands after the patch. */
+  patch<T extends KubeObject>(
+    kind: KubeKind,
+    namespace: string,
+    name: string,
+    body: object,
+    opts?: { status?: boolean },
+  ): Promise<T>;
+  /** Server-side apply as field manager `jr2`, forced: create-or-update of every field the body
+   * names. Answers the object as it stands afterwards (its `uid` included). */
+  apply<T extends KubeObject>(kind: KubeKind, namespace: string, body: T): Promise<T & KubeObject>;
+  /** One watch request's events, from `resourceVersion`, until the server closes it. Throws on a
+   * refused request or a broken stream — the caller decides what each means (sandbox-watch.ts). */
+  watch<T extends KubeObject>(
+    kind: KubeKind,
+    namespace: string,
+    opts: { resourceVersion: string; labelSelector?: string; timeoutSeconds: number; signal?: AbortSignal },
+  ): AsyncIterable<WatchEvent<T>>;
+}
+
+/** The in-cluster base URL, from the Service env the kubelet injects into every pod. */
+export function inClusterBaseUrl(env: Record<string, string | undefined> = process.env): string {
+  const host = env.KUBERNETES_SERVICE_HOST;
+  const port = env.KUBERNETES_SERVICE_PORT ?? "443";
+  if (!host) {
+    throw new Error(
+      "no Kubernetes API server: KUBERNETES_SERVICE_HOST is unset. The Orchestrator drives the cluster " +
+        "only from inside it (ADR-0019, ADR-0063) — `jr2 up` deploys it there.",
+    );
+  }
+  // An IPv6 address needs brackets in a URL.
+  return `https://${host.includes(":") ? `[${host}]` : host}:${port}`;
+}
+
+/** Build the client. Nothing is read until the first request: a boot never fails on the cluster. */
+export function kubeClient(opts: KubeClientOptions = {}): KubeClient {
+  const fetchImpl = opts.fetch ?? fetch;
+  const token = opts.token ?? (async () => (await readFile(SERVICE_ACCOUNT_TOKEN, "utf8")).trim());
+  const writes = semaphore(opts.maxWrites ?? DEFAULT_MAX_WRITES);
+  let base: string | undefined = opts.baseUrl;
+  const baseUrl = () => (base ??= inClusterBaseUrl(opts.env));
+
+  /** One request, with the bearer read fresh and a 401 re-read and retried once. */
+  const send = async (
+    method: string,
+    path: string,
+    init: { query?: Record<string, string>; body?: string; contentType?: string; signal?: AbortSignal } = {},
+  ): Promise<Response> => {
+    const url = new URL(path, baseUrl());
+    for (const [k, v] of Object.entries(init.query ?? {})) url.searchParams.set(k, v);
+    for (let attempt = 0; ; attempt++) {
+      const res = await fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${await token()}`,
+          accept: "application/json",
+          ...(init.contentType ? { "content-type": init.contentType } : {}),
+        },
+        ...(init.body !== undefined ? { body: init.body } : {}),
+        ...(init.signal ? { signal: init.signal } : {}),
+      });
+      // A rotation landed between the read and the request: the file already holds the new one.
+      if (res.status === 401 && attempt === 0) {
+        await res.body?.cancel();
+        continue;
+      }
+      return res;
+    }
+  };
+
+  /** The answer as JSON, or a {@link KubeError} carrying the Status body's reason and words. */
+  const json = async <T>(res: Response, what: string): Promise<T> => {
+    const text = await res.text();
+    if (res.ok) return (text ? JSON.parse(text) : {}) as T;
+    throw errorOf(res.status, text, what);
+  };
+
+  /** A write: inside the cap until its answer is read, so the cap bounds connections, not calls. */
+  const write = <T>(method: string, path: string, what: string, init: Parameters<typeof send>[2]) =>
+    writes(async () => json<T>(await send(method, path, init), what));
+
+  return {
+    async get<T extends KubeObject>(kind: KubeKind, ns: string, name: string) {
+      const res = await send("GET", pathOf(kind, ns, name));
+      if (res.status === 404) {
+        await res.body?.cancel();
+        return undefined;
+      }
+      return json<T>(res, `get ${kind.plural}/${name}`);
+    },
+
+    async list<T extends KubeObject>(kind: KubeKind, ns: string, opts: { labelSelector?: string } = {}) {
+      const res = await send("GET", pathOf(kind, ns), {
+        query: opts.labelSelector ? { labelSelector: opts.labelSelector } : {},
+      });
+      const out = await json<{ items?: T[]; metadata?: { resourceVersion?: string } }>(res, `list ${kind.plural}`);
+      return { items: out.items ?? [], resourceVersion: out.metadata?.resourceVersion ?? "" };
+    },
+
+    create<T extends KubeObject>(kind: KubeKind, ns: string, body: T) {
+      return write<T & KubeObject>("POST", pathOf(kind, ns), `create ${kind.plural}/${body.metadata?.name ?? "?"}`, {
+        body: JSON.stringify(body),
+        contentType: "application/json",
+      });
+    },
+
+    delete(kind: KubeKind, ns: string, name: string) {
+      return writes(async () => {
+        const res = await send("DELETE", pathOf(kind, ns, name));
+        if (res.status === 404) {
+          await res.body?.cancel();
+          return false;
+        }
+        await json(res, `delete ${kind.plural}/${name}`);
+        return true;
+      });
+    },
+
+    patch<T extends KubeObject>(kind: KubeKind, ns: string, name: string, body: object, o: { status?: boolean } = {}) {
+      return write<T>(
+        "PATCH",
+        pathOf(kind, ns, name, o.status ? "status" : undefined),
+        `patch ${kind.plural}/${name}`,
+        {
+          body: JSON.stringify(body),
+          contentType: "application/merge-patch+json",
+        },
+      );
+    },
+
+    apply<T extends KubeObject>(kind: KubeKind, ns: string, body: T) {
+      const name = body.metadata?.name;
+      if (!name) throw new Error(`apply ${kind.plural}: the object names no metadata.name`);
+      // JSON is YAML, so the apply content type takes the object as it is.
+      return write<T & KubeObject>("PATCH", pathOf(kind, ns, name), `apply ${kind.plural}/${name}`, {
+        query: { fieldManager: FIELD_MANAGER, force: "true" },
+        body: JSON.stringify(body),
+        contentType: "application/apply-patch+yaml",
+      });
+    },
+
+    async *watch<T extends KubeObject>(
+      kind: KubeKind,
+      ns: string,
+      o: { resourceVersion: string; labelSelector?: string; timeoutSeconds: number; signal?: AbortSignal },
+    ): AsyncIterable<WatchEvent<T>> {
+      const res = await send("GET", pathOf(kind, ns), {
+        query: {
+          watch: "true",
+          allowWatchBookmarks: "true",
+          timeoutSeconds: String(o.timeoutSeconds),
+          resourceVersion: o.resourceVersion,
+          ...(o.labelSelector ? { labelSelector: o.labelSelector } : {}),
+        },
+        ...(o.signal ? { signal: o.signal } : {}),
+      });
+      if (!res.ok) throw errorOf(res.status, await res.text(), `watch ${kind.plural}`);
+      if (!res.body) return;
+      // One JSON object per line. A line can straddle two chunks, so the tail waits for the next.
+      let buf = "";
+      for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
+        buf += chunk;
+        let nl: number;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (line) yield JSON.parse(line) as WatchEvent<T>;
+        }
+      }
+      if (buf.trim()) yield JSON.parse(buf) as WatchEvent<T>;
+    },
+  };
+}
+
+/** A `Status` body read into a {@link KubeError}; a body that is not one keeps its raw text. */
+function errorOf(status: number, text: string, what: string): KubeError {
+  let reason: string | undefined;
+  let message = text;
+  try {
+    const parsed = JSON.parse(text) as { reason?: string; message?: string };
+    reason = parsed.reason;
+    message = parsed.message ?? text;
+  } catch {
+    // not a Status: the raw text is the most there is to say
+  }
+  return new KubeError(status, reason, `${what} failed (${status}${reason ? ` ${reason}` : ""}): ${message}`);
+}
+
+/** The REST path of a kind in a namespace, optionally one object and one subresource. */
+function pathOf(kind: KubeKind, ns: string, name?: string, sub?: string): string {
+  const root = kind.group ? `/apis/${kind.group}/${kind.version}` : `/api/${kind.version}`;
+  return (
+    `${root}/namespaces/${encodeURIComponent(ns)}/${kind.plural}` +
+    (name !== undefined ? `/${encodeURIComponent(name)}` : "") +
+    (sub !== undefined ? `/${sub}` : "")
+  );
+}
+
+/** At most `n` of the wrapped calls at once; the rest queue in arrival order. */
+function semaphore(n: number): <T>(fn: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const queue: Array<() => void> = [];
+  return async (fn) => {
+    // A released slot passes straight to the next waiter, so a caller arriving in between can
+    // never slip past the cap.
+    if (active >= n) await new Promise<void>((resolve) => queue.push(resolve));
+    else active++;
+    try {
+      return await fn();
+    } finally {
+      const next = queue.shift();
+      if (next) next();
+      else active--;
+    }
+  };
+}
+
+/** True for the API server's "no such object" — the one refusal most callers read as an answer. */
+export const isNotFound = (err: unknown): boolean => err instanceof KubeError && err.status === 404;
+/** True for "already exists" on a create. */
+export const isAlreadyExists = (err: unknown): boolean => err instanceof KubeError && err.status === 409;

package/src/machine-doc.ts

@@ -18,7 +18,8 @@
 import type { AnyStateMachine, StateNode, TransitionDefinition } from "xstate";
 import { z } from "zod";
 import type { EventAudience } from "@jr2/agent-protocol";
-import { vocabularyOf } from "./vocabulary.ts";
+import { argvText, isEffect, targetText, type EffectParts } from "./effect.ts";
+import { loadWarningsOf, seatsOf, vocabularyOf, type MachineSeat } from "./vocabulary.ts";
 
 /** One transition of the Machine, id-addressed at both ends. */
 export type MachineTransitionDoc = {
@@ -32,9 +33,30 @@ export type MachineTransitionDoc = {
   label: string;
   /** Normalized guard name, if guarded. */
   guard?: string;
+  /** xstate's own transition `description`, as authored: what this writing does, where one name
+   * has writings that differ (ADR-0015's "one def, one meaning"). */
+  description?: string;
   kind: "event" | "always" | "after" | "done" | "error";
 };
 
+/** An Effect slot's parts, as the doc carries them (ADR-0067): a command's argv (an argv slot reads
+ * `<name>`), its timeout, and the Repo Slot whose Worktree is its cwd, when it names one. */
+export type EffectDoc =
+  | { kind: "command"; argv: string[]; timeoutMs: number; slot?: string; secrets?: string[]; pin?: true }
+  /** An http Effect (ADR-0068): its method, its fixed target, the secrets it names — never a value
+   * — and `file` when its body is a Worktree file (ADR-0067). */
+  | {
+      kind: "http";
+      method: string;
+      target: string;
+      secrets: string[];
+      timeoutMs: number;
+      idempotent: boolean;
+      file?: true;
+    }
+  /** A push (ADR-0067): which options the author set. */
+  | { kind: "push"; sign: boolean; squash: boolean; force: boolean; pin: boolean; timeoutMs: number; slot?: string };
+
 /** One state of the Machine; `states` nests in document order. */
 export type MachineStateDoc = {
   /** Unique state id (custom `id:` respected). */
@@ -44,7 +66,9 @@ export type MachineStateDoc = {
   type: "atomic" | "compound" | "parallel" | "final" | "history";
   /** Initial child state id (compound only). */
   initial?: string;
-  invoke: Array<{ id: string; src: string }>;
+  /** Each invoke's id and slot; an Effect's carries its plain-data parts (ADR-0067) — what it runs,
+   * where, and for how long, read without running anything. */
+  invoke: Array<{ id: string; src: string; effect?: EffectDoc }>;
   tags: string[];
   description?: string;
   states: MachineStateDoc[];
@@ -98,7 +122,8 @@ export type ChildMachineDoc = {
 export type MachineEventDoc = {
   name: string;
   description?: string;
-  audience: EventAudience;
+  /** Absent: each writing's state decides who may send it (ADR-0015) — see the body's `seats`. */
+  audience?: EventAudience;
   /** The def's input schema as JSON Schema — what a form or a `jr2 send` prompt generates from. */
   input: unknown;
 };
@@ -112,6 +137,13 @@ export type MachineBodyDoc = {
   /** 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[];
+  /** Who may send what, per state (ADR-0015): one entry per party on each state that invokes one —
+   * the audience rule's answer for this Machine, as `jr2 up` prints it. Empty for a Machine not
+   * built by `jr2Setup`. */
+  seats: MachineSeat[];
+  /** What the build found legal and suspect (ADR-0015) — a mode nothing enters, a pick a Gate above
+   * takes from the Agent below, one name written for two parties on one path. */
+  warnings: string[];
 };
 
 /** The serialized structure of a workflow's Machine. */
@@ -122,6 +154,10 @@ export type MachineDoc = MachineBodyDoc & {
    * 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[];
+  /** A run's doc only (`runMachine`, ADR-0070): each bound Chart the doc could not draw, so its Open
+   * body shows the slot's own subgraph — the body's path in the run, its slot, and why (a stored
+   * Chart the door no longer admits is drift, D-B). Absent when every bound Chart is drawn. */
+  chartsNotDrawn?: Array<{ path: string; src: string; reason: string }>;
 };
 
 /** Normalize a guard to a display name: setup() name, parameterized type, or `"inline"`. */
@@ -172,6 +208,7 @@ function serializeTransition(t: TransitionDefinition<any, any>): MachineTransiti
     kind,
   };
   if (guard !== undefined) doc.guard = guard;
+  if (t.description !== undefined) doc.description = t.description;
   return doc;
 }
 
@@ -287,7 +324,11 @@ function serializeState(node: StateNode<any, any>, into: MachineTransitionDoc[],
     id: node.id,
     key: node.key,
     type: node.type,
-    invoke: node.invoke.map((inv) => ({ id: inv.id, src: srcName(inv.src) })),
+    invoke: node.invoke.map((inv) => {
+      const logic = typeof inv.src === "string" ? scope.actors[inv.src] : undefined;
+      if (!isEffect(logic)) return { id: inv.id, src: srcName(inv.src) };
+      return { id: inv.id, src: srcName(inv.src), effect: effectDoc(logic.effect) };
+    }),
     tags: [...node.tags],
     states: children.map((child) => serializeState(child, into, scope)),
     children: childMachines(node, scope),
@@ -311,6 +352,18 @@ export function opaqueStates(doc: MachineDoc): string[] {
   return ids;
 }
 
+/** Every Machine body in a doc — the root's, then each child Machine's, depth-first in state order.
+ * A recursive reference is not repeated: its body is already above it. */
+export function machineBodies(doc: MachineBodyDoc): MachineBodyDoc[] {
+  const out: MachineBodyDoc[] = [doc];
+  const walk = (state: MachineStateDoc): void => {
+    for (const child of state.children) if (child.machine) out.push(...machineBodies(child.machine));
+    for (const nested of state.states) walk(nested);
+  };
+  walk(doc.root);
+  return out;
+}
+
 /** 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 {
@@ -321,10 +374,10 @@ function serializeBody(machine: AnyStateMachine, path: Set<AnyStateMachine>): Ma
   const events = [...(vocabularyOf(machine)?.values() ?? [])].map((def) => ({
     name: def.name,
     ...(def.description !== undefined ? { description: def.description } : {}),
-    audience: def.audience,
+    ...(def.audience !== undefined ? { audience: def.audience } : {}),
     input: z.toJSONSchema(def.input),
   }));
-  return { id: machine.id, root, transitions, events };
+  return { id: machine.id, root, transitions, events, seats: seatsOf(machine), warnings: loadWarningsOf(machine) };
 }
 
 /** Serialize a workflow's template Machine into the Console's DTO, child machines and all. */
@@ -332,3 +385,32 @@ export function serializeMachine(workflow: string, machine: AnyStateMachine): Ma
   const doc: MachineDoc = { workflow, ...serializeBody(machine, new Set()) };
   return { ...doc, opaqueStates: opaqueStates(doc) };
 }
+
+/** An Effect's plain data as the doc carries it: what it runs, read without running anything. */
+function effectDoc(parts: EffectParts): EffectDoc {
+  if (parts.kind === "http") {
+    const { method, secrets, timeoutMs, idempotent } = parts;
+    return {
+      kind: "http",
+      method,
+      target: targetText(parts),
+      secrets: [...secrets],
+      timeoutMs,
+      idempotent,
+      ...(parts.file ? { file: true as const } : {}),
+    };
+  }
+  if (parts.kind === "push") {
+    const { sign, squash, force, pin, timeoutMs, slot } = parts;
+    return { kind: "push", sign, squash, force, pin, timeoutMs, ...(slot ? { slot } : {}) };
+  }
+  const { argv, timeoutMs, slot, secrets, pin } = parts;
+  return {
+    kind: "command",
+    argv: argvText(argv),
+    timeoutMs,
+    ...(slot ? { slot } : {}),
+    ...(secrets?.length ? { secrets: [...secrets] } : {}),
+    ...(pin ? { pin } : {}),
+  };
+}

package/src/mount-digest.ts

@@ -0,0 +1,53 @@
+// What a mounted ConfigMap holds, as one digest (ADR-0038, ADR-0069). A publish rolls no pod, so
+// the Orchestrator reads `jr2-images` and `jr2-held` through mounts the kubelet refreshes on its
+// own period. `jr2 up` digests the data it applied, `GET /assembly` reports the digest of what the
+// process reads, and the publish waits until the two agree. Then the door's checks, and the
+// provisions that follow the converge, read the data this converge wrote.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { HELD_CONFIGMAP, HELD_MOUNT, IMAGES_CONFIGMAP, IMAGES_MOUNT } from "./names.ts";
+
+/** The ConfigMaps the Orchestrator reads through a mount, by name, and where each is mounted. */
+export const MOUNTED_CONFIGMAPS: Readonly<Record<string, string>> = {
+  [IMAGES_CONFIGMAP]: IMAGES_MOUNT,
+  [HELD_CONFIGMAP]: HELD_MOUNT,
+};
+
+/** One digest of a ConfigMap's `data`: the same bytes give the same digest at both ends. */
+export function configMapDigest(data: Readonly<Record<string, string>>): string {
+  const entries = Object.keys(data)
+    .sort()
+    .map((key) => [key, data[key]]);
+  return createHash("sha256").update(JSON.stringify(entries)).digest("hex").slice(0, 16);
+}
+
+/**
+ * The digest of a mounted ConfigMap, read from its mount (ADR-0069). The kubelet writes each key
+ * as a file and keeps its own entries under names that start with `.`, which are not data. An
+ * absent mount reads as `undefined`.
+ */
+export async function readMountDigest(dir: string): Promise<string | undefined> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return undefined;
+  }
+  const data: Record<string, string> = {};
+  for (const name of names.filter((n) => !n.startsWith("."))) data[name] = await readFile(join(dir, name), "utf8");
+  return configMapDigest(data);
+}
+
+/** Every mounted ConfigMap's digest, by name; a mount that is absent is left out. */
+export async function readMountDigests(
+  mounts: Readonly<Record<string, string>> = MOUNTED_CONFIGMAPS,
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [name, dir] of Object.entries(mounts)) {
+    const digest = await readMountDigest(dir);
+    if (digest !== undefined) out[name] = digest;
+  }
+  return out;
+}

package/src/names.ts

@@ -9,7 +9,7 @@ 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
+/** The Instance Harness's StatefulSet + 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 Sandbox token is signed for (tokens.ts, ADR-0013), which its Custodian holds. The port is the
@@ -17,6 +17,19 @@ export const INSTANCE_SECRET = "jr2-instance";
 export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
 export const INSTANCE_HARNESS_PORT = 8080;
 
+/** The Instance Effector (ADR-0068): its Deployment, headless Service, NetworkPolicy and Secret all
+ * carry this name. `jr2 up` converges them when a registered Machine places an Effect there. The
+ * port is the Effector's own (`JR2_EFFECTOR_PORT` default) — none of the Harness pod's ports. */
+export const INSTANCE_EFFECTOR = "jr2-instance-effector";
+export const EFFECTOR_PORT = 8082;
+
+/** Where a Harness persists its conversations, and the env var that tells it so (ADR-0031): one
+ * fixed path in both placements — the Instance Harness's PersistentVolumeClaim (deploy.ts) and a
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. */
+export const CONVERSATIONS_DIR = "/conversations";
+export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
+export const CONVERSATIONS_VOLUME = "conversations";
+
 /** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
  * REACH — the custom model provider minus its key, and the catalog providers' gateways (ADR-0059). No Agents ride it: a Machine carries its own
  * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
@@ -50,17 +63,40 @@ export const CA_CONFIGMAP = "jr2-ca";
 /** Held secrets (ADR-0059). The per-Instance CA — its key included — that `jr2 up` alone reads over
  * the kube API, and that NO pod mounts: every leaf is issued before a pod starts. */
 export const HELD_CA_SECRET = "jr2-held-ca";
-/** The literal held values, one key per name — mounted into the Custodian and nothing else. */
+/** The prefix of each pod's literal held values (`heldSecretsSecret`): one Secret per pod, one key
+ * per name it holds — mounted into that pod's Custodian and nothing else. */
 export const HELD_SECRETS_SECRET = "jr2-held-secrets";
-/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodian's alone. */
+/** The literal held values of one pod (ADR-0059): `jr2-held-secrets-<pod>`. */
+export function heldSecretsSecret(pod: string): string {
+  return `${HELD_SECRETS_SECRET}-${pod}`;
+}
+/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodians' alone. */
 export const HELD_TLS_SECRET = "jr2-held-tls";
-/** `held.json` (what `jr2 up` resolved) plus the Custodian's bootstrap and script. Always applied,
- * possibly holding no secret: every Harness pod runs a Custodian. */
+/** What `jr2 up` DECLARES about held secrets: each pod's held manifest (`heldManifestKey` — names,
+ * bindings, headers; never a value) and the Custodian's program once (`CUSTODIAN_PROGRAM_KEY`).
+ * Nothing rendered per pod lives here: a shared object stops at 1 MiB, and Envoy's files are a
+ * pod's own, rendered where the pod is made (`sandboxCustodianConfigMap`,
+ * `INSTANCE_CUSTODIAN_CONFIGMAP`). Always applied, possibly holding no secret: every Harness pod
+ * runs a Custodian. */
 export const HELD_CONFIGMAP = "jr2-held";
-/** Where the Orchestrator reads `held.json`, per provision — a mount, so a held-secret edit reaches
- * future Sandboxes without rolling the Orchestrator (the `jr2-images` pattern, ADR-0038). */
+/** Where the Orchestrator reads a Workspace's held manifest, per provision — a mount, so a
+ * held-secret edit reaches future Sandboxes without rolling the Orchestrator (the `jr2-images`
+ * pattern, ADR-0038). */
 export const HELD_MOUNT = "/etc/jr2/held";
-export const HELD_KEY = "held.json";
+/** The `jr2-held` key of one pod's manifest. */
+export const heldManifestKey = (pod: string): string => `held-${pod}.json`;
+/** The `jr2-held` key of the Custodian's fixed Lua — `custodian.lua` as written, once per Instance;
+ * each pod's own script loads it by this name from its config mount. */
+export const CUSTODIAN_PROGRAM_KEY = "program.lua";
+/** The ConfigMap with the Instance Harness's Custodian's two rendered files (`envoy.json`,
+ * `custodian.lua`), written by `jr2 up`: the one pod it makes. */
+export const INSTANCE_CUSTODIAN_CONFIGMAP = "jr2-held-custodian";
+/** The ConfigMap with one Sandbox's Custodian's two rendered files, written by the Orchestrator at
+ * provision and owned by the Sandbox CR — the `<name>-token` family: it goes with the pod. */
+export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox}-custodian`;
+/** The Instance Harness's pod, as its held objects are keyed. A Workspace's is `ws-<digest>`
+ * (`workspaceHeldPod`), so the two cannot collide. */
+export const INSTANCE_HARNESS_HELD_POD = "instance";
 
 /** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
  * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
@@ -100,3 +136,25 @@ export const ANNOTATION_REPO_LAST_ATTACHED = "jr2.dev/last-attached";
  * 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}`;
+
+/** The two PriorityClasses `jr2 up` creates, cluster-scoped, beside the CRDs (ADR-0060) — unless
+ * `priorityClasses` in jr2.config.ts names existing ones. `jr2-control` (100000,
+ * PreemptLowerPriority) is for the Orchestrator, the operator and the Repo cache agent: small, fixed,
+ * and needed by every Sandbox. `jr2-sandbox` (1000, preemptionPolicy Never) is for Sandboxes and the
+ * Instance Harness: an ordinary pod cannot preempt a live Workspace, and a waiting Sandbox evicts
+ * nobody. Both stay far below the system classes. */
+export const PRIORITY_CLASS_CONTROL = "jr2-control";
+export const PRIORITY_CLASS_SANDBOX = "jr2-sandbox";
+
+/** The voluntary-disruption opt-outs (ADR-0060) a Sandbox pod and the Instance Harness pod carry:
+ * moving either loses work (`/work`; live conversations). No PodDisruptionBudget — `maxUnavailable:
+ * 0` blocks node upgrades without end. */
+export const NO_DISRUPT_ANNOTATIONS = {
+  "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
+  "karpenter.sh/do-not-disrupt": "true",
+} as const;
+
+/** The API server's CA as the kubelet mounts it with the Pod's ServiceAccount. The Orchestrator
+ * Deployment points `NODE_EXTRA_CA_CERTS` at it, so the Orchestrator's own Kubernetes client
+ * (kube-client.ts, ADR-0063) trusts the API server with built-in `fetch` and no TLS code. */
+export const SERVICE_ACCOUNT_CA = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt";