@jr2/orchestrator 0.4.1 → 0.5.1

package/src/custodian.ts

@@ -217,30 +217,72 @@ function meta(fields: Record<string, string>): Json {
   return { filter_metadata: { [LUA_FILTER]: fields } };
 }
 
-/** An upstream that never answered, said as the Custodian's own 502 (§5.4) — the host and Envoy's
- * reason, never a retry without verification. */
-function unreachable(target: string): Json {
+/** Envoy's flags for a request it did not send to the target (ADR-0059): the connection failed, no
+ * host was healthy, the DNS lookup failed. */
+export const NOT_SENT_FLAGS = ["UF", "UH", "DF"] as const;
+
+/** Envoy's flags for a request that may have reached the target before the stream ended (ADR-0059):
+ * the target closed the connection or reset the stream, Envoy reset it, a protocol error on either
+ * side (a body framing error can come after the headers went). `UMSDR` (the maximum stream
+ * duration) ends a stream that was sent. `URX` (the retry limit) comes with the last attempt's own
+ * flag (`UF,URX`, `UC,URX`), so alone it says nothing of the send; the mapper for
+ * {@link NOT_SENT_FLAGS} comes first, so `UF,URX` still reads "could not be reached". These routes
+ * set no retry policy and no `max_stream_duration`, so Envoy sets neither flag on them; they keep
+ * the union equal to ORCHESTRATOR_UNREACHABLE's. */
+export const MAY_HAVE_SENT_FLAGS = ["UC", "DPE", "UMSDR", "URX", "UPE", "UR", "LR"] as const;
+
+/** One of the Custodian's own 502s for a target that gave no answer (§5.4): the target, what
+ * jr2 knows about the request, and Envoy's reason — never a retry without verification. */
+function noAnswer(target: string, flags: readonly string[], words: string): Json {
   return {
-    mappers: [
-      {
-        filter: { response_flag_filter: { flags: ["UF", "URX", "UH", "UC", "DF", "DPE", "UMSDR"] } },
-        status_code: 502,
-        body_format_override: {
-          text_format_source: {
-            inline_string: `jr2 custodian: ${target} could not be reached: %RESPONSE_CODE_DETAILS% %UPSTREAM_TRANSPORT_FAILURE_REASON%\n`,
-          },
-        },
+    filter: { response_flag_filter: { flags: [...flags] } },
+    status_code: 502,
+    body_format_override: {
+      text_format_source: {
+        inline_string: `jr2 custodian: ${target} ${words}: %RESPONSE_CODE_DETAILS% %UPSTREAM_TRANSPORT_FAILURE_REASON%\n`,
       },
-    ],
+    },
   };
 }
 
+const NOT_REACHED = "could not be reached";
+const MAY_HAVE_REACHED = "did not answer; the request may have reached it";
+
+/**
+ * An intercepted target that gave no answer (ADR-0059). Two mappers, because the words must be
+ * true: after a `NOT_SENT_FLAGS` failure the target did not get the request, and after a
+ * `MAY_HAVE_SENT_FLAGS` one it may have it — so an Agent that sends a POST again can write twice,
+ * and the text must not tell it the first one went nowhere. One reply can carry several flags,
+ * and Envoy uses the first mapper that matches, in order: the `NOT_SENT_FLAGS` mapper is first, so
+ * a reply with `UF`, `UH` or `DF` reads "could not be reached" whatever else it carries. Without
+ * the mappers, Envoy answers each of these flags itself (503 for most, 502 for `UPE`) with a body
+ * that names no target, which a caller can read as the target's answer. No caller reads the flags;
+ * the Orchestrator route's go to the Harness, which tells "never reached" from "not known"
+ * (ADR-0002).
+ */
+function unreachable(target: string): Json {
+  return {
+    mappers: [noAnswer(target, NOT_SENT_FLAGS, NOT_REACHED), noAnswer(target, MAY_HAVE_SENT_FLAGS, MAY_HAVE_REACHED)],
+  };
+}
+
+/** The tunnel's 502 (ADR-0059): every flag, one text. Envoy answers a `CONNECT` with 200 only after
+ * its TCP connection to the target is up, and no byte of the Agent's request goes before that 200.
+ * So a 502 on the tunnel always comes before the request reached the target, whatever its flag. */
+function tunnelUnreachable(target: string): Json {
+  return { mappers: [noAnswer(target, [...NOT_SENT_FLAGS, ...MAY_HAVE_SENT_FLAGS], NOT_REACHED)] };
+}
+
 /** The Orchestrator unreachable, said so the Harness can tell it from an answer and retry the
  * surface read the way ADR-0042 asks — the one route on this pod that retries. */
 const ORCHESTRATOR_UNREACHABLE: Json = {
   mappers: [
     {
-      filter: { response_flag_filter: { flags: ["UF", "URX", "UH", "UC", "DF", "DPE", "UMSDR"] } },
+      // Envoy's own answers for a stream it reset (`UPE`, `UR`, `LR`: 503, or 502 for `UPE`) are said
+      // here too, so the Harness reads them as "not known" and not as a stopping Orchestrator's 503
+      // (ADR-0002). One text for
+      // both lists: the Harness reads the flags, not the words.
+      filter: { response_flag_filter: { flags: [...NOT_SENT_FLAGS, ...MAY_HAVE_SENT_FLAGS] } },
       status_code: 502,
       headers_to_add: [
         { header: { key: "x-jr2-custodian", value: "unreachable" }, append_action: "OVERWRITE_IF_EXISTS_OR_ADD" },
@@ -333,7 +375,7 @@ function egressReplies(): Json {
           },
         },
       },
-      ...(unreachable("%REQ(:AUTHORITY)%").mappers as Json[]),
+      ...(tunnelUnreachable("%REQ(:AUTHORITY)%").mappers as Json[]),
     ],
   };
 }
@@ -794,6 +836,12 @@ export type CustodianCompositionOptions = {
   /** This pod's Sandbox — the name the ask is addressed by (ADR-0053). Absent on the Instance
    * Harness, which mounts no Repo and answers an ask by saying so. */
   sandbox?: string;
+  /** The names of the Instance objects that this Custodian reads in place of the defaults. The
+   * defaults are the Instance's own: `pod`'s literal values (`heldSecretsSecret(pod)`),
+   * `jr2-held-tls`, `jr2-ca`, and the program in `jr2-held`.
+   * The check pod (ADR-0019) reads its own copies, so a check pod writes nothing that a running pod
+   * of the Instance reads. */
+  reads?: { literals: string; tls: string; trust: string; program: string };
   /** The Instance ships a `harness.caBundle` (ADR-0020). */
   caBundle: boolean;
   /** The Custodian container's resources (ADR-0060) — the placement's to choose: a Sandbox's fixed
@@ -837,6 +885,12 @@ const CUSTODIAN_SECURITY = {
 export function custodianComposition(manifest: HeldManifest, opts: CustodianCompositionOptions): CustodianComposition {
   const held = manifest.secrets.length > 0;
   const literal = manifest.secrets.filter((s) => s.source.kind === "literal").map((s) => s.name);
+  const {
+    literals = heldSecretsSecret(opts.pod),
+    tls = HELD_TLS_SECRET,
+    trust: trustMap = CA_CONFIGMAP,
+    program = HELD_CONFIGMAP,
+  } = opts.reads ?? {};
 
   const harnessEnv: HarnessEnvVar[] = [
     { name: "JR2_CUSTODIAN_URL", value: CUSTODIAN_URL },
@@ -870,9 +924,7 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
         defaultMode: 0o440,
         sources: [
           { secret: { name: opts.token.secret, items: [{ key: opts.token.key, path: SANDBOX_TOKEN_NAME }] } },
-          ...(literal.length
-            ? [{ secret: { name: heldSecretsSecret(opts.pod), items: literal.map((n) => ({ key: n, path: n })) } }]
-            : []),
+          ...(literal.length ? [{ secret: { name: literals, items: literal.map((n) => ({ key: n, path: n })) } }] : []),
           ...manifest.secrets.flatMap((s) =>
             s.source.kind === "secret"
               ? [{ secret: { name: s.source.secret, items: [{ key: s.source.key, path: s.name }] } }]
@@ -896,20 +948,20 @@ export function custodianComposition(manifest: HeldManifest, opts: CustodianComp
               ],
             },
           },
-          { configMap: { name: HELD_CONFIGMAP, items: [{ key: CUSTODIAN_PROGRAM_KEY, path: CUSTODIAN_PROGRAM_KEY }] } },
+          { configMap: { name: program, items: [{ key: CUSTODIAN_PROGRAM_KEY, path: CUSTODIAN_PROGRAM_KEY }] } },
         ],
       },
     },
     ...(held
       ? [
-          { name: "custodian-tls", secret: { secretName: HELD_TLS_SECRET, defaultMode: 0o440 } },
+          { name: "custodian-tls", secret: { secretName: tls, defaultMode: 0o440 } },
           {
             name: "custodian-trust",
-            configMap: { name: CA_CONFIGMAP, items: [{ key: "upstream.crt", path: "upstream.crt" }] },
+            configMap: { name: trustMap, items: [{ key: "upstream.crt", path: "upstream.crt" }] },
           },
         ]
       : []),
-    ...(trust ? [{ name: "ca", configMap: { name: CA_CONFIGMAP } }] : []),
+    ...(trust ? [{ name: "ca", configMap: { name: trustMap } }] : []),
   ];
 
   const custodianContainer: Container = {

package/src/customize.ts

@@ -77,7 +77,7 @@ import {
 import { isEffect, type Arg } from "./effect.ts";
 import { attachLent, copyOpenBody, lentIn, openBodiesOf, openBodyDeclarationOf } from "./open-body.ts";
 import { effectChecks } from "./effect-checks.ts";
-import type { Text } from "./http-effect.ts";
+import type { NamedSecret, Text } from "./http-effect.ts";
 import {
   binderOf,
   effectBindingShape,
@@ -116,37 +116,61 @@ type SlotsOf<M extends AnyStateMachine> =
     ? TActor
     : never;
 
-/** The logic a Machine declares under one slot key. */
+/**
+ * The logic a Machine declares under one slot key.
+ *
+ * @internal
+ */
 type LogicAt<M extends AnyStateMachine, K extends string> = Extract<SlotsOf<M>, { src: K }>["logic"];
 
-/** The Agent slots — told from every other slot by their logic, which no other actor kind has. */
+/**
+ * The Agent slots — told from every other slot by their logic, which no other actor kind has.
+ *
+ * @internal
+ */
 type AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
 
 /** The Effect slots with an Open part — told by the phantom `OpenEffect` their constructor's
- * overload states for an `open` url or argv, or a `secret(open)` (open-effect.ts). */
+ * overload states for an `open` url or argv, or a `secret(open)` (open-effect.ts).
+ *
+ * @internal
+ */
 type OpenEffectSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: OpenEffect<OpenEffectPart> }>["src"];
 
-/** What one Open part binds to: a url, an argv, a secret's name. */
+/** What one Open part binds to: a url, an argv, a secret's name, a dispatch's target — another
+ * Orchestrator's origin and the secret that holds its Instance token, together (ADR-0071). */
 type PartBinding<P> = P extends "url"
   ? { url: string | Text }
   : P extends "argv"
     ? { argv: readonly (string | Arg)[] }
     : P extends "secret"
       ? { secret: string }
-      : never;
+      : P extends "target"
+        ? { target: { url: string; token: NamedSecret } }
+        : never;
 
 /** A union of object types as their intersection: one binding object with every key. */
 type Intersected<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 
 /** What one Open Effect binds to: its url, its argv or its secret — for an Effect with two Open
- * parts, one object with both keys, the intersection of their bindings (ADR-0054). */
+ * parts, one object with both keys, the intersection of their bindings (ADR-0054).
+ *
+ * @internal
+ */
 type BindingOf<L> = L extends OpenEffect<infer P> ? Intersected<PartBinding<P>> : never;
 
 /** The child-Machine slots: the slots composition reaches (ADR-0049 — a nested Machine is an
- * ordinary `invoke` of an ordinary slot). */
+ * ordinary `invoke` of an ordinary slot).
+ *
+ * @internal
+ */
 type ChildSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AnyStateMachine }>["src"];
 
-/** The child Machine under one slot key, constrained so `Customize` may recurse into it. */
+/**
+ * The child Machine under one slot key, constrained so `Customize` may recurse into it.
+ *
+ * @internal
+ */
 type ChildAt<M extends AnyStateMachine, K extends string> = Extract<LogicAt<M, K>, AnyStateMachine>;
 
 /**
@@ -160,6 +184,7 @@ type ChildAt<M extends AnyStateMachine, K extends string> = Extract<LogicAt<M, K
 // Each step is taken on the wrapper's MARKER (`JR2Wrapper`, parts.ts), never on a slot's spelling —
 // an author is free to name a slot `body` or `worker`, and routing through it because of the name
 // would offer the Agents of a Machine the composer never named.
+/** @internal */
 type Reached<M extends AnyStateMachine> = M extends JR2Wrapper<infer TBody> ? Reached<TBody> : M;
 
 /**
@@ -167,67 +192,125 @@ type Reached<M extends AnyStateMachine> = M extends JR2Wrapper<infer TBody> ? Re
  * {@link Reached}: down through the wrappers to the first Machine that composes a Sandbox, which
  * is the one whose `JR2Repos` marker says which slots exist (ADR-0051). `never` when no wrapper on
  * the chain composes one, which is what makes `repos` unavailable there rather than `{}`.
+ *
+ * @internal
  */
 type WorkspaceOf<M extends AnyStateMachine> =
   M extends JR2Repos<any> ? M : M extends JR2Wrapper<infer TBody> ? WorkspaceOf<TBody> : never;
 
 /** The Repo Slot keys the reached `workspace()` declared. The `never` case is tested by itself,
  * because `never extends JR2Repos<infer TSlots>` is true with nothing to infer from — and an
- * uninferred `TSlots` widens to `string`, which would offer every key exactly where there are none. */
+ * uninferred `TSlots` widens to `string`, which would offer every key exactly where there are none.
+ *
+ * @internal
+ */
 type RepoSlotsOf<M extends AnyStateMachine> = [WorkspaceOf<M>] extends [never]
   ? never
   : WorkspaceOf<M> extends JR2Repos<infer TSlots>
     ? TSlots
     : never;
 
+// What may be retuned on one Machine, mirroring the DECLARATION's own shape and recursively
+// partial (ADR-0049): every key optional, every Agent override a partial definition, every child a
+// `Customize` of that child. `image`/`user` are the `workspace()` options (ADR-0037, ADR-0005) and
+// apply to the wrapper the chain reaches; a Machine that composes no Sandbox refuses them at build
+// time, because there is nothing for them to name.
 /**
- * What may be retuned on one Machine, mirroring the DECLARATION's own shape and recursively
- * partial (ADR-0049): every key optional, every Agent override a partial definition, every child
- * a `Customize` of that child.
+ * The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the
+ * Machines it composes, and the Sandbox of its `workspace()`. The type comes from the Machine
+ * itself, so it offers only the parts that the Machine declares. A key for a part the Machine does
+ * not declare does not compile. The `agents`, `effects`, `actors` and `repos` keys take no value
+ * when the Machine has no such part. `image`, `user` and `resources` compile on every Machine, and
+ * `customize()` refuses them when the Machine composes no `workspace()`.
+ *
+ * Every key is optional. Write only what you change.
+ *
+ * @example
+ * ```ts
+ * import { customize, type Customize } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * const parts: Customize<typeof task> = {
+ *   repos: { app: { url: "https://github.com/you/app.git", ref: "main" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5", thinkingLevel: "high" } },
+ * };
  *
- * `image`/`user` are the `workspace()` options (ADR-0037, ADR-0005) and apply to the wrapper the
- * chain reaches; a Machine that composes no Sandbox refuses them at build time, because there is
- * nothing for them to name.
+ * export const machine = customize(task, parts);
+ * ```
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/concepts/composition.md
+ * @see docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md
  */
 export type Customize<M extends AnyStateMachine> = {
-  /** Retune an Agent this Machine carries: the override is layered over the stock definition, so
-   * `{ model }` alone keeps the instructions the author wrote — and BINDS the model when the
-   * author left it Open (ADR-0054), which is the common consumer line for a packaged Machine. The
-   * override is a `Partial<AgentDefinition>`, never a declaration: a composer binds, and binding
-   * to `open` again is not a thing anyone means. A Machine carrying no Agent takes `never` rather
-   * than `{}`: an empty object type accepts any literal, which would make the one case with
-   * nothing to name the one case with nothing checked. */
+  // `{ model }` alone BINDS the model when the author left it Open (ADR-0054), which is the common
+  // consumer line for a packaged Machine. The override is a `Partial<AgentDefinition>`, never a
+  // declaration: a composer binds, and binding to `open` again is not a thing anyone means
+  // (ADR-0054). A Machine carrying no Agent takes `never` rather than `{}`: an empty object type
+  // accepts any literal, which would make the one case with nothing to name the one case with
+  // nothing checked.
+  /** Retune the Agents that this Machine carries, by slot name: `{ coder: { model } }`. Each
+   * override goes over the definition that the author wrote, field by field, so `{ model }` alone
+   * keeps the author's instructions. When the author left the model Open, this is where you bind
+   * it. Allowed fields: the fields of an `agent()` definition. At run time, `customize()` refuses a
+   * slot that holds no Agent: `customize(): machine "<id>" carries no Agent slot "<slot>" — its
+   * Agents are: <slots>`. */
   agents?: [AgentSlots<Reached<M>>] extends [never]
     ? never
     : { [K in AgentSlots<Reached<M>>]?: Partial<AgentDefinition> };
-  /** Bind an Effect's Open parts (ADR-0054): `{ url }` for an http Effect (whatever its body) whose url
-   * the package left Open, `{ argv }` for a command whose argv it left Open, `{ secret }` for an
-   * Effect that names `secret(open)` — one object with both keys for an Effect with two, so a binding
-   * that leaves one out does not compile. Bound once, here — a value, never a mapper over the door,
-   * so the host is fixed before any run. Only an Effect with an Open part is offered: a part its
-   * author fixed stays fixed. A Machine with none takes `never`, as `agents` does. */
+  // `{ url }` is for an http Effect whatever its body (ADR-0054); `{ target }` binds a dispatch's
+  // url and token as one (ADR-0071). Bound once, here — a value, never a mapper over the door, so
+  // the host is fixed before any run (ADR-0054). Only an Effect with an Open part is offered: a
+  // part its author fixed stays fixed. A Machine with none takes `never`, as `agents` does.
+  /** Bind the Open parts of this Machine's Effects, by slot name: `{ url }` for an `http` Effect
+   * whose url is Open, `{ argv }` for a `command` whose argv is Open, `{ secret }` for an Effect
+   * that names `secret(open)`, `{ target: { url, token: secret("<name>") } }` for a `dispatch`
+   * whose target is Open. For an Effect with two Open parts, one object holds both keys, and
+   * a binding that leaves one out does not compile. Only Effects with an Open part are offered.
+   * See {@link EffectBinding} for the values and the refusals. */
   effects?: [OpenEffectSlots<Reached<M>>] extends [never]
     ? never
     : { [K in OpenEffectSlots<Reached<M>>]?: BindingOf<LogicAt<Reached<M>, K>> };
-  /** Retune a Machine this one composes — the same shape, one level down. */
+  /** Retune a Machine that this Machine composes, by slot name. The value has the same shape as
+   * these parts, one level down. At run time, `customize()` refuses a slot that holds no Machine:
+   * `customize(): machine "<id>" composes no Machine under "<slot>"`. */
   actors?: [ChildSlots<Reached<M>>] extends [never]
     ? never
     : { [K in ChildSlots<Reached<M>>]?: Customize<ChildAt<Reached<M>, K>> };
-  /** The Sandbox Image (ADR-0037): a `file:` URL to a docker context this module ships, or a
-   * registry ref. */
+  // The Sandbox Image (ADR-0037).
+  /** The Sandbox Image: a `file:` URL to a docker context that your module ships
+   * (`import.meta.resolve("./image")`), which `jr2 up` builds, or a registry ref. It replaces the
+   * image of the `workspace()`. When the Machine composes no `workspace()`, `customize()` refuses it
+   * at run time. */
   image?: string;
-  /** The User Container (ADR-0005): its image in the same two shapes, or `{ image, resources }`
-   * with its split of the Size (ADR-0060). Replaces the seat whole — split included. */
+  // The User Container (ADR-0005), in the same two shapes, or `{ image, resources }` with its split
+  // of the Size (ADR-0060). Replaces the seat whole — split included.
+  /** The User Container: its image, as a `file:` URL or a registry ref, or a
+   * {@link UserContainer} that also gives its part of the Size. It replaces the whole User
+   * Container, its part of the Size included. When the Machine composes no `workspace()`,
+   * `customize()` refuses it at run time. */
   user?: string | UserContainer;
-  /** The Size (ADR-0060), layered field by field over the `workspace()`'s own: the composer's
-   * Repo may be bigger than the author's. `limits.memory` and `limits.cpu`, nothing else. */
+  // The Size (ADR-0060), layered over the `workspace()`'s own: the composer's Repo may be bigger
+  // than the author's.
+  /** The Size, layered field by field over the Size of the `workspace()`: `{ limits: { memory } }`
+   * keeps the author's cpu. Only `limits.memory` and `limits.cpu`. See {@link Size}. Only for a
+   * Machine that composes a `workspace()`. */
   resources?: Size;
-  /** Bind the Repo Slots the reached `workspace()` declared (ADR-0051) — an open slot to a url,
-   * or a bound or per-run one to a different Binding; any of the three forms, so a consumer can
-   * also bind a mapper over the wrapper's door. A slot the Machine does not declare is a compile
-   * error, and a Machine that composes no Sandbox takes `never`, as `agents` does. A `workspace()`
-   * that declared its map Open takes any keys — they are the composer's words, in the order the
-   * Machine documents — and at least one, checked at the call. */
+  // Any of the three slot forms, so a consumer can also bind a mapper over the wrapper's door
+  // (ADR-0051). A Machine that composes no Sandbox takes `never`, as `agents` does. A
+  // `workspace()` that declared its map Open takes any keys — they are the composer's words, in the
+  // order the Machine documents — and at least one, checked at the call.
+  /** Bind the Repo Slots of the `workspace()`, by slot name. Each value is one of these:
+   *
+   * - a url
+   * - a Binding `{ url, ref? }`
+   * - a function `({ input }) => url | { url, ref? }` over the run input
+   * - `open`, to leave the slot for the next composer to bind
+   *
+   * You can bind an Open slot, or give a bound or per-run slot a different Binding. A slot that
+   * the Machine does not declare does not compile. Some Machines, such as `task`, leave their
+   * whole slot map Open. Then you name every slot, and at least one. The keys are your names for
+   * the Repos, and the Machine says what their order means. */
   repos?: [RepoSlotsOf<M>] extends [never] ? never : { [K in RepoSlotsOf<M>]?: RepoSlot<InputFrom<WorkspaceOf<M>>> };
 };
 
@@ -242,10 +325,55 @@ type LooseParts = {
   resources?: Size;
 };
 
+// Returns a NEW Machine of the same type — the original is untouched, so two customizations of one
+// import are two independent Machines (ADR-0049's `deep`/`quick`), and a run of either carries what
+// it was given.
 /**
- * Retune the parts a Machine carries, returning a NEW Machine of the same type — the original is
- * untouched, so two customizations of one import are two independent Machines (ADR-0049's
- * `deep`/`quick`), and a run of either carries what it was given.
+ * Retune the parts that a Machine carries, without a change to the module that exports it. Use it
+ * where you register a Machine as a Workflow. It binds the parts that a packaged Machine leaves
+ * Open: its Repo Slots, an Agent's model, or an Effect's url, argv or secret. It also changes the
+ * parts that its author fixed: an Agent's instructions, the Sandbox Image, or the Size.
+ *
+ * It gives back a new Machine of the same type. The original does not change, so two
+ * `customize()` calls on one import give two Machines. Only the parts the Machine declares can be
+ * retuned. You cannot add a part: a Machine that needs another Agent is a new Machine. The types
+ * refuse most mistakes when you compile. At run time, `customize()` also throws:
+ *
+ * - `customize(): machine "<id>" carries no Agent slot "<slot>" — its Agents are: <slots>`
+ * - `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots>`
+ * - `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots>`
+ * - `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots>`
+ * - `customize(): machine "<id>" declares its Repo Slots open as a map — name at least one`
+ * - `` customize(): `repos` say what a SANDBOX is made of, how big it is and which Repos it
+ *   attaches, and machine "<id>" composes none `` (for `resources`, the text starts
+ *   `` customize(): `resources` ``; for `image` or `user`, it starts `` customize(): `image`/`user` ``)
+ * - `customize(): machine "<id>": <errors>`, when an Effect argv that you bind fails the checks
+ *   that the Machine passed when it was built
+ * - the refusals of {@link EffectBinding}, {@link RepoSlot}, {@link Size} and
+ *   {@link UserContainer}, which start with `customize()`
+ *
+ * @param machine - The Machine to retune: one you import from a package, or one you wrote. When
+ * its root is a `workspace()` or a `pool()`, `customize()` reaches through to the Machine inside,
+ * so you never name the wrapper's own slot.
+ * @param parts - The parts to change. See {@link Customize}.
+ * @returns A new Machine of the same type, with the parts changed.
+ *
+ * @example
+ * ```ts
+ * import { customize } from "@jr2/orchestrator";
+ * import { task } from "@jr2/machines";
+ *
+ * export const machine = customize(task, {
+ *   repos: { app: { url: "https://github.com/you/app.git" } },
+ *   agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
+ *   resources: { limits: { memory: "4Gi" } },
+ * });
+ * ```
+ *
+ * @see docs/guides/bind-open-parts.md
+ * @see docs/concepts/composition.md
+ * @see docs/reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md
+ * @see docs/reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md
  */
 export function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M {
   const { agents, effects, actors, image, user, repos, resources } = parts as LooseParts;
@@ -360,7 +488,7 @@ function retune(machine: AnyStateMachine, parts: LooseParts): AnyStateMachine {
 /**
  * Bind one Effect's Open parts (ADR-0054): the slot must be an Effect, each key of the binding one
  * of its Open parts, and each value the value that part takes — a url (a string, or a `text` with a
- * secret in its path), an argv, or a secret's name. A key left out leaves that part Open. The binder
+ * secret in its path), an argv, a secret's name, or a dispatch's target (ADR-0071). A key left out leaves that part Open. The binder
  * builds the Effect again, whole, so the bound one meets every check its constructor runs: the url's
  * literal host, the argv's entries, the secret's name. The compiler's check of the
  * invoke's input against the argv's slots does not reach it (an Open argv's input is one string per
@@ -400,6 +528,17 @@ function bindEffect(machine: AnyStateMachine, name: string, binding: EffectBindi
           `${value === open ? "`open` again" : "a function of the run"}: no run chooses an Effect's ${part} (ADR-0054)`,
       );
     }
+    if (part === "target") {
+      // The whole target is the Open part (ADR-0071): an origin and a named secret, bound together.
+      // The dispatch's own constructor checks the url and the name when the binder rebuilds it.
+      const target = value as { url?: unknown; token?: unknown } | null;
+      if (typeof target !== "object" || target === null || typeof target.url !== "string" || !isSecret(target.token)) {
+        throw new Error(
+          `customize(): the dispatch Effect "${name}"'s target is bound to another Orchestrator's origin and the ` +
+            `secret that holds its Instance token: ${effectBindingShape("target")} (ADR-0071)`,
+        );
+      }
+    }
     if (part === "secret" && typeof value !== "string") {
       throw new Error(
         `customize(): the ${logic.effect.kind} Effect "${name}"'s secret is bound to a secret's name, a string — ` +
@@ -410,6 +549,9 @@ function bindEffect(machine: AnyStateMachine, name: string, binding: EffectBindi
   return binder(binding);
 }
 
+const isSecret = (value: unknown): boolean =>
+  typeof value === "object" && value !== null && typeof (value as { secret?: unknown }).secret === "string";
+
 /**
  * The load walk's Effect checks (ADR-0067), again, on a Machine whose Open argv this `customize()`
  * bound: at build its argv slots were unknown and every pick param counted as read; now the bound