@jr2/orchestrator 0.3.0 → 0.5.1

package/src/images.ts

@@ -1,7 +1,7 @@
 // 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` and the `custodian` sit beside a `sandbox`
@@ -10,8 +10,8 @@
 //
 // 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,6 +24,7 @@ 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` is the kit's own (built from a kit checkout, or
@@ -143,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).
  *
@@ -156,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);
@@ -182,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> {
@@ -194,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.`,
     );
   }
 }
@@ -227,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;
 };
@@ -249,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.
@@ -256,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;
@@ -280,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 };
@@ -288,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]) };
 }
 
 /**
@@ -298,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

@@ -1,44 +1,63 @@
-// @jr2/orchestrator — the deployed app that runs Machines: workflow config, the agent + gate
-// 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.
+// @jr2/orchestrator — the Authoring surface (GLOSSARY.md): the names an author writes in a
+// workflow module or in `jr2.config.ts`, and no other name. A name is here when an author writes
+// it; a name an author only meets through inference (a jr2Setup event union, a gate's input, a
+// pick's Frame) stays internal. A workflow authors against ONE package — `defineEvent`,
+// `jr2Setup`, `workspace`, … all import from "@jr2/orchestrator" (ADR-0015) — and an Assistant that
+// reads this file reads the whole of what it may write.
 //
-// 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";
-export * from "./parts.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";
-export * from "./vocabulary.ts";
-export * from "./tokens.ts";
-export * from "./durability.ts";
-export * from "./snapshot-store.ts";
-export * from "./actor.ts";
-export * from "./gate.ts";
-export * from "./workspace.ts";
-export * from "./images.ts";
-export * from "./model-keys.ts";
-export * from "./held-secrets.ts";
-export * from "./custodian.ts";
-export * from "./sandbox-kubectl.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 * from "./machine-doc.ts";
-export * from "./run-host.ts";
-export * from "./http.ts";
-export * from "./harness-client.ts";
-export * from "./stub-harness.ts";
-export * from "./instance.ts";
-export * from "./server.ts";
-export * from "./names.ts";
+// Named re-exports only, never `export *`: each name below is a decision, and
+// test/authoring-surface.test.ts pins the list. The kit's own packages (the CLI, the e2e suite,
+// the Harness's tests) import "@jr2/orchestrator/internal", which holds everything here and the
+// runtime besides.
+
+// Machine and events: the setup a workflow writes its Machine with, the events its parties send,
+// and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+export { defineEvent } from "@jr2/agent-protocol";
+export { jr2Setup } from "./setup.ts";
+export { sentBy } from "./party.ts";
+export type { HostInjectedInput } from "./vocabulary.ts";
+
+// Failure: the Part a Machine invokes to fail its run, and the guard that tells a Failure from a
+// defect in an `onError` (ADR-0073).
+export { fail, isFailure } from "./fail.ts";
+
+// Agents: an Agent slot and the definition it carries (ADR-0028, ADR-0049).
+export { agent } from "./harness-client.ts";
+export type { AgentDefinition, ThinkingLevel } from "./agent.ts";
+
+// Workspaces and Repos: a Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+export { workspace } from "./workspace.ts";
+export type { Workspaced } from "./workspace.ts";
+export type { Binding, RepoSlot } from "./parts.ts";
+
+// Effects: work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071),
+// and what an author writes between a pick and that work.
+export { arg } from "./effect.ts";
+export type { CommandOutput } from "./effect.ts";
+export { command } from "./harness-client.ts";
+export { basic, bearer, file, http, secret, text } from "./http-effect.ts";
+export type { HttpOutput } from "./effector-wire.ts";
+export { push } from "./sandbox-effect.ts";
+export type { PushOutput } from "./sandbox-effect.ts";
+export { dispatch } from "./dispatch-effect.ts";
+export type { DispatchOutput } from "./effect.ts";
+export { answer, fromPick, paramsOf } from "./pick.ts";
+
+// Composition: a part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017,
+// ADR-0049, ADR-0054, ADR-0060).
+export { open } from "./parts.ts";
+export { customize } from "./customize.ts";
+export type { Customize } from "./customize.ts";
+export type { EffectBinding } from "./open-effect.ts";
+export type { Size, UserContainer } from "./size.ts";
+export { pool, source } from "./pool.ts";
+
+// Charts: the Open body a Chart wrapper places in `actors`, and the grammar a planner's pick
+// declares, whole or narrowed to one wrapper (ADR-0070).
+export { openBody } from "./open-body.ts";
+export type { OpenBodyDeclaration, OpenBodyOutput } from "./open-body.ts";
+export { chartSchema, chartSchemaFor } from "./chart.ts";
+
+// Config: `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
+export { defineConfig } from "./config.ts";
+export type { JR2Config } from "./config.ts";