@nanobpm/agentic 0.1.0

package/src/vocab/core-vocab.ts

@@ -0,0 +1,88 @@
+/**
+ * The opinionated core vocabulary.
+ *
+ * Ships working out of the box (S0 invariant 6): the standard agentic SDLC
+ * networks — `planning.*`, `qa.*`, `implementation.*`, `ci.*` — plus the bare
+ * `decide` role, each gated by an enrolment `requires` predicate and sized with
+ * seats. Authors EXTEND this in the SAME schema (see {@link mergeVocab}); there
+ * is no second schema for extensions.
+ *
+ * Seats & diversity: review roles carry two named seats `#red` / `#blue` with
+ * `seatsDistinctFamily: true` so the diversity SLO (S3) fails RED when both
+ * reviewers are the same family. Non-review roles leave `seatsDistinctFamily`
+ * off (warn-default): a same-family collision there is AMBER, not RED.
+ *
+ * Capability is NEVER in the token — `requires` is the registry gate, evaluated
+ * over the declared enrolment capability (cognition/weight/family/host).
+ */
+import type { VocabDocument } from "../protocol/index.ts";
+
+/** The current core-vocabulary artifact version. */
+export const CORE_VOCAB_VERSION = 1;
+
+/**
+ * The frozen core vocabulary document. Deep-frozen so a consumer cannot mutate
+ * the shared artifact; author extensions go through {@link mergeVocab}, which
+ * returns a fresh document.
+ */
+export const CORE_VOCAB: VocabDocument = deepFreeze({
+  version: CORE_VOCAB_VERSION,
+  networks: {
+    planning: {
+      roles: {
+        planner: { requires: ["cognition=planning"], weight: 5, seats: 1 },
+        reviewer: {
+          requires: ["cognition=planning"],
+          weight: 4,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+      },
+    },
+    qa: {
+      roles: {
+        tester: { requires: ["cognition=qa"], weight: 3, seats: 2 },
+        reviewer: {
+          requires: ["cognition=qa"],
+          weight: 3,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+      },
+    },
+    implementation: {
+      roles: {
+        senior: { requires: ["cognition=implementation", "weight>=4"], weight: 5, seats: 1 },
+        junior: { requires: ["cognition=implementation"], weight: 2, seats: 3 },
+        reviewer: {
+          requires: ["cognition=implementation"],
+          weight: 4,
+          seats: ["red", "blue"],
+          seatsDistinctFamily: true,
+        },
+      },
+    },
+    ci: {
+      roles: {
+        runner: { requires: ["cognition=ci"], weight: 1, seats: 1 },
+      },
+    },
+    // The bare `decide` role (single-segment token): a self-named top-level role
+    // the resolver collapses to the network-less token `decide`.
+    decide: {
+      roles: {
+        decide: { requires: ["cognition=decide"], weight: 5, seats: 1 },
+      },
+    },
+  },
+});
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/vocab/diversity.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { CORE_VOCAB } from "./core-vocab.ts";
+import {
+  computeDiversity,
+  correlateRegistry,
+  type RegisteredWorker,
+  type SeatAssignment,
+} from "./diversity.ts";
+import { VocabResolver } from "./resolver.ts";
+
+const resolver = new VocabResolver(CORE_VOCAB);
+
+function assignments(entries: Array<[string, SeatAssignment[]]>): Map<string, SeatAssignment[]> {
+  return new Map(entries);
+}
+
+test("green when distinct families fill a strict role's seats", () => {
+  const report = computeDiversity(
+    resolver,
+    assignments([
+      [
+        "planning.reviewer",
+        [
+          { seat: "red", family: "acme" },
+          { seat: "blue", family: "globex" },
+        ],
+      ],
+    ]),
+  );
+  assert.equal(report.status, "green");
+  assert.equal(report.roles[0]?.status, "green");
+  assert.deepEqual(report.roles[0]?.collidingFamilies, []);
+});
+
+test("red when a strict role's seats share a family", () => {
+  const report = computeDiversity(
+    resolver,
+    assignments([
+      [
+        "planning.reviewer",
+        [
+          { seat: "red", family: "acme" },
+          { seat: "blue", family: "acme" },
+        ],
+      ],
+    ]),
+  );
+  assert.equal(report.status, "red");
+  assert.equal(report.roles[0]?.status, "red");
+  assert.deepEqual(report.roles[0]?.collidingFamilies, ["acme"]);
+});
+
+test("amber when a warn-default role's seats share a family (no opt-in)", () => {
+  // qa.tester has 2 counted seats and does NOT opt into distinct families.
+  const report = computeDiversity(
+    resolver,
+    assignments([
+      [
+        "qa.tester",
+        [
+          { seat: "0", family: "acme" },
+          { seat: "1", family: "acme" },
+        ],
+      ],
+    ]),
+  );
+  assert.equal(report.status, "amber");
+  assert.equal(report.roles[0]?.status, "amber");
+});
+
+test("overall status is the worst across roles (red dominates amber)", () => {
+  const report = computeDiversity(
+    resolver,
+    assignments([
+      [
+        "qa.tester",
+        [
+          { seat: "0", family: "acme" },
+          { seat: "1", family: "acme" },
+        ],
+      ],
+      [
+        "planning.reviewer",
+        [
+          { seat: "red", family: "globex" },
+          { seat: "blue", family: "globex" },
+        ],
+      ],
+    ]),
+  );
+  assert.equal(report.status, "red");
+  assert.equal(report.roles.length, 2);
+  // roles are sorted by token
+  assert.equal(report.roles[0]?.token, "planning.reviewer");
+  assert.equal(report.roles[1]?.token, "qa.tester");
+});
+
+test("unknown tokens are ignored", () => {
+  const report = computeDiversity(
+    resolver,
+    assignments([["mystery.role", [{ seat: "red", family: "acme" }]]]),
+  );
+  assert.equal(report.status, "green");
+  assert.equal(report.roles.length, 0);
+});
+
+test("correlateRegistry seats registered workers and grades the live family mix", () => {
+  const workers: RegisteredWorker[] = [
+    { instance: "w-a", capability: { cognition: "planning", family: "acme" } },
+    { instance: "w-b", capability: { cognition: "planning", family: "acme" } },
+  ];
+  // Both planning workers share family "acme"; planning.reviewer is strict → red.
+  const report = correlateRegistry(resolver, workers);
+  const reviewer = report.roles.find((r) => r.token === "planning.reviewer");
+  assert.ok(reviewer !== undefined);
+  assert.equal(reviewer?.status, "red");
+  assert.equal(report.status, "red");
+});
+
+test("correlateRegistry is green when distinct families cover the review seats", () => {
+  const workers: RegisteredWorker[] = [
+    { instance: "w-a", capability: { cognition: "planning", family: "acme" } },
+    { instance: "w-b", capability: { cognition: "planning", family: "globex" } },
+  ];
+  const report = correlateRegistry(resolver, workers);
+  const reviewer = report.roles.find((r) => r.token === "planning.reviewer");
+  assert.equal(reviewer?.status, "green");
+});
+
+test("correlateRegistry skips workers with no declared family", () => {
+  const workers: RegisteredWorker[] = [
+    { instance: "w-a", capability: { cognition: "planning" } },
+    { instance: "w-b", capability: { cognition: "planning" } },
+  ];
+  const report = correlateRegistry(resolver, workers);
+  assert.equal(report.status, "green");
+  assert.equal(report.roles.length, 0);
+});
+
+test("correlateRegistry seats deterministically by instance id", () => {
+  const workers: RegisteredWorker[] = [
+    { instance: "w-b", capability: { cognition: "planning", family: "globex" } },
+    { instance: "w-a", capability: { cognition: "planning", family: "acme" } },
+  ];
+  const report = correlateRegistry(resolver, workers);
+  const reviewer = report.roles.find((r) => r.token === "planning.reviewer");
+  // Sorted by instance: w-a(acme)->red, w-b(globex)->blue.
+  assert.deepEqual(reviewer?.assignments, [
+    { seat: "red", family: "acme", instance: "w-a" },
+    { seat: "blue", family: "globex", instance: "w-b" },
+  ]);
+});

package/src/vocab/diversity.ts

@@ -0,0 +1,169 @@
+/**
+ * The diversity SLO — `family(#red) ≠ family(#blue)`.
+ *
+ * A role may declare `seatsDistinctFamily: true` (STRICT opt-in) to require its
+ * seats be filled by distinct families. The SLO grades an assignment of seats to
+ * families red / amber / green:
+ *
+ *  - GREEN  — no role has two seats sharing a family.
+ *  - AMBER  — a same-family collision on a WARN-DEFAULT role (one that did NOT
+ *             opt into `seatsDistinctFamily`): tolerated, but surfaced.
+ *  - RED    — a same-family collision on a STRICT role (`seatsDistinctFamily`):
+ *             an SLO violation.
+ *
+ * Warn-default is the point of the "strict opt-in per role": every role wants
+ * family diversity, but only a role that opts in makes a collision RED; elsewhere
+ * a collision is an AMBER warning, never a hard failure.
+ *
+ * The assignment can be given explicitly (seat→family) or CORRELATED from the S2
+ * presence registry: {@link correlateRegistry} resolves each registered worker's
+ * capability to the roles it may fill and seats them deterministically, so the
+ * live registry's family mix is graded against the same SLO.
+ */
+import type { Capability } from "../protocol/index.ts";
+import type { ResolvedRole, VocabResolver } from "./resolver.ts";
+
+export type DiversityStatus = "green" | "amber" | "red";
+
+/** One seat of a role filled by a worker of a given family. */
+export interface SeatAssignment {
+  /** The seat label (named seat, or a synthesised index for counted seats). */
+  readonly seat: string;
+  /** The enrolment family occupying the seat. */
+  readonly family: string;
+  /** The worker instance occupying the seat, when known (registry correlation). */
+  readonly instance?: string;
+}
+
+/** The diversity grade for a single role. */
+export interface RoleDiversity {
+  /** The role's routing token. */
+  readonly token: string;
+  /** Whether the role opted into strict distinct-family seating. */
+  readonly seatsDistinctFamily: boolean;
+  /** The seats considered, in seat order. */
+  readonly assignments: readonly SeatAssignment[];
+  /** Families that fill more than one seat of this role (the collisions). */
+  readonly collidingFamilies: readonly string[];
+  /** This role's grade. */
+  readonly status: DiversityStatus;
+}
+
+/** The overall diversity report across every graded role. */
+export interface DiversityReport {
+  /** The worst grade across all roles (red > amber > green). */
+  readonly status: DiversityStatus;
+  /** Per-role grades, sorted by token. */
+  readonly roles: readonly RoleDiversity[];
+}
+
+const SEVERITY: Record<DiversityStatus, number> = { green: 0, amber: 1, red: 2 };
+
+function worst(a: DiversityStatus, b: DiversityStatus): DiversityStatus {
+  return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+
+function collidingFamilies(assignments: readonly SeatAssignment[]): string[] {
+  const counts = new Map<string, number>();
+  for (const { family } of assignments) {
+    counts.set(family, (counts.get(family) ?? 0) + 1);
+  }
+  const colliding: string[] = [];
+  for (const [family, count] of counts) {
+    if (count > 1) colliding.push(family);
+  }
+  colliding.sort();
+  return colliding;
+}
+
+function gradeRole(role: ResolvedRole, assignments: readonly SeatAssignment[]): RoleDiversity {
+  const colliding = collidingFamilies(assignments);
+  const status: DiversityStatus =
+    colliding.length === 0 ? "green" : role.seatsDistinctFamily ? "red" : "amber";
+  return {
+    token: role.token,
+    seatsDistinctFamily: role.seatsDistinctFamily,
+    assignments,
+    collidingFamilies: colliding,
+    status,
+  };
+}
+
+/**
+ * Grade an explicit seat assignment. `assignments` maps a role's routing token
+ * to the families seated in it. Only roles known to the resolver are graded; an
+ * unknown token is ignored (there is nothing to grade it against).
+ */
+export function computeDiversity(
+  resolver: VocabResolver,
+  assignments: ReadonlyMap<string, readonly SeatAssignment[]>,
+): DiversityReport {
+  const roles: RoleDiversity[] = [];
+  let status: DiversityStatus = "green";
+  for (const [token, seatAssignments] of assignments) {
+    const role = resolver.roleForToken(token);
+    if (role === undefined) continue;
+    const graded = gradeRole(role, seatAssignments);
+    roles.push(graded);
+    status = worst(status, graded.status);
+  }
+  roles.sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+  return { status, roles };
+}
+
+/** A registered worker as seen on the S2 presence registry (structural). */
+export interface RegisteredWorker {
+  /** The worker instance id. */
+  readonly instance: string;
+  /** The declared enrolment capability (its `family` fills a seat). */
+  readonly capability: Capability;
+}
+
+/** Seat labels for a role: its named seats, or synthesised `0..n-1` for a count. */
+function seatLabels(role: ResolvedRole): string[] {
+  if (typeof role.seats === "number") {
+    return Array.from({ length: role.seats }, (_unused, index) => String(index));
+  }
+  return [...role.seats];
+}
+
+/**
+ * Correlate the live S2 registry against the vocab and grade its diversity.
+ *
+ * Each registered worker is resolved to the roles it may fill; for every role,
+ * the workers that qualify are seated deterministically (sorted by instance)
+ * into the role's seats, and the resulting family mix is graded by
+ * {@link computeDiversity}. Workers with no declared family, and roles with no
+ * qualifying worker, are skipped. Overflow workers beyond a role's seat count do
+ * not take a seat (they are surplus supply, not a diversity collision).
+ */
+export function correlateRegistry(
+  resolver: VocabResolver,
+  workers: readonly RegisteredWorker[],
+): DiversityReport {
+  const sorted = [...workers].sort((a, b) => (a.instance < b.instance ? -1 : a.instance > b.instance ? 1 : 0));
+  // Resolve each worker's SERVE token set once (O(workers)) so per-role seating
+  // is a membership check, not a repeated resolve — correlation stays O(workers × roles).
+  const workerTokens = sorted.map((worker) => new Set(resolver.resolve(worker.capability).tokens));
+  const perRole = new Map<string, SeatAssignment[]>();
+
+  for (const role of resolver.roles()) {
+    const seats = seatLabels(role);
+    if (seats.length === 0) continue;
+    const qualifying = sorted.filter(
+      (worker, index) => worker.capability.family !== undefined && workerTokens[index].has(role.token),
+    );
+    const assignments: SeatAssignment[] = [];
+    for (let index = 0; index < seats.length && index < qualifying.length; index += 1) {
+      const worker = qualifying[index];
+      const family = worker.capability.family;
+      if (family === undefined) continue;
+      assignments.push({ seat: seats[index], family, instance: worker.instance });
+    }
+    if (assignments.length > 0) {
+      perRole.set(role.token, assignments);
+    }
+  }
+
+  return computeDiversity(resolver, perRole);
+}

package/src/vocab/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @nanobpm/agentic-vocab — the vocab resolver & core vocabulary for the Nano
+ * agentic protocol (ADR 0056, slice S3).
+ *
+ * Turns the versioned vocab artifact (the ONE capability→token map) into the
+ * REGISTER→SERVE handshake: a declared enrolment capability resolves to a
+ * deterministic SERVE token set ({@link VocabResolver}); the opinionated core
+ * vocabulary ships working out of the box ({@link CORE_VOCAB}); authors extend it
+ * in the same schema ({@link mergeVocab}); and the diversity SLO grades seating
+ * red / amber / green ({@link computeDiversity} / {@link correlateRegistry}).
+ *
+ * The wire contract (family set, token grammar, vocab schema, `serve` payload)
+ * lives in `@nanobpm/agentic-protocol`; this package builds on it and never
+ * redefines it. Capability is NEVER in the routing token — it is the enrolment
+ * attribute the `requires` gate reads.
+ */
+export {
+  VocabResolver,
+  VocabDocumentError,
+  type Resolution,
+  type ResolvedRole,
+} from "./resolver.ts";
+
+export { CORE_VOCAB, CORE_VOCAB_VERSION } from "./core-vocab.ts";
+
+export { mergeVocab } from "./merge.ts";
+
+export {
+  REQUIRES_FIELDS,
+  RequiresParseError,
+  parseRequires,
+  parseRequiresList,
+  satisfiesRequires,
+  satisfiesPredicate,
+  type RequiresField,
+  type RequiresOp,
+  type RequiresPredicate,
+} from "./requires.ts";
+
+export {
+  computeDiversity,
+  correlateRegistry,
+  type DiversityStatus,
+  type DiversityReport,
+  type RoleDiversity,
+  type SeatAssignment,
+  type RegisteredWorker,
+} from "./diversity.ts";
+
+export {
+  buildServePayload,
+  buildServeFrame,
+  serveCapability,
+  type ServeSink,
+} from "./serve.ts";

package/src/vocab/merge.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { CORE_VOCAB } from "./core-vocab.ts";
+import { mergeVocab } from "./merge.ts";
+import { VocabDocumentError, VocabResolver } from "./resolver.ts";
+
+test("an author extension adds a new network without disturbing the core", () => {
+  const merged = mergeVocab({
+    version: 1,
+    networks: { research: { roles: { scout: { requires: ["cognition=research"], seats: 2 } } } },
+  });
+  const resolver = new VocabResolver(merged);
+  assert.ok(resolver.tokens().includes("research.scout"));
+  // Core roles survive intact.
+  assert.ok(resolver.tokens().includes("planning.planner"));
+  assert.ok(resolver.tokens().includes("decide"));
+});
+
+test("an extension retunes a single role field, leaving the rest", () => {
+  const merged = mergeVocab({
+    version: 1,
+    networks: { implementation: { roles: { junior: { weight: 9 } } } },
+  });
+  const resolver = new VocabResolver(merged);
+  const junior = resolver.roleForToken("implementation.junior");
+  assert.equal(junior?.weight, 9, "extension weight wins");
+  // The core requires/seats on junior are preserved (not clobbered).
+  assert.deepEqual(junior?.seats, 3);
+  const light = resolver.resolve({ cognition: "implementation", weight: 2 });
+  assert.ok(light.tokens.includes("implementation.junior"), "core requires gate preserved");
+});
+
+test("an extension can add a seatsDistinctFamily opt-in to an existing role", () => {
+  const merged = mergeVocab({
+    version: 1,
+    networks: { qa: { roles: { tester: { seats: ["red", "blue"], seatsDistinctFamily: true } } } },
+  });
+  const tester = new VocabResolver(merged).roleForToken("qa.tester");
+  assert.equal(tester?.seatsDistinctFamily, true);
+  assert.deepEqual(tester?.seats, ["red", "blue"]);
+});
+
+test("version becomes the max of base and extension", () => {
+  assert.equal(mergeVocab({ version: 7, networks: {} }).version, Math.max(CORE_VOCAB.version, 7));
+  assert.equal(mergeVocab({ version: 1, networks: {} }).version, CORE_VOCAB.version);
+});
+
+test("merge does not mutate either input", () => {
+  const before = JSON.stringify(CORE_VOCAB);
+  const ext = { version: 1, networks: { x: { roles: { y: {} } } } };
+  const extBefore = JSON.stringify(ext);
+  mergeVocab(ext);
+  assert.equal(JSON.stringify(CORE_VOCAB), before, "core vocab untouched");
+  assert.equal(JSON.stringify(ext), extBefore, "extension untouched");
+});
+
+test("merge over an explicit base merges recursively into subnetworks", () => {
+  const base = JSON.parse(
+    '{"version":1,"networks":{"net":{"subnetworks":{"sub":{"roles":{"a":{"weight":1}}}}}}}',
+  );
+  const merged = mergeVocab(
+    { version: 1, networks: { net: { subnetworks: { sub: { roles: { b: { weight: 2 } } } } } } },
+    base,
+  );
+  const tokens = new VocabResolver(merged).tokens();
+  assert.ok(tokens.includes("net.sub.a"));
+  assert.ok(tokens.includes("net.sub.b"));
+});
+
+test("merge rejects an invalid extension", () => {
+  const bad = JSON.parse('{"version":1,"networks":{"Bad Name":{}}}');
+  assert.throws(() => mergeVocab(bad), VocabDocumentError);
+});

package/src/vocab/merge.ts

@@ -0,0 +1,117 @@
+/**
+ * Author-extension merge — extend the core vocabulary in the SAME schema.
+ *
+ * Authors do not get a second schema for extensions (S0 invariant 6): they hand
+ * a {@link VocabDocument} in the exact core shape and {@link mergeVocab} deep-
+ * merges it over a base (the {@link CORE_VOCAB} by default). The merge is
+ * structural and deterministic:
+ *
+ *  - networks / subnetworks are merged recursively (union of names);
+ *  - a role present in both is merged field-by-field, the extension winning per
+ *    field, so an author can retune one attribute (e.g. bump `weight` or add a
+ *    `seatsDistinctFamily`) without restating the whole role;
+ *  - a role/network present only in the extension is added;
+ *  - `version` becomes the MAX of the two, so an extension can advance it.
+ *
+ * The merged document is re-validated against the S0 schema and returned fresh —
+ * neither input is mutated, and a merge that produces an invalid artifact throws
+ * {@link VocabDocumentError} rather than yielding a subtly broken vocab.
+ */
+import { validateVocabDocument } from "../protocol/index.ts";
+import type { VocabDocument, VocabNetwork, VocabRole } from "../protocol/index.ts";
+import { CORE_VOCAB } from "./core-vocab.ts";
+import { VocabDocumentError } from "./resolver.ts";
+
+function mergeRole(base: VocabRole, ext: VocabRole): VocabRole {
+  const merged: {
+    requires?: readonly string[];
+    weight?: number;
+    seats?: number | readonly string[];
+    seatsDistinctFamily?: boolean;
+  } = {};
+  const requires = ext.requires ?? base.requires;
+  if (requires !== undefined) merged.requires = [...requires];
+  const weight = ext.weight ?? base.weight;
+  if (weight !== undefined) merged.weight = weight;
+  const seats = ext.seats ?? base.seats;
+  if (seats !== undefined) merged.seats = typeof seats === "number" ? seats : [...seats];
+  const seatsDistinctFamily = ext.seatsDistinctFamily ?? base.seatsDistinctFamily;
+  if (seatsDistinctFamily !== undefined) merged.seatsDistinctFamily = seatsDistinctFamily;
+  return merged;
+}
+
+const EMPTY_ROLE: VocabRole = {};
+
+function cloneRole(role: VocabRole): VocabRole {
+  return mergeRole(EMPTY_ROLE, role);
+}
+
+function mergeRoles(
+  base: Readonly<Record<string, VocabRole>> | undefined,
+  ext: Readonly<Record<string, VocabRole>> | undefined,
+): Record<string, VocabRole> | undefined {
+  if (base === undefined && ext === undefined) return undefined;
+  const out: Record<string, VocabRole> = {};
+  for (const [name, role] of Object.entries(base ?? {})) {
+    out[name] = cloneRole(role);
+  }
+  for (const [name, role] of Object.entries(ext ?? {})) {
+    const existing = out[name];
+    out[name] = existing === undefined ? cloneRole(role) : mergeRole(existing, role);
+  }
+  return out;
+}
+
+function mergeNetwork(base: VocabNetwork | undefined, ext: VocabNetwork): VocabNetwork {
+  const roles = mergeRoles(base?.roles, ext.roles);
+  const subnetworks = mergeNetworks(base?.subnetworks, ext.subnetworks);
+  const merged: { roles?: Record<string, VocabRole>; subnetworks?: Record<string, VocabNetwork> } = {};
+  if (roles !== undefined) merged.roles = roles;
+  if (subnetworks !== undefined) merged.subnetworks = subnetworks;
+  return merged;
+}
+
+function mergeNetworks(
+  base: Readonly<Record<string, VocabNetwork>> | undefined,
+  ext: Readonly<Record<string, VocabNetwork>> | undefined,
+): Record<string, VocabNetwork> | undefined {
+  if (base === undefined && ext === undefined) return undefined;
+  const out: Record<string, VocabNetwork> = {};
+  for (const [name, network] of Object.entries(base ?? {})) {
+    out[name] = mergeNetwork(undefined, network);
+  }
+  for (const [name, network] of Object.entries(ext ?? {})) {
+    out[name] = mergeNetwork(out[name], network);
+  }
+  return out;
+}
+
+/**
+ * Merge an author `extension` over a `base` vocab (default {@link CORE_VOCAB}),
+ * returning a fresh, re-validated {@link VocabDocument}.
+ *
+ * @throws VocabDocumentError if either input or the merged result is not a valid
+ *   vocab artifact.
+ */
+export function mergeVocab(extension: VocabDocument, base: VocabDocument = CORE_VOCAB): VocabDocument {
+  for (const [label, doc] of [
+    ["base", base],
+    ["extension", extension],
+  ] as const) {
+    const check = validateVocabDocument(doc);
+    if (!check.ok) {
+      throw new VocabDocumentError(check.errors.map((e) => ({ path: `${label}:${e.path}`, message: e.message })));
+    }
+  }
+
+  const merged = {
+    version: Math.max(base.version, extension.version),
+    networks: mergeNetworks(base.networks, extension.networks) ?? {},
+  };
+
+  const result = validateVocabDocument(merged);
+  if (!result.ok) {
+    throw new VocabDocumentError(result.errors.map((e) => ({ path: `merged:${e.path}`, message: e.message })));
+  }
+  return result.value;
+}