@jr2/orchestrator 0.3.0 → 0.4.1

package/src/customize.ts

@@ -9,24 +9,31 @@
 // `.provide()`, nothing to learn (ADR-0015's rule, restated by ADR-0049 — a `.with()` method and
 // a callable-machine hybrid were both rejected there).
 //
-// Three moves, and each is the smallest one that works:
+// Four moves, and each is the smallest one that works:
 //
 //   - An AGENT override is xstate's own `provide`: `machine.provide({ actors: { coder:
 //     agent({ ...stock, ...override }) } })`. The slot already IS the Agent (ADR-0049), so
 //     retuning one is substituting a slot's logic, which is what `provide` is for.
+//   - An EFFECT binding is the same substitution (ADR-0054): an Effect whose url or argv the
+//     package left `open`, or whose auth, header or env names `secret(open)`, carries a binder,
+//     which builds the Effect again with the composer's parts, so the bound slot is checked as a
+//     written one is. Once — a bound part is fixed from then on.
 //   - A CHILD override is the same call one level down, recursing. Each level is exactly the
 //     one-level reach ADR-0015 found `provide` has — held by the composer who owns the child
 //     object, never host-side injection into somebody else's Machine.
-//   - The IMAGE and the REPOS are the parts `provide` cannot carry: xstate copies implementations
+//   - The IMAGE, the REPOS and the SIZE are the parts `provide` cannot carry: xstate copies implementations
 //     and passes the CONFIG through by reference, and every part a Machine carries is keyed on
 //     that config (parts.ts, vocabulary.ts). A new image or a bound slot therefore needs a new key
 //     — so those fields clone the wrapper's config and rebuild it with the same implementations,
-//     re-attaching what the original carried.
+//     re-attaching what the original carried. The load warnings of a bound argv are the same
+//     kind of part: the Machine the author wrote is rebuilt the same way, carrying the rechecked
+//     warnings in place of the Open Machine's.
 //
 // jr2's wrappers are TRANSPARENT: `agents`/`actors` route through `workspace()`'s `body` and
 // `pool()`'s `worker`, so a consumer customizing a Workspace-rooted workflow never writes `body`
-// and never has to know that jr2 wrapped anything. `image`/`user`/`repos` travel the same chain in
-// the other direction — down to the `workspace()` that owns the seats and the slots.
+// and never has to know that jr2 wrapped anything. `image`/`user`/`repos`/`resources` travel the same
+// chain in the other direction — down to the `workspace()` that owns the seats, the slots and the
+// Size.
 //
 // Both halves route on the wrapper's own RECORD of being one, never on a slot's spelling: the
 // runtime reads `wrapperBodyOf` and the types read `JR2Wrapper` (parts.ts), which the wrappers
@@ -38,7 +45,7 @@
 // its slot MAP Open (`repos: open`, ADR-0051) declared exactly this: every slot is the composer's
 // to name, so the map they write is the declaration, not an addition to one.
 
-import { StateMachine, type AnyStateMachine, type InputFrom, type ProvidedActor } from "xstate";
+import { StateMachine, type AnyStateMachine, type InputFrom, type ProvidedActor, type UnknownActorLogic } from "xstate";
 import type { AgentLogic } from "./actor.ts";
 import { isAgent, type AgentDefinition } from "./agent.ts";
 import { agent } from "./harness-client.ts";
@@ -56,7 +63,30 @@ import {
   type RepoSlot,
   type SandboxParts,
 } from "./parts.ts";
-import { attachInputSchema, attachVocabulary, inputSchemaOf, vocabularyOf } from "./vocabulary.ts";
+import { assertSize, assertUserSeat, layerSize, type Size, type UserContainer } from "./size.ts";
+import {
+  attachInputSchema,
+  attachLoadWarnings,
+  attachSeats,
+  attachVocabulary,
+  inputSchemaOf,
+  loadWarningsOf,
+  seatsOf,
+  vocabularyOf,
+} from "./vocabulary.ts";
+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 {
+  binderOf,
+  effectBindingShape,
+  openPartsOf,
+  openPartsText,
+  type EffectBinding,
+  type OpenEffect,
+  type OpenEffectPart,
+} from "./open-effect.ts";
 
 // --- What a Machine declares, read at the TYPE level ---------------------------------------------
 // Everything below reads xstate's own `TActor` parameter — the `{ src, logic, id }` union
@@ -92,6 +122,26 @@ type LogicAt<M extends AnyStateMachine, K extends string> = Extract<SlotsOf<M>,
 /** The Agent slots — told from every other slot by their logic, which no other actor kind has. */
 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). */
+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. */
+type PartBinding<P> = P extends "url"
+  ? { url: string | Text }
+  : P extends "argv"
+    ? { argv: readonly (string | Arg)[] }
+    : P extends "secret"
+      ? { secret: string }
+      : 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). */
+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). */
 type ChildSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AnyStateMachine }>["src"];
@@ -150,6 +200,15 @@ export type Customize<M extends AnyStateMachine> = {
   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. */
+  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. */
   actors?: [ChildSlots<Reached<M>>] extends [never]
     ? never
@@ -157,8 +216,12 @@ export type Customize<M extends AnyStateMachine> = {
   /** The Sandbox Image (ADR-0037): a `file:` URL to a docker context this module ships, or a
    * registry ref. */
   image?: string;
-  /** The User Container's image (ADR-0005), in the same two shapes. */
-  user?: 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. */
+  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. */
+  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
@@ -171,10 +234,12 @@ export type Customize<M extends AnyStateMachine> = {
 /** The same shape with the types erased — what the implementation walks. */
 type LooseParts = {
   agents?: Record<string, Partial<AgentDefinition> | undefined>;
+  effects?: Record<string, EffectBinding | undefined>;
   actors?: Record<string, LooseParts | undefined>;
   image?: string;
-  user?: string;
+  user?: string | UserContainer;
   repos?: Record<string, RepoSlot | undefined>;
+  resources?: Size;
 };
 
 /**
@@ -183,23 +248,32 @@ type LooseParts = {
  * `deep`/`quick`), and a run of either carries what it was given.
  */
 export function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M {
-  const { agents, actors, image, user, repos } = parts as LooseParts;
+  const { agents, effects, actors, image, user, repos, resources } = parts as LooseParts;
   let out: AnyStateMachine = machine;
   // Order matters in one direction only: the Sandbox seats and slots REBUILD the wrapper, so they
   // go last and carry the retuned implementations with them.
-  if (agents || actors) out = retune(out, { agents, actors });
+  if (agents || effects || actors) out = retune(out, { agents, effects, actors });
   const seats: Seats = {
     ...(image !== undefined ? { image } : {}),
     ...(user !== undefined ? { user } : {}),
     ...(repos !== undefined ? { repos } : {}),
+    ...(resources !== undefined ? { resources } : {}),
   };
-  if (seats.image !== undefined || seats.user !== undefined || seats.repos !== undefined) out = reseat(out, seats);
+  // Refused where the composer wrote them, by field (ADR-0060), before any wrapper is rebuilt.
+  if (seats.user !== undefined) assertUserSeat("customize()", seats.user);
+  if (seats.resources !== undefined) assertSize("customize(): resources", seats.resources);
+  if (Object.keys(seats).length > 0) out = reseat(out, seats);
   return out as M;
 }
 
-/** What `reseat` carries down the chain: the two image seats and the slot overrides, each present
- * only when the composer named it. */
-type Seats = { image?: string; user?: string; repos?: Record<string, RepoSlot | undefined> };
+/** What `reseat` carries down the chain: the two image seats, the slot overrides and the Size, each
+ * present only when the composer named it. */
+type Seats = {
+  image?: string;
+  user?: string | UserContainer;
+  repos?: Record<string, RepoSlot | undefined>;
+  resources?: Size;
+};
 
 /** The slot keys whose logic answers `pred` — what an error names, so the message is the
  * Machine's own declaration rather than advice. */
@@ -246,6 +320,8 @@ function retune(machine: AnyStateMachine, parts: LooseParts): AnyStateMachine {
     // walk reports it again (ADR-0054).
     actors[name] = agent({ ...logic.definition, ...override });
   }
+  const bound = Object.entries(parts.effects ?? {}).filter(([, b]) => b !== undefined);
+  for (const [name, binding] of bound) actors[name] = bindEffect(machine, name, binding!);
   for (const [name, childParts] of Object.entries(parts.actors ?? {})) {
     if (!childParts) continue;
     const child = asMachine((machine.implementations.actors as Record<string, unknown>)[name]);
@@ -257,15 +333,114 @@ function retune(machine: AnyStateMachine, parts: LooseParts): AnyStateMachine {
     }
     actors[name] = customize(child, childParts as Customize<AnyStateMachine>);
   }
-  return substitute(machine, actors);
+  // An Open body lends by slot name (ADR-0070), and its stamped lent set must be the retuned slots,
+  // not the import's: each body is copied (the import keeps its own stamp) and stamped again over
+  // the retuned actors.
+  if (Object.keys(actors).length > 0) {
+    const impl = machine.implementations as Parameters<typeof lentIn>[0];
+    const merged = { ...impl, actors: { ...(impl.actors ?? {}), ...actors } };
+    for (const { slot, logic } of openBodiesOf(machine)) {
+      const copy = copyOpenBody(logic);
+      attachLent(copy, lentIn(merged, openBodyDeclarationOf(logic)));
+      actors[slot] = copy;
+    }
+  }
+  const out = substitute(machine, actors);
+  if (bound.length === 0) return out;
+  // The bound Machine's warnings differ from the Open one's, and `provide` kept the Open one's
+  // config, which is what every attachment keys on (ADR-0049) — so it gets a config of its own,
+  // carrying what the original carried and the rechecked warnings, and any later `provide()` of
+  // it (a run's, ADR-0015) keeps them.
+  const warnings = recheck(machine, out);
+  const rebuilt = cloneConfig(out);
+  attachLoadWarnings(rebuilt, warnings);
+  return rebuilt;
+}
+
+/**
+ * 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
+ * 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
+ * key): a slot the invoke does not supply faults when the Effect starts (ADR-0054).
+ */
+function bindEffect(machine: AnyStateMachine, name: string, binding: EffectBinding): unknown {
+  const logic = (machine.implementations.actors as Record<string, unknown>)[name];
+  if (!isEffect(logic)) {
+    throw new Error(
+      `customize(): machine "${machine.id}" carries no Effect slot "${name}" — its Effects are: ` +
+        `${listed(slotsWhere(machine, isEffect))} (ADR-0067). Only declared parts can be bound.`,
+    );
+  }
+  const parts = openPartsOf(logic.effect);
+  const binder = binderOf(logic);
+  if (parts.length === 0 || binder === undefined) {
+    throw new Error(
+      `customize(): the ${logic.effect.kind} Effect "${name}" of machine "${machine.id}" leaves nothing Open — its ` +
+        "parts are fixed in its definition, and only a part a package left `open` is bound, once (ADR-0054).",
+    );
+  }
+  // One object binds them, each key an Open part; a key it leaves out leaves that part Open, and
+  // the walk reports it again (ADR-0054).
+  const given = typeof binding === "object" && binding !== null ? (binding as Record<string, unknown>) : {};
+  const keys = Object.keys(given).filter((k) => given[k] !== undefined);
+  if (keys.length === 0 || keys.some((k) => !parts.includes(k as OpenEffectPart))) {
+    throw new Error(
+      `customize(): the ${logic.effect.kind} Effect "${name}" leaves its ${openPartsText(parts)} Open — bind it ` +
+        `with ${effectBindingShape(parts)} (ADR-0054)`,
+    );
+  }
+  for (const part of keys) {
+    const value = given[part];
+    if (value === open || typeof value === "function") {
+      throw new Error(
+        `customize(): the ${logic.effect.kind} Effect "${name}"'s ${part} is bound once, to a value — not ` +
+          `${value === open ? "`open` again" : "a function of the run"}: no run chooses an Effect's ${part} (ADR-0054)`,
+      );
+    }
+    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 — ` +
+          `the file the Effector reads it from: { secret: "<name>" } (ADR-0054, ADR-0068)`,
+      );
+    }
+  }
+  return binder(binding);
+}
+
+/**
+ * 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
+ * argv names them. A param it does not read is refused as at build, and a warning the walk gives
+ * for the bound argv (a param only an action the probe does not run may read) replaces the
+ * findings it gave for the Open one: the result is the warnings the same Machine written with that
+ * argv carries, which the caller attaches to the bound Machine's own config.
+ */
+function recheck(before: AnyStateMachine, machine: AnyStateMachine): string[] {
+  const defs = vocabularyOf(machine);
+  if (!defs) return loadWarningsOf(before);
+  const checks = (m: AnyStateMachine) =>
+    effectChecks(m, m.implementations.actors as Record<string, UnknownActorLogic>, defs);
+  const { errors, warnings } = checks(machine);
+  if (errors.length) throw new Error(`customize(): machine "${machine.id}": ${errors.join("; ")}`);
+  const unbound = new Set(checks(before).warnings);
+  const kept = loadWarningsOf(before).filter((warning) => !unbound.has(warning));
+  return [...new Set([...kept, ...warnings])];
 }
 
 /** The Sandbox seats and slots, applied to the `workspace()` the chain reaches. */
 function reseat(machine: AnyStateMachine, seats: Seats): AnyStateMachine {
   if (composesSandbox(machine)) {
-    const { repos: override, ...images } = seats;
+    const { repos: override, resources, ...images } = seats;
     const parts = sandboxPartsOf(machine);
-    if (parts.repos === open) return rebuild(machine, { ...parts, ...images, repos: nameSlots(machine, override) });
+    // The Size layers over the author's, field by field — a composer who raises memory keeps the
+    // author's cpu (ADR-0060).
+    const size = layerSize(parts.resources, resources);
+    const sized = size !== undefined ? { resources: size } : {};
+    if (parts.repos === open)
+      return rebuild(machine, { ...parts, ...images, ...sized, repos: nameSlots(machine, override) });
     const repos = { ...parts.repos };
     // Only DECLARED slots can be bound (ADR-0051): the Machine's own word for each Repo is the
     // key, and a key it never declared would attach a repository the body has no handle for.
@@ -285,15 +460,16 @@ function reseat(machine: AnyStateMachine, seats: Seats): AnyStateMachine {
       assertRepoSlot("customize()", slot, value);
       repos[slot] = value;
     }
-    return rebuild(machine, { ...parts, ...images, repos });
+    return rebuild(machine, { ...parts, ...images, ...sized, repos });
   }
   const inner = bodyOf(machine);
   if (!inner) {
-    const named = seats.repos !== undefined ? "`repos`" : "`image`/`user`";
+    const named =
+      seats.repos !== undefined ? "`repos`" : seats.resources !== undefined ? "`resources`" : "`image`/`user`";
     throw new Error(
-      `customize(): ${named} say what a SANDBOX is made of and which Repos it attaches, and machine ` +
-        `"${machine.id}" composes none — only a workspace() wrapper carries those seats and slots ` +
-        "(ADR-0049, ADR-0037, ADR-0051).",
+      `customize(): ${named} say what a SANDBOX is made of, how big it is and which Repos it attaches, and ` +
+        `machine "${machine.id}" composes none — only a workspace() wrapper carries those seats, that Size ` +
+        "and those slots (ADR-0049, ADR-0037, ADR-0051, ADR-0060).",
     );
   }
   return substitute(machine, { [inner.slot]: reseat(inner.body, seats) });
@@ -336,13 +512,28 @@ function nameSlots(machine: AnyStateMachine, override: Seats["repos"]): SandboxP
  * fingerprint a restore compares (ADR-0030) — is bit-identical to the original's.
  */
 function rebuild(machine: AnyStateMachine, seats: SandboxParts): AnyStateMachine {
+  const clone = cloneConfig(machine);
+  attachSandboxParts(clone, seats);
+  return clone;
+}
+
+/**
+ * The Machine around a NEW config object — a shallow clone, so the shape and the fingerprint are
+ * the original's — with the same implementations, and every attachment the original carried
+ * re-attached under the new key (ADR-0049): the vocabulary, the door, the seats, the load
+ * warnings and a wrapper's body. What the caller attaches after is the clone's alone.
+ */
+function cloneConfig(machine: AnyStateMachine): AnyStateMachine {
   const clone = new StateMachine({ ...machine.config }, machine.implementations) as AnyStateMachine;
   const vocabulary = vocabularyOf(machine);
   if (vocabulary) attachVocabulary(clone, vocabulary);
   const door = inputSchemaOf(machine);
   if (door) attachInputSchema(clone, door);
+  const seats = seatsOf(machine);
+  if (seats.length > 0) attachSeats(clone, seats);
+  const warnings = loadWarningsOf(machine);
+  if (warnings.length > 0) attachLoadWarnings(clone, warnings);
   const slot = wrapperBodyOf(machine);
   if (slot) attachWrapperBody(clone, slot);
-  attachSandboxParts(clone, seats);
   return clone;
 }