@jr2/orchestrator 0.2.1 → 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/model-keys.ts

@@ -0,0 +1,92 @@
+// The known model keys (ADR-0059): every env var pi's catalog reads a provider's credential from,
+// the catalog provider(s) that read it, and the one host those providers' calls go to by default.
+//
+// A COPY of pi's data at the exact pin `@jr2/harness` holds, because this package has no pi
+// dependency and must not grow one: `jr2 up` reads this table host-side (R1, and the default
+// `hosts` of a held secret), and the in-cluster Orchestrator never touches pi. The copy cannot
+// drift silently — `@jr2/harness`'s `model-keys.test.ts` checks it against pi itself, env names per
+// provider and every provider's default host, in the default gate. A pi bump that adds or moves a
+// provider fails there first, the same canary role Harness conformance plays (ADR-0027).
+//
+// `host` is present only when every model of every provider that reads the name goes to ONE static
+// host. It is absent when there is none: the base URL is a template (`{location}`, an account id),
+// the providers disagree (MOONSHOT_API_KEY serves two regions), or the host is regional (Bedrock).
+// A held secret with such a name must then say its `hosts` itself (§3.4 of the spec, R5).
+
+/** One known model-key env name. */
+export type ModelKey = {
+  /** The catalog provider ids that read this name. */
+  providers: readonly string[];
+  /** The host (port 443) those providers' calls go to by default, when there is exactly one. */
+  host?: string;
+};
+
+export const MODEL_KEYS: Readonly<Record<string, ModelKey>> = {
+  // anthropic reads three names. AUTH_TOKEN goes as `Authorization: Bearer`, the other two as
+  // `x-api-key` (an `sk-ant-oat` value is an OAuth token, which a Stand-in never is).
+  ANTHROPIC_API_KEY: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_AUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  ANTHROPIC_OAUTH_TOKEN: { providers: ["anthropic"], host: "api.anthropic.com" },
+  OPENAI_API_KEY: { providers: ["openai"], host: "api.openai.com" },
+  GEMINI_API_KEY: { providers: ["google"], host: "generativelanguage.googleapis.com" },
+  // `https://{location}-aiplatform.googleapis.com` — regional, so no default.
+  GOOGLE_CLOUD_API_KEY: { providers: ["google-vertex"] },
+  COPILOT_GITHUB_TOKEN: { providers: ["github-copilot"], host: "api.individual.githubcopilot.com" },
+  // The bearer form of Bedrock auth. Regional, so no default. (SigV4 credentials cannot be held at
+  // all — a signature is not a header a Stand-in can be swapped into — and `jr2 up` warns on them.)
+  AWS_BEARER_TOKEN_BEDROCK: { providers: ["amazon-bedrock"] },
+  ANT_LING_API_KEY: { providers: ["ant-ling"], host: "api.ant-ling.com" },
+  QWEN_TOKEN_PLAN_API_KEY: {
+    providers: ["qwen-token-plan"],
+    host: "token-plan.ap-southeast-1.maas.aliyuncs.com",
+  },
+  QWEN_TOKEN_PLAN_CN_API_KEY: { providers: ["qwen-token-plan-cn"], host: "token-plan.cn-beijing.maas.aliyuncs.com" },
+  // The catalog names no base URL: an Azure deployment is the user's own resource.
+  AZURE_OPENAI_API_KEY: { providers: ["azure-openai-responses"] },
+  NVIDIA_API_KEY: { providers: ["nvidia"], host: "integrate.api.nvidia.com" },
+  DEEPSEEK_API_KEY: { providers: ["deepseek"], host: "api.deepseek.com" },
+  GROQ_API_KEY: { providers: ["groq"], host: "api.groq.com" },
+  CEREBRAS_API_KEY: { providers: ["cerebras"], host: "api.cerebras.ai" },
+  XAI_API_KEY: { providers: ["xai"], host: "api.x.ai" },
+  // pi reads the name, and its catalog lists no model for the provider at this pin.
+  RADIUS_API_KEY: { providers: ["radius"] },
+  OPENROUTER_API_KEY: { providers: ["openrouter"], host: "openrouter.ai" },
+  AI_GATEWAY_API_KEY: { providers: ["vercel-ai-gateway"], host: "ai-gateway.vercel.sh" },
+  ZAI_API_KEY: { providers: ["zai"], host: "api.z.ai" },
+  ZAI_CODING_CN_API_KEY: { providers: ["zai-coding-cn"], host: "open.bigmodel.cn" },
+  MISTRAL_API_KEY: { providers: ["mistral"], host: "api.mistral.ai" },
+  MINIMAX_API_KEY: { providers: ["minimax"], host: "api.minimax.io" },
+  MINIMAX_CN_API_KEY: { providers: ["minimax-cn"], host: "api.minimaxi.com" },
+  // Two providers, two hosts (`.ai` and `.cn`): no single default.
+  MOONSHOT_API_KEY: { providers: ["moonshotai", "moonshotai-cn"] },
+  HF_TOKEN: { providers: ["huggingface"], host: "router.huggingface.co" },
+  FIREWORKS_API_KEY: { providers: ["fireworks"], host: "api.fireworks.ai" },
+  TOGETHER_API_KEY: { providers: ["together"], host: "api.together.ai" },
+  // Two providers, one host.
+  OPENCODE_API_KEY: { providers: ["opencode", "opencode-go"], host: "opencode.ai" },
+  KIMI_API_KEY: { providers: ["kimi-coding"], host: "api.kimi.com" },
+  // Account-templated base URLs.
+  CLOUDFLARE_API_KEY: { providers: ["cloudflare-workers-ai", "cloudflare-ai-gateway"] },
+  XIAOMI_API_KEY: { providers: ["xiaomi"], host: "api.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_CN_API_KEY: { providers: ["xiaomi-token-plan-cn"], host: "token-plan-cn.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_AMS_API_KEY: { providers: ["xiaomi-token-plan-ams"], host: "token-plan-ams.xiaomimimo.com" },
+  XIAOMI_TOKEN_PLAN_SGP_API_KEY: { providers: ["xiaomi-token-plan-sgp"], host: "token-plan-sgp.xiaomimimo.com" },
+};
+
+/** Every catalog provider id some known model key belongs to — the set `harness.catalog` may name. */
+export const MODEL_KEY_PROVIDERS: ReadonlySet<string> = new Set(
+  Object.values(MODEL_KEYS).flatMap((key) => key.providers),
+);
+
+/**
+ * Credentials that sign a request instead of riding it in a header (ADR-0059). A Stand-in cannot be
+ * swapped into a signature, so these cannot be held — `jr2 up` warns when `harness.env` sets one,
+ * because the Agent can read it, and names a gateway as the way out.
+ */
+export const SIGNING_CREDENTIALS: readonly string[] = [
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+  "AWS_PROFILE",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+];

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;
+}