@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/runtime.ts

@@ -0,0 +1,1345 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+
+import {
+  Caller,
+  HostedService,
+  HostedServiceFactory,
+  JsonRecord,
+  LogEntry,
+  LogLevel,
+  ProcessContext,
+  RuntimeConfiguration,
+  RuntimeDescriptor,
+  RuntimeHost,
+  RuntimeNotification,
+  RunActor,
+  RuntimeScope,
+  ServiceCreator,
+  ServiceConfiguration,
+  ServiceDescriptor,
+  SlotStore,
+} from "./types";
+import { ADDRESS_SEPARATOR, descend, splitAddress } from "./address";
+import { SecretVault } from "./secrets";
+import { AssetDescriptor, AssetStore, AssetStoreOptions } from "./assets";
+import { ANONYMOUS_SUB, AuthenticatedUser } from "./auth";
+import { MountHandle, MountHandlers } from "./mounts";
+
+/** Severity order, so a runtime can drop anything below what it records. */
+export const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/** A run with no parent: something outside the board asked for this. */
+export const DEFAULT_PERSON_RUN_TTL_MS = 15 * 60 * 1000;
+
+export function newRun(
+  kind: Exclude<RunActor["kind"], "person"> = "board",
+): ProcessContext {
+  return { runId: randomUUID(), actor: { kind } };
+}
+
+/**
+ * Reads a context a peer sent, filling in what it left out.
+ *
+ * A caller that names no run is not continuing one, so a run is begun rather
+ * than left unidentified — work that cannot be attributed to anything is worse
+ * than work attributed to a run of its own. Returns undefined only when there
+ * was no context at all, which lets the caller decide.
+ */
+export function contextFromWire(value: unknown): ProcessContext | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const wire = value as Record<string, unknown>;
+  const str = (key: string): string | undefined =>
+    typeof wire[key] === "string" && wire[key] ? (wire[key] as string) : undefined;
+
+  return {
+    runId: str("runId") ?? randomUUID(),
+    parentRunId: str("parentRunId"),
+    requestId: str("requestId"),
+    actor: { kind: "local" },
+  };
+}
+
+/**
+ * Who a signed-in user is to a run they begin, or nothing where there is no
+ * identity to state.
+ *
+ * A client holding a token reaches only the runtimes of its own tenant, so it
+ * is their owner. A member reaches somebody else's board only through its
+ * coordinator, which says so itself.
+ *
+ * A server running without authentication resolves everybody to the one
+ * anonymous tenant. That is *no caller*, not a caller called anonymous —
+ * otherwise everybody on a development machine would be the same person.
+ */
+export function callerOf(user: AuthenticatedUser | undefined): Caller | undefined {
+  if (!user || user.sub === ANONYMOUS_SUB) {
+    return undefined;
+  }
+  return {
+    sub: user.sub,
+    ...(user.email ? { email: user.email } : {}),
+    role: "owner",
+  };
+}
+
+/**
+ * The context of a run a client holding a token begins: a REST process call,
+ * or a `processRuntime` on a runtime's socket.
+ *
+ * The run metadata the client sent is kept, as `contextFromWire` reads it.
+ * Whatever it said about a caller is not read at all: who is calling is what
+ * the server verified, so a client cannot act in another person's name by
+ * saying so.
+ */
+export function contextForClient(
+  wire: unknown,
+  user: AuthenticatedUser | undefined,
+): ProcessContext {
+  const context =
+    contextFromWire(wire) ?? newRun("local");
+  const caller = callerOf(user);
+  return {
+    ...context,
+    actor: caller
+      ? {
+          kind: "person",
+          ...caller,
+          expiresAt: Date.now() + DEFAULT_PERSON_RUN_TTL_MS,
+        }
+      : { kind: "local" },
+  };
+}
+
+/** A caller as a participant link states one, or nothing when the shape is off. */
+export function callerFromWire(value: unknown): Caller | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const wire = value as Record<string, unknown>;
+  if (typeof wire.sub !== "string" || !wire.sub) {
+    return undefined;
+  }
+  return {
+    sub: wire.sub,
+    ...(typeof wire.email === "string" && wire.email
+      ? { email: wire.email }
+      : {}),
+    ...(typeof wire.name === "string" && wire.name ? { name: wire.name } : {}),
+    ...(wire.role === "owner" || wire.role === "member"
+      ? { role: wire.role }
+      : {}),
+  };
+}
+
+/** An actor as a trusted participant link states it. */
+export function actorFromWire(value: unknown): RunActor | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const wire = value as Record<string, unknown>;
+  if (wire.kind === "person") {
+    const caller = callerFromWire(wire);
+    return caller
+      ? {
+          kind: "person",
+          ...caller,
+          expiresAt:
+            typeof wire.expiresAt === "number" &&
+            Number.isFinite(wire.expiresAt)
+              ? wire.expiresAt
+              : 0,
+        }
+      : { kind: "person", sub: "", expiresAt: 0 };
+  }
+  if (
+    wire.kind === "board" ||
+    wire.kind === "mount" ||
+    wire.kind === "local"
+  ) {
+    return { kind: wire.kind };
+  }
+  return undefined;
+}
+
+/**
+ * The context of a run as it is said over a participant link, by either end:
+ * a coordinator continuing a run on a runtime, or a runtime handing back what
+ * it produced.
+ *
+ * The one path on which a caller is taken as stated. The link is the board's
+ * own — opened by a runtime server with the board's ticket — and the
+ * coordinator on it is what verified the person. Kept apart from
+ * `contextFromWire` so that no other entry point can come to trust a caller by
+ * sharing a parser.
+ */
+export function contextFromLink(value: unknown): ProcessContext | undefined {
+  const context = contextFromWire(value);
+  if (!context) {
+    return undefined;
+  }
+  const wire = value as Record<string, unknown>;
+  // The reply address belongs to whoever was waiting at the other end.
+  const { requestId: _requestId, ...run } = context;
+  return {
+    ...run,
+    actor: actorFromWire(wire.actor) ?? { kind: "board" },
+  };
+}
+
+/**
+ * A run as it is said to another runtime: which run, and who began it. The
+ * reply address is left out — it means something only to whoever is waiting.
+ */
+export function contextToWire(
+  context: ProcessContext | null | undefined,
+): ProcessContext | undefined {
+  if (!context) {
+    return undefined;
+  }
+  return {
+    runId: context.runId,
+    ...(context.parentRunId ? { parentRunId: context.parentRunId } : {}),
+    actor: context.actor,
+  };
+}
+
+/**
+ * A run invoked from inside another one, as a nested pipeline is.
+ *
+ * The child gets an identity of its own rather than borrowing its parent's, so
+ * that work done inside a sub-pipeline stays distinguishable from work done
+ * around it — which is the whole difference between a trace that shows nesting
+ * and one that shows a flat list in timestamp order. The actor is inherited
+ * exactly, whether it is a person, the board, a mount, or local work.
+ */
+export function childRun(parent: ProcessContext | null): ProcessContext {
+  return parent
+    ? {
+        runId: randomUUID(),
+        parentRunId: parent.runId,
+        actor: parent.actor,
+      }
+    : newRun();
+}
+
+/** Whether a run's delegated person authority is no longer valid. */
+export function runExpired(
+  context: ProcessContext | null | undefined,
+  now = Date.now(),
+): boolean {
+  return (
+    context?.actor.kind === "person" && context.actor.expiresAt <= now
+  );
+}
+
+/**
+ * Where work that belongs to no call begins, across every runtime in the
+ * process. A run's frame remembers which of these it was begun under, and is
+ * only the current one while that still holds.
+ */
+const detachments = new AsyncLocalStorage<object>();
+
+/**
+ * Runs `fn` outside whatever run it was scheduled from.
+ *
+ * A callback keeps the async context of the code that scheduled it, so a tick
+ * armed from inside a call would otherwise go on reading that call's run —
+ * and its caller, and its expiry — for as long as it fires. A service that
+ * emits by itself wraps the emission in this, and what it emits begins a run
+ * of its own. Nested runtimes are covered by the one call: each keeps its own
+ * frame, and none of them outlives the detachment.
+ */
+export function detached<T>(fn: () => T): T {
+  return detachments.run({}, fn);
+}
+
+/** One call in progress on a runtime; see `HostedRuntime.runState`. */
+type RunFrame = {
+  context: ProcessContext;
+  service: string | null;
+  /** The detachment this frame was begun under; see `detached`. */
+  detachment: object | undefined;
+  /** Set once the call it stood for has returned; see `configureService`. */
+  ended?: boolean;
+};
+
+/**
+ * Grants a runtime's services public endpoints. Supplied by the server, which
+ * owns the listening socket; absent for inner sub-service pipelines, which are
+ * not addressable from outside.
+ */
+export type RuntimeMounts = {
+  mount(
+    serviceUuid: string,
+    handlers: MountHandlers,
+    options?: { boardName?: string; mountName?: string },
+  ): MountHandle | null;
+};
+
+/**
+ * How a runtime reads a `file://` asset source, supplied by the server that owns
+ * the file store. Given the runtime's scope, because a path only means
+ * something inside the tenant it belongs to. Absent: no `file://` source
+ * resolves.
+ */
+export type AssetFileReader = (
+  scope: RuntimeScope,
+  url: URL,
+) => Promise<Uint8Array | null>;
+
+export class HostedRuntime implements RuntimeHost {
+  readonly id: string;
+  readonly name: string;
+  boardName: string;
+  /** The tenant this runtime answers to; see RuntimeScope. */
+  private owner: string;
+  /** See RuntimeConfiguration.garbageCollected. Absent means persist. */
+  readonly garbageCollected: boolean;
+
+  private readonly services = new Map<string, HostedService>();
+  private serviceOrder: string[] = [];
+  private readonly notificationTargets = new Set<
+    (notification: RuntimeNotification) => void
+  >();
+  private readonly resultTargets = new Set<
+    (result: unknown, context: ProcessContext | null) => void
+  >();
+  private readonly createService: ServiceCreator;
+  private readonly mounts?: RuntimeMounts;
+  /**
+   * Where this runtime's mounts are claimed, when it has no server of its own;
+   * see `delegateMounts`.
+   */
+  private mountsFrom:
+    | ((
+        serviceUuid: string,
+        handlers: MountHandlers,
+        options: { mountName?: string },
+      ) => MountHandle | null)
+    | null = null;
+  /**
+   * The call being processed right now, and which service it is inside.
+   *
+   * Async-local rather than a field: a pass awaits the services it calls, so
+   * two runs started independently — a timer tick and an arriving message —
+   * interleave freely. A plain field would let the second overwrite the first's
+   * context mid-await, and every log entry and captured run id after that point
+   * would name the wrong run. `AsyncLocalStorage` gives each run its own view
+   * and restores the outer one on the way out, which is what a nested pull
+   * needs.
+   */
+  private readonly runState = new AsyncLocalStorage<RunFrame>();
+  private readonly logTargets = new Set<(entry: LogEntry) => void>();
+  /** See RuntimeConfiguration.logData. A board-wide override, not the gate. */
+  private logData = true;
+  private capture = false;
+  /** Whether anything is recorded at all; see RuntimeConfiguration.logging. */
+  private logging = false;
+  /** The least severe level recorded; see RuntimeConfiguration.logLevel. */
+  private logLevel: LogLevel = "info";
+  /**
+   * Values for the references this runtime's services carry. Held apart from
+   * every service's state, and reachable only through `secrets()`.
+   */
+  private readonly vault = new SecretVault();
+  /**
+   * Where this runtime's secrets actually come from, when they are not its
+   * own; see `delegateSecrets`.
+   */
+  private secretsFrom: (() => SecretVault | null) | null = null;
+  /**
+   * The descriptors of the assets this runtime's services reference, and the
+   * content they resolve to. Reachable through `assets()`.
+   */
+  private readonly assetStore: AssetStore;
+  /**
+   * Where this runtime's assets actually come from, when they are not its own;
+   * see `delegateAssets`.
+   */
+  private assetsFrom: (() => AssetStore | null) | null = null;
+  /**
+   * The cells services in this runtime hold values in between passes.
+   *
+   * Owned rather than delegated by default: a runtime is the outermost thing a
+   * slot name can mean, so two services that name the same slot and are given
+   * nothing more specific share this one.
+   */
+  private readonly ownSlots: SlotStore = new Map<string, unknown>();
+  /**
+   * Where this runtime's slots actually come from, when they are not its own;
+   * see `delegateSlots`.
+   */
+  private slotsFrom: (() => SlotStore | null) | null = null;
+
+  constructor(
+    config: RuntimeConfiguration,
+    createService: (config: ServiceConfiguration) => HostedService,
+    mounts?: RuntimeMounts,
+    // Known only to whoever resolved the caller, so it is passed in rather than
+    // read from the config a client sent. Absent collapses to the single tenant
+    // an unauthenticated server already uses.
+    owner: string = ANONYMOUS_SUB,
+    readAssetFile?: AssetFileReader,
+    assetLimits?: AssetStoreOptions,
+  ) {
+    this.id = config.id;
+    this.name = config.name;
+    this.owner = owner;
+    this.boardName = config.boardName ?? "";
+    this.garbageCollected = config.garbageCollected === true;
+    this.logData = config.logData !== false;
+    this.logging = config.logging === true;
+    if (config.logLevel && config.logLevel in LOG_LEVELS) {
+      this.logLevel = config.logLevel;
+    }
+    this.createService = createService;
+    this.mounts = mounts;
+
+    // Before any service is built, because a service that opens a connection
+    // while being configured asks for its credential during `addService`.
+    if (config.secrets) {
+      this.vault.replace(config.secrets);
+    }
+    // Likewise assets: a service that loads its content while being configured
+    // asks for it during `addService`.
+    this.assetStore = new AssetStore(
+      {
+        readFile: readAssetFile
+          ? (url) => readAssetFile(this.scope(), url)
+          : undefined,
+      },
+      assetLimits,
+    );
+    if (config.assets) {
+      this.assetStore.replace(config.assets);
+    }
+
+    for (const serviceConfig of config.services) {
+      this.addService(serviceConfig);
+    }
+  }
+
+  serialize(outputUrl?: string): RuntimeDescriptor {
+    const descriptor: RuntimeDescriptor = {
+      id: this.id,
+      name: this.name,
+      garbageCollected: this.garbageCollected,
+      boardName: this.boardName,
+      services: this.listServices(),
+      inputs: [],
+    };
+
+    if (outputUrl) {
+      descriptor.outputUrl = outputUrl;
+    }
+
+    return descriptor;
+  }
+
+  listServices(): ServiceDescriptor[] {
+    return this.serviceOrder
+      .map((serviceId) => this.services.get(serviceId))
+      .filter((service): service is HostedService => Boolean(service))
+      .map((service) => ({
+        serviceId: service.serviceId,
+        serviceName: service.serviceName,
+        version: service.version,
+        capabilities: service.capabilities,
+        uuid: service.uuid,
+        state: service.getState(),
+      }));
+  }
+
+  /**
+   * The service an address names, flat or scoped.
+   *
+   * The flat list is asked first, so a uuid that happens to contain a dot is
+   * still that service rather than a path into something else. Only when no
+   * service carries the whole address is it read as one — see `address.ts`.
+   */
+  getService(address: string): HostedService | undefined {
+    const direct = this.services.get(address);
+    if (direct) {
+      return direct;
+    }
+    const segments = splitAddress(address);
+    if (segments.length < 2) {
+      return undefined;
+    }
+    const head = this.services.get(segments[0]);
+    return head ? descend(head, segments.slice(1)) : undefined;
+  }
+
+  addService(config: ServiceConfiguration): JsonRecord {
+    if (this.services.has(config.uuid)) {
+      throw new Error(`Service already exists: ${config.uuid}`);
+    }
+
+    const service = this.createService(config);
+
+    service.setHost?.(this);
+
+    this.services.set(service.uuid, service);
+    this.serviceOrder.push(service.uuid);
+    return service.getState();
+  }
+
+  configureService(
+    address: string,
+    config: JsonRecord,
+    context?: ProcessContext | null,
+  ): JsonRecord | null {
+    const service = this.getService(address);
+    if (!service) {
+      return null;
+    }
+    const configure = () =>
+      this.inService(service.uuid, () => service.configure(config));
+    if (!context) {
+      return configure();
+    }
+    // Configuring is over when `configure` returns, and the run ends with it.
+    // What a service arms while being configured — an interval, a socket, a
+    // poll — keeps this frame as its async context, and without an end it
+    // would go on emitting as whoever configured it, until their authority
+    // expired and the board stopped with it.
+    const frame: RunFrame = {
+      context,
+      service: this.currentService,
+      detachment: detachments.getStore(),
+    };
+    try {
+      return this.runState.run(frame, configure);
+    } finally {
+      frame.ended = true;
+    }
+  }
+
+  removeService(uuid: string): boolean {
+    const service = this.services.get(uuid);
+    service?.destroy?.();
+
+    const deleted = this.services.delete(uuid);
+    if (deleted) {
+      this.serviceOrder = this.serviceOrder.filter(
+        (serviceUuid) => serviceUuid !== uuid,
+      );
+    }
+    return deleted;
+  }
+
+  destroy(): void {
+    for (const service of this.services.values()) {
+      service.destroy?.();
+    }
+    this.services.clear();
+    this.serviceOrder = [];
+    this.notificationTargets.clear();
+    this.resultTargets.clear();
+    this.logTargets.clear();
+  }
+
+  registerNotificationTarget(
+    target: (notification: RuntimeNotification) => void,
+  ): () => void {
+    this.notificationTargets.add(target);
+    return () => {
+      this.notificationTargets.delete(target);
+    };
+  }
+
+  /**
+   * Where what this runtime emits goes. A target is told the run the value was
+   * emitted in, or null when it was emitted outside one, so that whoever
+   * carries it on can say which run it continues.
+   */
+  registerResultTarget(
+    target: (result: unknown, context: ProcessContext | null) => void,
+  ): () => void {
+    this.resultTargets.add(target);
+    return () => {
+      this.resultTargets.delete(target);
+    };
+  }
+
+  emitResult(output: unknown, context?: ProcessContext | null): void {
+    context = context ?? this.currentContext();
+    for (const target of this.resultTargets) {
+      target(output, context);
+    }
+  }
+
+  rearrangeServices(newOrder: string[]): boolean {
+    if (newOrder.length !== this.serviceOrder.length) {
+      return false;
+    }
+
+    const known = new Set(this.serviceOrder);
+    for (const uuid of newOrder) {
+      if (!known.has(uuid)) {
+        return false;
+      }
+    }
+
+    this.serviceOrder = [...newOrder];
+    return true;
+  }
+
+  process(
+    input: unknown,
+    onNotification: (notification: RuntimeNotification) => void,
+    context?: ProcessContext,
+  ): Promise<unknown> {
+    return this.withContext(context ?? newRun(), () =>
+      this.processFromIndex(0, input, onNotification),
+    );
+  }
+
+  // ── RuntimeHost ────────────────────────────────────────────────────────────
+
+  currentContext(): ProcessContext | null {
+    return this.frame?.context ?? null;
+  }
+
+  /** Which service the current pass is inside, for a log entry to name. */
+  private get currentService(): string | null {
+    return this.frame?.service ?? null;
+  }
+
+  /**
+   * The call in progress, or nothing when the frame this code inherited is no
+   * longer one: its call has returned, or the work has been detached from it.
+   */
+  private get frame(): RunFrame | undefined {
+    const frame = this.runState.getStore();
+    return frame &&
+      !frame.ended &&
+      frame.detachment === detachments.getStore()
+      ? frame
+      : undefined;
+  }
+
+  processFrom(
+    startAfterUuid: string,
+    input: unknown,
+    onNotification: (notification: RuntimeNotification) => void,
+    context?: ProcessContext,
+  ): Promise<unknown> {
+    const startIndex = this.serviceOrder.indexOf(startAfterUuid) + 1;
+    // Three ways to arrive here, and each wants a different run:
+    //
+    // - Named explicitly: a service that left its call and came back — an HTTP
+    //   response, an awaited write — handing back what it captured.
+    // - Called from inside a call: a service pulling the services after it
+    //   rather than returning to them. Still the same run, and the current
+    //   context already says which, so nothing has to be threaded by hand.
+    // - Neither: a timer tick, an arriving message. Nothing to continue, so
+    //   this begins a run.
+    //
+    // A service that leaves its call and forgets to capture lands in the third
+    // case, which splits its trace in two rather than attributing its work to
+    // whichever run happened to be in flight. Fragmentation is visible in a
+    // trace; misattribution reads as fact.
+    const runContext = context ?? this.currentContext() ?? newRun();
+
+    // A service pushing from itself (a Timer tick, an inbound message, a peer
+    // event) was never called by the loop below, so the loop never reported it.
+    // Report it here, or the UI shows a service producing nothing while the
+    // service after it plainly receives data.
+    this.emitNotification(
+      {
+        instanceId: startAfterUuid,
+        payload: { __internal: { state: "call-process", data: null } },
+      },
+      onNotification,
+    );
+    this.emitNotification(
+      {
+        instanceId: startAfterUuid,
+        payload: { __internal: { state: "call-process-finished", data: input } },
+      },
+      onNotification,
+    );
+
+    return this.withContext(runContext, () =>
+      this.processFromIndex(startIndex, input, onNotification),
+    );
+  }
+
+  /**
+   * Runs the pipeline starting **at** a service rather than after it.
+   *
+   * `processFrom` exists for a service handing work onward — it means "carry on
+   * behind me", so it advances past the caller. This is the other question:
+   * something outside the pipeline wants a particular service to do its job
+   * with a given payload, and that service must actually run.
+   *
+   * hkp-rt spells the same distinction as `processFrom(service, data,
+   * advanceBefore)`; kept as a separate entry point here so the advancing call,
+   * which every service uses, cannot change shape by accident.
+   */
+  processAt(
+    startAtUuid: string,
+    input: unknown,
+    onNotification: (notification: RuntimeNotification) => void,
+    context?: ProcessContext,
+  ): Promise<unknown> {
+    const startIndex = this.serviceOrder.indexOf(startAtUuid);
+    if (startIndex < 0) {
+      // Not one of this runtime's own: a scoped address enters the pipeline
+      // that holds it instead, and runs to the end of *that* list. What it
+      // produces is the nested pipeline's answer, and reaches the board the
+      // way that pipeline's answers always do.
+      const segments = splitAddress(startAtUuid);
+      const head = segments.length > 1 && this.services.get(segments[0]);
+      const enter = head ? head.processNested : undefined;
+      if (!head || !enter) {
+        throw new Error(`No such service: ${startAtUuid}`);
+      }
+      return enter.call(
+        head,
+        segments.slice(1).join(ADDRESS_SEPARATOR),
+        input,
+        context,
+      );
+    }
+    // Nothing to continue: whoever asked for this is outside the board, so it
+    // begins a run rather than joining one.
+    return this.withContext(context ?? newRun(), () =>
+      this.processFromIndex(startIndex, input, onNotification),
+    );
+  }
+
+  notify(
+    payload: unknown,
+    instanceId: string,
+    context?: ProcessContext | null,
+  ): void {
+    this.emitNotification(
+      { instanceId, payload, ...(context ? { context } : {}) },
+      () => {},
+    );
+  }
+
+  log(level: LogLevel, event: string, data?: unknown): void {
+    // Nothing to attribute an entry to means nothing worth recording: a service
+    // logging outside a call has no run, and an entry that names no run cannot
+    // be found again.
+    // Off means off: no entry is built, so nothing is spent deciding what it
+    // would have said.
+    if (
+      !this.logging ||
+      LOG_LEVELS[level] < LOG_LEVELS[this.logLevel] ||
+      this.logTargets.size === 0
+    ) {
+      return;
+    }
+
+    const run = this.currentContext();
+    if (!run) {
+      return;
+    }
+
+    const entry: LogEntry = {
+      runId: run.runId,
+      ts: new Date().toISOString(),
+      runtimeId: this.id,
+      serviceUuid: this.currentService ?? "",
+      level,
+      event,
+    };
+    if (run.parentRunId) {
+      entry.parentRunId = run.parentRunId;
+    }
+    if (run.actor.kind === "person") {
+      entry.caller = run.actor.sub;
+    }
+    if (this.logData && data !== undefined) {
+      entry.data = data;
+    }
+
+    for (const target of this.logTargets) {
+      target(entry);
+    }
+  }
+
+  /** service.processed, carrying how long the call took. */
+  private logProcessed(result: unknown, durationMs: number): void {
+    if (!this.logging || LOG_LEVELS.debug < LOG_LEVELS[this.logLevel]) {
+      return;
+    }
+    const before = this.logTargets.size;
+    const run = this.currentContext();
+    if (before === 0 || !run) {
+      return;
+    }
+    for (const target of this.logTargets) {
+      target({
+        runId: run.runId,
+        ...(run.parentRunId ? { parentRunId: run.parentRunId } : {}),
+        ...(run.actor.kind === "person" ? { caller: run.actor.sub } : {}),
+        ts: new Date().toISOString(),
+        runtimeId: this.id,
+        serviceUuid: this.currentService ?? "",
+        level: "debug",
+        event: "service.processed",
+        durationMs,
+      });
+    }
+  }
+
+  /**
+   * Where this runtime's entries go. The server registers one to carry them to
+   * the board's coordinator; a nested pipeline's host registers one to carry
+   * them out to the runtime around it.
+   */
+  registerLogTarget(target: (entry: LogEntry) => void): () => void {
+    this.logTargets.add(target);
+    return () => {
+      this.logTargets.delete(target);
+    };
+  }
+
+  /** Forwards an entry produced by a nested pipeline, unchanged. */
+  forwardLog(entry: LogEntry): void {
+    for (const target of this.logTargets) {
+      target(entry);
+    }
+  }
+
+  setLogData(enabled: boolean): void {
+    this.logData = enabled;
+  }
+
+  /**
+   * Capture mode: whether this runtime's call reports leave it with their
+   * values. Switched while the board runs and never part of its configuration,
+   * so a runtime always starts without it. Read where a report leaves the
+   * server (`outgoingPayload`), so a pipeline nested at any depth — whose
+   * reports reach the server only through this runtime — follows it too.
+   */
+  setCapture(enabled: boolean): void {
+    this.capture = enabled;
+  }
+
+  capturesCalls(): boolean {
+    return this.capture;
+  }
+
+  getLogData(): boolean {
+    return this.logData;
+  }
+
+  logSettings(): { logging: boolean; logData: boolean; logLevel: LogLevel } {
+    return {
+      logging: this.logging,
+      logData: this.logData,
+      logLevel: this.logLevel,
+    };
+  }
+
+  scope(): RuntimeScope {
+    return { owner: this.owner, boardName: this.boardName };
+  }
+
+  secrets(): SecretVault {
+    return this.secretsFrom?.() ?? this.vault;
+  }
+
+  /**
+   * Take secrets from somewhere else rather than from this runtime's own vault.
+   *
+   * A nested pipeline is a runtime nobody provisions: no create payload reaches
+   * it, so its own vault stays empty and a service inside it could never
+   * resolve a reference. What it does have is the runtime around it, which was
+   * provisioned — so it asks that one instead.
+   *
+   * Asked for each time rather than copied, so that a value pushed after a
+   * board is running reaches a nested service as immediately as a top-level
+   * one, and so that nesting composes: each level delegates outward until it
+   * reaches the runtime that was actually given something.
+   */
+  delegateSecrets(source: () => SecretVault | null): void {
+    this.secretsFrom = source;
+  }
+
+  assets(): AssetStore {
+    return this.assetsFrom?.() ?? this.assetStore;
+  }
+
+  /**
+   * Take assets from somewhere else rather than from this runtime's own store.
+   *
+   * The same arrangement as secrets: a nested pipeline is provisioned by nobody,
+   * so it asks the runtime around it — on each lookup, so an asset edited while
+   * the board runs is what a nested service resolves next, and so nesting
+   * composes outward to the runtime that was actually given the descriptors.
+   */
+  delegateAssets(source: () => AssetStore | null): void {
+    this.assetsFrom = source;
+  }
+
+  /**
+   * Takes in descriptors for assets this runtime's services reference, or
+   * `null` for one that was deleted. Merges, like secrets, because a client
+   * edits one asset at a time.
+   */
+  setAssets(entries: Record<string, AssetDescriptor | null>): void {
+    this.assetStore.merge(entries);
+  }
+
+  slots(): SlotStore {
+    return this.slotsFrom?.() ?? this.ownSlots;
+  }
+
+  /**
+   * Hold values somewhere other than this runtime's own cells.
+   *
+   * What a nested pipeline shares with is decided by the service hosting it: an
+   * endpoint that wants its two entry points to hold between them gives both of
+   * them one store, and a service with nothing to share passes its parent's
+   * along — so a slot named deep inside reaches the nearest owner that declared
+   * one, and nesting never isolates what is inside it by accident.
+   */
+  delegateSlots(source: () => SlotStore | null): void {
+    this.slotsFrom = source;
+  }
+
+  /**
+   * Takes in values for references this runtime's services already hold.
+   *
+   * Merges rather than replaces, because this is what a client editing one
+   * entry sends, and what a client re-pushes after a restart. Replacing on a
+   * partial push would strip credentials from services nobody touched.
+   */
+  setSecrets(entries: Record<string, { value: string; audience?: string[] }>): void {
+    this.vault.merge(entries);
+  }
+
+  /**
+   * Adopt the scope of the runtime around this one.
+   *
+   * A nested pipeline is built by the service hosting it, which knows neither
+   * tenant nor board — so a runtime created that way starts anonymous, and
+   * anything it stores would land beside every other anonymous board's. The
+   * host hands it the scope once there is one to hand.
+   */
+  setScope(scope: RuntimeScope): void {
+    this.owner = scope.owner;
+    this.boardName = scope.boardName;
+    // Down, however deep it goes. A service holding a pipeline passes this to
+    // its own runtime, whose services pass it on again — which is what makes a
+    // `conversations` inside a `join` inside an `iterator` answer to the board
+    // it is actually part of rather than to the anonymous default.
+    for (const service of this.services.values()) {
+      service.setScope?.(scope);
+    }
+  }
+
+  setLogLevel(level: LogLevel): void {
+    this.logLevel = level;
+  }
+
+  getLogLevel(): LogLevel {
+    return this.logLevel;
+  }
+
+  setLogging(enabled: boolean): void {
+    this.logging = enabled;
+  }
+
+  getLogging(): boolean {
+    return this.logging;
+  }
+
+  mount(
+    serviceUuid: string,
+    handlers: MountHandlers,
+    options: { mountName?: string } = {},
+  ): MountHandle | null {
+    // A nested runtime has no server of its own, so it asks the one around it
+    // — the same arrangement as secrets and slots. Without this an endpoint
+    // inside a scope had no address at all, which made a scope something a
+    // board could not put an endpoint in.
+    if (this.mountsFrom) {
+      return this.mountsFrom(serviceUuid, handlers, options);
+    }
+    // The board comes from the runtime, not from the service: a mount's address
+    // is derived from where it sits, and a service does not know that.
+    return (
+      this.mounts?.mount(serviceUuid, handlers, {
+        boardName: this.boardName,
+        mountName: options.mountName,
+      }) ?? null
+    );
+  }
+
+  /**
+   * Claim mounts somewhere else rather than on a server of this runtime's own.
+   *
+   * Read on each call rather than copied, so a pipeline attached before its
+   * host could answer still reaches one, and so nesting composes outward to
+   * whichever runtime is actually listening.
+   */
+  delegateMounts(
+    source: (
+      serviceUuid: string,
+      handlers: MountHandlers,
+      options: { mountName?: string },
+    ) => MountHandle | null,
+  ): void {
+    this.mountsFrom = source;
+    // The services here were built before this runtime could serve a mount, so
+    // any that wanted one gave up on it. Now that there is somewhere to claim
+    // from, they are told to ask again; a service with nothing to claim has
+    // nothing to do here and does not answer.
+    for (const service of this.services.values()) {
+      service.remount?.();
+    }
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Runs `fn` with `context` as the current one, restoring what was there
+   * before.
+   *
+   * Restoring rather than clearing is what makes this survive a service that
+   * calls back into this runtime from inside its own `process` — the pull that
+   * a cache miss or a router performs. That inner call is still part of the
+   * outer run, and when it returns the outer loop has more services to visit,
+   * so the context it was running under has to come back.
+   *
+   * Safe as ambient state only because a pass is synchronous: the loop never
+   * yields, so no second call can interleave with this one and observe a
+   * context that is not its own. A pass that awaited would need the context
+   * threaded through the call instead.
+   */
+  private withContext<T>(context: ProcessContext, fn: () => T): T {
+    // The service is carried alongside the context so both are restored
+    // together on the way out of a nested pull.
+    return this.runState.run(
+      {
+        context,
+        service: this.currentService,
+        detachment: detachments.getStore(),
+      },
+      fn,
+    );
+  }
+
+  /** Runs `fn` with the pass recorded as being inside `uuid`. */
+  private inService<T>(uuid: string | null, fn: () => T): T {
+    const store = this.frame;
+    if (!store) {
+      return fn();
+    }
+    const outer = store.service;
+    store.service = uuid;
+    try {
+      return fn();
+    } finally {
+      store.service = outer;
+    }
+  }
+
+  private async processFromIndex(
+    startIndex: number,
+    input: unknown,
+    onNotification: (notification: RuntimeNotification) => void,
+  ): Promise<unknown> {
+    let result: unknown = input;
+
+    for (const uuid of this.serviceOrder.slice(startIndex)) {
+      if (runExpired(this.currentContext())) {
+        this.log("warn", "run.expired");
+        return null;
+      }
+      const service = this.services.get(uuid);
+      if (!service) {
+        continue;
+      }
+
+      this.emitNotification(
+        {
+          instanceId: uuid,
+          payload: {
+            __internal: {
+              state: "call-process",
+              data: result,
+            },
+          },
+        },
+        onNotification,
+      );
+
+      const startedAt = Date.now();
+      // Restored rather than cleared, for the same reason the context is: a
+      // service that pulls the ones after it re-enters this loop, and when it
+      // returns the entries that follow still belong to the service that
+      // pulled.
+      const pending = this.inService(uuid, () => {
+        // The flow itself, at debug: which service the runtime called, and
+        // below, what it returned and how long it took.
+        //
+        // Deliberately without the value flowing through. The level says how
+        // much of the shape of a run to keep, and turning it up must not also
+        // start recording the data — a board author reaching for more detail
+        // about *what ran* is not asking to write payloads to disk. What flows
+        // through is recorded only where a service was configured to record it.
+        this.log("debug", "service.process");
+        const notificationContext = this.currentContext() ?? undefined;
+        return service.process(result, (payload, instanceId) => {
+          this.emitNotification(
+            {
+              instanceId: instanceId ?? uuid,
+              payload,
+              context: notificationContext,
+            },
+            onNotification,
+          );
+        });
+      });
+
+      // A service may answer within the call or after it. Awaiting either is
+      // what lets the one that answers late still be a service the pipeline
+      // reads a result from, rather than one that has to call the rest of the
+      // pipeline itself. Awaiting a plain value costs a microtask.
+      result = isThenable(pending) ? await pending : pending;
+      this.inService(uuid, () =>
+        this.logProcessed(result, Date.now() - startedAt),
+      );
+
+      this.emitNotification(
+        {
+          instanceId: uuid,
+          payload: {
+            __internal: {
+              state: "call-process-finished",
+              data: result,
+            },
+          },
+        },
+        onNotification,
+      );
+
+      if (result === null || result === undefined) {
+        // Where the run ended, named. Recorded above debug because it is the
+        // outcome of the run rather than a step in it: a board that keeps only
+        // what matters still wants to know its flow stopped, and where.
+        this.inService(uuid, () => this.log("info", "pipeline.stopped"));
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  private emitNotification(
+    notification: RuntimeNotification,
+    onNotification: (notification: RuntimeNotification) => void,
+  ): void {
+    const contextual = notification.context
+      ? notification
+      : {
+          ...notification,
+          context: this.currentContext() ?? newRun("board"),
+        };
+    onNotification(contextual);
+    for (const target of this.notificationTargets) {
+      target(contextual);
+    }
+  }
+}
+
+/**
+ * A single tenant's view of the runtime app. Runtime ids are only unique within
+ * an owner — boards ship stable, human-readable ids (`node`, `chat-node`), so
+ * two users loading the same board must each get their own runtime rather than
+ * sharing one. Every route resolves runtimes through one of these views, so a
+ * handler cannot reach another tenant's runtime even by id.
+ */
+export class TenantRuntimes {
+  constructor(
+    readonly owner: string,
+    private readonly app: RuntimeApp,
+  ) {}
+
+  createRuntime(config: RuntimeConfiguration): HostedRuntime {
+    return this.app.createRuntime(this.owner, config);
+  }
+
+  getRuntime(runtimeId: string): HostedRuntime | undefined {
+    return this.app.getRuntime(this.owner, runtimeId);
+  }
+
+  getRuntimes(): HostedRuntime[] {
+    return this.app.getRuntimes(this.owner);
+  }
+
+  removeRuntime(runtimeId: string): boolean {
+    return this.app.removeRuntime(this.owner, runtimeId);
+  }
+
+  removeAllRuntimes(): void {
+    this.app.removeAllRuntimes(this.owner);
+  }
+}
+
+/**
+ * The space the runtimes of one deployed board live in.
+ *
+ * A runtime id is unique within a space, and there are two kinds. What a
+ * tenant's clients create over the api shares one space, named by the tenant
+ * alone. What a coordinator builds for a board gets a space per board, so two
+ * boards that both call a runtime `node` each keep their own, and neither is
+ * replaced by a client creating a runtime of that id.
+ *
+ * NUL occurs in neither part, so a board's space is never a tenant's.
+ */
+export function boardSpace(owner: string, boardName: string): string {
+  return `${owner}\u0000${boardName}`;
+}
+
+export class RuntimeApp {
+  // space → runtimeId → runtime. A tenant's own space is its owner key: the
+  // authenticated `sub` (or "anonymous" when auth is off, collapsing to a
+  // single bucket). A deployed board's is `boardSpace`.
+  private readonly runtimes = new Map<string, Map<string, HostedRuntime>>();
+
+  constructor(
+    private readonly registry: Map<string, HostedServiceFactory>,
+    // Supplied by the server, which owns the listening socket. Absent in tests
+    // and anywhere runtimes need no public endpoints.
+    private readonly mountsFor?: (
+      owner: string,
+      runtimeId: string,
+      space: string,
+    ) => RuntimeMounts,
+    // Supplied by the server, which owns the file store. Absent: no runtime
+    // resolves a `file://` asset.
+    private readonly readAssetFile?: AssetFileReader,
+    // What an asset may weigh, which the server also sizes its requests by.
+    private readonly assetLimits?: AssetStoreOptions,
+  ) {}
+
+  /** A tenant-scoped view; the only way route handlers reach runtimes. */
+  forOwner(owner: string): TenantRuntimes {
+    return new TenantRuntimes(owner, this);
+  }
+
+  /**
+   * Builds a runtime for `owner`, replacing anything under its id in `space`:
+   * the tenant's own unless a board's is named.
+   */
+  createRuntime(
+    owner: string,
+    config: RuntimeConfiguration,
+    space: string = owner,
+  ): HostedRuntime {
+    const owned = this.ownerRuntimes(space);
+    const existing = owned.get(config.id);
+    existing?.destroy();
+
+    const runtime = new HostedRuntime(
+      config,
+      (serviceConfig) => this.createService(serviceConfig),
+      this.mountsFor?.(owner, config.id, space),
+      owner,
+      this.readAssetFile,
+      this.assetLimits,
+    );
+    owned.set(runtime.id, runtime);
+    return runtime;
+  }
+
+  getRuntime(space: string, runtimeId: string): HostedRuntime | undefined {
+    return this.runtimes.get(space)?.get(runtimeId);
+  }
+
+  getRuntimes(space: string): HostedRuntime[] {
+    const owned = this.runtimes.get(space);
+    return owned ? [...owned.values()] : [];
+  }
+
+  /** The runtimes a tenant's deployed boards have here, whichever board. */
+  getBoardRuntimes(owner: string): HostedRuntime[] {
+    const boards = boardSpace(owner, "");
+    return [...this.runtimes]
+      .filter(([space]) => space.startsWith(boards))
+      .flatMap(([, owned]) => [...owned.values()]);
+  }
+
+  /** How many runtimes a tenant has, in its own space and its boards'. */
+  countRuntimes(owner: string): number {
+    return this.getRuntimes(owner).length + this.getBoardRuntimes(owner).length;
+  }
+
+  removeRuntime(space: string, runtimeId: string): boolean {
+    const owned = this.runtimes.get(space);
+    if (!owned) {
+      return false;
+    }
+    const runtime = owned.get(runtimeId);
+    runtime?.destroy();
+    const deleted = owned.delete(runtimeId);
+    if (owned.size === 0) {
+      this.runtimes.delete(space);
+    }
+    return deleted;
+  }
+
+  /** Removes what is in a tenant's own space; a board's runtimes are its
+   *  coordinator's to remove. */
+  removeAllRuntimes(owner: string): void {
+    const owned = this.runtimes.get(owner);
+    if (!owned) {
+      return;
+    }
+    for (const runtime of owned.values()) {
+      runtime.destroy();
+    }
+    this.runtimes.delete(owner);
+  }
+
+  getRegistry() {
+    return [...this.registry.values()].map((entry) => entry.descriptor);
+  }
+
+  private ownerRuntimes(owner: string): Map<string, HostedRuntime> {
+    const existing = this.runtimes.get(owner);
+    if (existing) {
+      return existing;
+    }
+    const created = new Map<string, HostedRuntime>();
+    this.runtimes.set(owner, created);
+    return created;
+  }
+
+  createService(config: ServiceConfiguration): HostedService {
+    const factory = this.registry.get(config.serviceId);
+    if (!factory) {
+      throw new Error(`Unknown serviceId: ${config.serviceId}`);
+    }
+    return factory.create(config, (serviceConfig) =>
+      this.createService(serviceConfig),
+    );
+  }
+}
+
+/** Whether a value is worth awaiting — a promise, or anything promise-like. */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as PromiseLike<unknown>).then === "function"
+  );
+}