Skip to content

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

11.8 KB
Raw Blame
/**
 * The module-tree check: manifests + interface table in, problems out. Nothing here
 * executes module code, so it runs on the sending side of a push (against the target's
 * published table), at boot (before any create), and in CI.
 *
 * Three questions, per module:
 *   1. every `requires` resolves to a visible module whose provided interface
 *      structurally satisfies the required one ({@link satisfies});
 *   2. every contribution names an existing `<module>.<slot>` and parses under that
 *      slot's data schema;
 *   3. every `provides` names an interface the table actually carries.
 *
 * Visibility is lexical: a module sees its siblings, its ancestors and their siblings —
 * not another subtree's internals, and not itself. Anything the host publishes (the
 * runtime's capabilities) is visible everywhere, as a virtual root-level sibling.
 *
 * Ancestors are visible to CONTRIBUTE to (a child fills its parent's slots), not to
 * REQUIRE from: a parent is created after its children, so its api does not exist when
 * a child is created. The booter orders it so; the check refuses the requirement here,
 * before any code runs, rather than letting it surface as a dependency cycle at boot.
 */
import { type } from "arktype";
import type { Json } from "./json.js";
import type { IfaceDecl, TableLike } from "./sig.js";
import { satisfies, tableOf } from "./sig.js";
import type { Manifest } from "./manifest.js";
import { ifaceKey, splitSlotKey } from "./manifest.js";

/** A manifest and its children, as the tree is declared. */
export interface ManifestNode {
  manifest: Manifest;
  children: ManifestNode[];
}

/** What the host publishes: modules with provided interfaces, no manifests of their own. */
export type Published = Record<string /* module name */, Record<string /* alias */, IfaceDecl>>;

export type Problem =
  | { path: string; kind: "unresolved"; alias: string; from: string; why: string }
  | { path: string; kind: "mismatch"; alias: string; from: string; method: string; why: string }
  | { path: string; kind: "unknown-iface"; alias: string; ref: string }
  | { path: string; kind: "no-such-slot"; slotKey: string }
  | { path: string; kind: "bad-contribution"; slotKey: string; id: string; why: string }
  | { path: string; kind: "duplicate-id"; id: string; other: string }
  | { path: string; kind: "duplicate-module"; name: string; other: string };

interface Located {
  path: string;
  manifest: Manifest;
  /** Module names this module may wire to or contribute to. */
  visible: Set<string>;
  /** Module names above this one — never a provider for it (their exports face outward). */
  ancestors: Set<string>;
}

/** Provided interfaces of a module, by alias, resolved through the table. */
function provided(
  manifest: Manifest,
  table: TableLike,
): { byAlias: Record<string, IfaceDecl>; unknown: Array<{ alias: string; ref: string }> } {
  const byAlias: Record<string, IfaceDecl> = {};
  const unknown: Array<{ alias: string; ref: string }> = [];
  for (const [alias, ref] of Object.entries(manifest.provides)) {
    const decl = tableOf(table).ifaces[ifaceKey(manifest.name, ref)];
    if (decl === undefined) unknown.push({ alias, ref });
    else byAlias[alias] = decl;
  }
  return { byAlias, unknown };
}

function locate(root: ManifestNode): Located[] {
  const out: Located[] = [];
  const walk = (node: ManifestNode, path: string, inherited: string[], above: string[]) => {
    const siblings = node.children.map((c) => c.manifest.name);
    const ancestors = new Set([...above, node.manifest.name]);
    for (const child of node.children) {
      const childPath = `${path}/${child.manifest.name}`;
      const visible = new Set([...inherited, node.manifest.name, ...siblings]);
      out.push({ path: childPath, manifest: child.manifest, visible, ancestors });
      walk(child, childPath, [...inherited, node.manifest.name, ...siblings], [...ancestors]);
    }
  };
  out.push({
    path: `/${root.manifest.name}`,
    manifest: root.manifest,
    visible: new Set(),
    ancestors: new Set(),
  });
  walk(root, `/${root.manifest.name}`, [], []);
  return out;
}

export interface CheckResult {
  problems: Problem[];
  /** Module name → its provided interfaces by alias (the tree's own plus the published). */
  provides: Record<string, Record<string, IfaceDecl>>;
}

export function checkTree(
  root: ManifestNode,
  table: TableLike,
  published: Published = {},
): CheckResult {
  const problems: Problem[] = [];
  const located = locate(root);
  const byName = new Map<string, Located>();
  for (const m of located) {
    const other = byName.get(m.manifest.name);
    if (other !== undefined) {
      problems.push({
        path: m.path,
        kind: "duplicate-module",
        name: m.manifest.name,
        other: other.path,
      });
      continue;
    }
    byName.set(m.manifest.name, m);
  }
  const provides: Record<string, Record<string, IfaceDecl>> = { ...published };
  for (const m of byName.values()) {
    const { byAlias, unknown } = provided(m.manifest, table);
    for (const u of unknown) problems.push({ path: m.path, kind: "unknown-iface", ...u });
    provides[m.manifest.name] = byAlias;
  }
  const ids = new Map<string, string>();
  for (const m of byName.values()) {
    const mf = m.manifest;
    for (const [alias, need] of Object.entries(mf.requires)) {
      const required = tableOf(table).ifaces[ifaceKey(mf.name, need.iface)];
      if (required === undefined) {
        problems.push({ path: m.path, kind: "unknown-iface", alias, ref: need.iface });
        continue;
      }
      const requirable = (from: string) =>
        (m.visible.has(from) && !m.ancestors.has(from)) || from in published;
      const candidates =
        need.from !== undefined
          ? [need.from]
          : [...m.visible, ...Object.keys(published)].filter(
              (name) => name !== mf.name && !m.ancestors.has(name),
            );
      const matches: string[] = [];
      // Providers that DECLARE this very interface (the same table entry): when exactly
      // one does, it wins over the others that merely have the shape.
      const declared: string[] = [];
      let lastMismatch: { from: string; method: string; why: string } | null = null;
      for (const from of candidates) {
        if (!requirable(from)) continue;
        const offered = provides[from];
        if (offered === undefined) continue;
        let satisfied = false;
        for (const decl of Object.values(offered)) {
          const gaps = satisfies(decl, required, table);
          if (gaps.length === 0) {
            satisfied = true;
            if (decl === required) declared.push(from);
            continue;
          }
          lastMismatch = { from, method: gaps[0]!.method, why: gaps[0]!.why };
        }
        if (satisfied) matches.push(from);
      }
      if (matches.length === 1 || declared.length === 1) continue;
      if (need.from !== undefined) {
        const from = need.from;
        if (!requirable(from) || provides[from] === undefined) {
          problems.push({
            path: m.path,
            kind: "unresolved",
            alias,
            from,
            why: m.ancestors.has(from)
              ? "an ancestor — created after its children, so its api is not there yet"
              : from === mf.name
                ? "itself"
                : byName.has(from)
                  ? "not visible from here"
                  : "no such module",
          });
        } else if (lastMismatch !== null) {
          problems.push({ path: m.path, kind: "mismatch", alias, ...lastMismatch });
        } else {
          problems.push({ path: m.path, kind: "unresolved", alias, from, why: "provides nothing" });
        }
      } else {
        problems.push({
          path: m.path,
          kind: "unresolved",
          alias,
          from: "",
          why:
            matches.length === 0
              ? "no visible module provides an interface satisfying it"
              : `ambiguous: ${matches.join(", ")} all satisfy it — name one with 'from'`,
        });
      }
    }
    for (const [slotKey, entries] of Object.entries(mf.contributes)) {
      const split = splitSlotKey(slotKey);
      const target = split === null ? undefined : provides[split.module];
      const slot =
        split === null || target === undefined
          ? undefined
          : Object.values(target)
              .map((decl) => decl.slots[split.slot])
              .find((s) => s !== undefined);
      if (slot === undefined) {
        problems.push({ path: m.path, kind: "no-such-slot", slotKey });
        continue;
      }
      let schema: ((v: unknown) => unknown) | null = null;
      try {
        schema = slotSchema(inlineRefs(slot.data, tableOf(table).types));
      } catch (err) {
        problems.push({
          path: m.path,
          kind: "bad-contribution",
          slotKey,
          id: "*",
          why: `slot schema is not an arktype definition: ${err instanceof Error ? err.message : String(err)}`,
        });
        continue;
      }
      for (const entry of entries) {
        const other = ids.get(entry.id);
        if (other !== undefined) {
          problems.push({ path: m.path, kind: "duplicate-id", id: entry.id, other });
        } else {
          ids.set(entry.id, m.path);
        }
        const { id: _id, ...data } = entry;
        const out = schema(data);
        if (out instanceof type.errors) {
          problems.push({
            path: m.path,
            kind: "bad-contribution",
            slotKey,
            id: entry.id,
            why: out.summary,
          });
        }
      }
    }
  }
  return { problems, provides };
}

/**
 * A slot's contribution schema, parsed once per definition. arktype files every parse in a
 * registry that lives as long as the process and never shrinks, and every boot checks every
 * contribution: parsed afresh, each boot grew it (see leafExtends in ./data.ts).
 */
const slotSchemas = new Map<string, (v: unknown) => unknown>();

function slotSchema(def: Json): (v: unknown) => unknown {
  const key = JSON.stringify(def);
  let schema = slotSchemas.get(key);
  if (schema === undefined) {
    schema = type.raw(def).onUndeclaredKey("reject");
    slotSchemas.set(key, schema);
  }
  return schema;
}

/** A definition with its `$ref`s substituted, for arktype (which knows no references); a cycle stays a reference and parses as `unknown`. */
export function inlineRefs(def: Json, types: Record<string, Json>, stack: string[] = []): Json {
  if (Array.isArray(def)) return def.map((d) => inlineRefs(d, types, stack));
  if (def !== null && typeof def === "object") {
    const keys = Object.keys(def);
    if (keys.length === 1 && keys[0] === "$ref" && typeof def.$ref === "string") {
      const name = def.$ref;
      const target = types[name];
      if (target === undefined || stack.includes(name)) return "unknown";
      return inlineRefs(target, types, [...stack, name]);
    }
    return Object.fromEntries(
      Object.entries(def).map(([k, v]) => [k, inlineRefs(v, types, stack)]),
    );
  }
  return def;
}

export function describeProblem(p: Problem): string {
  switch (p.kind) {
    case "unresolved":
      return `${p.path}: requires.${p.alias}${p.from ? ` from '${p.from}'` : ""}: ${p.why}`;
    case "mismatch":
      return `${p.path}: requires.${p.alias} from '${p.from}': ${p.method}: ${p.why}`;
    case "unknown-iface":
      return `${p.path}: '${p.alias}' names interface '${p.ref}', which the table does not carry`;
    case "no-such-slot":
      return `${p.path}: contributes to '${p.slotKey}', which no visible module declares`;
    case "bad-contribution":
      return `${p.path}: contribution '${p.id}' to '${p.slotKey}': ${p.why}`;
    case "duplicate-id":
      return `${p.path}: contribution id '${p.id}' is already used by ${p.other}`;
    case "duplicate-module":
      return `${p.path}: module name '${p.name}' is already used by ${p.other}`;
  }
}