@nanobpm/agentic 0.1.0

package/dist/protocol/conformance/frames.d.ts

@@ -0,0 +1,24 @@
+import type { Frame } from "../frame.ts";
+/** The channels a golden frame may travel on. Single source of truth for the
+ * direction contract — the corpus completeness test derives its coverage from
+ * this union so a new variant cannot be added without a covering vector. */
+export type FrameDirection = "worker->hub" | "hub->worker" | "hub->observers";
+/**
+ * Golden frame vectors: canonical (frame ↔ bytes) pairs the codec must satisfy
+ * in BOTH directions. `hex` is the exact wire encoding of `frame`. These are
+ * committed goldens — a codec change that alters the wire bytes fails the
+ * round-trip test, catching drift between this repo and the c8ctl client.
+ *
+ * Coverage spans every message family, every QoS lane, both directions, and
+ * boundary values (seq = 0, seq = uint32 max, null payload, empty string,
+ * multi-byte UTF-8).
+ */
+export interface GoldenFrame {
+    readonly name: string;
+    /** Informational: which way the frame travels on the channel. */
+    readonly direction: FrameDirection;
+    readonly frame: Frame;
+    /** Exact wire encoding of `frame`, as a lowercase hex string. */
+    readonly hex: string;
+}
+export declare const GOLDEN_FRAMES: readonly GoldenFrame[];

package/dist/protocol/conformance/frames.js

@@ -0,0 +1,116 @@
+export const GOLDEN_FRAMES = [
+    {
+        name: "register-worker-to-hub",
+        direction: "worker->hub",
+        frame: {
+            lane: "control",
+            family: "register",
+            seq: 1,
+            payload: {
+                instance: "w-abc123",
+                capability: { cognition: "opus", weight: 3, family: "anthropic", host: "mac-01" },
+            },
+        },
+        hex: "4e4101000100000001000000697b22696e7374616e6365223a22772d616263313233222c226361706162696c697479223a7b22636f676e6974696f6e223a226f707573222c22776569676874223a332c2266616d696c79223a22616e7468726f706963222c22686f7374223a226d61632d3031227d7d",
+    },
+    {
+        name: "heartbeat-seq-zero",
+        direction: "worker->hub",
+        frame: { lane: "control", family: "heartbeat", seq: 0, payload: { instance: "w-abc123" } },
+        hex: "4e4101000200000000000000177b22696e7374616e6365223a22772d616263313233227d",
+    },
+    {
+        name: "deregister-with-reason",
+        direction: "worker->hub",
+        frame: {
+            lane: "control",
+            family: "deregister",
+            seq: 42,
+            payload: { instance: "w-abc123", reason: "shutdown" },
+        },
+        hex: "4e410100030000002a0000002b7b22696e7374616e6365223a22772d616263313233222c22726561736f6e223a2273687574646f776e227d",
+    },
+    {
+        name: "serve-hub-to-worker",
+        direction: "hub->worker",
+        frame: {
+            lane: "control",
+            family: "serve",
+            seq: 2,
+            payload: { instance: "w-abc123", tokens: ["implementation.qa.red#1", "planning.decide"] },
+        },
+        hex: "4e41010004000000020000004e7b22696e7374616e6365223a22772d616263313233222c22746f6b656e73223a5b22696d706c656d656e746174696f6e2e71612e7265642331222c22706c616e6e696e672e646563696465225d7d",
+    },
+    {
+        name: "demand-hub-to-observers",
+        direction: "hub->observers",
+        frame: {
+            lane: "control",
+            family: "demand",
+            seq: 7,
+            payload: { network: "implementation", missing: ["implementation.ci"] },
+        },
+        hex: "4e41010005000000070000003c7b226e6574776f726b223a22696d706c656d656e746174696f6e222c226d697373696e67223a5b22696d706c656d656e746174696f6e2e6369225d7d",
+    },
+    {
+        name: "blackboard-append-interactive",
+        direction: "worker->hub",
+        frame: {
+            lane: "interactive",
+            family: "blackboard",
+            seq: 100,
+            payload: { op: "append", dedupeKey: "regen-before-build" },
+        },
+        hex: "4e4101010600000064000000307b226f70223a22617070656e64222c226465647570654b6579223a22726567656e2d6265666f72652d6275696c64227d",
+    },
+    {
+        name: "blackboard-read-interactive",
+        direction: "worker->hub",
+        frame: {
+            lane: "interactive",
+            family: "blackboard",
+            seq: 101,
+            payload: { op: "read", since: 12 },
+        },
+        hex: "4e4101010600000065000000187b226f70223a2272656164222c2273696e6365223a31327d",
+    },
+    {
+        name: "relay-chunk-bulk",
+        direction: "worker->hub",
+        frame: {
+            lane: "bulk",
+            family: "relay",
+            seq: 5,
+            payload: { stream: "job-1223", offset: 2048, chunk: "hello world\n" },
+        },
+        hex: "4e41010207000000050000003b7b2273747265616d223a226a6f622d31323233222c226f6666736574223a323034382c226368756e6b223a2268656c6c6f20776f726c645c6e227d",
+    },
+    {
+        name: "relay-seq-max-bulk",
+        direction: "hub->worker",
+        frame: {
+            lane: "bulk",
+            family: "relay",
+            seq: 4294967295,
+            payload: { stream: "job-1223", offset: 0, chunk: "" },
+        },
+        hex: "4e41010207ffffffff0000002b7b2273747265616d223a226a6f622d31323233222c226f6666736574223a302c226368756e6b223a22227d",
+    },
+    {
+        name: "null-payload-envelope",
+        direction: "hub->worker",
+        frame: { lane: "control", family: "heartbeat", seq: 3, payload: null },
+        hex: "4e4101000200000003000000046e756c6c",
+    },
+    {
+        name: "unicode-payload-relay",
+        direction: "worker->hub",
+        frame: {
+            lane: "bulk",
+            family: "relay",
+            seq: 9,
+            payload: { stream: "job-1223", offset: 4, chunk: "✓ café — 日本語" },
+        },
+        hex: "4e4101020700000009000000427b2273747265616d223a226a6f622d31323233222c226f6666736574223a342c226368756e6b223a22e29c9320636166c3a920e2809420e697a5e69cace8aa9e227d",
+    },
+];

package/dist/protocol/conformance/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared conformance corpus for the Nano agentic protocol.
+ *
+ * Exported so cross-repo tests (this repo AND jwulf/c8ctl-plugin-nano) consume
+ * the SAME golden frames, malformed vectors, vocab documents and token vectors.
+ * Import it and hold your codec/client to it:
+ *
+ *   import { GOLDEN_FRAMES, MALFORMED_FRAMES } from "./index.ts";
+ */
+export { GOLDEN_FRAMES, type GoldenFrame, } from "./frames.ts";
+export { MALFORMED_FRAMES, type MalformedFrame, } from "./malformed.ts";
+export { VALID_VOCABS, INVALID_VOCABS, type ValidVocab, type InvalidVocab, } from "./vocab.ts";
+export { VALID_TOKENS, INVALID_TOKENS, type ValidToken, type InvalidToken, } from "./tokens.ts";

package/dist/protocol/conformance/index.js

@@ -0,0 +1,13 @@
+/**
+ * Shared conformance corpus for the Nano agentic protocol.
+ *
+ * Exported so cross-repo tests (this repo AND jwulf/c8ctl-plugin-nano) consume
+ * the SAME golden frames, malformed vectors, vocab documents and token vectors.
+ * Import it and hold your codec/client to it:
+ *
+ *   import { GOLDEN_FRAMES, MALFORMED_FRAMES } from "./index.ts";
+ */
+export { GOLDEN_FRAMES, } from "./frames.js";
+export { MALFORMED_FRAMES, } from "./malformed.js";
+export { VALID_VOCABS, INVALID_VOCABS, } from "./vocab.js";
+export { VALID_TOKENS, INVALID_TOKENS, } from "./tokens.js";

package/dist/protocol/conformance/malformed.d.ts

@@ -0,0 +1,14 @@
+import type { FrameDecodeErrorCode } from "../frame.ts";
+/**
+ * Malformed frame vectors: adversarial byte sequences that MUST be rejected,
+ * each paired with the exact {@link FrameDecodeErrorCode} the decoder must
+ * raise. A shared prose spec does not stop divergence — shared adversarial
+ * vectors do. Both this decoder and the c8ctl client are held to these.
+ */
+export interface MalformedFrame {
+    readonly name: string;
+    /** The raw bytes to feed the decoder, as a lowercase hex string (may be ""). */
+    readonly hex: string;
+    readonly expected: FrameDecodeErrorCode;
+}
+export declare const MALFORMED_FRAMES: readonly MalformedFrame[];

package/dist/protocol/conformance/malformed.js

@@ -0,0 +1,44 @@
+export const MALFORMED_FRAMES = [
+    { name: "empty-buffer", hex: "", expected: "empty" },
+    { name: "short-header", hex: "4e410100", expected: "short-header" },
+    {
+        name: "bad-magic",
+        hex: "ffff01000200000000000000177b22696e7374616e6365223a22772d616263313233227d",
+        expected: "bad-magic",
+    },
+    {
+        name: "unsupported-version",
+        hex: "4e4102000200000000000000177b22696e7374616e6365223a22772d616263313233227d",
+        expected: "unsupported-version",
+    },
+    {
+        name: "unknown-lane",
+        hex: "4e4101090200000000000000177b22696e7374616e6365223a22772d616263313233227d",
+        expected: "unknown-lane",
+    },
+    {
+        name: "unknown-family",
+        hex: "4e4101006300000000000000177b22696e7374616e6365223a22772d616263313233227d",
+        expected: "unknown-family",
+    },
+    {
+        name: "truncated-payload",
+        hex: "4e4101000200000000000000177b",
+        expected: "truncated-payload",
+    },
+    {
+        name: "trailing-bytes",
+        hex: "4e4101000200000000000000177b22696e7374616e6365223a22772d616263313233227d00",
+        expected: "trailing-bytes",
+    },
+    {
+        name: "invalid-payload-json-nonjson",
+        hex: "4e4101000200000000000000027a7a",
+        expected: "invalid-payload-json",
+    },
+    {
+        name: "invalid-payload-json-bad-utf8",
+        hex: "4e410100020000000000000001ff",
+        expected: "invalid-payload-json",
+    },
+];

package/dist/protocol/conformance/tokens.d.ts

@@ -0,0 +1,19 @@
+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 declare const VALID_TOKENS: readonly ValidToken[];
+export declare const INVALID_TOKENS: readonly InvalidToken[];

package/dist/protocol/conformance/tokens.js

@@ -0,0 +1,49 @@
+export const VALID_TOKENS = [
+    {
+        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 = [
+    { 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/dist/protocol/conformance/vocab.d.ts

@@ -0,0 +1,23 @@
+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 declare const VALID_VOCABS: readonly ValidVocab[];
+export declare const INVALID_VOCABS: readonly InvalidVocab[];

package/dist/protocol/conformance/vocab.js

@@ -0,0 +1,97 @@
+export const VALID_VOCABS = [
+    {
+        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 = [
+    { 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/dist/protocol/families.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare const MESSAGE_FAMILIES: readonly ["register", "heartbeat", "deregister", "serve", "demand", "blackboard", "relay"];
+export type MessageFamily = (typeof MESSAGE_FAMILIES)[number];
+export declare function isMessageFamily(value: unknown): value is MessageFamily;
+/**
+ * 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 declare const FAMILY_CODES: {
+    readonly register: 1;
+    readonly heartbeat: 2;
+    readonly deregister: 3;
+    readonly serve: 4;
+    readonly demand: 5;
+    readonly blackboard: 6;
+    readonly relay: 7;
+};
+export declare function familyForCode(code: number): MessageFamily | undefined;

package/dist/protocol/families.js

@@ -0,0 +1,45 @@
+/**
+ * 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",
+];
+const FAMILY_SET = new Set(MESSAGE_FAMILIES);
+export function isMessageFamily(value) {
+    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,
+};
+const CODE_TO_FAMILY = new Map(MESSAGE_FAMILIES.map((family) => [FAMILY_CODES[family], family]));
+export function familyForCode(code) {
+    return CODE_TO_FAMILY.get(code);
+}

package/dist/protocol/frame.d.ts

@@ -0,0 +1,45 @@
+import { type MessageFamily } from "./families.ts";
+import { 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 declare const FRAME_MAGIC = 20033;
+export declare const FRAME_VERSION = 1;
+export declare const FRAME_HEADER_BYTES = 13;
+export declare const MAX_SEQ = 4294967295;
+export type FrameDecodeErrorCode = "empty" | "short-header" | "bad-magic" | "unsupported-version" | "unknown-lane" | "unknown-family" | "truncated-payload" | "trailing-bytes" | "invalid-payload-json";
+export declare class FrameDecodeError extends Error {
+    readonly code: FrameDecodeErrorCode;
+    constructor(code: FrameDecodeErrorCode, message: string);
+}
+export type FrameEncodeErrorCode = "invalid-lane" | "invalid-family" | "invalid-seq" | "unserialisable-payload";
+export declare class FrameEncodeError extends Error {
+    readonly code: FrameEncodeErrorCode;
+    constructor(code: FrameEncodeErrorCode, message: string);
+}
+export declare function encodeFrame(frame: Frame): Uint8Array;
+export declare function decodeFrame(bytes: Uint8Array): Frame;

package/dist/protocol/frame.js

@@ -0,0 +1,114 @@
+import { FAMILY_CODES, familyForCode, isMessageFamily, } from "./families.js";
+import { LANE_CODES, laneForCode, isQosLane } from "./lanes.js";
+/**
+ * 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 class FrameDecodeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "FrameDecodeError";
+        this.code = code;
+    }
+}
+export class FrameEncodeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "FrameEncodeError";
+        this.code = code;
+    }
+}
+export function encodeFrame(frame) {
+    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;
+    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) {
+    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;
+    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/dist/protocol/hex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;