@jr2/orchestrator 0.4.1 → 0.6.0

package/src/registration.ts

@@ -30,7 +30,7 @@ import { SENDER_KEY, type EventDef, type Sender } from "@jr2/agent-protocol";
 import type { AgentAdmission } from "./actor.ts";
 import type { EffectMarker, EffectRow } from "./effect.ts";
 import type { EffectorPlacement, EffectorTarget } from "./http-effect.ts";
-import type { NoticeScope, TakenNotices } from "./notices.ts";
+import type { NoticeScope, RaiseOptions, TakenNotices } from "./notices.ts";
 import type { AnswerSeat } from "./pick.ts";
 import type { Notice, PickAnswer } from "./wire.ts";
 import type { SandboxPort } from "./workspace.ts";
@@ -38,6 +38,7 @@ import { invokingMachine, vocabularyOf } from "./vocabulary.ts";
 import type { ChartText } from "./chart.ts";
 import { notTaken, senderText, takesNow, type NotTakenWriting } from "./party.ts";
 import { restOf } from "./rest.ts";
+import type { RunStatus } from "./run-host.ts";
 
 /** xstate doesn't export its internal AnyActorSystem; this matches what actors receive. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -81,6 +82,20 @@ export type Registration = {
    * Harness runs on the host, in no Sandbox at all): those are the Instance token's business.
    */
   sandbox?: string;
+  /**
+   * An Agent's: its SLOT (ADR-0076) — the actor path of its Machine and its agent name, which is its
+   * continued conversation's Instance ID without the run id ({@link continuedIid}). The Harness
+   * states it on every control request, from its own record of the conversation, and the
+   * Orchestrator speaks here only for that slot. Two Agents with one key in two child Machines are
+   * two slots. Absent on gates.
+   */
+  slot?: string;
+  /** An Agent's: the step boundary's read of its conversation's pending notices (ADR-0062), each
+   * reserved for this Turn until {@link noticesHeard} or the Turn's end releases it. */
+  boundaryNotices?: () => Promise<Array<{ id: string; notice: Notice }>>;
+  /** An Agent's: the Harness appended these step-boundary notices — they are heard, ledgered in one
+   * save. Answers how many were this Turn's reservations. */
+  noticesHeard?: (ids: readonly string[]) => number;
   /** Close over the invoking state's `sendBack`; delivery lands where the actor was invoked. */
   deliver: (event: DeliveredEvent) => void;
   /** An Agent's: the Harness read this surface (`GET /agents/:iid/surface`), so it has the Turn in
@@ -312,9 +327,15 @@ export function actorPath(ref: AnyActorRef): string[] {
  * Turn adds a random suffix, a burned conversation's successor its epoch), and the Agent's Actor
  * names the conversation it burns with it.
  */
-export function continuedIid(machine: AnyActorRef | undefined, runId: string, agentName: string): string {
+/** An Agent's slot (ADR-0076): its continued conversation's Instance ID without the run id —
+ * `<machine actor path>/<agent>`. What the Harness states and the registration records. */
+export function agentSlot(machine: AnyActorRef | undefined, agentName: string): string {
   const path = (machine ? actorPath(machine).join(".") : "") || "root";
-  return `${runId}/${path}/${agentName}`;
+  return `${path}/${agentName}`;
+}
+
+export function continuedIid(machine: AnyActorRef | undefined, runId: string, agentName: string): string {
+  return `${runId}/${agentSlot(machine, agentName)}`;
 }
 
 /** The address of a run's gate: gate ids are run-scoped by construction (ADR-0011). */
@@ -329,6 +350,9 @@ export function agentAddress(instanceId: string): string {
 
 export class RegistrationTable {
   private readonly byAddress = new Map<string, Registration>();
+  /** The same registrations by run, so a run's are read without a scan of every run's: the run host
+   * reads them on every microstep of the run (`cause.ts`). */
+  private readonly ofRun = new Map<string, Set<Registration>>();
 
   /** Register a live surface; returns its disposer (actors call it from their stop cleanup). */
   register(reg: Registration): () => void {
@@ -338,10 +362,16 @@ export class RegistrationTable {
       );
     }
     this.byAddress.set(reg.address, reg);
+    const ofRun = this.ofRun.get(reg.runId) ?? new Set<Registration>();
+    ofRun.add(reg);
+    this.ofRun.set(reg.runId, ofRun);
     return () => {
       // Dispose only our own entry — a re-registration under the same address must not be
       // clobbered by a stale disposer running late (dev reload, restore races).
       if (this.byAddress.get(reg.address) === reg) this.byAddress.delete(reg.address);
+      const runRegs = this.ofRun.get(reg.runId);
+      runRegs?.delete(reg);
+      if (runRegs?.size === 0) this.ofRun.delete(reg.runId);
     };
   }
 
@@ -349,9 +379,10 @@ export class RegistrationTable {
     return this.byAddress.get(address);
   }
 
-  /** All live registrations for one run — the `GET /runs/:id` discovery listing. */
+  /** All live registrations for one run, in the order they registered — the `GET /runs/:id`
+   * discovery listing. */
   byRun(runId: string): Registration[] {
-    return [...this.byAddress.values()].filter((r) => r.runId === runId);
+    return [...(this.ofRun.get(runId) ?? [])];
   }
 
   /**
@@ -398,10 +429,55 @@ export class RegistrationTable {
   }
 }
 
+/**
+ * Which run dispatched a run (ADR-0071): the caller's run id, the slot of its `dispatch` Effect, and
+ * that Effect's ledger row id, which is the idempotency key — a start that carries a key some run
+ * already carries answers that run. `depth` is the dispatched run's depth in the chain, one below
+ * its caller, stated by the caller and recorded as sent: one meaning on the wire, on the binding
+ * and on the row. `instance` is set for a foreign caller, whose Orchestrator this one cannot
+ * verify: opaque text, never resolved.
+ */
+export type DispatchedBy = { run: string; slot: string; effect: string; depth: number; instance?: string };
+
+/** The header a foreign `dispatch` carries its {@link DispatchedBy} in, as JSON (ADR-0071): out of
+ * band, so the callee's door reserves no body field for it. */
+export const DISPATCHED_BY_HEADER = "jr2-dispatched-by";
+
+/**
+ * A dispatch's start as the run host answers it in-process (ADR-0071): the run, and whether the key
+ * found one that already existed; or the door's refusal, with the status `POST /workflows/:name/runs`
+ * would answer — 400 input the door refuses, 404 a name the current Assembly lacks, 409 a named
+ * Chart that cannot run now, 422 a Chart the door refuses — and its report. A refusal is the
+ * Effect's output, never thrown.
+ */
+export type DispatchStart =
+  | { ok: true; runId: string; existing: boolean }
+  | { ok: false; status: 400 | 404 | 409 | 422; report: string[] };
+
 /** What a callback actor needs from its host: run identity, the table, and the host's ports. */
 export type RunBinding = {
   runId: string;
   workflow: string;
+  /** The name this run's Orchestrator gives itself at another Orchestrator's door (ADR-0071): the
+   * `instance` of a foreign dispatch's `dispatchedBy` — stable across its runs and restarts, and not
+   * secret, since the callee serves it on its open band. Deployed, its namespace. Never an Instance
+   * ID, which names an Agent's conversation and stays behind the token. Absent on a bare unit-test
+   * binding and an undeployed Orchestrator. */
+  orchestratorName?: string;
+  /** The run's depth in a chain of dispatches (ADR-0071): 0 for a run nothing dispatched. Absent
+   * on a bare unit-test binding, which reads 0. */
+  depth?: number;
+  /**
+   * The in-process half of a `dispatch` Effect (ADR-0071): the run host, reached directly, with no
+   * wire and no token — the Orchestrator is the single writer of runs. `start` answers a refusal as
+   * {@link DispatchStart}, never by throwing; `settled` resolves with the run's status once it is no
+   * longer live — at once for a run already settled, and across a restore in either order — and
+   * rejects when `signal` aborts. Absent outside a RunHost: a dispatch with no target faults.
+   */
+  dispatch?: {
+    start(workflow: string, input: Record<string, unknown>, by: DispatchedBy): Promise<DispatchStart>;
+    settled(runId: string, signal: AbortSignal): Promise<RunStatus>;
+  };
   /** The hash of the Assembly the run holds (ADR-0069): the one it started under, through
    * restarts. Absent for a run no Assembly started. */
   assembly?: string;
@@ -432,9 +508,18 @@ export type RunBinding = {
    * Record an Agent invocation's durable admission in the host ledger (ADR-0016): persisted
    * beside the snapshot in the same RunBlob save, keyed by iid (globally unique, so the map is
    * flat). Optional so a bare unit-test binding can omit it — then admissions simply are not
-   * durable.
+   * durable. `delivered` are the notices the admission carried, delivered by this save in `taker`'s
+   * conversation — the Instance ID the admission rides (ADR-0062). `member`: the Workspace the
+   * conversation was admitted in, its slot and whether it continues — so it is in the audience of
+   * every kill there from now on, in the same save.
    */
-  recordAdmission?: (instanceId: string, admission: AgentAdmission, delivered?: readonly string[]) => void;
+  recordAdmission?: (
+    instanceId: string,
+    admission: AgentAdmission,
+    delivered?: readonly string[],
+    taker?: string,
+    member?: { workspace: string; slot: string; continued: boolean },
+  ) => void;
   /**
    * The admission ledger's READ half (ADR-0016): the last admission ledgered under this iid. A
    * continued Turn asks it whether its conversation was ever admitted — only then can the Harness
@@ -461,14 +546,31 @@ export type RunBinding = {
   /**
    * The notices' write half (ADR-0062): keep a notice for the next admission in scope — `to` is a
    * continued conversation's base id or a Sandbox name, as the notice's `scope` says. Persisted at
-   * the write, like the ledgers. `source` names the event, so one event raised twice is one notice.
+   * the write, like the ledgers. `source` names the event, so one event raised twice is one notice;
+   * `older` names earlier events this one tells the same as, marked raised with it (`NoticeLedger`).
    * A burned conversation's notice is raised by `bumpEpoch` itself, in the same save.
    */
-  raiseNotice?: (notice: Notice, to: string, source?: string) => void;
-  /** Reserve the pending notices in one admission's scope. They are delivered by the
-   * `recordAdmission` that ledgers it (its `delivered` ids), or released if the admission fails. */
+  raiseNotice?: (notice: Notice, to: string, source?: string, older?: readonly string[], opts?: RaiseOptions) => void;
+  /** Put back a notice an admission carried that no model heard, WITH its source (`NoticeLedger.restore`):
+   * a raise would drop it, its source being seen. A Workspace notice is pending again for `taker`,
+   * the conversation that did not hear it. Persisted at the write. */
+  restoreNotice?: (notice: Notice, to: string, source?: string, taker?: string) => void;
+  /** Reserve the pending notices in one admission's scope, for its conversation (`scope.taker`).
+   * They are delivered by the `recordAdmission` that ledgers it (its `delivered` ids and `taker`),
+   * or released for that conversation if the admission fails. */
   takeNotices?: (scope: NoticeScope) => TakenNotices;
-  releaseNotices?: (ids: readonly string[]) => void;
+  releaseNotices?: (ids: readonly string[], taker?: string) => void;
+  /** What `takeNotices` would reserve in this scope, reserving nothing (`NoticeLedger.peek`). */
+  peekNotices?: (scope: NoticeScope) => Array<{ id: string; notice: Notice; source?: string }>;
+  /** The Harness acknowledged a step boundary's notices (ADR-0062): each that `taker` reserved is
+   * heard there, persisted at the write. Answers how many were. */
+  acknowledgeNotices?: (ids: readonly string[], taker: string) => number;
+  /** The conversations each kill's `bash` answer told (ADR-0062, D4 rule 3), off the pod's list:
+   * they leave that kill's audience. Persisted at the write when anything changed. */
+  noticesTold?: (told: ReadonlyArray<{ source: string; takers: readonly string[] }>) => void;
+  /** A Turn of these conversations in `workspace` ended: a fresh one leaves every audience there,
+   * a continued one stays for its next Turn (ADR-0062). Persisted at the write. */
+  noticeTurnEnded?: (workspace: string, takers: readonly string[]) => void;
   /**
    * The pick the Turn now at this address has outstanding, or answered and not yet read (ADR-0024):
    * what the Agent's Actor asks when its Harness restarted under a Turn — a Turn whose pick is still
@@ -480,6 +582,18 @@ export type RunBinding = {
   /** The held answer reached the model by another road — a re-admission's notice — so the poll's
    * copy is spent (ADR-0031). */
   heldAnswerDelivered?: (instanceId: string) => void;
+  /**
+   * Did this Turn's own pick end it (ADR-0024)? Asked by the Agent's Actor as its invocation stops,
+   * before its registration goes, so its sweep can say so (`cause: "pick"`) and the Harness settles
+   * the Submission `ended`. True exactly when the transition that stopped the invocation came from
+   * the Turn's own pick, by the four rules of ADR-0024 (`cause.ts`): the pick in its own send; the
+   * work below the Agent's state while the pick is out; a send of an actor that takes a relay from
+   * the pick (rule 3); and a timer armed while its Machine took such a relay (rule 4) — so a timer
+   * that the pick's route armed gives true. False for every other end — a timer armed before the
+   * pick, an outside event, another party's event, the run's CANCEL, a fault. Absent outside a RunHost: the
+   * sweep then says no cause.
+   */
+  turnEndedByPick?: (instanceId: string) => boolean;
   /**
    * Surface absorbed-retry telemetry on the run feed (ADR-0016): attempts are observable, but
    * as `{ child, attempt }` — state-key-class data, never iids (ADR-0014's line holds on the
@@ -509,6 +623,13 @@ export type RunBinding = {
    * process), so it says so here, before it stops the actor.
    */
   hostStopping?: boolean;
+  /**
+   * The Sandbox names that a live Workspace of this run holds now, a Workspace in `placing` too
+   * (ADR-0064, ADR-0073). A delete that runs after a stop leaves these alone: a parent that invokes
+   * the same Machine again gives its new Workspace the same invoke id, and so the same name. Absent
+   * outside a RunHost: no name is held.
+   */
+  heldSandboxes?: () => ReadonlySet<string>;
   /**
    * Every reply since the pick that `machine`'s Agent has outstanding, or is delivering now, oldest
    * first (ADR-0024) — what an `answer` action reads as its `chain` (ADR-0067). `seat` is the place

package/src/repo-identity.ts

@@ -18,7 +18,8 @@ export type RepoIdentity = {
    * absolute path for a local repository. Path case is KEPT: hosts are case-insensitive, paths on
    * most forges are not. */
   identity: string;
-  /** `<slug>-<sha256(identity)[:8]>` — a DNS-1123 label of at most 49 characters. */
+  /** `<slug>-<sha256(identity)[:32]>` — a DNS-1123 label of at most 49 characters: a slug of at
+   * most 16 characters and 128 bits of the hash, so no one finds two identities with one key. */
   key: string;
   scheme: "https" | "http" | "ssh" | "git" | "local";
 };
@@ -139,7 +140,10 @@ function keyOf(identity: string): string {
       .toLowerCase()
       .replace(/[^a-z0-9]+/g, "-")
       .replace(/^-+|-+$/g, "")
-      .slice(0, 40)
+      .slice(0, 16)
       .replace(/-+$/, "") || "repo";
-  return `${slug}-${createHash("sha256").update(identity).digest("hex").slice(0, 8)}`;
+  // 128 bits (ADR-0051): the key names the cache that a Sandbox mounts, and a per-run url is the
+  // Agent's text. With 32 bits a search found a url of another repository with the same key in
+  // seconds, and that url mounted the other repository's cache.
+  return `${slug}-${createHash("sha256").update(identity).digest("hex").slice(0, 32)}`;
 }

package/src/repos.ts

@@ -54,7 +54,8 @@ export type RepoNodeState = {
 
 /** One `Repo` resource as the instance reports it (`GET /repos`). */
 export type RepoStatus = {
-  /** The cache key (repo-identity.ts): the resource's name, the hostPath leaf, `/repos/<key>`. */
+  // repo-identity.ts makes the key.
+  /** The cache key: the resource's name, the hostPath leaf, `/repos/<key>`. */
   key: string;
   /** The Binding's own spelling — what the cache clones. */
   url: string;
@@ -191,10 +192,28 @@ export function kubeRepos(opts: KubeReposOptions): RepoResources {
     return item;
   };
 
+  /** The resource that stands under `repo.key`, when it is `repo`'s identity; else a throw that names
+   * both urls (ADR-0051). The key is collision-resistant, so another identity under one key is a
+   * defect or an attack, and no statement of this port writes a resource of another identity: not
+   * its url, not its `secretRef`, not its clock. */
+  const sameIdentity = async (repo: { url: string; identity: string; key: string }): Promise<RepoItem> => {
+    const item = await get(repo.key);
+    const stands = item.metadata?.annotations?.[ANNOTATION_REPO_IDENTITY];
+    if (stands !== repo.identity) {
+      throw new Error(
+        `Repo "${repo.key}" stands for ${stands === undefined ? "no stated identity" : `"${stands}"`} ` +
+          `(url ${item.spec?.url ?? "unknown"}), not for "${repo.identity}" (url ${repo.url}): one key, two ` +
+          "repositories, so jr2 changes nothing on it (ADR-0051). Delete that Repo if it is stale.",
+      );
+    }
+    return item;
+  };
+
   return {
     async bind(repo) {
       const { secretRef, cr } = await resourceFor({ ...repo, bound: true });
       if (await create(cr)) return;
+      await sameIdentity(repo);
       // Already there from an earlier deploy: ONE merge patch says what the Machine resolves now —
       // url, credential, and the label `jr2 gc` honors. `secretRef: null` clears a credential the
       // config no longer names, so a dropped entry does not linger. The clock is not touched: it
@@ -215,12 +234,12 @@ export function kubeRepos(opts: KubeReposOptions): RepoResources {
       // Already there — the boot's statement, or an earlier run's. The eviction clock moves: the
       // run attached it now. The url stays as stated, whatever spelling this run brought.
       const clock = { metadata: { annotations: { [ANNOTATION_REPO_LAST_ATTACHED]: attached } } };
+      const standing = await sameIdentity(repo);
       // A Machine's slot binds it: the boot is its writer, and restates the credential at the next
-      // deploy. Read nothing.
+      // deploy.
       if (repo.bound) return patch(repo.key, clock);
       // This run's slot is per-run, but another registered Machine may bind the identity — the
       // label says so, and then the boot is still the writer.
-      const standing = await get(repo.key);
       if (standing.metadata?.labels?.[LABEL_REPO_BOUND] === "true") return patch(repo.key, clock);
       // Nothing binds it: no boot ever restates it, so this attach does — the credential resolved
       // against the url that STANDS, since the scheme picks the Secret's kind (config.ts) and the