@nanobpm/agentic 0.1.0

package/src/vocab/requires.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  parseRequires,
+  parseRequiresList,
+  RequiresParseError,
+  satisfiesPredicate,
+  satisfiesRequires,
+} from "./requires.ts";
+
+test("parses equality, inequality and ordering predicates", () => {
+  assert.deepEqual(parseRequires("cognition=planning"), {
+    field: "cognition",
+    op: "=",
+    value: "planning",
+    source: "cognition=planning",
+  });
+  assert.deepEqual(parseRequires("weight>=4"), { field: "weight", op: ">=", value: 4, source: "weight>=4" });
+  assert.equal(parseRequires("family != acme").op, "!=");
+  assert.equal(parseRequires("family != acme").value, "acme");
+});
+
+test("tolerates surrounding whitespace", () => {
+  const p = parseRequires("  cognition  ==  qa  ");
+  assert.equal(p.field, "cognition");
+  assert.equal(p.op, "==");
+  assert.equal(p.value, "qa");
+});
+
+test("rejects malformed predicates", () => {
+  assert.throws(() => parseRequires("nonsense"), RequiresParseError);
+  assert.throws(() => parseRequires("host"), RequiresParseError);
+  assert.throws(() => parseRequires("colour=red"), RequiresParseError);
+});
+
+test("ordering operators are weight-only; string ordering rejected", () => {
+  assert.throws(() => parseRequires("cognition>=planning"), RequiresParseError);
+  assert.throws(() => parseRequires("weight>=notanumber"), RequiresParseError);
+});
+
+test("satisfiesPredicate is fail-closed on absent fields (except !=)", () => {
+  assert.equal(satisfiesPredicate(parseRequires("cognition=planning"), {}), false);
+  assert.equal(satisfiesPredicate(parseRequires("weight>=3"), {}), false);
+  // Absent field provably is not the forbidden value.
+  assert.equal(satisfiesPredicate(parseRequires("family!=acme"), {}), true);
+});
+
+test("numeric comparisons evaluate against weight", () => {
+  assert.equal(satisfiesPredicate(parseRequires("weight>=4"), { weight: 5 }), true);
+  assert.equal(satisfiesPredicate(parseRequires("weight>=4"), { weight: 4 }), true);
+  assert.equal(satisfiesPredicate(parseRequires("weight>=4"), { weight: 3 }), false);
+  assert.equal(satisfiesPredicate(parseRequires("weight<2"), { weight: 1 }), true);
+});
+
+test("string comparisons evaluate against the field", () => {
+  assert.equal(satisfiesPredicate(parseRequires("cognition=qa"), { cognition: "qa" }), true);
+  assert.equal(satisfiesPredicate(parseRequires("cognition=qa"), { cognition: "planning" }), false);
+  assert.equal(satisfiesPredicate(parseRequires("family!=acme"), { family: "acme" }), false);
+  assert.equal(satisfiesPredicate(parseRequires("family!=acme"), { family: "globex" }), true);
+});
+
+test("satisfiesRequires requires EVERY predicate; empty list is open", () => {
+  const preds = parseRequiresList(["cognition=implementation", "weight>=4"]);
+  assert.equal(satisfiesRequires(preds, { cognition: "implementation", weight: 5 }), true);
+  assert.equal(satisfiesRequires(preds, { cognition: "implementation", weight: 2 }), false);
+  assert.equal(satisfiesRequires(preds, { cognition: "qa", weight: 9 }), false);
+  assert.equal(satisfiesRequires(parseRequiresList(undefined), {}), true);
+  assert.equal(satisfiesRequires(parseRequiresList([]), { cognition: "anything" }), true);
+});

package/src/vocab/requires.ts

@@ -0,0 +1,155 @@
+/**
+ * The enrolment-capability gate: `requires` predicates.
+ *
+ * A vocab role's `requires` list is the REGISTRY GATE — it decides WHO may fill
+ * the role based on the declared enrolment capability (cognition / weight /
+ * family / host). It is deliberately NOT part of the routing token: capability
+ * never rides the token (S0 invariant 3); it gates enrolment here.
+ *
+ * Each `requires` entry is a single predicate over one capability field:
+ *
+ *   predicate = field op value
+ *   field     = cognition | weight | family | host
+ *   op        = "=" | "==" | "!=" | ">=" | "<=" | ">" | "<"
+ *
+ * Ordering/numeric operators (`>=`, `<=`, `>`, `<`) apply to `weight` only (the
+ * one numeric capability field); the string fields support only `=`/`==`/`!=`.
+ * A role with no `requires` (or an empty list) is open to any capability.
+ *
+ * Match semantics are FAIL-CLOSED for a gate: an absent field fails every
+ * positive predicate (`=`,`==`,`>=`,`<=`,`>`,`<`); only `!=` is satisfied by an
+ * absent field (the worker's field is provably not the forbidden value). A
+ * capability satisfies a role iff it satisfies EVERY predicate.
+ */
+import type { Capability } from "../protocol/index.ts";
+
+/** The capability fields a `requires` predicate may gate on. */
+export const REQUIRES_FIELDS = ["cognition", "weight", "family", "host"] as const;
+export type RequiresField = (typeof REQUIRES_FIELDS)[number];
+
+export type RequiresOp = "=" | "==" | "!=" | ">=" | "<=" | ">" | "<";
+
+/** The numeric field; ordering operators are valid only for it. */
+const NUMERIC_FIELD: RequiresField = "weight";
+const ORDERING_OPS: ReadonlySet<string> = new Set([">=", "<=", ">", "<"]);
+const STRING_FIELDS: ReadonlySet<string> = new Set(["cognition", "family", "host"]);
+
+export interface RequiresPredicate {
+  readonly field: RequiresField;
+  readonly op: RequiresOp;
+  /** The compared value: a number for `weight`, a string otherwise. */
+  readonly value: string | number;
+  /** The original source text, for diagnostics. */
+  readonly source: string;
+}
+
+/** Raised when a `requires` entry is not a well-formed predicate. */
+export class RequiresParseError extends Error {
+  readonly source: string;
+  constructor(source: string, detail: string) {
+    super(`invalid requires predicate "${source}": ${detail}`);
+    this.name = "RequiresParseError";
+    this.source = source;
+  }
+}
+
+// Longest operators first so `>=` is not mis-split as `>`; `==` before `=`.
+const PREDICATE_RE = /^(cognition|weight|family|host)\s*(>=|<=|==|!=|=|>|<)\s*(.+?)\s*$/;
+
+const FIELD_SET: ReadonlySet<string> = new Set(REQUIRES_FIELDS);
+
+function isRequiresField(value: string): value is RequiresField {
+  return FIELD_SET.has(value);
+}
+
+function isRequiresOp(value: string): value is RequiresOp {
+  return value === "=" || value === "==" || value === "!=" || value === ">=" || value === "<=" || value === ">" || value === "<";
+}
+
+/** Parse one `requires` entry into a predicate, or throw {@link RequiresParseError}. */
+export function parseRequires(source: string): RequiresPredicate {
+  const match = PREDICATE_RE.exec(source.trim());
+  if (match === null) {
+    throw new RequiresParseError(source, "expected `field op value` (field: cognition|weight|family|host)");
+  }
+  const field = match[1];
+  const op = match[2];
+  const rawValue = match[3];
+  if (!isRequiresField(field) || !isRequiresOp(op)) {
+    throw new RequiresParseError(source, "unrecognised field or operator");
+  }
+
+  if (field === NUMERIC_FIELD) {
+    const value = Number(rawValue);
+    if (!Number.isFinite(value)) {
+      throw new RequiresParseError(source, "weight predicate needs a finite numeric value");
+    }
+    return { field, op, value, source };
+  }
+
+  // String field: reject ordering operators (no total order on strings here).
+  if (ORDERING_OPS.has(op)) {
+    throw new RequiresParseError(source, `operator ${op} is only valid for the numeric field "weight"`);
+  }
+  if (!STRING_FIELDS.has(field)) {
+    throw new RequiresParseError(source, `field ${field} is not a string field`);
+  }
+  return { field, op, value: rawValue, source };
+}
+
+/** Parse every entry of a role's `requires` list. */
+export function parseRequiresList(requires: readonly string[] | undefined): RequiresPredicate[] {
+  if (requires === undefined) return [];
+  return requires.map(parseRequires);
+}
+
+function evalNumeric(op: RequiresOp, actual: number, expected: number): boolean {
+  switch (op) {
+    case "=":
+    case "==":
+      return actual === expected;
+    case "!=":
+      return actual !== expected;
+    case ">=":
+      return actual >= expected;
+    case "<=":
+      return actual <= expected;
+    case ">":
+      return actual > expected;
+    case "<":
+      return actual < expected;
+  }
+}
+
+function evalString(op: RequiresOp, actual: string, expected: string): boolean {
+  switch (op) {
+    case "=":
+    case "==":
+      return actual === expected;
+    case "!=":
+      return actual !== expected;
+    // Ordering operators are rejected at parse time for string fields.
+    default:
+      return false;
+  }
+}
+
+/** True when `capability` satisfies a single predicate (fail-closed on absent fields). */
+export function satisfiesPredicate(predicate: RequiresPredicate, capability: Capability): boolean {
+  const actual = capability[predicate.field];
+  if (actual === undefined) {
+    // An absent field can only satisfy a "must NOT equal" predicate.
+    return predicate.op === "!=";
+  }
+  if (predicate.field === NUMERIC_FIELD) {
+    if (typeof actual !== "number" || typeof predicate.value !== "number") return false;
+    return evalNumeric(predicate.op, actual, predicate.value);
+  }
+  if (typeof actual !== "string" || typeof predicate.value !== "string") return false;
+  return evalString(predicate.op, actual, predicate.value);
+}
+
+/** True when `capability` satisfies EVERY predicate (an empty list is open). */
+export function satisfiesRequires(predicates: readonly RequiresPredicate[], capability: Capability): boolean {
+  return predicates.every((predicate) => satisfiesPredicate(predicate, capability));
+}

package/src/vocab/resolver.test.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseToken } from "../protocol/index.ts";
+import { VALID_VOCABS } from "../protocol/conformance/vocab.ts";
+import { CORE_VOCAB } from "./core-vocab.ts";
+import { VocabDocumentError, VocabResolver } from "./resolver.ts";
+
+test("derives leaf tokens for every core role, sorted and unique", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const tokens = resolver.tokens();
+  assert.deepEqual([...tokens].sort(), tokens, "tokens must be sorted");
+  assert.equal(new Set(tokens).size, tokens.length, "tokens must be unique");
+  assert.ok(tokens.includes("planning.planner"));
+  assert.ok(tokens.includes("planning.reviewer"));
+  assert.ok(tokens.includes("qa.tester"));
+  assert.ok(tokens.includes("implementation.senior"));
+  assert.ok(tokens.includes("ci.runner"));
+});
+
+test("a self-named top-level role collapses to a bare single-segment token", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  assert.ok(resolver.tokens().includes("decide"), "decide must be a bare token");
+  // And it is a valid single-segment routing token (network-less).
+  const parsed = parseToken("decide");
+  assert.equal(parsed.network, undefined);
+  assert.equal(parsed.role, "decide");
+});
+
+test("resolve is deterministic: a capability yields a stable SERVE token set", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const cap = { cognition: "planning", family: "acme" };
+  const a = resolver.resolve(cap);
+  const b = resolver.resolve(cap);
+  assert.deepEqual(a.tokens, b.tokens);
+  assert.deepEqual(a.tokens, ["planning.planner", "planning.reviewer"]);
+});
+
+test("the weight gate excludes an under-weight senior but not a junior", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const heavy = resolver.resolve({ cognition: "implementation", weight: 5 });
+  assert.ok(heavy.tokens.includes("implementation.senior"));
+  assert.ok(heavy.tokens.includes("implementation.junior"));
+
+  const light = resolver.resolve({ cognition: "implementation", weight: 2 });
+  assert.ok(!light.tokens.includes("implementation.senior"), "weight<4 fails the senior gate");
+  assert.ok(light.tokens.includes("implementation.junior"));
+});
+
+test("a non-matching cognition serves nothing", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  assert.deepEqual(resolver.resolve({ cognition: "marketing" }).tokens, []);
+  assert.deepEqual(resolver.resolve({}).tokens, []);
+});
+
+test("roleForToken normalises spelling and returns role metadata", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const role = resolver.roleForToken("planning.reviewer");
+  assert.ok(role !== undefined);
+  assert.equal(role?.seatsDistinctFamily, true);
+  assert.deepEqual(role?.seats, ["red", "blue"]);
+  assert.equal(resolver.roleForToken("decide")?.role, "decide");
+  assert.equal(resolver.roleForToken("nope.nope"), undefined);
+  assert.equal(resolver.roleForToken("!!bad!!"), undefined);
+});
+
+test("construction rejects an invalid vocab document", () => {
+  const bad = JSON.parse('{"version":0,"networks":{}}');
+  assert.throws(() => new VocabResolver(bad), VocabDocumentError);
+});
+
+test("construction rejects a malformed requires predicate, naming the offending token", () => {
+  const doc = JSON.parse('{"version":1,"networks":{"n":{"roles":{"r":{"requires":["not a predicate"]}}}}}');
+  assert.throws(
+    () => new VocabResolver(doc),
+    (error: unknown) => {
+      assert.ok(error instanceof VocabDocumentError);
+      assert.equal(error.errors.length, 1);
+      assert.equal(error.errors[0]?.path, "n.r");
+      assert.match(error.errors[0]?.message ?? "", /not a predicate/);
+      return true;
+    },
+  );
+});
+
+test("a self-named collapse does not collide with a network-qualified token of the same leaf", () => {
+  // A self-named top-level `decide` role collapses to the bare token `decide`,
+  // while a `decide` role under network `x` stays `x.decide`. The two are
+  // distinct routing tokens, so construction succeeds and exposes both.
+  //
+  // A genuine duplicate token is structurally unreachable through the schema:
+  // every network/subnetwork/role key is unique, and the only collapse is a
+  // top-level self-named role — which can fire at most once per bare token — so
+  // no two roles can derive the same string. The constructor's duplicate-token
+  // guard is therefore defensive, and this test pins the near-miss it protects.
+  const doc = JSON.parse(
+    '{"version":1,"networks":{"decide":{"roles":{"decide":{}}},"x":{"roles":{"decide":{}}}}}',
+  );
+  const resolver = new VocabResolver(doc);
+  assert.deepEqual([...resolver.tokens()].sort(), ["decide", "x.decide"]);
+  assert.equal(resolver.roleForToken("decide")?.role, "decide");
+  assert.equal(resolver.roleForToken("x.decide")?.role, "decide");
+});
+
+test("every VALID_VOCABS conformance sample constructs a resolver without throwing", () => {
+  // Guard the defect class: the conformance corpus advertises these documents as
+  // resolver-valid ("held to the same schema this repo's validator enforces"), so
+  // a sample that passes `validateVocabDocument` but carries an unparseable
+  // `requires` gate (e.g. the `field:value` colon form instead of `field=value`)
+  // would still throw `RequiresParseError` the moment a consumer builds a
+  // resolver. Constructing a resolver over every sample parses each gate up front,
+  // catching that drift categorically rather than one predicate at a time.
+  for (const vector of VALID_VOCABS) {
+    assert.doesNotThrow(
+      () => new VocabResolver(vector.document),
+      `${vector.name}: every VALID_VOCABS sample must build a resolver`,
+    );
+  }
+});

package/src/vocab/resolver.ts

@@ -0,0 +1,187 @@
+/**
+ * The vocab resolver — S3's REGISTER→SERVE core.
+ *
+ * The versioned vocab artifact (S0 {@link VocabDocument}) is the ONE
+ * capability→token map; no map is ever baked into a worker. This resolver reads
+ * it and, given a declared enrolment capability, produces the deterministic
+ * SERVE token set the worker is entitled to fill — the `serve` reply to a
+ * `register` handshake.
+ *
+ * Token derivation walks `networks → subnetworks → roles`, joining segments into
+ * a routing token `network[.subnetwork…].role` (never a seat, never a
+ * capability). One exception encodes a BARE (network-less) role such as
+ * `decide`: a top-level role whose name equals its containing network and that
+ * has no subnetworks collapses to the single-segment token `role` — the only way
+ * the S0 network→role schema can express the bare tokens the grammar allows. So
+ * `networks.decide.roles.decide` serves the token `decide`.
+ */
+import { formatToken, parseToken, validateVocabDocument } from "../protocol/index.ts";
+import type { Capability, VocabDocument, VocabNetwork, VocabRole } from "../protocol/index.ts";
+import { parseRequiresList, RequiresParseError, satisfiesRequires, type RequiresPredicate } from "./requires.ts";
+
+/** A role flattened out of the vocab tree, with its derived routing token. */
+export interface ResolvedRole {
+  /** The leaf routing token (`network[.subnetwork…].role`, or a bare role). */
+  readonly token: string;
+  /** The network segment, absent for a bare role. */
+  readonly network?: string;
+  /** The subnetwork segments between network and role (possibly empty). */
+  readonly subnetworks: readonly string[];
+  /** The role segment. */
+  readonly role: string;
+  /** Cognition weight for the role, if declared. */
+  readonly weight?: number;
+  /** Normalised seats: a non-negative count, or the explicit named-seat list. */
+  readonly seats: number | readonly string[];
+  /** Diversity SLO opt-in: when true, seats must be filled by distinct families. */
+  readonly seatsDistinctFamily: boolean;
+  /** The parsed enrolment gate for the role. */
+  readonly requires: readonly RequiresPredicate[];
+}
+
+/** The result of resolving one capability against the vocab. */
+export interface Resolution {
+  /** The SERVE token set — sorted, de-duplicated leaf tokens. */
+  readonly tokens: readonly string[];
+  /** The matched roles (sorted by token) the tokens came from. */
+  readonly roles: readonly ResolvedRole[];
+}
+
+/** Raised when the document handed to the resolver is not a valid vocab artifact. */
+export class VocabDocumentError extends Error {
+  readonly errors: readonly { path: string; message: string }[];
+  constructor(errors: readonly { path: string; message: string }[]) {
+    super(`invalid vocab document: ${errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`);
+    this.name = "VocabDocumentError";
+    this.errors = errors;
+  }
+}
+
+/**
+ * Parse a role's `requires` gate, tagging any failure with the routing token so a
+ * malformed predicate names the role that carries it (e.g. when merging author
+ * extensions) instead of surfacing a bare, context-free {@link RequiresParseError}.
+ */
+function parseRequires(token: string, requires: readonly string[] | undefined): RequiresPredicate[] {
+  try {
+    return parseRequiresList(requires);
+  } catch (error) {
+    if (error instanceof RequiresParseError) {
+      throw new VocabDocumentError([{ path: token, message: error.message }]);
+    }
+    throw error;
+  }
+}
+
+function deriveToken(network: string, subnetworks: readonly string[], role: string): string {
+  // A self-named top-level role denotes a rootless (network-less) role: the only
+  // way the network→role schema can express a single-segment token like `decide`.
+  if (subnetworks.length === 0 && network === role) {
+    return formatToken({ subnetworks: [], role });
+  }
+  return formatToken({ network, subnetworks: [...subnetworks], role });
+}
+
+function normaliseSeats(seats: VocabRole["seats"]): number | readonly string[] {
+  if (seats === undefined) return 1;
+  if (typeof seats === "number") return seats;
+  return [...seats];
+}
+
+export class VocabResolver {
+  readonly #roles: readonly ResolvedRole[];
+  readonly #byToken: ReadonlyMap<string, ResolvedRole>;
+  readonly #version: number;
+
+  /**
+   * Build a resolver over a vocab document. The document is re-validated against
+   * the S0 schema and every role's `requires` gate is parsed up front, so a
+   * malformed gate fails loudly at construction rather than silently at match.
+   */
+  constructor(doc: VocabDocument) {
+    const validation = validateVocabDocument(doc);
+    if (!validation.ok) {
+      throw new VocabDocumentError(validation.errors.map((e) => ({ path: e.path, message: e.message })));
+    }
+    const document = validation.value;
+    this.#version = document.version;
+
+    const roles: ResolvedRole[] = [];
+    const collect = (network: string, subnetworks: readonly string[], node: VocabNetwork): void => {
+      if (node.roles !== undefined) {
+        for (const [roleName, role] of Object.entries(node.roles)) {
+          const token = deriveToken(network, subnetworks, roleName);
+          roles.push({
+            token,
+            ...(subnetworks.length === 0 && network === roleName ? {} : { network }),
+            subnetworks: [...subnetworks],
+            role: roleName,
+            ...(role.weight === undefined ? {} : { weight: role.weight }),
+            seats: normaliseSeats(role.seats),
+            seatsDistinctFamily: role.seatsDistinctFamily === true,
+            requires: parseRequires(token, role.requires),
+          });
+        }
+      }
+      if (node.subnetworks !== undefined) {
+        for (const [subName, sub] of Object.entries(node.subnetworks)) {
+          collect(network, [...subnetworks, subName], sub);
+        }
+      }
+    };
+    for (const [networkName, network] of Object.entries(document.networks)) {
+      collect(networkName, [], network);
+    }
+
+    // Deterministic order + a token→role index; a duplicate token is a modelling
+    // error (two roles cannot claim one routing token).
+    roles.sort((a, b) => (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+    const byToken = new Map<string, ResolvedRole>();
+    for (const role of roles) {
+      if (byToken.has(role.token)) {
+        throw new VocabDocumentError([{ path: role.token, message: `duplicate routing token: ${role.token}` }]);
+      }
+      byToken.set(role.token, role);
+    }
+    this.#roles = roles;
+    this.#byToken = byToken;
+  }
+
+  /** The vocab artifact version this resolver was built from. */
+  get version(): number {
+    return this.#version;
+  }
+
+  /** Every role in the vocab, sorted by token. */
+  roles(): readonly ResolvedRole[] {
+    return this.#roles;
+  }
+
+  /** Every leaf token in the vocab, sorted. */
+  tokens(): readonly string[] {
+    return this.#roles.map((role) => role.token);
+  }
+
+  /** Look up a role by its routing token. */
+  roleForToken(token: string): ResolvedRole | undefined {
+    // Normalise through the grammar so `planning.planner` and any equivalent
+    // spelling resolve identically.
+    let key: string;
+    try {
+      key = formatToken(parseToken(token));
+    } catch {
+      return undefined;
+    }
+    return this.#byToken.get(key);
+  }
+
+  /**
+   * Resolve a declared enrolment capability to its SERVE token set: every role
+   * whose `requires` gate the capability satisfies. The token list is sorted and
+   * de-duplicated, so the same capability always yields the same SERVE.
+   */
+  resolve(capability: Capability): Resolution {
+    const matched = this.#roles.filter((role) => satisfiesRequires(role.requires, capability));
+    return { tokens: matched.map((role) => role.token), roles: matched };
+  }
+}

package/src/vocab/serve.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { decodeFrame, encodeFrame, type Frame, MAX_SEQ, validatePayload } from "../protocol/index.ts";
+import { CORE_VOCAB } from "./core-vocab.ts";
+import { VocabResolver } from "./resolver.ts";
+import { buildServeFrame, buildServePayload, serveCapability, type ServeSink } from "./serve.ts";
+
+test("buildServePayload copies tokens into a serve payload", () => {
+  const payload = buildServePayload("w-1", ["planning.planner"]);
+  assert.deepEqual(payload, { instance: "w-1", tokens: ["planning.planner"] });
+  assert.equal(validatePayload("serve", payload).ok, true);
+});
+
+test("buildServeFrame rides the control lane and round-trips through the codec", () => {
+  const frame = buildServeFrame("w-1", ["planning.planner", "planning.reviewer"], 3);
+  assert.equal(frame.lane, "control");
+  assert.equal(frame.family, "serve");
+  assert.equal(frame.seq, 3);
+  const decoded = decodeFrame(encodeFrame(frame));
+  assert.deepEqual(decoded.payload, { instance: "w-1", tokens: ["planning.planner", "planning.reviewer"] });
+});
+
+test("buildServeFrame refuses an invalid routing token", () => {
+  assert.throws(() => buildServeFrame("w-1", ["Not A Token"]), /invalid serve frame/);
+});
+
+test("buildServeFrame refuses a seq outside the wire's uint32 bound", () => {
+  for (const badSeq of [-1, 1.5, MAX_SEQ + 1, Number.NaN, Number.POSITIVE_INFINITY]) {
+    assert.throws(() => buildServeFrame("w-1", ["planning.planner"], badSeq), /invalid seq/);
+  }
+});
+
+test("buildServeFrame accepts the seq boundary values the wire allows", () => {
+  for (const seq of [0, MAX_SEQ]) {
+    const frame = buildServeFrame("w-1", ["planning.planner"], seq);
+    assert.equal(frame.seq, seq);
+    assert.deepEqual(decodeFrame(encodeFrame(frame)).payload, { instance: "w-1", tokens: ["planning.planner"] });
+  }
+});
+
+test("serveCapability resolves a capability and emits the serve frame", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const sent: Frame[] = [];
+  const sink: ServeSink = { send: (frame) => sent.push(frame) };
+
+  const resolution = serveCapability(resolver, sink, "w-1", { cognition: "planning", family: "acme" }, 1);
+
+  assert.deepEqual(resolution.tokens, ["planning.planner", "planning.reviewer"]);
+  assert.equal(sent.length, 1);
+  assert.equal(sent[0]?.family, "serve");
+  assert.equal(sent[0]?.lane, "control");
+  assert.deepEqual(sent[0]?.payload, {
+    instance: "w-1",
+    tokens: ["planning.planner", "planning.reviewer"],
+  });
+});
+
+test("serveCapability serves an empty token set for an unqualified capability", () => {
+  const resolver = new VocabResolver(CORE_VOCAB);
+  const sent: Frame[] = [];
+  const resolution = serveCapability(resolver, { send: (f) => sent.push(f) }, "w-2", { cognition: "unknown" });
+  assert.deepEqual(resolution.tokens, []);
+  assert.deepEqual(sent[0]?.payload, { instance: "w-2", tokens: [] });
+});

package/src/vocab/serve.ts

@@ -0,0 +1,66 @@
+/**
+ * The REGISTER→SERVE handshake mechanics.
+ *
+ * S2 owns the `register` family on the hub (one family, one owning module — this
+ * slice does NOT claim it). S3 supplies the other half of the handshake: given a
+ * declared enrolment capability, resolve it (via {@link VocabResolver}) to its
+ * SERVE token set and emit a `serve` frame back to the worker.
+ *
+ * The `serve` reply rides the CONTROL lane — it is a control/facts message, so a
+ * bulk relay storm can never delay a worker learning which tokens it may serve
+ * (S0 invariant 5). The composition root wires this after presence register
+ * (e.g. from S2's register path or an app-level adapter); keeping it a pure,
+ * connection-agnostic helper is what lets it compose without editing S2.
+ */
+import type { Capability, Frame, ServePayload } from "../protocol/index.ts";
+import { MAX_SEQ, validatePayload } from "../protocol/index.ts";
+import type { Resolution, VocabResolver } from "./resolver.ts";
+
+/** The minimal per-connection sink a serve reply needs — S1's `HubConnection.send`. */
+export interface ServeSink {
+  send(frame: Frame): void;
+}
+
+/** Build the `serve` payload for an instance and its resolved token set. */
+export function buildServePayload(instance: string, tokens: readonly string[]): ServePayload {
+  return { instance, tokens: [...tokens] };
+}
+
+/**
+ * Build the `serve` frame carrying an instance's SERVE token set. Rides the
+ * control lane; `seq` defaults to 0 (the caller owns per-connection sequencing).
+ * The built payload is validated against the S0 `serve` contract, so a
+ * malformed token set fails loudly here rather than on the wire. `seq` is
+ * likewise checked against the wire's uint32 bound (the same {@link MAX_SEQ}
+ * `encodeFrame` enforces) so a bad sequence number fails here — at construction
+ * — rather than later during encoding.
+ */
+export function buildServeFrame(instance: string, tokens: readonly string[], seq = 0): Frame {
+  if (!Number.isInteger(seq) || seq < 0 || seq > MAX_SEQ) {
+    throw new Error(`refusing to build serve frame with invalid seq (must be a uint32): ${String(seq)}`);
+  }
+  const payload = buildServePayload(instance, tokens);
+  const check = validatePayload("serve", payload);
+  if (!check.ok) {
+    throw new Error(`refusing to build invalid serve frame: ${check.errors.map((e) => e.message).join("; ")}`);
+  }
+  return { lane: "control", family: "serve", seq, payload };
+}
+
+/**
+ * Resolve `capability` and send the resulting `serve` frame to `sink`. Returns
+ * the {@link Resolution} so the caller can also record the assigned tokens (e.g.
+ * for demand×supply or diversity correlation). This is the server side of
+ * `REGISTER {capability}` → `SERVE [leaf tokens]`.
+ */
+export function serveCapability(
+  resolver: VocabResolver,
+  sink: ServeSink,
+  instance: string,
+  capability: Capability,
+  seq = 0,
+): Resolution {
+  const resolution = resolver.resolve(capability);
+  sink.send(buildServeFrame(instance, resolution.tokens, seq));
+  return resolution;
+}