@nanobpm/agentic 0.1.0

package/src/protocol/lanes.test.ts

@@ -0,0 +1,82 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  MESSAGE_FAMILIES,
+  FAMILY_CODES,
+  familyForCode,
+  isMessageFamily,
+} from "./families.ts";
+import {
+  QOS_LANES,
+  LANE_CODES,
+  laneForCode,
+  lanePriority,
+  isQosLane,
+  compareFrameOrder,
+  type QosLane,
+} from "./lanes.ts";
+
+test("MESSAGE_FAMILIES is the exact canonical set", () => {
+  assert.deepEqual(
+    [...MESSAGE_FAMILIES],
+    ["register", "heartbeat", "deregister", "serve", "demand", "blackboard", "relay"],
+  );
+});
+
+test("family codes are a bijection with the family set", () => {
+  const codes = MESSAGE_FAMILIES.map((f) => FAMILY_CODES[f]);
+  assert.equal(new Set(codes).size, MESSAGE_FAMILIES.length, "codes must be unique");
+  for (const family of MESSAGE_FAMILIES) {
+    assert.equal(familyForCode(FAMILY_CODES[family]), family);
+  }
+});
+
+test("isMessageFamily gates unknown values", () => {
+  assert.ok(isMessageFamily("relay"));
+  assert.ok(!isMessageFamily("gossip"));
+  assert.ok(!isMessageFamily(4));
+});
+
+test("familyForCode returns undefined for unknown codes", () => {
+  assert.equal(familyForCode(99), undefined);
+});
+
+test("QOS_LANES are in strict priority order control > interactive > bulk", () => {
+  assert.deepEqual([...QOS_LANES], ["control", "interactive", "bulk"]);
+  assert.ok(lanePriority("control") < lanePriority("interactive"));
+  assert.ok(lanePriority("interactive") < lanePriority("bulk"));
+});
+
+test("lane codes are a bijection with the lane set", () => {
+  for (const lane of QOS_LANES) {
+    assert.equal(laneForCode(LANE_CODES[lane]), lane);
+  }
+  assert.equal(laneForCode(9), undefined);
+});
+
+test("isQosLane gates unknown values", () => {
+  assert.ok(isQosLane("bulk"));
+  assert.ok(!isQosLane("urgent"));
+});
+
+test("compareFrameOrder: a bulk storm never head-of-line-blocks control/interactive", () => {
+  // A queue where a bulk storm is enqueued first, then a single control
+  // heartbeat and an interactive blackboard write. Draining by the scheduler
+  // ordering MUST surface control first, interactive second, bulk last —
+  // regardless of enqueue order or seq.
+  const queue: Array<{ lane: QosLane; seq: number; tag: string }> = [
+    { lane: "bulk", seq: 1, tag: "bulk-a" },
+    { lane: "bulk", seq: 2, tag: "bulk-b" },
+    { lane: "bulk", seq: 3, tag: "bulk-c" },
+    { lane: "control", seq: 50, tag: "heartbeat" },
+    { lane: "interactive", seq: 40, tag: "blackboard" },
+    { lane: "bulk", seq: 0, tag: "bulk-d" },
+  ];
+  const drained = [...queue].sort(compareFrameOrder).map((f) => f.tag);
+  assert.deepEqual(drained, ["heartbeat", "blackboard", "bulk-d", "bulk-a", "bulk-b", "bulk-c"]);
+});
+
+test("compareFrameOrder: within a lane, lower seq drains first", () => {
+  assert.ok(compareFrameOrder({ lane: "bulk", seq: 1 }, { lane: "bulk", seq: 2 }) < 0);
+  assert.equal(compareFrameOrder({ lane: "bulk", seq: 5 }, { lane: "bulk", seq: 5 }), 0);
+});

package/src/protocol/lanes.ts

@@ -0,0 +1,54 @@
+/**
+ * The three QoS lanes carried on the one agentic channel, in STRICT priority
+ * order: control/facts > interactive > bulk.
+ *
+ * The ordering is the contract: a bulk-output storm (relay chunks) must never
+ * head-of-line-block a heartbeat or a blackboard write. The scheduler that
+ * enforces this lives in S5; this module owns the canonical lane set, their
+ * wire codes, and the priority comparison every scheduler derives from.
+ */
+export const QOS_LANES = ["control", "interactive", "bulk"] as const;
+
+export type QosLane = (typeof QOS_LANES)[number];
+
+const LANE_SET: ReadonlySet<string> = new Set(QOS_LANES);
+
+export function isQosLane(value: unknown): value is QosLane {
+  return typeof value === "string" && LANE_SET.has(value);
+}
+
+/**
+ * On-wire lane codes. The numeric value is also the priority rank: a LOWER
+ * code is HIGHER priority (control=0 outranks bulk=2). Do not renumber.
+ */
+export const LANE_CODES = {
+  control: 0,
+  interactive: 1,
+  bulk: 2,
+} as const satisfies Record<QosLane, number>;
+
+const CODE_TO_LANE: ReadonlyMap<number, QosLane> = new Map(
+  QOS_LANES.map((lane) => [LANE_CODES[lane], lane]),
+);
+
+export function laneForCode(code: number): QosLane | undefined {
+  return CODE_TO_LANE.get(code);
+}
+
+/** Priority rank of a lane; lower is dispatched first. */
+export function lanePriority(lane: QosLane): number {
+  return LANE_CODES[lane];
+}
+
+/**
+ * Canonical scheduler ordering derived from the lane priorities: control before
+ * interactive before bulk, ties broken by ascending `seq` so a single lane
+ * drains in emission order. Returns <0 when `a` should be dispatched before `b`.
+ */
+export function compareFrameOrder(
+  a: { readonly lane: QosLane; readonly seq: number },
+  b: { readonly lane: QosLane; readonly seq: number },
+): number {
+  const byLane = lanePriority(a.lane) - lanePriority(b.lane);
+  return byLane !== 0 ? byLane : a.seq - b.seq;
+}

package/src/protocol/payloads.test.ts

@@ -0,0 +1,91 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { validatePayload } from "./payloads.ts";
+import { GOLDEN_FRAMES } from "./conformance/frames.ts";
+
+test("every golden frame payload satisfies its family contract", () => {
+  for (const golden of GOLDEN_FRAMES) {
+    // The null-payload envelope frame is a codec-level fixture, not a valid
+    // family payload; skip it for the payload-contract check.
+    if (golden.frame.payload === null) continue;
+    const result = validatePayload(golden.frame.family, golden.frame.payload);
+    assert.ok(
+      result.ok,
+      `${golden.name}: ${result.ok ? "" : JSON.stringify(result.errors)}`,
+    );
+  }
+});
+
+test("register requires a non-empty instance and a capability object", () => {
+  assert.ok(validatePayload("register", { instance: "w", capability: {} }).ok);
+  assert.ok(!validatePayload("register", { instance: "", capability: {} }).ok);
+  assert.ok(!validatePayload("register", { instance: "w" }).ok);
+  assert.ok(!validatePayload("register", { instance: "w", capability: "opus" }).ok);
+});
+
+test("register validates known capability field types when present", () => {
+  assert.ok(
+    validatePayload("register", {
+      instance: "w",
+      capability: { cognition: "reason", weight: 3, family: "opus", host: "h1" },
+    }).ok,
+  );
+  for (const capability of [
+    { weight: "3" },
+    { cognition: 1 },
+    { family: true },
+    { host: 0 },
+  ]) {
+    const bad = validatePayload("register", { instance: "w", capability });
+    assert.ok(!bad.ok, JSON.stringify(capability));
+    if (!bad.ok) assert.ok(bad.errors.some((e) => e.code === "bad-capability"));
+  }
+});
+
+test("serve rejects an invalid routing token in tokens[]", () => {
+  assert.ok(validatePayload("serve", { instance: "w", tokens: ["planning.decide"] }).ok);
+  const bad = validatePayload("serve", { instance: "w", tokens: ["Bad Token"] });
+  assert.ok(!bad.ok);
+  if (!bad.ok) assert.ok(bad.errors.some((e) => e.code === "bad-token"));
+});
+
+test("blackboard op must be append or read", () => {
+  assert.ok(validatePayload("blackboard", { op: "append" }).ok);
+  assert.ok(validatePayload("blackboard", { op: "read", since: 0 }).ok);
+  assert.ok(!validatePayload("blackboard", { op: "delete" }).ok);
+  assert.ok(!validatePayload("blackboard", { op: "read", since: -1 }).ok);
+});
+
+test("blackboard files must be an array of only strings when present", () => {
+  assert.ok(validatePayload("blackboard", { op: "append", files: [] }).ok);
+  assert.ok(validatePayload("blackboard", { op: "append", files: ["a.rs", "b.rs"] }).ok);
+  const notArray = validatePayload("blackboard", { op: "append", files: "a.rs" });
+  assert.ok(!notArray.ok);
+  if (!notArray.ok) assert.ok(notArray.errors.some((e) => e.code === "bad-files"));
+  // A mixed array must be rejected outright, not silently coerced to its string subset:
+  // dropping the non-string element would store an incomplete file-claim and skew conflict detection.
+  const mixed = validatePayload("blackboard", { op: "append", files: ["a.rs", 123] });
+  assert.ok(!mixed.ok);
+  if (!mixed.ok) assert.ok(mixed.errors.some((e) => e.code === "bad-files"));
+});
+
+test("relay requires stream, non-negative integer offset, and string chunk", () => {
+  assert.ok(validatePayload("relay", { stream: "s", offset: 0, chunk: "" }).ok);
+  assert.ok(!validatePayload("relay", { stream: "s", offset: -1, chunk: "" }).ok);
+  assert.ok(!validatePayload("relay", { stream: "s", offset: 1.5, chunk: "" }).ok);
+  assert.ok(!validatePayload("relay", { stream: "", offset: 0, chunk: "" }).ok);
+});
+
+test("deregister accepts optional string reason and rejects non-string reason", () => {
+  assert.ok(validatePayload("deregister", { instance: "w" }).ok);
+  assert.ok(validatePayload("deregister", { instance: "w", reason: "shutdown" }).ok);
+  const bad = validatePayload("deregister", { instance: "w", reason: 42 });
+  assert.ok(!bad.ok);
+  if (!bad.ok) assert.ok(bad.errors.some((e) => e.code === "bad-reason"));
+});
+
+test("non-object payloads are rejected for every family", () => {
+  assert.ok(!validatePayload("heartbeat", null).ok);
+  assert.ok(!validatePayload("heartbeat", "w").ok);
+  assert.ok(!validatePayload("relay", []).ok);
+});

package/src/protocol/payloads.ts

@@ -0,0 +1,201 @@
+import { isMessageFamily, type MessageFamily } from "./families.ts";
+import { isValidToken } from "./token.ts";
+
+/**
+ * Minimal per-family payload contract. This is the wire-level shape every
+ * family module (S1 hub, S2 presence, S3 vocab, S5 relay, S7 blackboard) builds
+ * on — the single source of truth for the payload of each message family, held
+ * to by both this repo's codec and the c8ctl client.
+ *
+ * Validators are STRUCTURAL and forward-compatible: they require the core
+ * fields with correct types and otherwise tolerate additional properties, so a
+ * later slice may enrich a payload without breaking older peers.
+ *
+ * Capability (cognition/weight/family/host) travels on `register` as an
+ * enrolment attribute — it is NEVER a routing token.
+ */
+export interface Capability {
+  readonly cognition?: string;
+  readonly weight?: number;
+  readonly family?: string;
+  readonly host?: string;
+}
+
+export interface RegisterPayload {
+  readonly instance: string;
+  readonly capability: Capability;
+}
+
+export interface HeartbeatPayload {
+  readonly instance: string;
+}
+
+export interface DeregisterPayload {
+  readonly instance: string;
+  readonly reason?: string;
+}
+
+export interface ServePayload {
+  readonly instance: string;
+  readonly tokens: readonly string[];
+}
+
+export interface DemandPayload {
+  readonly network: string;
+  readonly missing: readonly string[];
+}
+
+export type BlackboardOp = "append" | "read";
+
+export interface BlackboardPayload {
+  readonly op: BlackboardOp;
+  readonly dedupeKey?: string;
+  readonly since?: number;
+}
+
+export interface RelayPayload {
+  readonly stream: string;
+  readonly offset: number;
+  readonly chunk: string;
+}
+
+export interface PayloadError {
+  readonly code: string;
+  readonly message: string;
+}
+
+export type PayloadValidationResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly errors: readonly PayloadError[] };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function validateRegister(p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (!nonEmptyString(p.instance)) {
+    errors.push({ code: "bad-instance", message: "register.instance must be a non-empty string" });
+  }
+  if (!isPlainObject(p.capability)) {
+    errors.push({ code: "bad-capability", message: "register.capability must be an object" });
+    return;
+  }
+  const cap = p.capability;
+  for (const field of ["cognition", "family", "host"] as const) {
+    if (field in cap && typeof cap[field] !== "string") {
+      errors.push({ code: "bad-capability", message: `register.capability.${field} must be a string when present` });
+    }
+  }
+  if ("weight" in cap && typeof cap.weight !== "number") {
+    errors.push({ code: "bad-capability", message: "register.capability.weight must be a number when present" });
+  }
+}
+
+function validateInstanceOnly(family: string, p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (!nonEmptyString(p.instance)) {
+    errors.push({ code: "bad-instance", message: `${family}.instance must be a non-empty string` });
+  }
+}
+
+function validateDeregister(p: Record<string, unknown>, errors: PayloadError[]): void {
+  validateInstanceOnly("deregister", p, errors);
+  if ("reason" in p && typeof p.reason !== "string") {
+    errors.push({ code: "bad-reason", message: "deregister.reason must be a string when present" });
+  }
+}
+
+function validateServe(p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (!nonEmptyString(p.instance)) {
+    errors.push({ code: "bad-instance", message: "serve.instance must be a non-empty string" });
+  }
+  const tokens = p.tokens;
+  if (!Array.isArray(tokens)) {
+    errors.push({ code: "bad-tokens", message: "serve.tokens must be an array" });
+    return;
+  }
+  tokens.forEach((token, index) => {
+    if (typeof token !== "string" || !isValidToken(token)) {
+      errors.push({ code: "bad-token", message: `serve.tokens[${index}] is not a valid routing token` });
+    }
+  });
+}
+
+function validateDemand(p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (!nonEmptyString(p.network)) {
+    errors.push({ code: "bad-network", message: "demand.network must be a non-empty string" });
+  }
+  const missing = p.missing;
+  if (!Array.isArray(missing) || !missing.every((entry) => typeof entry === "string")) {
+    errors.push({ code: "bad-missing", message: "demand.missing must be an array of strings" });
+  }
+}
+
+function validateBlackboard(p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (p.op !== "append" && p.op !== "read") {
+    errors.push({ code: "bad-op", message: "blackboard.op must be 'append' or 'read'" });
+  }
+  if ("dedupeKey" in p && typeof p.dedupeKey !== "string") {
+    errors.push({ code: "bad-dedupe-key", message: "blackboard.dedupeKey must be a string when present" });
+  }
+  if ("since" in p && (typeof p.since !== "number" || !Number.isInteger(p.since) || p.since < 0)) {
+    errors.push({ code: "bad-since", message: "blackboard.since must be a non-negative integer when present" });
+  }
+  if ("files" in p && (!Array.isArray(p.files) || !p.files.every((f) => typeof f === "string"))) {
+    errors.push({ code: "bad-files", message: "blackboard.files must be an array of strings when present" });
+  }
+}
+
+function validateRelay(p: Record<string, unknown>, errors: PayloadError[]): void {
+  if (!nonEmptyString(p.stream)) {
+    errors.push({ code: "bad-stream", message: "relay.stream must be a non-empty string" });
+  }
+  if (typeof p.offset !== "number" || !Number.isInteger(p.offset) || p.offset < 0) {
+    errors.push({ code: "bad-offset", message: "relay.offset must be a non-negative integer" });
+  }
+  if (typeof p.chunk !== "string") {
+    errors.push({ code: "bad-chunk", message: "relay.chunk must be a string" });
+  }
+}
+
+/**
+ * Validate a decoded payload against its family's minimal contract.
+ */
+export function validatePayload(family: MessageFamily, payload: unknown): PayloadValidationResult {
+  if (!isMessageFamily(family)) {
+    return { ok: false, errors: [{ code: "unknown-family", message: `unknown family: ${String(family)}` }] };
+  }
+  if (!isPlainObject(payload)) {
+    return { ok: false, errors: [{ code: "not-object", message: `${family} payload must be an object` }] };
+  }
+
+  const errors: PayloadError[] = [];
+  switch (family) {
+    case "register":
+      validateRegister(payload, errors);
+      break;
+    case "heartbeat":
+      validateInstanceOnly("heartbeat", payload, errors);
+      break;
+    case "deregister":
+      validateDeregister(payload, errors);
+      break;
+    case "serve":
+      validateServe(payload, errors);
+      break;
+    case "demand":
+      validateDemand(payload, errors);
+      break;
+    case "blackboard":
+      validateBlackboard(payload, errors);
+      break;
+    case "relay":
+      validateRelay(payload, errors);
+      break;
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}

package/src/protocol/token.test.ts

@@ -0,0 +1,57 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { formatToken, parseToken, isValidToken, TokenParseError } from "./token.ts";
+import { VALID_TOKENS, INVALID_TOKENS } from "./conformance/tokens.ts";
+
+test("valid tokens parse into the expected decomposition", () => {
+  for (const vector of VALID_TOKENS) {
+    assert.deepEqual(parseToken(vector.token), vector.parsed, vector.name);
+    assert.ok(isValidToken(vector.token), vector.name);
+  }
+});
+
+test("valid tokens round-trip through formatToken", () => {
+  for (const vector of VALID_TOKENS) {
+    assert.equal(formatToken(parseToken(vector.token)), vector.token, vector.name);
+  }
+});
+
+test("formatToken rejects subnetworks without a network", () => {
+  assert.throws(
+    () => formatToken({ subnetworks: ["sub"], role: "decide" }),
+    /subnetworks present without a network/,
+  );
+});
+
+test("formatToken rejects a RoutingToken with an invalid segment", () => {
+  assert.throws(
+    () => formatToken({ network: "Net", subnetworks: [], role: "decide" }),
+    /invalid segment: Net/,
+  );
+  assert.throws(
+    () => formatToken({ network: "mesh", subnetworks: ["Bad_Sub"], role: "decide" }),
+    /invalid segment: Bad_Sub/,
+  );
+});
+
+test("formatToken rejects a RoutingToken with an invalid seat label", () => {
+  assert.throws(
+    () => formatToken({ subnetworks: [], role: "decide", seat: "Seat#1" }),
+    /invalid seat label: Seat#1/,
+  );
+});
+
+test("invalid tokens reject with the specified error code", () => {
+  for (const vector of INVALID_TOKENS) {
+    assert.throws(
+      () => parseToken(vector.token),
+      (error: unknown) => {
+        assert.ok(error instanceof TokenParseError, `${vector.name}: expected TokenParseError`);
+        assert.equal(error.code, vector.expected, vector.name);
+        return true;
+      },
+      vector.name,
+    );
+    assert.ok(!isValidToken(vector.token), vector.name);
+  }
+});

package/src/protocol/token.ts

@@ -0,0 +1,123 @@
+/**
+ * Routing-token grammar: `network[.subnetwork…].role[#seat]`.
+ *
+ * The token is what the engine matches 1:1. Capability — cognition, weight,
+ * family, host — is NEVER encoded in the token; it is an enrolment attribute
+ * and a registry gate. Do not smuggle capability into a segment.
+ *
+ * Grammar:
+ *   token   = segment ("." segment)* ("#" seat)?
+ *   segment = [a-z][a-z0-9-]*        (first is the network, last is the role,
+ *                                     any in between are subnetworks)
+ *   seat    = [a-z0-9-]+
+ *
+ * A single-segment token (e.g. `decide`) is a bare role with no network and no
+ * subnetworks (`network` is absent).
+ */
+export interface RoutingToken {
+  readonly network?: string;
+  readonly subnetworks: readonly string[];
+  readonly role: string;
+  readonly seat?: string;
+}
+
+const SEGMENT_RE = /^[a-z][a-z0-9-]*$/;
+const SEAT_RE = /^[a-z0-9-]+$/;
+
+/** True when `name` is a valid network/subnetwork/role segment. */
+export function isSegmentName(name: string): boolean {
+  return SEGMENT_RE.test(name);
+}
+
+/** True when `seat` is a valid seat label. */
+export function isSeatLabel(seat: string): boolean {
+  return SEAT_RE.test(seat);
+}
+
+export type TokenParseErrorCode =
+  | "empty"
+  | "whitespace"
+  | "multiple-seat-markers"
+  | "empty-seat"
+  | "bad-seat"
+  | "empty-segment"
+  | "bad-segment";
+
+export class TokenParseError extends Error {
+  readonly code: TokenParseErrorCode;
+  constructor(code: TokenParseErrorCode, message: string) {
+    super(message);
+    this.name = "TokenParseError";
+    this.code = code;
+  }
+}
+
+export function parseToken(token: string): RoutingToken {
+  if (token.length === 0) {
+    throw new TokenParseError("empty", "routing token must not be empty");
+  }
+  if (/\s/.test(token)) {
+    throw new TokenParseError("whitespace", "routing token must not contain whitespace");
+  }
+
+  const hashParts = token.split("#");
+  if (hashParts.length > 2) {
+    throw new TokenParseError("multiple-seat-markers", "routing token has more than one '#'");
+  }
+  const pathPart = hashParts[0];
+  const seatPart = hashParts.length === 2 ? hashParts[1] : undefined;
+
+  if (seatPart !== undefined) {
+    if (seatPart.length === 0) {
+      throw new TokenParseError("empty-seat", "seat after '#' must not be empty");
+    }
+    if (!isSeatLabel(seatPart)) {
+      throw new TokenParseError("bad-seat", `invalid seat label: ${seatPart}`);
+    }
+  }
+
+  const segments = pathPart.split(".");
+  for (const segment of segments) {
+    if (segment.length === 0) {
+      throw new TokenParseError("empty-segment", "routing token has an empty '.' segment");
+    }
+    if (!isSegmentName(segment)) {
+      throw new TokenParseError("bad-segment", `invalid token segment: ${segment}`);
+    }
+  }
+
+  const role = segments[segments.length - 1];
+  const base =
+    segments.length === 1
+      ? { subnetworks: [], role }
+      : { network: segments[0], subnetworks: segments.slice(1, -1), role };
+  return seatPart === undefined ? base : { ...base, seat: seatPart };
+}
+
+export function isValidToken(token: string): boolean {
+  try {
+    parseToken(token);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function formatToken(token: RoutingToken): string {
+  if (token.network === undefined && token.subnetworks.length > 0) {
+    throw new Error("invalid RoutingToken: subnetworks present without a network");
+  }
+  const segments = token.network === undefined
+    ? [token.role]
+    : [token.network, ...token.subnetworks, token.role];
+  for (const segment of segments) {
+    if (!isSegmentName(segment)) {
+      throw new Error(`invalid RoutingToken: invalid segment: ${segment}`);
+    }
+  }
+  if (token.seat !== undefined && !isSeatLabel(token.seat)) {
+    throw new Error(`invalid RoutingToken: invalid seat label: ${token.seat}`);
+  }
+  const path = segments.join(".");
+  return token.seat === undefined ? path : `${path}#${token.seat}`;
+}

package/src/protocol/vocab/schema.test.ts

@@ -0,0 +1,67 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { validateVocabDocument } from "./schema.ts";
+import { VALID_VOCABS, INVALID_VOCABS } from "../conformance/vocab.ts";
+
+test("valid vocab documents pass validation and narrow to the document", () => {
+  for (const vector of VALID_VOCABS) {
+    const result = validateVocabDocument(vector.document);
+    assert.ok(result.ok, `${vector.name}: expected ok, got ${result.ok ? "" : JSON.stringify(result.errors)}`);
+    if (result.ok) {
+      assert.deepEqual(result.value, vector.document, vector.name);
+    }
+  }
+});
+
+test("invalid vocab documents fail with the expected error code", () => {
+  for (const vector of INVALID_VOCABS) {
+    const result = validateVocabDocument(vector.document);
+    assert.ok(!result.ok, `${vector.name}: expected failure`);
+    if (!result.ok) {
+      const codes = result.errors.map((e) => e.code);
+      assert.ok(
+        codes.includes(vector.expectedCode),
+        `${vector.name}: expected code ${vector.expectedCode} among ${JSON.stringify(codes)}`,
+      );
+    }
+  }
+});
+
+test("subnetwork roles are validated recursively", () => {
+  const result = validateVocabDocument({
+    version: 1,
+    networks: {
+      implementation: {
+        subnetworks: { ci: { roles: { fix: { weight: "bad" } } } },
+      },
+    },
+  });
+  assert.ok(!result.ok);
+  if (!result.ok) {
+    assert.ok(result.errors.some((e) => e.code === "bad-weight"));
+    assert.ok(result.errors.some((e) => e.path === "$.networks.implementation.subnetworks.ci.roles.fix.weight"));
+  }
+});
+
+test("narrowed document does not share array references with the input", () => {
+  const requires = ["relay"];
+  const seats = ["a", "b"];
+  const input = {
+    version: 1,
+    networks: { impl: { roles: { fix: { requires, seats } } } },
+  };
+  const result = validateVocabDocument(input);
+  assert.ok(result.ok);
+  if (result.ok) {
+    const role = result.value.networks.impl?.roles?.fix;
+    assert.ok(role);
+    assert.notStrictEqual(role.requires, requires);
+    assert.deepEqual(role.requires, requires);
+    assert.notStrictEqual(role.seats, seats);
+    assert.deepEqual(role.seats, seats);
+    requires.push("mutated");
+    seats.push("mutated");
+    assert.deepEqual(role.requires, ["relay"]);
+    assert.deepEqual(role.seats, ["a", "b"]);
+  }
+});