@nanobpm/agentic 0.1.0

package/dist/protocol/hex.js

@@ -0,0 +1,26 @@
+/**
+ * Language-neutral hex helpers so the conformance corpus can express golden
+ * frames as hex strings that any consumer (this repo, jwulf/c8ctl-plugin-nano,
+ * a future non-JS client) can decode identically.
+ */
+export function bytesToHex(bytes) {
+    let out = "";
+    for (const byte of bytes) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+export function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error("hex string must have an even length");
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const pair = hex.slice(i * 2, i * 2 + 2);
+        if (!/^[0-9a-fA-F]{2}$/.test(pair)) {
+            throw new Error(`invalid hex byte at index ${i * 2}`);
+        }
+        out[i] = Number.parseInt(pair, 16);
+    }
+    return out;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @nanobpm/agentic/protocol — the wire contract for the Nano agentic protocol
+ * (ADR 0056): one app-tier channel carrying agent presence/registry,
+ * demand×supply, the blackboard and live terminal relay.
+ *
+ * This package is the single source of truth every other slice keys off:
+ *  - the canonical message-family set ({@link MESSAGE_FAMILIES}),
+ *  - the three QoS lanes ({@link QOS_LANES}),
+ *  - the frame codec ({@link encodeFrame} / {@link decodeFrame}),
+ *  - the routing-token grammar ({@link parseToken}),
+ *  - the vocab-artifact schema ({@link validateVocabDocument}), and
+ *  - per-family payload contracts ({@link validatePayload}).
+ *
+ * The shared conformance corpus is published at the
+ * `@nanobpm/agentic/protocol/conformance` subpath.
+ */
+export { MESSAGE_FAMILIES, FAMILY_CODES, familyForCode, isMessageFamily, type MessageFamily, } from "./families.ts";
+export { QOS_LANES, LANE_CODES, laneForCode, lanePriority, isQosLane, compareFrameOrder, type QosLane, } from "./lanes.ts";
+export { encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, FRAME_MAGIC, FRAME_VERSION, FRAME_HEADER_BYTES, MAX_SEQ, type Frame, type FrameDecodeErrorCode, type FrameEncodeErrorCode, } from "./frame.ts";
+export { parseToken, formatToken, isValidToken, isSegmentName, isSeatLabel, TokenParseError, type RoutingToken, type TokenParseErrorCode, } from "./token.ts";
+export { validateVocabDocument, type VocabDocument, type VocabNetwork, type VocabRole, type VocabError, type VocabValidationResult, } from "./vocab/schema.ts";
+export { validatePayload, type Capability, type RegisterPayload, type HeartbeatPayload, type DeregisterPayload, type ServePayload, type DemandPayload, type BlackboardPayload, type BlackboardOp, type RelayPayload, type PayloadError, type PayloadValidationResult, } from "./payloads.ts";
+export { bytesToHex, hexToBytes } from "./hex.ts";

package/dist/protocol/index.js

@@ -0,0 +1,23 @@
+/**
+ * @nanobpm/agentic/protocol — the wire contract for the Nano agentic protocol
+ * (ADR 0056): one app-tier channel carrying agent presence/registry,
+ * demand×supply, the blackboard and live terminal relay.
+ *
+ * This package is the single source of truth every other slice keys off:
+ *  - the canonical message-family set ({@link MESSAGE_FAMILIES}),
+ *  - the three QoS lanes ({@link QOS_LANES}),
+ *  - the frame codec ({@link encodeFrame} / {@link decodeFrame}),
+ *  - the routing-token grammar ({@link parseToken}),
+ *  - the vocab-artifact schema ({@link validateVocabDocument}), and
+ *  - per-family payload contracts ({@link validatePayload}).
+ *
+ * The shared conformance corpus is published at the
+ * `@nanobpm/agentic/protocol/conformance` subpath.
+ */
+export { MESSAGE_FAMILIES, FAMILY_CODES, familyForCode, isMessageFamily, } from "./families.js";
+export { QOS_LANES, LANE_CODES, laneForCode, lanePriority, isQosLane, compareFrameOrder, } from "./lanes.js";
+export { encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, FRAME_MAGIC, FRAME_VERSION, FRAME_HEADER_BYTES, MAX_SEQ, } from "./frame.js";
+export { parseToken, formatToken, isValidToken, isSegmentName, isSeatLabel, TokenParseError, } from "./token.js";
+export { validateVocabDocument, } from "./vocab/schema.js";
+export { validatePayload, } from "./payloads.js";
+export { bytesToHex, hexToBytes } from "./hex.js";

package/dist/protocol/lanes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const QOS_LANES: readonly ["control", "interactive", "bulk"];
+export type QosLane = (typeof QOS_LANES)[number];
+export declare function isQosLane(value: unknown): value is QosLane;
+/**
+ * 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 declare const LANE_CODES: {
+    readonly control: 0;
+    readonly interactive: 1;
+    readonly bulk: 2;
+};
+export declare function laneForCode(code: number): QosLane | undefined;
+/** Priority rank of a lane; lower is dispatched first. */
+export declare function lanePriority(lane: QosLane): number;
+/**
+ * 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 declare function compareFrameOrder(a: {
+    readonly lane: QosLane;
+    readonly seq: number;
+}, b: {
+    readonly lane: QosLane;
+    readonly seq: number;
+}): number;

package/dist/protocol/lanes.js

@@ -0,0 +1,40 @@
+/**
+ * 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"];
+const LANE_SET = new Set(QOS_LANES);
+export function isQosLane(value) {
+    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,
+};
+const CODE_TO_LANE = new Map(QOS_LANES.map((lane) => [LANE_CODES[lane], lane]));
+export function laneForCode(code) {
+    return CODE_TO_LANE.get(code);
+}
+/** Priority rank of a lane; lower is dispatched first. */
+export function lanePriority(lane) {
+    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, b) {
+    const byLane = lanePriority(a.lane) - lanePriority(b.lane);
+    return byLane !== 0 ? byLane : a.seq - b.seq;
+}

package/dist/protocol/payloads.d.ts

@@ -0,0 +1,64 @@
+import { type MessageFamily } from "./families.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[];
+};
+/**
+ * Validate a decoded payload against its family's minimal contract.
+ */
+export declare function validatePayload(family: MessageFamily, payload: unknown): PayloadValidationResult;

package/dist/protocol/payloads.js

@@ -0,0 +1,122 @@
+import { isMessageFamily } from "./families.js";
+import { isValidToken } from "./token.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function validateRegister(p, errors) {
+    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"]) {
+        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, p, errors) {
+    if (!nonEmptyString(p.instance)) {
+        errors.push({ code: "bad-instance", message: `${family}.instance must be a non-empty string` });
+    }
+}
+function validateDeregister(p, errors) {
+    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, errors) {
+    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, errors) {
+    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, errors) {
+    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, errors) {
+    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, payload) {
+    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 = [];
+    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/dist/protocol/token.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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;
+}
+/** True when `name` is a valid network/subnetwork/role segment. */
+export declare function isSegmentName(name: string): boolean;
+/** True when `seat` is a valid seat label. */
+export declare function isSeatLabel(seat: string): boolean;
+export type TokenParseErrorCode = "empty" | "whitespace" | "multiple-seat-markers" | "empty-seat" | "bad-seat" | "empty-segment" | "bad-segment";
+export declare class TokenParseError extends Error {
+    readonly code: TokenParseErrorCode;
+    constructor(code: TokenParseErrorCode, message: string);
+}
+export declare function parseToken(token: string): RoutingToken;
+export declare function isValidToken(token: string): boolean;
+export declare function formatToken(token: RoutingToken): string;

package/dist/protocol/token.js

@@ -0,0 +1,81 @@
+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) {
+    return SEGMENT_RE.test(name);
+}
+/** True when `seat` is a valid seat label. */
+export function isSeatLabel(seat) {
+    return SEAT_RE.test(seat);
+}
+export class TokenParseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TokenParseError";
+        this.code = code;
+    }
+}
+export function parseToken(token) {
+    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) {
+    try {
+        parseToken(token);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function formatToken(token) {
+    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/dist/protocol/vocab/schema.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The versioned vocab artifact: the capability→token map applied over the
+ * channel (REGISTER → SERVE). It is authoritative and out-of-band from any
+ * worker — no capability→token map is ever baked into a worker.
+ *
+ * Core vocabulary ships opinionated and works out of the box; authors extend it
+ * by adding networks/subnetworks/roles in THIS SAME schema (there is no second
+ * schema for extensions).
+ *
+ * Per-role attributes:
+ *  - `requires`             — enrolment capability requirements (the registry
+ *                             gate). These gate WHO may fill the role; they are
+ *                             never encoded in the routing token.
+ *  - `weight`               — cognition weight for the role.
+ *  - `seats`                — either a seat count (integer ≥ 0) or an explicit
+ *                             list of named seats (each a valid seat label).
+ *  - `seatsDistinctFamily`  — diversity SLO: when true, seats of this role must
+ *                             be filled by distinct families (e.g. #red ≠ #blue).
+ */
+export interface VocabRole {
+    readonly requires?: readonly string[];
+    readonly weight?: number;
+    readonly seats?: number | readonly string[];
+    readonly seatsDistinctFamily?: boolean;
+}
+export interface VocabNetwork {
+    readonly roles?: Readonly<Record<string, VocabRole>>;
+    readonly subnetworks?: Readonly<Record<string, VocabNetwork>>;
+}
+export interface VocabDocument {
+    readonly version: number;
+    readonly networks: Readonly<Record<string, VocabNetwork>>;
+}
+export interface VocabError {
+    readonly path: string;
+    readonly code: string;
+    readonly message: string;
+}
+export type VocabValidationResult = {
+    readonly ok: true;
+    readonly value: VocabDocument;
+} | {
+    readonly ok: false;
+    readonly errors: readonly VocabError[];
+};
+/**
+ * Validate an unknown value against the vocab-artifact schema. On success the
+ * returned `value` is a newly constructed {@link VocabDocument} normalized from
+ * the input — it does not share referential identity with `input`.
+ */
+export declare function validateVocabDocument(input: unknown): VocabValidationResult;