@jr2/orchestrator 0.2.1 → 0.4.1

package/src/images.ts

@@ -1,17 +1,17 @@
 // The resolved key→ref image map, from the READ side (ADR-0037/0038/0049). `jr2 up` builds every
 // image it deploys and writes this map into the `jr2-images` ConfigMap; the Sandbox port consults it
 // when it creates a pod. This module is the shape both sides agree on — deliberately its own file,
-// not folded into sandbox-kubectl.ts, because the CLI needs the type without dragging in the
+// not folded into sandbox-kube.ts, because the CLI needs the type without dragging in the
 // kubectl port.
 //
-// The map is NESTED, never flat. The kit's own `harness`/`adapter` refs sit beside a `sandbox`
+// The map is NESTED, never flat. The kit's own `harness` and the `custodian` sit beside a `sandbox`
 // sub-map, so a user image can never shadow them — and `default` is the one reserved key in that
 // sub-map, because ADR-0037's fallback chain is built on it.
 //
 // A user image's key is its build context's CONTENT DIGEST (ADR-0049). That is what lets the two
 // sides agree without a path table: a Machine names its context as a `file:` URL, whose absolute
-// path differs between the host at `jr2 up` and the baked Orchestrator, while the FOLDER is the same
-// folder — the instance's `node_modules` holds the very tree the converge hashed. Digest in, digest
+// path differs between the host at `jr2 up` and the Orchestrator Kit image, while the FOLDER is the
+// same folder — the published Assembly's `node_modules` holds the very tree the converge hashed. Digest in, digest
 // out, no dirname registry in between.
 //
 // There is NO cache and NO memo for the map itself. The whole reason it arrives as a mounted
@@ -24,10 +24,12 @@ import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { byteOrder } from "./content-hash.ts";
 
 /**
- * Every image ref one converge resolved. `harness`/`adapter` are the kit's own (built from a kit
- * checkout, or the published `<kitversion>` tags); `sandbox` is the instance's own docker-context
+ * Every image ref one converge resolved. `harness` is the kit's own (built from a kit checkout, or
+ * the published `<kitversion>` tag); `custodian` is the pinned Envoy the kit deploys and never
+ * builds (ADR-0038, ADR-0059); `sandbox` is the instance's own docker-context
  * builds — one `docker build` straight to a content tag, carrying no jr2 layers at all, because the
  * Harness arrives at POD time on the `/opt/jr2` volume (ADR-0037).
  *
@@ -38,9 +40,10 @@ import { fileURLToPath } from "node:url";
 export type ImageRefs = {
   /** The stock Harness image — also the last leg of the Sandbox Image fallback chain. */
   harness: string;
-  /** The Adapter image (ADR-0013). An Agent with no Adapter cannot drive its Machine at all, so
+  /** The Custodian's image (ADR-0059) — upstream Envoy, pinned by digest, re-homed onto a
+   * `kitRegistry` when one is set. Every Harness pod runs one (it carries the Menu, ADR-0013), so
    * this is required: a map without it fails the provision rather than shipping a mute pod. */
-  adapter: string;
+  custodian: string;
   /** Built Sandbox Images by their build context's CONTENT DIGEST (ADR-0049), plus the reserved
    * key `default` — the Instance's `images/default`, ADR-0037's middle leg. Empty when the
    * instance ships no context and scaffolded no default. */
@@ -99,10 +102,9 @@ export async function readImageRefs(path: string): Promise<ImageRefs> {
     return value as string;
   };
   const harness = ref("harness");
-  // Required, not optional: with the ref living in the map there is no "no adapter configured"
-  // branch left to gate on, and an Agent whose pod has no Adapter parks forever on a tool call it
-  // cannot make (ADR-0013). Failing the provision is the only honest outcome.
-  const adapter = ref("adapter");
+  // Required, not optional: an Agent whose pod has no Custodian parks forever on a Menu it cannot
+  // read (ADR-0013). Failing the provision is the only honest outcome.
+  const custodian = ref("custodian");
   const sandboxRaw = map["sandbox"];
   if (sandboxRaw !== undefined && (typeof sandboxRaw !== "object" || sandboxRaw === null || Array.isArray(sandboxRaw)))
     bad("`sandbox` must be an object of name → ref");
@@ -121,7 +123,7 @@ export async function readImageRefs(path: string): Promise<ImageRefs> {
     if (typeof value !== "string") bad(`\`sandboxUser.${name}\` is not a USER (got ${JSON.stringify(value)})`);
     sandboxUser[name] = value as string;
   }
-  return { harness, adapter, sandbox, sandboxUser };
+  return { harness, custodian, sandbox, sandboxUser };
 }
 
 /**
@@ -142,7 +144,8 @@ export function isImageContext(image: string): boolean {
  * nothing else (ADR-0037/0038).
  *
  * It lives HERE, not in the CLI's build module, because BOTH sides compute it: `jr2 up` keys the
- * map it publishes by this digest, and the baked Orchestrator computes it again at provision to
+ * map it publishes by this digest, and the Orchestrator computes it again at provision, over the
+ * published Assembly, to
  * look the ref up. One implementation is what makes "the host and the pod agree without a path
  * table" true rather than hopeful (ADR-0049).
  *
@@ -155,12 +158,11 @@ export function isImageContext(image: string): boolean {
 export async function imageContextDigest(dir: string): Promise<string> {
   const h = createHash("sha256");
   // A domain separator, and the whole of it: a Sandbox Image's build is `docker build` of the
-  // user's own directory with no generated text anywhere in it, so — unlike the instance image,
-  // whose generated Dockerfile is image content the context never holds — there is nothing to salt
-  // WITH. The constant only keeps this hash's domain apart from the bundle's.
+  // user's own directory with no generated text anywhere in it, so there is nothing to salt WITH.
+  // The constant only keeps this hash's domain apart from the Assembly's.
   h.update("salt:sandbox\n");
   const walk = async (root: string, d: string): Promise<void> => {
-    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    const entries = (await readdir(d, { withFileTypes: true })).sort((a, b) => byteOrder(a.name, b.name));
     for (const e of entries) {
       const p = join(d, e.name);
       if (e.isDirectory()) await walk(root, p);
@@ -181,7 +183,7 @@ export async function imageContextDigest(dir: string): Promise<string> {
  * own key and is never looked up. Absent is the reserved `default` key — ADR-0037's middle leg.
  *
  * A context whose folder is unreadable fails HERE, before a Secret or a CR exists, naming the path:
- * in a deployed Orchestrator that means the module shipped a context the instance bundle does not
+ * in a deployed Orchestrator that means the module shipped a context the current Assembly does not
  * hold, which is a packaging bug and not a cluster one.
  */
 async function imageKey(image: string): Promise<string> {
@@ -193,7 +195,7 @@ async function imageKey(image: string): Promise<string> {
     throw new Error(
       `the Sandbox Image context ${image} cannot be read (${(err as NodeJS.ErrnoException).code ?? "read failed"}) — ` +
         "a `file:` image names a docker context the Machine's own module ships (ADR-0037), so it must travel " +
-        `with the module: check that ${dir} exists in the instance's node_modules.`,
+        `with the module: check that ${dir} exists in the current Assembly.`,
     );
   }
 }
@@ -226,13 +228,14 @@ export type ResolvedImage = {
    * cannot prove is non-root because it does not read the image's `/etc/passwd`, and uid 0
    * (`USER root`, `USER 0`), which plainly is root.
    *
-   * Both surface as CreateContainerConfigError on the FIRST init step that runs the image — the
+   * Both surface as CreateContainerConfigError on the init step that runs the image — the
    * preflight — and that container never starts, so `kubectl logs -c preflight` prints nothing. The
    * record is the one place that can see it coming: `docker inspect` at converge already put the
    * string in the map, so the provision can fail BEFORE it applies anything. Only a BUILT image is
-   * knowable here; a registry ref was never inspected, so it answers undefined and that pod is
-   * caught later, from the cluster (`rootImageFault` in sandbox-kubectl.ts) — same fault, same fix,
-   * one round trip more expensive.
+   * knowable here; a registry ref was never inspected, so it answers undefined and that pod runs
+   * out the provision's Ready budget, whose message names the numeric non-root `USER` among the
+   * floor's causes (sandbox-kube.ts). The Orchestrator reads no Pod (ADR-0063), so the kubelet's
+   * waiting reason is not visible to it.
    */
   refusedUser?: string;
 };
@@ -248,6 +251,14 @@ function judgeUser(recorded: string | undefined): Pick<ResolvedImage, "fallbackS
   return { fallbackSeat: false };
 }
 
+/**
+ * The run a provision resolves images for, when it holds an Assembly that is not the current one
+ * (ADR-0069). The image map holds the current walk's contexts only, so a held run whose context the
+ * current Assembly dropped cannot provision, and `jr2 up` cannot fix it: the error must say which
+ * case it is.
+ */
+export type HeldImageScope = { runId: string; assembly: string; current: string | undefined };
+
 /**
  * Look one built key up in the map this converge wrote — for the Sandbox Image and the User
  * Container alike, because ADR-0005 gives the User Container "the same resolution" deliberately.
@@ -255,15 +266,27 @@ function judgeUser(recorded: string | undefined): Pick<ResolvedImage, "fallbackS
  * An unknown key throws: a converge-time check is impossible for a ref and unnecessary for a
  * context (the walk built every one it found), so this fires when the Orchestrator's own
  * `node_modules` holds a context the LAST converge did not build — a stale deployment. The error
- * says exactly that, because "re-run `jr2 up`" is the whole fix.
+ * says exactly that, because "re-run `jr2 up`" is the fix. It also fires for a run under a held
+ * Assembly (ADR-0069) whose context the current walk no longer carries, which `jr2 up` cannot fix.
+ * With `held`, the error names that case alone: the run, the held Assembly and the current one.
  */
-function builtRef(refs: ImageRefs, key: string, image: string, what: string): string {
+function builtRef(refs: ImageRefs, key: string, image: string, what: string, held?: HeldImageScope): string {
   const ref = refs.sandbox[key];
   if (ref === undefined) {
+    if (held) {
+      throw new Error(
+        `no ${what} for ${image} (context digest ${key}) — run ${held.runId} is under the held Assembly ` +
+          `${held.assembly}, whose context ${key} the current Assembly ${held.current ?? "(none)"} does not ` +
+          "carry. The image map holds the current Assembly's contexts only, so `jr2 up` does not fix this: " +
+          "publish an Assembly that names the context again, or cancel the run (ADR-0069).",
+      );
+    }
     throw new Error(
       `no ${what} for ${image} (context digest ${key}) — this instance's last converge built ` +
         `${Object.keys(refs.sandbox).length} image(s), none of them this one. Re-run \`jr2 up\`: it walks the ` +
-        "registered Machines and builds every `file:` context they carry (ADR-0037/0049).",
+        "registered Machines and builds every `file:` context they carry (ADR-0037/0049). A run under a held " +
+        "Assembly (ADR-0069) whose context the current Assembly no longer carries is the one case it does not " +
+        "fix: the map holds the current walk's contexts only.",
     );
   }
   return ref;
@@ -279,7 +302,11 @@ function builtRef(refs: ImageRefs, key: string, image: string, what: string): st
  * look up and nothing to say about its tag discipline — the cluster pulls it, and nothing was
  * inspected, so no seat fact is known.
  */
-export async function resolveSandboxImage(refs: ImageRefs, image?: string): Promise<ResolvedImage> {
+export async function resolveSandboxImage(
+  refs: ImageRefs,
+  image?: string,
+  held?: HeldImageScope,
+): Promise<ResolvedImage> {
   if (image === undefined) {
     const ref = refs.sandbox["default"];
     if (ref === undefined) return { ref: refs.harness, fallbackSeat: false };
@@ -287,7 +314,7 @@ export async function resolveSandboxImage(refs: ImageRefs, image?: string): Prom
   }
   if (!isImageContext(image)) return { ref: image, fallbackSeat: false };
   const key = await imageKey(image);
-  return { ref: builtRef(refs, key, image, "Sandbox Image"), ...judgeUser(refs.sandboxUser?.[key]) };
+  return { ref: builtRef(refs, key, image, "Sandbox Image", held), ...judgeUser(refs.sandboxUser?.[key]) };
 }
 
 /**
@@ -297,7 +324,7 @@ export async function resolveSandboxImage(refs: ImageRefs, image?: string): Prom
  * the one place ADR-0005 promises none. Its `USER` is not judged either: the seat carries no
  * `securityContext` at all, so root is allowed there.
  */
-export async function resolveUserImage(refs: ImageRefs, image: string): Promise<string> {
+export async function resolveUserImage(refs: ImageRefs, image: string, held?: HeldImageScope): Promise<string> {
   if (!isImageContext(image)) return image;
-  return builtRef(refs, await imageKey(image), image, "User Container image");
+  return builtRef(refs, await imageKey(image), image, "User Container image", held);
 }

package/src/index.ts

@@ -2,20 +2,42 @@
 // delivery surfaces, the duplex Actor over the Harness wire, and durable snapshot persistence
 // (ADR-0002/0006/0007). Builds on the `@jr2/agent-protocol` wire contract.
 //
-// It does NOT speak MCP (ADR-0013): the Agent's MCP surface is hosted by the Adapter, in the
-// Sandbox. What lives here is the registration table and two thin HTTP adapters over it.
+// It does NOT speak MCP (ADR-0013): the Harness presents the Menu to its model itself, and reaches
+// the surface here through the Custodian in its pod. What lives here is the registration table and
+// two thin HTTP adapters over it — plus what composes a Custodian (ADR-0059).
 
 // The wire contract, re-exported: a workflow authors against ONE package (`defineEvent`,
 // `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" — ADR-0015).
 export * from "@jr2/agent-protocol";
 export * from "./agent.ts";
+// The Effect surface (ADR-0067): `command` itself is the wire-bound one, from harness-client.ts;
+// `fromPick`, `paramsOf` and `answer` are what an author writes between a pick and its work.
+export * from "./effect.ts";
+// The http kind (ADR-0068): `http`, `secret`, `bearer`, `basic`, `text`, and the Effector's wire.
+export * from "./http-effect.ts";
+export * from "./sandbox-effect.ts";
+// An Effect's Open parts (ADR-0054): the types `customize({ effects })` reads.
+export type { EffectBinding, OpenEffect, OpenEffectPart } from "./open-effect.ts";
+export { openPartsText } from "./open-effect.ts";
+export * from "./effector-wire.ts";
+export * from "./pick.ts";
+// The Chart (ADR-0070): its grammar (`chartSchema`, which a Chart wrapper's door and a planner's pick
+// import), the door that admits one, and the resolver of its references.
+export * from "./chart.ts";
+// The Open body a Chart binds (`openBody`, the slot constructor a Chart wrapper places in `actors`)
+// and the named Charts of an Instance: Chart files and runtime Charts (ADR-0070).
+export * from "./open-body.ts";
+export * from "./charts.ts";
 export * from "./parts.ts";
+export * from "./size.ts";
 export * from "./customize.ts";
 export * from "./ambient.ts";
 export * from "./config.ts";
 export * from "./repo-identity.ts";
 export * from "./pool.ts";
 export * from "./setup.ts";
+// The author's routing guard (ADR-0015).
+export { sentBy } from "./party.ts";
 export * from "./vocabulary.ts";
 export * from "./tokens.ts";
 export * from "./durability.ts";
@@ -24,12 +46,35 @@ export * from "./actor.ts";
 export * from "./gate.ts";
 export * from "./workspace.ts";
 export * from "./images.ts";
-export * from "./sandbox-kubectl.ts";
+// The Assembly's content address and wire form (ADR-0069): `jr2 up` and the door share both.
+export * from "./content-hash.ts";
+export * from "./assembly-tar.ts";
+// The current Assembly and the publish door (ADR-0069), and the walk's refusal listing that
+// `jr2 up` and the door both run.
+export * from "./assembly.ts";
+export * from "./assembly-checks.ts";
+export * from "./mount-digest.ts";
+export * from "./model-keys.ts";
+export * from "./held-secrets.ts";
+export * from "./secret-placement.ts";
+export * from "./git-push.ts";
+export * from "./git-clone.ts";
+export * from "./custodian.ts";
+export * from "./sandbox-kube.ts";
+export {
+  effectorManifestKey,
+  LABEL_EFFECTOR_POD,
+  readSandboxEffectorManifest,
+  sandboxEffectorKeySecret,
+  sandboxEffectorObjectsOf,
+  type ProjectedSecret,
+  type SandboxEffectorManifest,
+} from "./sandbox-effector.ts";
 export * from "./repos.ts";
 export * from "./repo-fetch.ts";
 // Type-only: what a workflow event delivery looks like (the registration TABLE stays internal —
 // ADR-0011: workflows speak only defineEvent/agent/gate).
-export type { DeliveredEvent } from "./registration.ts";
+export type { ChildErrorMarker, DeliveredEvent, PlacingMarker, RunMarker, TurnMarker } from "./registration.ts";
 export * from "./machine-doc.ts";
 export * from "./run-host.ts";
 export * from "./http.ts";