@nanobpm/agentic 0.1.0

package/src/presence/store.ts

@@ -0,0 +1,287 @@
+/**
+ * The presence & registry store — S2's durable layer over the app DataLayer.
+ *
+ * S1 owns *connection* liveness in-memory (touch-on-frame + a TTL sweep that
+ * closes silent sockets). S2 layers a durable *presence* registry on top: one
+ * row per registered worker instance, carrying its declared capability
+ * (cognition/weight/family/host — an enrolment attribute, never a routing
+ * token), the connection it registered on, and its own `last_seen` liveness
+ * refreshed by heartbeats. Rows age out on the presence TTL via {@link sweep}.
+ *
+ * The store speaks only the tiny synchronous SQLite subset the runtime exposes
+ * ({@link SqliteDb}), so it works against any app DataLayer source without
+ * pulling in the whole runtime.
+ */
+import type { Capability } from "../protocol/index.ts";
+import { systemClock } from "../channel/index.ts";
+import type { Clock } from "../channel/index.ts";
+import { PRESENCE_SCHEMA_SQL, PRESENCE_TABLE } from "./schema.ts";
+
+/**
+ * The minimal synchronous SQLite handle the store needs — structurally the same
+ * surface the Urban runtime's DataLayer exposes (`host.openSqlite`). Kept local
+ * so the store depends on a shape, not on the runtime package.
+ */
+export interface SqliteDb {
+  /** Execute one or more statements with no result (DDL, migrations). */
+  exec(sql: string): void;
+  /** Run a parameterised statement, returning the changed-row count. */
+  run(sql: string, params?: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+  /** Run a parameterised query, returning all rows as plain objects. */
+  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+}
+
+/** A durable presence row for one registered worker instance. */
+export interface PresenceRow {
+  /** The worker instance id (`register.instance`) — the primary key. */
+  readonly instance: string;
+  /** The channel connection the instance last registered on. */
+  readonly connectionId: string;
+  /** The authenticated principal (ADR 0028 identity) of that connection. */
+  readonly identity: string;
+  /** The declared enrolment capability (never a routing token). */
+  readonly capability: Capability;
+  /** When the instance first registered, ISO-8601. */
+  readonly registeredAt: string;
+  /** Last liveness refresh (register/heartbeat), epoch ms. */
+  readonly lastSeen: number;
+}
+
+/** Input to {@link PresenceStore.register}. */
+export interface RegisterInput {
+  readonly instance: string;
+  readonly connectionId: string;
+  readonly identity: string;
+  readonly capability: Capability;
+}
+
+export interface PresenceStoreOptions {
+  /** Presence liveness TTL in ms; a row unseen for longer ages out. Default 30000. */
+  ttlMs?: number;
+  /** Injectable clock for deterministic tests. Default {@link systemClock}. */
+  clock?: Clock;
+}
+
+const DEFAULT_TTL_MS = 30_000;
+
+/**
+ * Raised when a `register` would overwrite an instance already owned by a
+ * different authenticated identity. Presence rows are bound to the identity
+ * that first registered them, so one authenticated peer can never take over
+ * (or change the identity of) another peer's instance.
+ */
+export class PresenceOwnershipError extends Error {
+  readonly instance: string;
+  constructor(instance: string) {
+    super(`instance "${instance}" is registered to a different identity`);
+    this.name = "PresenceOwnershipError";
+    this.instance = instance;
+  }
+}
+
+/** The raw DB row shape (snake_case columns) as read back from SQLite. */
+interface DbRow {
+  instance: string;
+  connection_id: string;
+  identity: string;
+  cognition: string | null;
+  weight: number | null;
+  family: string | null;
+  host: string | null;
+  registered_at: string;
+  last_seen: number;
+}
+
+function buildCapability(row: DbRow): Capability {
+  const cap: {
+    cognition?: string;
+    weight?: number;
+    family?: string;
+    host?: string;
+  } = {};
+  if (row.cognition !== null) cap.cognition = row.cognition;
+  if (row.weight !== null) cap.weight = row.weight;
+  if (row.family !== null) cap.family = row.family;
+  if (row.host !== null) cap.host = row.host;
+  return cap;
+}
+
+function toRow(row: DbRow): PresenceRow {
+  return {
+    instance: row.instance,
+    connectionId: row.connection_id,
+    identity: row.identity,
+    capability: buildCapability(row),
+    registeredAt: row.registered_at,
+    lastSeen: row.last_seen,
+  };
+}
+
+export class PresenceStore {
+  readonly #db: SqliteDb;
+  readonly #ttlMs: number;
+  readonly #clock: Clock;
+
+  constructor(db: SqliteDb, options: PresenceStoreOptions = {}) {
+    this.#db = db;
+    this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.#clock = options.clock ?? systemClock;
+  }
+
+  /** The presence liveness TTL in ms. */
+  get ttlMs(): number {
+    return this.#ttlMs;
+  }
+
+  /**
+   * Apply the canonical presence DDL (idempotent). Callers that let the app
+   * DataLayer migration runner apply `db/migrations/001_agentic_presence.sql`
+   * do not need this — but the family module calls it so the store is usable
+   * against a bare source too. The DDL is identical to the migration (guarded).
+   */
+  ensureSchema(): void {
+    this.#db.exec(PRESENCE_SCHEMA_SQL);
+  }
+
+  /**
+   * Register (or re-register) an instance. A first registration stamps
+   * `registered_at`; a re-registration (e.g. after a reconnect on a new
+   * connection) keeps the original `registered_at` and refreshes everything
+   * else, including `last_seen`. Returns the stored row.
+   *
+   * Ownership is bound to the authenticated `identity` that first registered the
+   * instance: a re-register from the same identity (the reconnect case) is
+   * allowed, but one from a *different* identity is rejected with a
+   * {@link PresenceOwnershipError} and leaves the existing row untouched — no
+   * peer can take over another peer's instance or rewrite its identity.
+   */
+  register(input: RegisterInput): PresenceRow {
+    const now = this.#clock.now();
+    const cap = input.capability;
+    this.#db.run(
+      `INSERT INTO ${PRESENCE_TABLE}
+         (instance, connection_id, identity, cognition, weight, family, host, registered_at, last_seen)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(instance) DO UPDATE SET
+         connection_id = excluded.connection_id,
+         identity      = excluded.identity,
+         cognition     = excluded.cognition,
+         weight        = excluded.weight,
+         family        = excluded.family,
+         host          = excluded.host,
+         last_seen     = excluded.last_seen
+       WHERE ${PRESENCE_TABLE}.identity = excluded.identity`,
+      [
+        input.instance,
+        input.connectionId,
+        input.identity,
+        cap.cognition ?? null,
+        cap.weight ?? null,
+        cap.family ?? null,
+        cap.host ?? null,
+        new Date(now).toISOString(),
+        now,
+      ],
+    );
+    // Enforce ownership on the *persisted* row rather than the driver's
+    // changed-row count. The identity guard in the UPSERT's `WHERE` leaves a
+    // foreign-owned row untouched, so after the statement the stored identity
+    // is authoritative: if it differs from the caller's, this register was a
+    // rejected takeover. Reading it back keeps the invariant independent of how
+    // SQLite counts UPSERT changes (which counts WHERE-matched rows, not just
+    // value-changing ones), so a same-identity no-op re-register never trips it.
+    const row = this.get(input.instance);
+    if (row === undefined) {
+      throw new Error(`presence row vanished immediately after register: ${input.instance}`);
+    }
+    if (row.identity !== input.identity) {
+      throw new PresenceOwnershipError(input.instance);
+    }
+    return row;
+  }
+
+  /**
+   * Refresh an instance's liveness to now. Returns `true` if the instance was
+   * registered, `false` if there is no such row (a heartbeat before register).
+   * When `identity` is given, the refresh is scoped to the owning identity, so a
+   * heartbeat from a foreign identity is a silent no-op (and cannot probe for
+   * the existence of another peer's instance).
+   */
+  heartbeat(instance: string, identity?: string): boolean {
+    const { changes } =
+      identity === undefined
+        ? this.#db.run(`UPDATE ${PRESENCE_TABLE} SET last_seen = ? WHERE instance = ?`, [this.#clock.now(), instance])
+        : this.#db.run(`UPDATE ${PRESENCE_TABLE} SET last_seen = ? WHERE instance = ? AND identity = ?`, [
+            this.#clock.now(),
+            instance,
+            identity,
+          ]);
+    return changes > 0;
+  }
+
+  /**
+   * Remove an instance's presence row. Returns `true` if a row was removed. When
+   * `identity` is given, the removal is scoped to the owning identity, so a
+   * deregister from a foreign identity is a silent no-op.
+   */
+  deregister(instance: string, identity?: string): boolean {
+    const { changes } =
+      identity === undefined
+        ? this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE instance = ?`, [instance])
+        : this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE instance = ? AND identity = ?`, [instance, identity]);
+    return changes > 0;
+  }
+
+  /**
+   * Remove every presence row registered on a now-dead connection (e.g. one S1
+   * closed on its own liveness sweep). Returns the removed instance ids so the
+   * caller can react. Presence also ages out via {@link sweep}; this is the
+   * eager path when a disconnect is observed.
+   */
+  removeByConnection(connectionId: string): string[] {
+    const removed = this.#db
+      .all<{ instance: string }>(`SELECT instance FROM ${PRESENCE_TABLE} WHERE connection_id = ?`, [connectionId])
+      .map((r) => r.instance);
+    if (removed.length > 0) {
+      this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE connection_id = ?`, [connectionId]);
+    }
+    return removed;
+  }
+
+  /**
+   * Age out every presence row whose `last_seen` is older than the TTL and
+   * return the removed rows. `now` defaults to the clock; pass an explicit value
+   * for deterministic tests. Matches S1's liveness predicate (`now - lastSeen >
+   * ttl`).
+   */
+  sweep(now: number = this.#clock.now()): PresenceRow[] {
+    const cutoff = now - this.#ttlMs;
+    const stale = this.#db
+      .all<DbRow>(`SELECT * FROM ${PRESENCE_TABLE} WHERE last_seen < ?`, [cutoff])
+      .map(toRow);
+    if (stale.length > 0) {
+      this.#db.run(`DELETE FROM ${PRESENCE_TABLE} WHERE last_seen < ?`, [cutoff]);
+    }
+    return stale;
+  }
+
+  /** Look up a single instance's presence row. */
+  get(instance: string): PresenceRow | undefined {
+    const rows = this.#db.all<DbRow>(`SELECT * FROM ${PRESENCE_TABLE} WHERE instance = ?`, [instance]);
+    const row = rows[0];
+    return row === undefined ? undefined : toRow(row);
+  }
+
+  /** Every presence row, ordered by first registration then instance id. */
+  list(): PresenceRow[] {
+    return this.#db
+      .all<DbRow>(`SELECT * FROM ${PRESENCE_TABLE} ORDER BY registered_at, instance`)
+      .map(toRow);
+  }
+
+  /** Number of registered instances. */
+  count(): number {
+    const rows = this.#db.all<{ n: number }>(`SELECT COUNT(*) AS n FROM ${PRESENCE_TABLE}`);
+    return rows[0]?.n ?? 0;
+  }
+}

package/src/presence/test-db.test.ts

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { openTestDb } from "./test-db.ts";
+
+/**
+ * The in-memory test adapter must mirror the Node host adapter's `wrapNodeSqlite`
+ * exactly: it rejects unsupported SQLite parameter types (including `undefined`)
+ * instead of silently coercing them, so a test can never pass on a parameter
+ * production would throw on.
+ */
+test("openTestDb rejects unsupported SQLite parameter types like the host adapter", () => {
+  const db = openTestDb();
+  try {
+    db.exec("CREATE TABLE t (v)");
+    assert.throws(() => db.run("INSERT INTO t (v) VALUES (?)", [{}]), TypeError);
+    assert.throws(() => db.run("INSERT INTO t (v) VALUES (?)", [undefined]), TypeError);
+    assert.throws(() => db.run("INSERT INTO t (v) VALUES (?)", [Symbol("x")]), TypeError);
+  } finally {
+    db.close();
+  }
+});
+
+test("openTestDb accepts the SQLite-native parameter types", () => {
+  const db = openTestDb();
+  try {
+    db.exec("CREATE TABLE t (v)");
+    db.run("INSERT INTO t (v) VALUES (?)", ["s"]);
+    db.run("INSERT INTO t (v) VALUES (?)", [1]);
+    db.run("INSERT INTO t (v) VALUES (?)", [10n]);
+    db.run("INSERT INTO t (v) VALUES (?)", [null]);
+    db.run("INSERT INTO t (v) VALUES (?)", [true]);
+    db.run("INSERT INTO t (v) VALUES (?)", [new Uint8Array([1, 2])]);
+    const rows = db.all<{ n: number }>("SELECT COUNT(*) AS n FROM t");
+    assert.equal(rows[0]?.n, 6);
+  } finally {
+    db.close();
+  }
+});
+
+/**
+ * `all()` must return the driver's row objects verbatim, exactly like the host
+ * `wrapNodeSqlite`. A JSON clone would mangle `Uint8Array` blobs into plain
+ * objects (and throw outright on `bigint`), so guard that blobs round-trip as
+ * real `Uint8Array` instances.
+ */
+test("openTestDb.all returns Uint8Array blobs intact, like the host adapter", () => {
+  const db = openTestDb();
+  try {
+    db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, blob BLOB)");
+    db.run("INSERT INTO t (id, blob) VALUES (?, ?)", [1, new Uint8Array([1, 2, 3])]);
+    const rows = db.all<{ blob: Uint8Array }>("SELECT blob FROM t WHERE id = ?", [1]);
+    assert.ok(rows[0]?.blob instanceof Uint8Array);
+    assert.deepEqual([...(rows[0]?.blob ?? [])], [1, 2, 3]);
+  } finally {
+    db.close();
+  }
+});

package/src/presence/test-db.ts

@@ -0,0 +1,47 @@
+/**
+ * Test-only helper: a {@link SqliteDb} backed by an in-memory `node:sqlite`
+ * database, mirroring the Node host adapter's `wrapNodeSqlite`. Kept out of the
+ * published build (see `tsconfig.build.json` exclude) — it exists solely so the
+ * store/family tests exercise the store against a real SQLite engine, not a mock.
+ */
+import { DatabaseSync } from "node:sqlite";
+import type { SqliteDb } from "./store.ts";
+
+export interface TestDb extends SqliteDb {
+  close(): void;
+}
+
+function toParams(params: unknown[]): (string | number | bigint | null | Uint8Array)[] {
+  return params.map((p) => {
+    if (p === null) return null;
+    if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || p instanceof Uint8Array) {
+      return p;
+    }
+    if (typeof p === "boolean") return p ? 1 : 0;
+    // Mirror wrapNodeSqlite's `sqliteParams`: unsupported types (including
+    // `undefined`) throw rather than coerce, so a test can never pass on a
+    // parameter production would reject.
+    throw new TypeError(`unsupported SQLite parameter type: ${typeof p}`);
+  });
+}
+
+export function openTestDb(): TestDb {
+  const db = new DatabaseSync(":memory:");
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const stmt = db.prepare(sql);
+      const r = stmt.run(...toParams(params));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T>(sql: string, params: unknown[] = []): T[] => {
+      const stmt = db.prepare(sql);
+      // Mirror wrapNodeSqlite exactly: return the driver's row objects directly.
+      // A JSON round-trip would throw on `bigint` values and mangle `Uint8Array`
+      // blobs, diverging from production and breaking test-only reads.
+      // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+      return stmt.all(...toParams(params)) as T[];
+    },
+    close: () => db.close(),
+  };
+}

package/src/protocol/conformance/corpus.test.ts

@@ -0,0 +1,66 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { MESSAGE_FAMILIES } from "../families.ts";
+import { QOS_LANES } from "../lanes.ts";
+import { GOLDEN_FRAMES } from "./frames.ts";
+import type { FrameDirection } from "./frames.ts";
+import { MALFORMED_FRAMES } from "./malformed.ts";
+import type { FrameDecodeErrorCode } from "../frame.ts";
+
+// The corpus is only a defence against drift if it is exhaustive. These tests
+// fail if a new family, lane, or decode-error code is added without a covering
+// vector — forcing the corpus to grow with the contract.
+
+test("golden frames cover every message family", () => {
+  const covered = new Set(GOLDEN_FRAMES.map((g) => g.frame.family));
+  for (const family of MESSAGE_FAMILIES) {
+    assert.ok(covered.has(family), `no golden frame covers family: ${family}`);
+  }
+});
+
+test("golden frames cover every QoS lane", () => {
+  const covered = new Set(GOLDEN_FRAMES.map((g) => g.frame.lane));
+  for (const lane of QOS_LANES) {
+    assert.ok(covered.has(lane), `no golden frame covers lane: ${lane}`);
+  }
+});
+
+test("golden frames cover every channel direction", () => {
+  // Derived from the FrameDirection union via an exhaustive Record so tsc fails
+  // when the union grows without a covering golden — no hand-maintained list.
+  const ALL_DIRECTIONS: Record<FrameDirection, true> = {
+    "worker->hub": true,
+    "hub->worker": true,
+    "hub->observers": true,
+  };
+  const covered = new Set<string>(GOLDEN_FRAMES.map((g) => g.direction));
+  for (const direction of Object.keys(ALL_DIRECTIONS)) {
+    assert.ok(covered.has(direction), `no golden frame covers direction: ${direction}`);
+  }
+});
+
+test("malformed corpus covers every decode-error code", () => {
+  // Derived from the FrameDecodeErrorCode union via an exhaustive Record so tsc
+  // fails when the union grows without a covering key — no hand-maintained list.
+  const ALL_CODES: Record<FrameDecodeErrorCode, true> = {
+    empty: true,
+    "short-header": true,
+    "bad-magic": true,
+    "unsupported-version": true,
+    "unknown-lane": true,
+    "unknown-family": true,
+    "truncated-payload": true,
+    "trailing-bytes": true,
+    "invalid-payload-json": true,
+  };
+  const allCodes = Object.keys(ALL_CODES);
+  const covered = new Set<string>(MALFORMED_FRAMES.map((m) => m.expected));
+  for (const code of allCodes) {
+    assert.ok(covered.has(code), `no malformed vector covers code: ${code}`);
+  }
+});
+
+test("golden frame names are unique", () => {
+  const names = GOLDEN_FRAMES.map((g) => g.name);
+  assert.equal(new Set(names).size, names.length);
+});

package/src/protocol/conformance/frames.ts

@@ -0,0 +1,142 @@
+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 const GOLDEN_FRAMES: readonly GoldenFrame[] = [
+  {
+    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/src/protocol/conformance/index.ts

@@ -0,0 +1,29 @@
+/**
+ * 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/src/protocol/conformance/malformed.ts

@@ -0,0 +1,59 @@
+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 const MALFORMED_FRAMES: readonly MalformedFrame[] = [
+  { 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",
+  },
+];