@nanobpm/agentic 0.1.0

package/src/protocol/conformance/tokens.ts

@@ -0,0 +1,70 @@
+import type { RoutingToken, TokenParseErrorCode } from "../token.ts";
+
+/**
+ * Routing-token vectors. Valid ones assert the parse decomposes exactly as
+ * `network[.subnetwork…].role[#seat]`; invalid ones assert the grammar rejects
+ * with a specific {@link TokenParseErrorCode}. Capability is never present in a
+ * token — there is deliberately no "capability" field to parse.
+ */
+export interface ValidToken {
+  readonly name: string;
+  readonly token: string;
+  readonly parsed: RoutingToken;
+}
+
+export interface InvalidToken {
+  readonly name: string;
+  readonly token: string;
+  readonly expected: TokenParseErrorCode;
+}
+
+export const VALID_TOKENS: readonly ValidToken[] = [
+  {
+    name: "single-segment-role",
+    token: "decide",
+    parsed: { subnetworks: [], role: "decide" },
+  },
+  {
+    name: "network-and-role",
+    token: "planning.decide",
+    parsed: { network: "planning", subnetworks: [], role: "decide" },
+  },
+  {
+    name: "nested-subnetwork",
+    token: "implementation.ci.fix",
+    parsed: { network: "implementation", subnetworks: ["ci"], role: "fix" },
+  },
+  {
+    name: "role-with-named-seat",
+    token: "qa.review#red",
+    parsed: { network: "qa", subnetworks: [], role: "review", seat: "red" },
+  },
+  {
+    name: "role-with-numeric-seat",
+    token: "implementation.qa.red#1",
+    parsed: { network: "implementation", subnetworks: ["qa"], role: "red", seat: "1" },
+  },
+  {
+    name: "hyphenated-segments",
+    token: "code-review.fast-lane.senior-dev#blue",
+    parsed: {
+      network: "code-review",
+      subnetworks: ["fast-lane"],
+      role: "senior-dev",
+      seat: "blue",
+    },
+  },
+];
+
+export const INVALID_TOKENS: readonly InvalidToken[] = [
+  { name: "empty", token: "", expected: "empty" },
+  { name: "whitespace", token: "planning .decide", expected: "whitespace" },
+  { name: "leading-dot", token: ".decide", expected: "empty-segment" },
+  { name: "trailing-dot", token: "planning.", expected: "empty-segment" },
+  { name: "double-dot", token: "planning..decide", expected: "empty-segment" },
+  { name: "uppercase-segment", token: "Planning.decide", expected: "bad-segment" },
+  { name: "segment-starts-with-digit", token: "1planning.decide", expected: "bad-segment" },
+  { name: "two-seat-markers", token: "qa.review#red#blue", expected: "multiple-seat-markers" },
+  { name: "empty-seat", token: "qa.review#", expected: "empty-seat" },
+  { name: "uppercase-seat", token: "qa.review#Red", expected: "bad-seat" },
+];

package/src/protocol/conformance/vocab.ts

@@ -0,0 +1,122 @@
+import type { VocabDocument } from "../vocab/schema.ts";
+
+/**
+ * Valid vocab documents (core-shaped + an author extension) and invalid ones
+ * paired with the error code they must surface. Shared so the c8ctl client's
+ * resolver is held to the same schema this repo's validator enforces.
+ *
+ * NOTE: the FULL opinionated core vocabulary is S3's deliverable; the valid
+ * document below is a representative, schema-complete sample (it exercises
+ * `requires`, `weight`, numeric `seats`, named `seats`, and
+ * `seatsDistinctFamily`), not the canonical core artifact.
+ */
+export interface ValidVocab {
+  readonly name: string;
+  readonly document: VocabDocument;
+}
+
+export interface InvalidVocab {
+  readonly name: string;
+  readonly document: unknown;
+  /** A `code` that MUST appear among the validation errors. */
+  readonly expectedCode: string;
+}
+
+export const VALID_VOCABS: readonly ValidVocab[] = [
+  {
+    name: "core-shaped-sample",
+    document: {
+      version: 1,
+      networks: {
+        planning: {
+          roles: {
+            decide: { requires: ["cognition=reasoning"], weight: 3, seats: 1 },
+          },
+        },
+        qa: {
+          roles: {
+            review: {
+              requires: ["cognition=reasoning"],
+              weight: 2,
+              seats: ["red", "blue"],
+              seatsDistinctFamily: true,
+            },
+          },
+        },
+        implementation: {
+          roles: { senior: { weight: 3, seats: 4 } },
+          subnetworks: {
+            ci: { roles: { fix: { weight: 1, seats: 2 } } },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: "author-extension-merges-in-same-schema",
+    document: {
+      version: 2,
+      networks: {
+        support: {
+          roles: {
+            triage: { requires: ["host=on-call"], weight: 1, seats: 3 },
+          },
+        },
+      },
+    },
+  },
+];
+
+export const INVALID_VOCABS: readonly InvalidVocab[] = [
+  { name: "not-an-object", document: 42, expectedCode: "not-object" },
+  { name: "missing-version", document: { networks: {} }, expectedCode: "bad-version" },
+  { name: "zero-version", document: { version: 0, networks: {} }, expectedCode: "bad-version" },
+  {
+    name: "missing-networks",
+    document: { version: 1 },
+    expectedCode: "bad-networks",
+  },
+  {
+    name: "unknown-document-field",
+    document: { version: 1, networks: {}, extra: true },
+    expectedCode: "unknown-document-field",
+  },
+  {
+    name: "bad-network-name",
+    document: { version: 1, networks: { "Bad Name": { roles: {} } } },
+    expectedCode: "bad-network-name",
+  },
+  {
+    name: "unknown-role-field",
+    document: { version: 1, networks: { planning: { roles: { decide: { bogus: 1 } } } } },
+    expectedCode: "unknown-role-field",
+  },
+  {
+    name: "bad-weight",
+    document: { version: 1, networks: { planning: { roles: { decide: { weight: "high" } } } } },
+    expectedCode: "bad-weight",
+  },
+  {
+    name: "bad-seats-count",
+    document: { version: 1, networks: { planning: { roles: { decide: { seats: -1 } } } } },
+    expectedCode: "bad-seats",
+  },
+  {
+    name: "bad-named-seat",
+    document: { version: 1, networks: { qa: { roles: { review: { seats: ["Red"] } } } } },
+    expectedCode: "bad-seat-label",
+  },
+  {
+    name: "bad-requires",
+    document: { version: 1, networks: { planning: { roles: { decide: { requires: "x" } } } } },
+    expectedCode: "bad-requires",
+  },
+  {
+    name: "bad-seats-distinct-family",
+    document: {
+      version: 1,
+      networks: { qa: { roles: { review: { seatsDistinctFamily: "yes" } } } },
+    },
+    expectedCode: "bad-seats-distinct-family",
+  },
+];

package/src/protocol/families.ts

@@ -0,0 +1,54 @@
+/**
+ * Canonical message-family set for the Nano agentic protocol.
+ *
+ * This is the single source of truth every family module keys off — S1's
+ * `registerFamilyHandler(family, handler)` seam, the frame codec, and each
+ * per-family module all derive their family key from {@link MESSAGE_FAMILIES}.
+ * Do not fork this list; extend it here.
+ *
+ * Directions (informational — the codec is direction-agnostic):
+ *  - `register` / `heartbeat` / `deregister` — worker → hub (presence)
+ *  - `serve`                                 — hub → worker (assigned tokens)
+ *  - `demand`                                — hub → observers (demand×supply)
+ *  - `blackboard`                            — both directions (coordination)
+ *  - `relay`                                 — both directions (terminal bytes)
+ */
+export const MESSAGE_FAMILIES = [
+  "register",
+  "heartbeat",
+  "deregister",
+  "serve",
+  "demand",
+  "blackboard",
+  "relay",
+] as const;
+
+export type MessageFamily = (typeof MESSAGE_FAMILIES)[number];
+
+const FAMILY_SET: ReadonlySet<string> = new Set(MESSAGE_FAMILIES);
+
+export function isMessageFamily(value: unknown): value is MessageFamily {
+  return typeof value === "string" && FAMILY_SET.has(value);
+}
+
+/**
+ * Stable on-wire codes for each family. Codes are part of the wire contract and
+ * MUST NOT be renumbered; only append new families with new, unused codes.
+ */
+export const FAMILY_CODES = {
+  register: 1,
+  heartbeat: 2,
+  deregister: 3,
+  serve: 4,
+  demand: 5,
+  blackboard: 6,
+  relay: 7,
+} as const satisfies Record<MessageFamily, number>;
+
+const CODE_TO_FAMILY: ReadonlyMap<number, MessageFamily> = new Map(
+  MESSAGE_FAMILIES.map((family) => [FAMILY_CODES[family], family]),
+);
+
+export function familyForCode(code: number): MessageFamily | undefined {
+  return CODE_TO_FAMILY.get(code);
+}

package/src/protocol/frame.test.ts

@@ -0,0 +1,116 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  decodeFrame,
+  encodeFrame,
+  FrameDecodeError,
+  FrameEncodeError,
+  MAX_SEQ,
+  type Frame,
+} from "./frame.ts";
+import { bytesToHex, hexToBytes } from "./hex.ts";
+import { GOLDEN_FRAMES } from "./conformance/frames.ts";
+import { MALFORMED_FRAMES } from "./conformance/malformed.ts";
+
+test("golden frames: encode matches the committed wire hex", () => {
+  for (const golden of GOLDEN_FRAMES) {
+    assert.equal(bytesToHex(encodeFrame(golden.frame)), golden.hex, golden.name);
+  }
+});
+
+test("golden frames: decode reproduces the frame (round-trip both directions)", () => {
+  for (const golden of GOLDEN_FRAMES) {
+    const decoded = decodeFrame(hexToBytes(golden.hex));
+    assert.deepEqual(decoded, golden.frame, golden.name);
+    // And re-encoding the decoded frame is byte-identical.
+    assert.equal(bytesToHex(encodeFrame(decoded)), golden.hex, golden.name);
+  }
+});
+
+test("malformed frames: decode rejects with the specified error code", () => {
+  for (const vector of MALFORMED_FRAMES) {
+    assert.throws(
+      () => decodeFrame(hexToBytes(vector.hex)),
+      (error: unknown) => {
+        assert.ok(error instanceof FrameDecodeError, `${vector.name}: expected FrameDecodeError`);
+        assert.equal(error.code, vector.expected, vector.name);
+        return true;
+      },
+      vector.name,
+    );
+  }
+});
+
+test("decode: decodes a frame subarray with a non-zero byteOffset correctly", () => {
+  // Guards the DataView(byteOffset,length) wiring: a valid frame embedded in a
+  // larger buffer must decode from its subarray view, not from offset 0.
+  const golden = GOLDEN_FRAMES[0];
+  const bytes = hexToBytes(golden.hex);
+  const padded = new Uint8Array(bytes.length + 5);
+  padded.set(bytes, 5);
+  const view = padded.subarray(5);
+  assert.deepEqual(decodeFrame(view), golden.frame);
+});
+
+test("encode: rejects an invalid lane", () => {
+  const frame: Frame = JSON.parse('{"lane":"urgent","family":"relay","seq":0,"payload":null}');
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "invalid-lane",
+  );
+});
+
+test("encode: rejects an invalid family", () => {
+  const frame: Frame = JSON.parse('{"lane":"control","family":"gossip","seq":0,"payload":null}');
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "invalid-family",
+  );
+});
+
+test("encode: rejects out-of-range seq (boundary above uint32 max)", () => {
+  const frame: Frame = { lane: "control", family: "heartbeat", seq: MAX_SEQ + 1, payload: null };
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "invalid-seq",
+  );
+});
+
+test("encode: rejects a non-integer seq", () => {
+  const frame: Frame = { lane: "control", family: "heartbeat", seq: 1.5, payload: null };
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "invalid-seq",
+  );
+});
+
+test("encode: rejects an unserialisable payload (bigint)", () => {
+  const frame: Frame = { lane: "bulk", family: "relay", seq: 0, payload: { n: 1n } };
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "unserialisable-payload",
+  );
+});
+
+test("encode: rejects a top-level undefined payload (not coerced to null)", () => {
+  // A top-level `undefined` is not valid JSON; the codec must reject it rather
+  // than silently coerce it to `null`, which would mask a caller that forgot to
+  // set a payload and make the encoding non-invertible.
+  const frame: Frame = { lane: "bulk", family: "relay", seq: 0, payload: undefined };
+  assert.throws(
+    () => encodeFrame(frame),
+    (error: unknown) => error instanceof FrameEncodeError && error.code === "unserialisable-payload",
+  );
+});
+
+test("encode: a null payload round-trips (null is valid JSON)", () => {
+  const frame: Frame = { lane: "control", family: "heartbeat", seq: 0, payload: null };
+  assert.deepEqual(decodeFrame(encodeFrame(frame)), frame);
+});
+
+test("encode: seq boundaries 0 and uint32 max round-trip", () => {
+  for (const seq of [0, MAX_SEQ]) {
+    const frame: Frame = { lane: "control", family: "heartbeat", seq, payload: { instance: "w" } };
+    assert.deepEqual(decodeFrame(encodeFrame(frame)), frame);
+  }
+});

package/src/protocol/frame.ts

@@ -0,0 +1,171 @@
+import {
+  FAMILY_CODES,
+  familyForCode,
+  isMessageFamily,
+  type MessageFamily,
+} from "./families.ts";
+import { LANE_CODES, laneForCode, isQosLane, type QosLane } from "./lanes.ts";
+
+/**
+ * A single agentic-channel frame: the QoS lane it rides, the message family it
+ * belongs to, a monotonic sequence number (used by the relay for
+ * resume-from-offset), and a JSON-serialisable family payload.
+ *
+ * The codec is an ENVELOPE codec — it does not interpret `payload` beyond
+ * round-tripping it as JSON. Per-family payload shape is validated separately
+ * (see `payloads.ts`).
+ */
+export interface Frame {
+  readonly lane: QosLane;
+  readonly family: MessageFamily;
+  readonly seq: number;
+  readonly payload: unknown;
+}
+
+/**
+ * Wire layout (all integers big-endian, unsigned):
+ *
+ *   offset  size  field
+ *   0       2     magic       0x4E41 ("NA")
+ *   2       1     version     = 1
+ *   3       1     lane code   0=control | 1=interactive | 2=bulk
+ *   4       1     family code 1..7 (see FAMILY_CODES)
+ *   5       4     seq         uint32
+ *   9       4     payloadLen  uint32 (bytes of UTF-8 JSON that follow)
+ *   13      N     payload     UTF-8 JSON
+ */
+export const FRAME_MAGIC = 0x4e41;
+export const FRAME_VERSION = 1;
+export const FRAME_HEADER_BYTES = 13;
+export const MAX_SEQ = 0xffffffff;
+
+export type FrameDecodeErrorCode =
+  | "empty"
+  | "short-header"
+  | "bad-magic"
+  | "unsupported-version"
+  | "unknown-lane"
+  | "unknown-family"
+  | "truncated-payload"
+  | "trailing-bytes"
+  | "invalid-payload-json";
+
+export class FrameDecodeError extends Error {
+  readonly code: FrameDecodeErrorCode;
+  constructor(code: FrameDecodeErrorCode, message: string) {
+    super(message);
+    this.name = "FrameDecodeError";
+    this.code = code;
+  }
+}
+
+export type FrameEncodeErrorCode =
+  | "invalid-lane"
+  | "invalid-family"
+  | "invalid-seq"
+  | "unserialisable-payload";
+
+export class FrameEncodeError extends Error {
+  readonly code: FrameEncodeErrorCode;
+  constructor(code: FrameEncodeErrorCode, message: string) {
+    super(message);
+    this.name = "FrameEncodeError";
+    this.code = code;
+  }
+}
+
+export function encodeFrame(frame: Frame): Uint8Array {
+  if (!isQosLane(frame.lane)) {
+    throw new FrameEncodeError("invalid-lane", `unknown QoS lane: ${String(frame.lane)}`);
+  }
+  if (!isMessageFamily(frame.family)) {
+    throw new FrameEncodeError("invalid-family", `unknown message family: ${String(frame.family)}`);
+  }
+  if (!Number.isInteger(frame.seq) || frame.seq < 0 || frame.seq > MAX_SEQ) {
+    throw new FrameEncodeError("invalid-seq", `seq must be a uint32, got: ${String(frame.seq)}`);
+  }
+
+  // Encode `payload` as-is: a top-level `undefined` is NOT valid JSON
+  // (`JSON.stringify(undefined) === undefined`), so it is rejected rather than
+  // silently coerced to `null` — that keeps the codec invertible and surfaces a
+  // caller that forgot to set a payload. A `null` payload is valid JSON and
+  // round-trips.
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(frame.payload);
+  } catch {
+    json = undefined;
+  }
+  if (json === undefined) {
+    throw new FrameEncodeError("unserialisable-payload", "payload is not JSON-serialisable");
+  }
+
+  const payloadBytes = new TextEncoder().encode(json);
+  const out = new Uint8Array(FRAME_HEADER_BYTES + payloadBytes.length);
+  const view = new DataView(out.buffer);
+  view.setUint16(0, FRAME_MAGIC);
+  view.setUint8(2, FRAME_VERSION);
+  view.setUint8(3, LANE_CODES[frame.lane]);
+  view.setUint8(4, FAMILY_CODES[frame.family]);
+  view.setUint32(5, frame.seq);
+  view.setUint32(9, payloadBytes.length);
+  out.set(payloadBytes, FRAME_HEADER_BYTES);
+  return out;
+}
+
+export function decodeFrame(bytes: Uint8Array): Frame {
+  if (bytes.length === 0) {
+    throw new FrameDecodeError("empty", "cannot decode an empty buffer");
+  }
+  if (bytes.length < FRAME_HEADER_BYTES) {
+    throw new FrameDecodeError(
+      "short-header",
+      `need at least ${FRAME_HEADER_BYTES} header bytes, got ${bytes.length}`,
+    );
+  }
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint16(0) !== FRAME_MAGIC) {
+    throw new FrameDecodeError("bad-magic", "frame magic mismatch");
+  }
+  const version = view.getUint8(2);
+  if (version !== FRAME_VERSION) {
+    throw new FrameDecodeError("unsupported-version", `unsupported frame version: ${version}`);
+  }
+
+  const lane = laneForCode(view.getUint8(3));
+  if (lane === undefined) {
+    throw new FrameDecodeError("unknown-lane", `unknown lane code: ${view.getUint8(3)}`);
+  }
+  const family = familyForCode(view.getUint8(4));
+  if (family === undefined) {
+    throw new FrameDecodeError("unknown-family", `unknown family code: ${view.getUint8(4)}`);
+  }
+
+  const seq = view.getUint32(5);
+  const payloadLen = view.getUint32(9);
+  const end = FRAME_HEADER_BYTES + payloadLen;
+  if (end > bytes.length) {
+    throw new FrameDecodeError(
+      "truncated-payload",
+      `payload length ${payloadLen} exceeds available ${bytes.length - FRAME_HEADER_BYTES} bytes`,
+    );
+  }
+  if (end < bytes.length) {
+    throw new FrameDecodeError(
+      "trailing-bytes",
+      `${bytes.length - end} trailing byte(s) after payload`,
+    );
+  }
+
+  const payloadBytes = bytes.subarray(FRAME_HEADER_BYTES, end);
+  let payload: unknown;
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(payloadBytes);
+    payload = JSON.parse(text);
+  } catch {
+    throw new FrameDecodeError("invalid-payload-json", "payload is not valid UTF-8 JSON");
+  }
+
+  return { lane, family, seq, payload };
+}

package/src/protocol/hex.ts

@@ -0,0 +1,28 @@
+/**
+ * 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: Uint8Array): string {
+  let out = "";
+  for (const byte of bytes) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  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/src/protocol/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @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";