Skip to content

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

11.3 KB
Raw Blame
/**
 * boot(): the only place instances are created. Walks the static tree declared
 * by the iface, boots children first (keyed collections get a handle with
 * add/remove — runtime cardinality changes still go through boot), then calls
 * the impl factory and verifies the returned api against the iface method set.
 *
 * State discipline (linear state):
 * - serializable state lives in the parked context document,
 * - live resources stay in the runtime-side `Resources` registry and the
 *   context only carries handle ids (claim on boot; a failed claim is an
 *   explicit discard, surfaced to the upgrade ladder),
 * - reseedable state is rebuilt after boot and never parked.
 */
import type { Json, JsonObject } from "./json.js";
import { isJsonObject } from "./json.js";
import type { AnyIface, ChildDecl, Iface, Park } from "./iface.js";
import { isKeyed } from "./iface.js";

/** Runtime-owned live resources (pty, child processes, connections). */
export interface Resources {
  /**
   * `dispose` is how a resource says what "shut down" means for it — the registry
   * itself knows nothing about kinds, so a platform can introduce a resource type the
   * runtime has never heard of and still have it cleaned up at process exit.
   *
   * Returns the PAIRED unregister for this exact registration: it removes the entry AND
   * runs its dispose — out of the registry means shut down, or the process-exit sweep
   * could no longer reach it. Both are identity-checked: a later overwrite by a successor
   * turns the handle into a no-op and moves shutdown responsibility to the new
   * registration — a dead generation can never touch a slot it no longer owns. This is
   * the only way to remove a single entry; there is deliberately no release-by-id, which
   * would be an unpaired delete aimed at whatever happens to occupy the slot.
   */
  register(id: string, resource: unknown, dispose?: () => void): () => void;
  claim<T = unknown>(id: string): T | undefined;
  /**
   * Disposes and removes every entry whose id belongs to the group (`terminal` covers
   * `terminal:*`), in reverse registration order — later entries may depend on earlier
   * ones, same convention as effects.
   *
   * A hook for IMPLEMENTATIONS, not a kernel mechanism: the kernel never calls it, and
   * upgrade() has no opinion about resource compatibility. An impl's create() uses it to
   * hard-stop the groups it cannot adopt from its predecessor (penguin does this over a
   * declaration it leaves in the registry itself — see server hmr/platform.ts). Optional,
   * so a registry that does not offer it simply carries every group across unchecked.
   */
  disposeGroup?(group: string): void;
}

export interface NodeCtx {
  resources: Resources;
  /** Self-cleaning registration: collected disposers are drained at dispose. */
  effect(dispose: () => void): void;
}

/** Handle a parent receives for a `keyed()` child collection. */
export interface KeyedHandle<A extends Park = Park> {
  get(key: string): A | undefined;
  keys(): string[];
  add(key: string, context: Json): Promise<A>;
  remove(key: string): void;
}

/**
 * An impl provides the factory for its node plus impls for declared children.
 * `children` values handed to create(): singleton child → its api, keyed
 * child → a KeyedHandle. (Loosely typed until the arktype-era inference —
 * see TODO(schema) in json.ts.)
 */
export interface Impl<A extends Park = Park, C extends Json = Json> {
  create(ctx: NodeCtx, context: C, children: Record<string, unknown>): A | Promise<A>;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  children?: Record<string, Impl<any, any>>;
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
export type AnyImpl = Impl<any, any>;

export class BootError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "BootError";
  }
}

/** Parked tree node: `v` is the iface version the document was parked under. */
export interface ParkedNode extends JsonObject {
  v: number;
  self: Json;
  children: { [name: string]: Json };
}

interface NodeInst {
  iface: AnyIface;
  api: Park & Record<string, unknown>;
  disposers: Array<() => void>;
  children: Map<string, NodeInst | KeyedInst>;
}

interface KeyedInst {
  kind: "keyed";
  iface: AnyIface;
  impl: AnyImpl;
  items: Map<string, NodeInst>;
}

function isKeyedInst(child: NodeInst | KeyedInst): child is KeyedInst {
  return "kind" in child && child.kind === "keyed";
}

export interface Instance<A extends Park = Park> {
  api: A;
  iface: Iface<A, Json>;
  /** Pure snapshot of the whole tree; does not touch the running instance. */
  park(): ParkedNode;
  /** Children-first teardown: drains every effect registered via ctx.effect. */
  dispose(): void;
}

/** Shapes a fresh (no prior state) parked document for an iface tree. */
export function initialDoc(
  iface: AnyIface,
  self: Json,
  children: { [name: string]: Json } = {},
): ParkedNode {
  const shaped: { [name: string]: Json } = {};
  for (const [name, decl] of Object.entries(iface.children)) {
    shaped[name] = children[name] ?? (isKeyed(decl) ? { items: {} } : null);
  }
  return { v: iface.version, self, children: shaped };
}

function parseParkedNode(doc: Json, path: string): ParkedNode {
  if (!isJsonObject(doc) || typeof doc.v !== "number" || doc.self === undefined) {
    throw new BootError(`${path}: not a parked node document`);
  }
  const children = doc.children;
  return {
    v: doc.v,
    self: doc.self,
    children: isJsonObject(children) ? children : {},
  };
}

/**
 * Accumulators a node fills as it builds — held by {@link bootNode} so that a failure
 * partway through still has something to unwind.
 */
interface PartialNode {
  children: Map<string, NodeInst | KeyedInst>;
  disposers: Array<() => void>;
}

async function bootNode(
  impl: AnyImpl,
  iface: AnyIface,
  doc: Json,
  resources: Resources,
  path: string,
): Promise<NodeInst> {
  const partial: PartialNode = { children: new Map(), disposers: [] };
  try {
    return await buildNode(impl, iface, doc, resources, path, partial);
  } catch (err) {
    // A node that fails half-built still HAS a half: children already booted, effects
    // already registered. Nothing else can reach them — the caller gets an exception,
    // not an instance — so unwinding here is the only chance to run them. Same
    // children-first convention as disposeNode; a throwing disposer must not mask the
    // failure actually being reported.
    try {
      disposeNode({ iface, api: {} as NodeInst["api"], ...partial });
    } catch {
      // Best-effort: the original failure is what the caller needs to see.
    }
    throw err;
  }
}

async function buildNode(
  impl: AnyImpl,
  iface: AnyIface,
  doc: Json,
  resources: Resources,
  path: string,
  partial: PartialNode,
): Promise<NodeInst> {
  const parked = parseParkedNode(doc, path);
  const parsed = iface.context.strictParse(parked.self, `${path}.self`);
  if (!parsed.ok) {
    throw new BootError(
      `${path}: context does not satisfy iface '${iface.name}' v${iface.version} ` +
        `(dropped=[${parsed.dropped}] missing=[${parsed.missing}] invalid=[${parsed.invalid}])`,
    );
  }

  const childInsts = partial.children;
  const childHandles: Record<string, unknown> = {};
  for (const [name, decl] of Object.entries(iface.children)) {
    const childImpl = impl.children?.[name];
    if (childImpl === undefined) {
      throw new BootError(`${path}: impl provides no child impl for '${name}'`);
    }
    if (isKeyed(decl)) {
      const collection: KeyedInst = {
        kind: "keyed",
        iface: decl.iface,
        impl: childImpl,
        items: new Map(),
      };
      const itemsDoc = isJsonObject(parked.children[name])
        ? (parked.children[name] as JsonObject).items
        : undefined;
      if (isJsonObject(itemsDoc)) {
        for (const [key, itemDoc] of Object.entries(itemsDoc)) {
          collection.items.set(
            key,
            await bootNode(
              childImpl,
              decl.iface,
              itemDoc,
              resources,
              `${path}.children.${name}.items.${key}`,
            ),
          );
        }
      }
      childInsts.set(name, collection);
      childHandles[name] = makeKeyedHandle(collection, resources, `${path}.children.${name}`);
    } else {
      const childDoc = parked.children[name] ?? initialDoc(decl, null);
      const inst = await bootNode(childImpl, decl, childDoc, resources, `${path}.children.${name}`);
      childInsts.set(name, inst);
      childHandles[name] = inst.api;
    }
  }

  const disposers = partial.disposers;
  const ctx: NodeCtx = {
    resources,
    effect: (dispose) => disposers.push(dispose),
  };
  const api = (await impl.create(ctx, parsed.value, childHandles)) as Park &
    Record<string, unknown>;

  // Go-style method-set check, moved to boot time: the impl satisfies the iface
  // implicitly or not at all.
  const missingMethods = iface.methods.filter((m) => typeof api[m] !== "function");
  if (missingMethods.length > 0) {
    throw new BootError(
      `${path}: impl does not satisfy iface '${iface.name}': missing method(s) [${missingMethods.join(", ")}]`,
    );
  }

  return { iface, api, disposers, children: childInsts };
}

function makeKeyedHandle(collection: KeyedInst, resources: Resources, path: string): KeyedHandle {
  return {
    get: (key) => collection.items.get(key)?.api,
    keys: () => [...collection.items.keys()],
    async add(key, context) {
      if (collection.items.has(key))
        throw new BootError(`${path}.items.${key}: key already exists`);
      const doc =
        isJsonObject(context) && typeof context.v === "number"
          ? context
          : initialDoc(collection.iface, context);
      const inst = await bootNode(
        collection.impl,
        collection.iface,
        doc,
        resources,
        `${path}.items.${key}`,
      );
      collection.items.set(key, inst);
      return inst.api;
    },
    remove(key) {
      const inst = collection.items.get(key);
      if (inst === undefined) return;
      collection.items.delete(key);
      disposeNode(inst);
    },
  };
}

function parkNode(node: NodeInst): ParkedNode {
  const children: { [name: string]: Json } = {};
  for (const [name, child] of node.children) {
    if (isKeyedInst(child)) {
      const items: { [key: string]: Json } = {};
      for (const [key, item] of child.items) items[key] = parkNode(item);
      children[name] = { items };
    } else {
      children[name] = parkNode(child);
    }
  }
  return { v: node.iface.version, self: node.api.park(), children };
}

function disposeNode(node: NodeInst): void {
  for (const child of node.children.values()) {
    if (isKeyedInst(child)) {
      for (const item of child.items.values()) disposeNode(item);
      child.items.clear();
    } else {
      disposeNode(child);
    }
  }
  // Reverse order: later effects may depend on earlier ones.
  for (const dispose of node.disposers.reverse()) dispose();
  node.disposers.length = 0;
}

export async function boot<A extends Park, C extends Json>(
  impl: Impl<A, C>,
  iface: Iface<A, C>,
  context: Json,
  resources: Resources,
): Promise<Instance<A>> {
  const root = await bootNode(impl, iface, context, resources, "$");
  return {
    api: root.api as unknown as A,
    iface: iface as Iface<A, Json>,
    park: () => parkNode(root),
    dispose: () => disposeNode(root),
  };
}