Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

26.9 KB
Raw Blame
/**
 * Module tree boot: manifests decide the wiring, code only provides implementations.
 *
 * A module is a manifest ({@link Manifest}) plus one `create`. Boot runs {@link checkTree}
 * over the manifests first — nothing is created while a problem stands — then creates
 * modules in dependency order: a module boots after everything it `requires` and after
 * every module that contributes to one of its slots WITH A CODE HALF (that half is the
 * contributor's `bind[id]`, which exists only once the contributor is created). A data-only
 * contribution is manifest data, there before anything is created, so it orders nothing — a
 * module may declare data on a slot and require the slot's owner.
 *
 * The tree shape is scope, not order: siblings are created in whatever order their
 * edges allow, and a cycle is a boot error naming the modules in it.
 *
 * Parked state: each module's `park()` result is stored under its name; `bootModules`
 * takes that map back and hands each module its own document after running the
 * module's migrations. This is the platform node's `modules` field.
 */
import { type } from "arktype";
import type { Json, JsonObject } from "./json.js";
import { isJsonObject } from "./json.js";
import type { Resources } from "./boot.js";
import type { IfaceDecl, TableLike } from "./sig.js";
import { satisfies, tableOf } from "./sig.js";
import type { ContextDecl, Manifest, Requirement } from "./manifest.js";
import { splitSlotKey } from "./manifest.js";
import type { ManifestNode, Problem, Published } from "./check.js";
import { checkTree, describeProblem } from "./check.js";
import type { Meta, ModuleClass } from "./decorators.js";
import { fieldsOf, metaOf } from "./decorators.js";

/** One contribution as the consuming module receives it. */
export interface Contributed<D = JsonObject, C = unknown> {
  id: string;
  /** The contributor module's name. */
  from: string;
  data: D;
  /** The contributor's `bind[id]`, when the slot declares a code half. */
  code?: C;
}

export interface ModuleCtx<Use = Record<string, unknown>> {
  /** Resolved requirements, by the manifest's alias. */
  use: Use;
  /** Contributions to this module's slots, by slot name. */
  contributions: Record<string, Contributed[]>;
  resources: Resources;
  /** Self-cleaning registration; drained at dispose in reverse order, children first. */
  effect(dispose: () => void): void;
}

export interface ModuleInstance<Api = Record<string, unknown>> {
  /** Provided implementations, by the manifest's provides alias. */
  api: Api;
  /** Implementations of this module's own contributions, by contribution id. */
  bind?: Record<string, unknown>;
  park?(): Json;
}

export interface ModuleDef<
  M extends Manifest = Manifest,
  Use = Record<string, unknown>,
  Api = Record<string, unknown>,
> {
  manifest: M;
  /** Context migrations by from-version, chained (1→2→3). */
  migrations?: Record<number, (old: Json) => Json>;
  create(ctx: ModuleCtx<Use>, context: Json): ModuleInstance<Api> | Promise<ModuleInstance<Api>>;
  children?: ModuleDef[];
}

type RefKey<Ref, Mod extends string> = Ref extends `${string}#${string}`
  ? Ref
  : Ref extends string
    ? `${Mod}#${Ref}`
    : never;
type Lookup<Reg, K> = K extends keyof Reg ? Reg[K] : unknown;

/**
 * Interface key (`<module>#<Export>`) → TypeScript type: a registry a package
 * may declare over its interface classes, and `moduleDefiner<ThatRegistry>()` is how a manifest literal
 * gets to type its own `use` and `api`.
 */
export type IfaceRegistry = object;

/** The `use` a manifest's `requires` resolves to, by alias. */
export type UseOf<M extends Manifest, Reg extends IfaceRegistry = IfaceRegistry> = {
  [A in keyof M["requires"]]: Lookup<Reg, RefKey<M["requires"][A]["iface"], M["name"]>>;
};
/** The `api` a manifest's `provides` demands, by alias. */
export type ApiOf<M extends Manifest, Reg extends IfaceRegistry = IfaceRegistry> = {
  [A in keyof M["provides"]]: Lookup<Reg, RefKey<M["provides"][A], M["name"]>>;
};

export interface ModuleImplOf<M extends Manifest, Reg extends IfaceRegistry> {
  migrations?: Record<number, (old: Json) => Json>;
  create(
    ctx: ModuleCtx<UseOf<M, Reg>>,
    context: Json,
  ): ModuleInstance<ApiOf<M, Reg>> | Promise<ModuleInstance<ApiOf<M, Reg>>>;
  children?: ModuleDef[];
}

/**
 * A `defineModule` bound to an interface registry. A module is its manifest as a literal
 * (the static half — the generator extracts it without executing the file) and its
 * create; `use` and `api` are typed FROM the manifest through the registry, so the two
 * cannot drift: an alias renamed in `requires` is a type error at every `ctx.use.<alias>`,
 * and an interface named in `provides` is what `api` must satisfy. A key the registry
 * does not carry types as `unknown` (a plugin requiring a host interface it has no
 * types for still boots; the host checks the signature).
 */
export function moduleDefiner<Reg extends IfaceRegistry>() {
  return function defineModule<const M extends Manifest>(
    manifest: M,
    impl: ModuleImplOf<M, Reg>,
  ): ModuleDef<M, UseOf<M, Reg>, ApiOf<M, Reg>> {
    return { manifest, ...impl };
  };
}

/** `defineModule` with no registry: every requirement is `unknown` at compile time. */
export const defineModule = moduleDefiner<IfaceRegistry>();

// ───────────────────────── class form: @Module / @Use / @Provide / @Bind ─────────────────────────

// The decorators themselves live in decorators.ts (no imports, so a plugin bundles just them);
// this file reads what they recorded.
export type { ComponentMeta, IfaceClass, ModuleClass, ModuleMeta } from "./decorators.js";
export { Bind, Component, Module, Provide, Use, wire } from "./decorators.js";

/** What a module class's `create` receives: everything in {@link ModuleCtx} except `use` — requirements are fields. */
export type ClassCtx = Omit<ModuleCtx, "use">;

/** The meta a class was decorated with; throws for an undecorated class. */
export function moduleMetaOf(cls: ModuleClass): Meta {
  const m = metaOf(cls);
  if (m === undefined)
    throw new ModuleBootError(`class '${cls.name}' is not a @Module or @Component`);
  return m;
}

/** The manifests the generator extracted, by module name — the `modules` section of the table. */
export type ManifestTable = Readonly<Record<string, Manifest>>;

/**
 * Turns a module class (and, recursively, its children) into the {@link ModuleDef} the
 * booter runs. The string manifest is the generator's (`table.modules[name]` — it read the
 * field annotations statically); the class is checked against it: every `@Use` field must
 * be a requirement there with the same `from`, every `@Provide` field a provision, every
 * child class a child. A mismatch means the table is stale, and says so. `instances`
 * supplies pre-built instances for classes whose constructor takes arguments.
 */
export function moduleDefOf(
  cls: ModuleClass,
  opts: {
    manifests: ManifestTable;
    instances?: ReadonlyMap<ModuleClass, object>;
    extra?: ModuleDef[];
    /**
     * Definitions standing in for nodes, by name — an extension's replacements. A
     * replaced class is not looked at (its table entry, its fields): the definition is
     * taken as it is, and the assembled tree is what gets checked.
     */
    replace?: ReadonlyMap<string, ModuleDef>;
  },
): ModuleDef {
  const meta = moduleMetaOf(cls);
  const replacement = opts.replace?.get(meta.name);
  if (replacement !== undefined) {
    if (replacement.manifest.name !== meta.name) {
      throw new ModuleBootError(
        `replacement for '${meta.name}' is named '${replacement.manifest.name}' — a replacement keeps the name of the node it stands in for`,
      );
    }
    return replacement;
  }
  const manifest = opts.manifests[meta.name];
  if (manifest === undefined) {
    throw new ModuleBootError(`${meta.name}: not in the generated manifest table — run gen:ifaces`);
  }
  // The field decorators record a class's @Use / @Provide / @Bind fields when an instance
  // is constructed. A replacement (a test double standing in for the class) is not one,
  // so the class is probed once to learn its fields before the double is checked against
  // them; the node classes' constructors only store what they are given.
  const supplied = opts.instances?.get(cls);
  if (
    supplied !== undefined &&
    fieldsOf(cls).use.size + fieldsOf(cls).provide.size + fieldsOf(cls).bind.size === 0
  ) {
    try {
      new (cls as unknown as new () => object)();
    } catch {
      // A class that cannot be built without arguments keeps whatever was recorded.
    }
  }
  const instance = (supplied ?? new (cls as unknown as new () => object)()) as Record<
    string,
    unknown
  > & {
    setup?: (ctx: ClassCtx, context: Json) => void | Promise<void>;
    park?: () => Json;
    migrations?: Record<number, (old: Json) => Json>;
  };
  const f = fieldsOf(cls);
  const stale = (what: string) =>
    new ModuleBootError(
      `${meta.name}: ${what} — the generated manifest table is stale; run gen:ifaces`,
    );
  for (const [field, from] of f.use) {
    const r = manifest.requires[field];
    if (r === undefined) throw stale(`@Use field '${field}' is not a requirement in the table`);
    // `@Use()` with no argument leaves the wiring to the table (the generator wires a field
    // typed by a component class to that component); an explicit argument must agree.
    const fromName = from === undefined ? undefined : moduleMetaOf(from).name;
    if (fromName !== undefined && r.from !== fromName)
      throw stale(
        `@Use field '${field}' is wired to '${fromName}' in code, '${r.from}' in the table`,
      );
  }
  for (const field of Object.keys(manifest.requires)) {
    if (!f.use.has(field)) throw stale(`requirement '${field}' in the table has no @Use field`);
  }
  // A component's provisions are all the instance: itself, and every interface it
  // `implements` (the generator records both).
  const selfAliases = meta.kind === "component" ? Object.keys(manifest.provides) : [];
  if (meta.kind === "component" && manifest.provides[cls.name] === undefined)
    throw stale(`component '${cls.name}' does not provide itself in the table`);
  for (const field of f.provide) {
    if (manifest.provides[field] === undefined)
      throw stale(`@Provide field '${field}' is not a provision in the table`);
  }
  const forwarded = new Set(manifest.exports ?? []);
  for (const field of Object.keys(manifest.provides)) {
    if (selfAliases.includes(field) || forwarded.has(field)) continue;
    if (!f.provide.has(field))
      throw stale(`provision '${field}' in the table has no @Provide field`);
  }
  const childNames = (meta.children ?? []).map((c) => moduleMetaOf(c).name);
  const declared = manifest.children
    .map((c) => (typeof c === "string" ? c : c.keyed))
    .filter((c) => c !== "*");
  if (childNames.join(",") !== declared.join(",")) {
    throw stale(
      `children are [${childNames.join(", ")}] in code, [${declared.join(", ")}] in the table`,
    );
  }
  const extra = opts.extra ?? [];
  const def: ModuleDef = {
    manifest: {
      ...manifest,
      children: [...manifest.children.filter((c) => c !== "*"), ...(extra.length > 0 ? ["*"] : [])],
    },
    async create(ctx, context) {
      // A supplied instance (a double) keeps the fields it came with; the tree fills the
      // rest, so a double may be partial.
      for (const field of f.use.keys())
        if (supplied === undefined || instance[field] === undefined)
          instance[field] = (ctx.use as Record<string, unknown>)[field];
      if (typeof instance.setup === "function") await instance.setup(ctx, context);
      const api: Record<string, unknown> = {};
      for (const alias of selfAliases) api[alias] = instance;
      for (const field of f.provide) {
        if (instance[field] === undefined) {
          throw new ModuleBootError(
            `${meta.name}: setup() left @Provide field '${field}' unassigned`,
          );
        }
        api[field] = instance[field];
      }
      const bind: Record<string, unknown> = {};
      for (const [field, id] of f.bind) {
        if (instance[field] === undefined) {
          throw new ModuleBootError(
            `${meta.name}: create() left @Bind field '${field}' ('${id}') unassigned`,
          );
        }
        bind[id] = instance[field];
      }
      const out: ModuleInstance = { api, bind };
      if (typeof instance.park === "function") out.park = () => instance.park!();
      return out;
    },
    children: [
      ...(meta.children ?? []).map((child) => moduleDefOf(child, { ...opts, extra: undefined })),
      ...extra,
    ],
  };
  if (instance.migrations !== undefined) def.migrations = instance.migrations;
  return def;
}

export class ModuleBootError extends Error {
  constructor(
    message: string,
    readonly problems: Problem[] = [],
  ) {
    super(message);
    this.name = "ModuleBootError";
  }
}

/** A booted tree. */
export interface ModuleTree {
  /** A module's provided api by module name and alias. */
  api<T = unknown>(module: string, alias: string): T;
  has(module: string): boolean;
  /** Every module's parked document, by name — the platform node stores this. */
  park(): Record<string, Json>;
  /** Reverse creation order. */
  dispose(): void;
}

export interface BootModulesOptions {
  ifaces: TableLike;
  /** What the host publishes: interface declarations AND the live values behind them. */
  published?: { ifaces: Published; values: Record<string, Record<string, unknown>> };
  resources: Resources;
  /** Parked documents from the previous generation, by module name. */
  parked?: Record<string, Json>;
}

interface Flat {
  def: ModuleDef;
  parent: Flat | null;
  childrenDefs: ModuleDef[];
  /** Module names above this one; a node never wires to an ancestor (its exports are for outsiders). */
  ancestors: Set<string>;
}

function flatten(root: ModuleDef): { nodes: Flat[]; tree: ManifestNode } {
  const nodes: Flat[] = [];
  const walk = (def: ModuleDef, parent: Flat | null): ManifestNode => {
    const flat: Flat = {
      def,
      parent,
      childrenDefs: def.children ?? [],
      ancestors: new Set(parent ? [...parent.ancestors, parent.def.manifest.name] : []),
    };
    nodes.push(flat);
    return { manifest: def.manifest, children: flat.childrenDefs.map((c) => walk(c, flat)) };
  };
  const tree = walk(root, null);
  return { nodes, tree };
}

/** The module each `requires` alias wires to, after the check has proven it unique. */
function wiring(
  manifest: Manifest,
  provides: Record<string, Record<string, IfaceDecl>>,
  ifaces: TableLike,
  ancestors: ReadonlySet<string> = new Set(),
): Record<string, { from: string; alias: string }> {
  const out: Record<string, { from: string; alias: string }> = {};
  for (const [alias, need] of Object.entries(manifest.requires)) {
    const required =
      tableOf(ifaces).ifaces[
        need.iface.includes("#") ? need.iface : `${manifest.name}#${need.iface}`
      ]!;
    const candidates = need.from !== undefined ? [need.from] : Object.keys(provides);
    // checkTree already established a unique satisfier — a provision DECLARING the very
    // interface (the same table entry) wins over one that merely has the shape.
    for (const exact of [true, false]) {
      for (const from of candidates) {
        if (from === manifest.name || ancestors.has(from)) continue;
        for (const [pAlias, decl] of Object.entries(provides[from] ?? {})) {
          if (exact ? decl === required : satisfiesQuick(decl, required, ifaces)) {
            out[alias] = { from, alias: pAlias };
            break;
          }
        }
        if (out[alias] !== undefined) break;
      }
      if (out[alias] !== undefined) break;
    }
  }
  return out;
}

function satisfiesQuick(offered: IfaceDecl, required: IfaceDecl, table: TableLike): boolean {
  return satisfies(offered, required, table).length === 0;
}

function migrateContext(def: ModuleDef, doc: Json | undefined): Json {
  const decl = def.manifest.context;
  if (decl === undefined || doc === undefined) return null; // No context, or a fresh boot: nothing to migrate.
  let version = 1;
  let self: Json = null;
  if (isJsonObject(doc) && typeof doc.v === "number" && "self" in doc) {
    version = doc.v;
    self = doc.self;
  } else if (doc !== undefined) {
    self = doc;
  }
  if (version > decl.version) {
    throw new ModuleBootError(
      `${def.manifest.name}: parked under context v${version}, newer than this module's v${decl.version}`,
    );
  }
  while (version < decl.version) {
    const migrate = def.migrations?.[version];
    if (migrate === undefined) {
      throw new ModuleBootError(
        `${def.manifest.name}: no context migration from v${version} to v${decl.version}`,
      );
    }
    self = migrate(self);
    version += 1;
  }
  if (decl.schema !== undefined && self !== null) {
    const out = type.raw(decl.schema).onUndeclaredKey("reject")(self);
    if (out instanceof type.errors) {
      throw new ModuleBootError(
        `${def.manifest.name}: parked context does not fit: ${out.summary}`,
      );
    }
  }
  return self;
}

export async function bootModules(root: ModuleDef, opts: BootModulesOptions): Promise<ModuleTree> {
  const { nodes, tree } = flatten(root);
  // The manifest's `children` is the declared shape; the defs are what boots. They must
  // agree — except that a manifest listing "*" accepts modules supplied at runtime
  // beyond the ones it names (plugin modules under the platform root).
  for (const n of nodes) {
    const declared = n.def.manifest.children.map((c) => (typeof c === "string" ? c : c.keyed));
    const open = declared.includes("*");
    const named = declared.filter((c) => c !== "*").sort();
    const actual = n.childrenDefs.map((c) => c.manifest.name).sort();
    const missing = named.filter((c) => !actual.includes(c));
    const extra = actual.filter((c) => !named.includes(c));
    if (missing.length > 0 || (!open && extra.length > 0)) {
      throw new ModuleBootError(
        `${n.def.manifest.name}: manifest declares children [${declared.join(", ")}] but the code supplies [${actual.join(", ")}]`,
      );
    }
  }
  const publishedIfaces = opts.published?.ifaces ?? {};
  const { problems, provides } = checkTree(tree, opts.ifaces, publishedIfaces);
  if (problems.length > 0) {
    throw new ModuleBootError(
      `module tree rejected:\n${problems.map((p) => `  - ${describeProblem(p)}`).join("\n")}`,
      problems,
    );
  }
  const byName = new Map(nodes.map((n) => [n.def.manifest.name, n]));
  const wires = new Map<string, Record<string, { from: string; alias: string }>>();
  for (const n of nodes)
    wires.set(n.def.manifest.name, wiring(n.def.manifest, provides, opts.ifaces, n.ancestors));

  /**
   * Where an exported alias actually comes from: the child declaring the interface (else
   * the one child whose provision satisfies it), followed through nested exports. A
   * module's exports are a scope's outward face, not a gate — a consumer waits for the
   * child, never for the whole group, which is what keeps two groups that need one
   * another's children from being a cycle.
   */
  const exportTarget = (module: string, alias: string): { module: string; alias: string } => {
    const n = byName.get(module);
    if (n === undefined || !(n.def.manifest.exports ?? []).includes(alias))
      return { module, alias };
    const wanted = provides[module]![alias]!;
    const found: Array<{ module: string; alias: string }> = [];
    for (const exact of [true, false]) {
      for (const child of n.childrenDefs) {
        const name = child.manifest.name;
        for (const [cAlias, decl] of Object.entries(provides[name] ?? {})) {
          if (exact ? decl === wanted : satisfiesQuick(decl, wanted, opts.ifaces)) {
            found.push({ module: name, alias: cAlias });
            break;
          }
        }
      }
      if (found.length > 0) break;
    }
    if (found.length !== 1) {
      throw new ModuleBootError(
        `${module}: exports '${alias}' but ${found.length === 0 ? "no child provides it" : `${found.map((f) => f.module).join(", ")} all do`}`,
      );
    }
    return exportTarget(found[0]!.module, found[0]!.alias);
  };

  // Edges: a module comes after what it requires (resolved through exports to the node
  // that provides it), after what contributes code to it, and after its children.
  const after = new Map<string, Set<string>>();
  for (const n of nodes) after.set(n.def.manifest.name, new Set());
  for (const n of nodes) {
    const name = n.def.manifest.name;
    for (const w of Object.values(wires.get(name)!)) {
      if (byName.has(w.from)) after.get(name)!.add(exportTarget(w.from, w.alias).module);
    }
    for (const slotKey of Object.keys(n.def.manifest.contributes)) {
      const split = splitSlotKey(slotKey)!;
      if (!byName.has(split.module)) continue;
      const slotDecl = Object.values(provides[split.module] ?? {})
        .map((d) => d.slots[split.slot])
        .find((s) => s !== undefined);
      if (slotDecl?.code !== undefined) after.get(split.module)!.add(name);
    }
    for (const child of n.childrenDefs) after.get(name)!.add(child.manifest.name);
  }
  const order: Flat[] = [];
  const state = new Map<string, "visiting" | "done">();
  const visit = (name: string, stack: string[]) => {
    const s = state.get(name);
    if (s === "done") return;
    if (s === "visiting") {
      throw new ModuleBootError(`module dependency cycle: ${[...stack, name].join(" → ")}`);
    }
    state.set(name, "visiting");
    for (const dep of after.get(name)!) visit(dep, [...stack, name]);
    state.set(name, "done");
    order.push(byName.get(name)!);
  };
  for (const n of nodes) visit(n.def.manifest.name, []);

  const instances = new Map<string, { inst: ModuleInstance; disposers: Array<() => void> }>();
  const created: string[] = [];
  const apiOf = (module: string, alias: string): unknown => {
    const inst = instances.get(module);
    if (inst !== undefined) return inst.inst.api[alias];
    const value = opts.published?.values[module]?.[alias];
    if (value === undefined) throw new ModuleBootError(`no api '${alias}' on module '${module}'`);
    return value;
  };
  /** Runs every disposer, newest first, through failures; the failures come back together. */
  const drain = (disposers: Array<() => void>): unknown[] => {
    const failures: unknown[] = [];
    for (const dispose of disposers.reverse()) {
      try {
        dispose();
      } catch (err) {
        failures.push(err);
      }
    }
    disposers.length = 0;
    return failures;
  };
  const disposeAll = () => {
    const failures: unknown[] = [];
    try {
      for (const name of [...created].reverse())
        failures.push(...drain(instances.get(name)!.disposers));
    } finally {
      created.length = 0;
      instances.clear();
    }
    if (failures.length === 1) throw failures[0];
    if (failures.length > 1)
      throw new AggregateError(failures, `${failures.length} disposers failed`);
  };
  try {
    for (const n of order) {
      const mf = n.def.manifest;
      const use: Record<string, unknown> = {};
      for (const [alias, w] of Object.entries(wires.get(mf.name)!)) {
        const t = exportTarget(w.from, w.alias);
        use[alias] = apiOf(t.module, t.alias);
      }
      const contributions: Record<string, Contributed[]> = {};
      for (const other of nodes) {
        for (const [slotKey, entries] of Object.entries(other.def.manifest.contributes)) {
          const split = splitSlotKey(slotKey)!;
          if (split.module !== mf.name) continue;
          const slotDecl = Object.values(provides[mf.name] ?? {})
            .map((d) => d.slots[split.slot])
            .find((s) => s !== undefined);
          const list = (contributions[split.slot] ??= []);
          const contributor = instances.get(other.def.manifest.name);
          for (const entry of entries) {
            const { id, ...data } = entry;
            const item: Contributed = { id, from: other.def.manifest.name, data };
            if (slotDecl?.code !== undefined) {
              const code = contributor?.inst.bind?.[id];
              if (code === undefined) {
                throw new ModuleBootError(
                  `${other.def.manifest.name}: contribution '${id}' to '${slotKey}' declared but not bound`,
                );
              }
              item.code = code;
            }
            list.push(item);
          }
        }
      }
      const disposers: Array<() => void> = [];
      const ctx: ModuleCtx = {
        use,
        contributions,
        resources: opts.resources,
        effect: (dispose) => disposers.push(dispose),
      };
      const context = migrateContext(n.def, opts.parked?.[mf.name]);
      // Effects registered while this module is being created are its own to release when
      // it fails — the outer cleanup only knows the modules that made it into `instances`.
      let inst: ModuleInstance;
      try {
        inst = await n.def.create(ctx, context);
      } catch (err) {
        drain(disposers);
        throw err;
      }
      // Exports: the alias is forwarded from the child that declares the interface — else
      // from the one child whose provision satisfies it — so the subtree offers it as one.
      for (const alias of mf.exports ?? []) {
        const t = exportTarget(mf.name, alias);
        inst.api[alias] = apiOf(t.module, t.alias);
      }
      const validate = () => {
        for (const alias of Object.keys(mf.provides)) {
          const value = inst.api[alias];
          if (value === null || (typeof value !== "object" && typeof value !== "function")) {
            throw new ModuleBootError(`${mf.name}: create() returned no api for provides.${alias}`);
          }
          const decl = provides[mf.name]![alias]!;
          const missing = Object.keys(decl.methods).filter(
            (m) => typeof (value as Record<string, unknown>)[m] !== "function",
          );
          const absent = Object.entries(decl.fields ?? {})
            .filter(([, expr]) => !("maybe" in expr))
            .filter(([f]) => (value as Record<string, unknown>)[f] === undefined)
            .map(([f]) => f);
          if (missing.length > 0 || absent.length > 0) {
            throw new ModuleBootError(
              `${mf.name}: api '${alias}' does not satisfy '${decl.name}': missing [${[...missing, ...absent].join(", ")}]`,
            );
          }
        }
      };
      try {
        validate();
      } catch (err) {
        drain(disposers);
        throw err;
      }
      instances.set(mf.name, { inst, disposers });
      created.push(mf.name);
    }
  } catch (err) {
    try {
      disposeAll();
    } catch {
      // The original failure is what the caller needs.
    }
    throw err;
  }
  return {
    api: <T>(module: string, alias: string) => apiOf(module, alias) as T,
    has: (module) => instances.has(module),
    park() {
      const out: Record<string, Json> = {};
      for (const [name, entry] of instances) {
        const decl = byName.get(name)!.def.manifest.context;
        if (decl === undefined || entry.inst.park === undefined) continue;
        out[name] = { v: decl.version, self: entry.inst.park() };
      }
      return out;
    },
    dispose: disposeAll,
  };
}