@nanobpm/agentic 0.1.0

package/dist/vocab/core-vocab.js

@@ -0,0 +1,67 @@
+/** 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 = 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(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/vocab/diversity.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { 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[];
+}
+/**
+ * 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 declare function computeDiversity(resolver: VocabResolver, assignments: ReadonlyMap<string, readonly SeatAssignment[]>): DiversityReport;
+/** 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;
+}
+/**
+ * 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 declare function correlateRegistry(resolver: VocabResolver, workers: readonly RegisteredWorker[]): DiversityReport;

package/dist/vocab/diversity.js

@@ -0,0 +1,89 @@
+const SEVERITY = { green: 0, amber: 1, red: 2 };
+function worst(a, b) {
+    return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+function collidingFamilies(assignments) {
+    const counts = new Map();
+    for (const { family } of assignments) {
+        counts.set(family, (counts.get(family) ?? 0) + 1);
+    }
+    const colliding = [];
+    for (const [family, count] of counts) {
+        if (count > 1)
+            colliding.push(family);
+    }
+    colliding.sort();
+    return colliding;
+}
+function gradeRole(role, assignments) {
+    const colliding = collidingFamilies(assignments);
+    const status = 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, assignments) {
+    const roles = [];
+    let status = "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 };
+}
+/** Seat labels for a role: its named seats, or synthesised `0..n-1` for a count. */
+function seatLabels(role) {
+    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, workers) {
+    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();
+    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 = [];
+        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/dist/vocab/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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/dist/vocab/index.js

@@ -0,0 +1,22 @@
+/**
+ * @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, } from "./resolver.js";
+export { CORE_VOCAB, CORE_VOCAB_VERSION } from "./core-vocab.js";
+export { mergeVocab } from "./merge.js";
+export { REQUIRES_FIELDS, RequiresParseError, parseRequires, parseRequiresList, satisfiesRequires, satisfiesPredicate, } from "./requires.js";
+export { computeDiversity, correlateRegistry, } from "./diversity.js";
+export { buildServePayload, buildServeFrame, serveCapability, } from "./serve.js";

package/dist/vocab/merge.d.ts

@@ -0,0 +1,9 @@
+import type { VocabDocument } from "../protocol/index.ts";
+/**
+ * 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 declare function mergeVocab(extension: VocabDocument, base?: VocabDocument): VocabDocument;

package/dist/vocab/merge.js

@@ -0,0 +1,104 @@
+/**
+ * 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.js";
+import { CORE_VOCAB } from "./core-vocab.js";
+import { VocabDocumentError } from "./resolver.js";
+function mergeRole(base, ext) {
+    const merged = {};
+    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 = {};
+function cloneRole(role) {
+    return mergeRole(EMPTY_ROLE, role);
+}
+function mergeRoles(base, ext) {
+    if (base === undefined && ext === undefined)
+        return undefined;
+    const out = {};
+    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, ext) {
+    const roles = mergeRoles(base?.roles, ext.roles);
+    const subnetworks = mergeNetworks(base?.subnetworks, ext.subnetworks);
+    const merged = {};
+    if (roles !== undefined)
+        merged.roles = roles;
+    if (subnetworks !== undefined)
+        merged.subnetworks = subnetworks;
+    return merged;
+}
+function mergeNetworks(base, ext) {
+    if (base === undefined && ext === undefined)
+        return undefined;
+    const out = {};
+    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, base = CORE_VOCAB) {
+    for (const [label, doc] of [
+        ["base", base],
+        ["extension", extension],
+    ]) {
+        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;
+}

package/dist/vocab/requires.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare const REQUIRES_FIELDS: readonly ["cognition", "weight", "family", "host"];
+export type RequiresField = (typeof REQUIRES_FIELDS)[number];
+export type RequiresOp = "=" | "==" | "!=" | ">=" | "<=" | ">" | "<";
+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 declare class RequiresParseError extends Error {
+    readonly source: string;
+    constructor(source: string, detail: string);
+}
+/** Parse one `requires` entry into a predicate, or throw {@link RequiresParseError}. */
+export declare function parseRequires(source: string): RequiresPredicate;
+/** Parse every entry of a role's `requires` list. */
+export declare function parseRequiresList(requires: readonly string[] | undefined): RequiresPredicate[];
+/** True when `capability` satisfies a single predicate (fail-closed on absent fields). */
+export declare function satisfiesPredicate(predicate: RequiresPredicate, capability: Capability): boolean;
+/** True when `capability` satisfies EVERY predicate (an empty list is open). */
+export declare function satisfiesRequires(predicates: readonly RequiresPredicate[], capability: Capability): boolean;

package/dist/vocab/requires.js

@@ -0,0 +1,107 @@
+/** The capability fields a `requires` predicate may gate on. */
+export const REQUIRES_FIELDS = ["cognition", "weight", "family", "host"];
+/** The numeric field; ordering operators are valid only for it. */
+const NUMERIC_FIELD = "weight";
+const ORDERING_OPS = new Set([">=", "<=", ">", "<"]);
+const STRING_FIELDS = new Set(["cognition", "family", "host"]);
+/** Raised when a `requires` entry is not a well-formed predicate. */
+export class RequiresParseError extends Error {
+    source;
+    constructor(source, detail) {
+        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 = new Set(REQUIRES_FIELDS);
+function isRequiresField(value) {
+    return FIELD_SET.has(value);
+}
+function isRequiresOp(value) {
+    return value === "=" || value === "==" || value === "!=" || value === ">=" || value === "<=" || value === ">" || value === "<";
+}
+/** Parse one `requires` entry into a predicate, or throw {@link RequiresParseError}. */
+export function parseRequires(source) {
+    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) {
+    if (requires === undefined)
+        return [];
+    return requires.map(parseRequires);
+}
+function evalNumeric(op, actual, expected) {
+    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, actual, expected) {
+    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, capability) {
+    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, capability) {
+    return predicates.every((predicate) => satisfiesPredicate(predicate, capability));
+}

package/dist/vocab/resolver.d.ts

@@ -0,0 +1,62 @@
+import type { Capability, VocabDocument } from "../protocol/index.ts";
+import { 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 declare class VocabDocumentError extends Error {
+    readonly errors: readonly {
+        path: string;
+        message: string;
+    }[];
+    constructor(errors: readonly {
+        path: string;
+        message: string;
+    }[]);
+}
+export declare class VocabResolver {
+    #private;
+    /**
+     * 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);
+    /** The vocab artifact version this resolver was built from. */
+    get version(): number;
+    /** Every role in the vocab, sorted by token. */
+    roles(): readonly ResolvedRole[];
+    /** Every leaf token in the vocab, sorted. */
+    tokens(): readonly string[];
+    /** Look up a role by its routing token. */
+    roleForToken(token: string): ResolvedRole | undefined;
+    /**
+     * 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;
+}