@nanobpm/agentic 0.1.0

package/src/protocol/vocab/schema.ts

@@ -0,0 +1,281 @@
+import { isSeatLabel, isSegmentName } from "../token.ts";
+
+/**
+ * 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[] };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const ROLE_KEYS: ReadonlySet<string> = new Set([
+  "requires",
+  "weight",
+  "seats",
+  "seatsDistinctFamily",
+]);
+const NETWORK_KEYS: ReadonlySet<string> = new Set(["roles", "subnetworks"]);
+const DOCUMENT_KEYS: ReadonlySet<string> = new Set(["version", "networks"]);
+
+function validateRole(role: unknown, path: string, errors: VocabError[]): void {
+  if (!isPlainObject(role)) {
+    errors.push({ path, code: "role-not-object", message: "role must be an object" });
+    return;
+  }
+  for (const key of Object.keys(role)) {
+    if (!ROLE_KEYS.has(key)) {
+      errors.push({ path: `${path}.${key}`, code: "unknown-role-field", message: `unknown role field: ${key}` });
+    }
+  }
+
+  if ("requires" in role) {
+    const requires = role.requires;
+    if (!Array.isArray(requires) || !requires.every((entry) => typeof entry === "string")) {
+      errors.push({
+        path: `${path}.requires`,
+        code: "bad-requires",
+        message: "requires must be an array of strings",
+      });
+    }
+  }
+
+  if ("weight" in role) {
+    const weight = role.weight;
+    if (typeof weight !== "number" || !Number.isFinite(weight)) {
+      errors.push({ path: `${path}.weight`, code: "bad-weight", message: "weight must be a finite number" });
+    }
+  }
+
+  if ("seats" in role) {
+    const seats = role.seats;
+    if (typeof seats === "number") {
+      if (!Number.isInteger(seats) || seats < 0) {
+        errors.push({ path: `${path}.seats`, code: "bad-seats", message: "seats count must be a non-negative integer" });
+      }
+    } else if (Array.isArray(seats)) {
+      seats.forEach((seat, index) => {
+        if (typeof seat !== "string" || !isSeatLabel(seat)) {
+          errors.push({
+            path: `${path}.seats[${index}]`,
+            code: "bad-seat-label",
+            message: `named seat must be a valid seat label: ${String(seat)}`,
+          });
+        }
+      });
+    } else {
+      errors.push({
+        path: `${path}.seats`,
+        code: "bad-seats",
+        message: "seats must be a non-negative integer or an array of seat labels",
+      });
+    }
+  }
+
+  if ("seatsDistinctFamily" in role && typeof role.seatsDistinctFamily !== "boolean") {
+    errors.push({
+      path: `${path}.seatsDistinctFamily`,
+      code: "bad-seats-distinct-family",
+      message: "seatsDistinctFamily must be a boolean",
+    });
+  }
+}
+
+function validateNetwork(network: unknown, path: string, errors: VocabError[]): void {
+  if (!isPlainObject(network)) {
+    errors.push({ path, code: "network-not-object", message: "network must be an object" });
+    return;
+  }
+  for (const key of Object.keys(network)) {
+    if (!NETWORK_KEYS.has(key)) {
+      errors.push({ path: `${path}.${key}`, code: "unknown-network-field", message: `unknown network field: ${key}` });
+    }
+  }
+
+  if ("roles" in network) {
+    const roles = network.roles;
+    if (!isPlainObject(roles)) {
+      errors.push({ path: `${path}.roles`, code: "bad-roles", message: "roles must be an object" });
+    } else {
+      for (const [roleName, role] of Object.entries(roles)) {
+        if (!isSegmentName(roleName)) {
+          errors.push({
+            path: `${path}.roles.${roleName}`,
+            code: "bad-role-name",
+            message: `invalid role name: ${roleName}`,
+          });
+        }
+        validateRole(role, `${path}.roles.${roleName}`, errors);
+      }
+    }
+  }
+
+  if ("subnetworks" in network) {
+    const subnetworks = network.subnetworks;
+    if (!isPlainObject(subnetworks)) {
+      errors.push({ path: `${path}.subnetworks`, code: "bad-subnetworks", message: "subnetworks must be an object" });
+    } else {
+      for (const [subName, sub] of Object.entries(subnetworks)) {
+        if (!isSegmentName(subName)) {
+          errors.push({
+            path: `${path}.subnetworks.${subName}`,
+            code: "bad-subnetwork-name",
+            message: `invalid subnetwork name: ${subName}`,
+          });
+        }
+        validateNetwork(sub, `${path}.subnetworks.${subName}`, errors);
+      }
+    }
+  }
+}
+
+/**
+ * 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 function validateVocabDocument(input: unknown): VocabValidationResult {
+  const errors: VocabError[] = [];
+
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: [{ path: "$", code: "not-object", message: "vocab document must be an object" }] };
+  }
+  for (const key of Object.keys(input)) {
+    if (!DOCUMENT_KEYS.has(key)) {
+      errors.push({ path: `$.${key}`, code: "unknown-document-field", message: `unknown document field: ${key}` });
+    }
+  }
+
+  const version = input.version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    errors.push({ path: "$.version", code: "bad-version", message: "version must be an integer ≥ 1" });
+  }
+
+  const networks = input.networks;
+  if (!isPlainObject(networks)) {
+    errors.push({ path: "$.networks", code: "bad-networks", message: "networks must be an object" });
+  } else {
+    for (const [networkName, network] of Object.entries(networks)) {
+      if (!isSegmentName(networkName)) {
+        errors.push({
+          path: `$.networks.${networkName}`,
+          code: "bad-network-name",
+          message: `invalid network name: ${networkName}`,
+        });
+      }
+      validateNetwork(network, `$.networks.${networkName}`, errors);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, value: narrowDocument(input) };
+}
+
+// Reached only after validateVocabDocument confirmed the shape; the recursive
+// structural checks above guarantee every field matches VocabDocument.
+function narrowDocument(input: Record<string, unknown>): VocabDocument {
+  const version = input.version;
+  const networks = input.networks;
+  if (typeof version !== "number" || !isPlainObject(networks)) {
+    throw new Error("narrowDocument called on an unvalidated value");
+  }
+  const out: Record<string, VocabNetwork> = {};
+  for (const [name, network] of Object.entries(networks)) {
+    out[name] = narrowNetwork(network);
+  }
+  return { version, networks: out };
+}
+
+function narrowNetwork(input: unknown): VocabNetwork {
+  if (!isPlainObject(input)) {
+    throw new Error("narrowNetwork called on an unvalidated value");
+  }
+  const result: { roles?: Record<string, VocabRole>; subnetworks?: Record<string, VocabNetwork> } = {};
+  if (isPlainObject(input.roles)) {
+    const roles: Record<string, VocabRole> = {};
+    for (const [roleName, role] of Object.entries(input.roles)) {
+      roles[roleName] = narrowRole(role);
+    }
+    result.roles = roles;
+  }
+  if (isPlainObject(input.subnetworks)) {
+    const subnetworks: Record<string, VocabNetwork> = {};
+    for (const [subName, sub] of Object.entries(input.subnetworks)) {
+      subnetworks[subName] = narrowNetwork(sub);
+    }
+    result.subnetworks = subnetworks;
+  }
+  return result;
+}
+
+function narrowRole(input: unknown): VocabRole {
+  if (!isPlainObject(input)) {
+    throw new Error("narrowRole called on an unvalidated value");
+  }
+  const role: {
+    requires?: readonly string[];
+    weight?: number;
+    seats?: number | readonly string[];
+    seatsDistinctFamily?: boolean;
+  } = {};
+  const requires = input.requires;
+  if (Array.isArray(requires) && requires.every((entry) => typeof entry === "string")) {
+    role.requires = [...requires];
+  }
+  if (typeof input.weight === "number") {
+    role.weight = input.weight;
+  }
+  const seats = input.seats;
+  if (typeof seats === "number") {
+    role.seats = seats;
+  } else if (Array.isArray(seats) && seats.every((seat) => typeof seat === "string")) {
+    role.seats = [...seats];
+  }
+  if (typeof input.seatsDistinctFamily === "boolean") {
+    role.seatsDistinctFamily = input.seatsDistinctFamily;
+  }
+  return role;
+}

package/src/relay/incarnation.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { IncarnationFence } from "./incarnation.ts";
+
+test("admits the first producer and records its incarnation", () => {
+  const fence = new IncarnationFence();
+  assert.equal(fence.current("s"), undefined);
+  assert.equal(fence.admit("s", 3), true);
+  assert.equal(fence.current("s"), 3);
+});
+
+test("admits the same incarnation repeatedly", () => {
+  const fence = new IncarnationFence();
+  fence.admit("s", 5);
+  assert.equal(fence.admit("s", 5), true);
+  assert.equal(fence.current("s"), 5);
+});
+
+test("a strictly higher incarnation takes over (advances the mark)", () => {
+  const fence = new IncarnationFence();
+  fence.admit("s", 1);
+  assert.equal(fence.admit("s", 2), true);
+  assert.equal(fence.current("s"), 2);
+});
+
+test("a stale (lower) incarnation is fenced and does not move the mark", () => {
+  const fence = new IncarnationFence();
+  fence.admit("s", 5);
+  assert.equal(fence.admit("s", 4), false);
+  assert.equal(fence.current("s"), 5);
+});
+
+test("fencing is per-stream", () => {
+  const fence = new IncarnationFence();
+  fence.admit("a", 9);
+  assert.equal(fence.admit("b", 1), true);
+  assert.equal(fence.current("a"), 9);
+  assert.equal(fence.current("b"), 1);
+});
+
+test("forget clears a stream's mark", () => {
+  const fence = new IncarnationFence();
+  fence.admit("s", 7);
+  fence.forget("s");
+  assert.equal(fence.current("s"), undefined);
+  assert.equal(fence.admit("s", 1), true); // a fresh start is admitted
+});
+
+test("rejects a negative or non-integer incarnation", () => {
+  const fence = new IncarnationFence();
+  assert.throws(() => fence.admit("s", -1), RangeError);
+  assert.throws(() => fence.admit("s", 1.5), RangeError);
+});

package/src/relay/incarnation.ts

@@ -0,0 +1,54 @@
+/**
+ * Generation / incarnation fencing for relay streams.
+ *
+ * A relay stream (e.g. a worker's terminal) may be produced by a succession of
+ * incarnations: a worker restarts, a job is retried on a fresh runner, a new
+ * process takes over the same logical stream. Each producer stamps its frames
+ * with an `incarnation` (a monotonically increasing generation number). Once a
+ * newer incarnation has taken over a stream, frames from an older incarnation
+ * are STALE and must be fenced off — otherwise a zombie producer could interleave
+ * bytes into a stream a live successor now owns, corrupting the transcript.
+ *
+ * The fence keeps, per stream, the highest incarnation seen so far and admits a
+ * frame only when its incarnation is `>=` that high-water mark. A strictly
+ * higher incarnation advances the mark (the takeover); a strictly lower one is
+ * fenced. This mirrors the classic storage/leader fencing token pattern.
+ */
+import { isNonNegInt } from "./validate.ts";
+
+export class IncarnationFence {
+  readonly #current = new Map<string, number>();
+
+  /** The current (highest admitted) incarnation for `stream`, or `undefined`. */
+  current(stream: string): number | undefined {
+    return this.#current.get(stream);
+  }
+
+  /**
+   * Decide whether a producer at `incarnation` may write to `stream`.
+   *
+   * Returns `true` and advances the high-water mark when `incarnation` is `>=`
+   * the current mark (a first producer, the same producer, or a takeover by a
+   * newer one). Returns `false` — fenced — when `incarnation` is strictly lower
+   * than a mark already established by a newer incarnation, leaving the mark
+   * untouched.
+   */
+  admit(stream: string, incarnation: number): boolean {
+    if (!isNonNegInt(incarnation)) {
+      throw new RangeError(`incarnation must be a non-negative integer, got ${incarnation}`);
+    }
+    const mark = this.#current.get(stream);
+    if (mark !== undefined && incarnation < mark) {
+      return false;
+    }
+    if (mark === undefined || incarnation > mark) {
+      this.#current.set(stream, incarnation);
+    }
+    return true;
+  }
+
+  /** Forget a stream's incarnation mark (e.g. when the stream is fully torn down). */
+  forget(stream: string): void {
+    this.#current.delete(stream);
+  }
+}

package/src/relay/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @nanobpm/agentic-relay — the relay ring + QoS scheduler for the Nano agentic
+ * protocol (ADR 0056, slice S5).
+ *
+ * Live terminal relay over the one app-tier channel: a bounded replay ring with
+ * resume-from-offset ({@link ReplayRing}), generation/incarnation fencing
+ * ({@link IncarnationFence}), a three-lane credit-based QoS scheduler that keeps
+ * a bulk-output storm from head-of-line-blocking control/interactive traffic
+ * ({@link QosScheduler}), and the `relay` message family ({@link RelayHub}) that
+ * composes them.
+ *
+ * The family attaches to the S1 hub through its `registerFamilyHandler` seam via
+ * {@link registerRelayFamily} — its own self-contained module, never a shared
+ * dispatch switch. It builds on the S0 contract (`@nanobpm/agentic-protocol`)
+ * and the S1 channel (`@nanobpm/agentic-channel`); the Camunda-8 engine
+ * transport is a separate connection and is never touched.
+ */
+export { ReplayRing } from "./ring.ts";
+export type { ReplayEntry, ReplayRingOptions, ReplaySlice } from "./ring.ts";
+
+export { IncarnationFence } from "./incarnation.ts";
+
+export { QosScheduler, compareFrameOrder, lanePriority } from "./scheduler.ts";
+export type { QosSchedulerOptions } from "./scheduler.ts";
+
+export {
+  RelayHub,
+  RelayMessageError,
+  registerRelayFamily,
+  RELAY_FAMILY,
+} from "./relay-family.ts";
+export type { RelayConnection, RelayHubOptions } from "./relay-family.ts";
+
+export { addSafeInt, isNonNegInt, isPosInt } from "./validate.ts";

package/src/relay/integration.test.ts

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { setImmediate as tick } from "node:timers/promises";
+import { test } from "node:test";
+import { decodeFrame, encodeFrame } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import { AgenticHub, sharedSecretAuthenticator } from "../channel/index.ts";
+import type { ChannelConnection, ChannelTransport, CloseCode, HandshakeRequest } from "../channel/index.ts";
+import { DuplicateFamilyHandlerError } from "../channel/index.ts";
+import { registerRelayFamily } from "./relay-family.ts";
+
+class FakeConnection implements ChannelConnection {
+  readonly id: string;
+  readonly handshake: HandshakeRequest;
+  readonly sent: Uint8Array[] = [];
+  #onMessage: ((bytes: Uint8Array) => void) | undefined;
+  #onClose: ((code?: CloseCode, reason?: string) => void) | undefined;
+  constructor(id: string, handshake: HandshakeRequest) {
+    this.id = id;
+    this.handshake = handshake;
+  }
+  send(bytes: Uint8Array): void {
+    this.sent.push(bytes);
+  }
+  close(code?: CloseCode, reason?: string): void {
+    this.#onClose?.(code, reason);
+  }
+  onMessage(listener: (bytes: Uint8Array) => void): void {
+    this.#onMessage = listener;
+  }
+  onClose(listener: (code?: CloseCode, reason?: string) => void): void {
+    this.#onClose = listener;
+  }
+  receive(bytes: Uint8Array): void {
+    this.#onMessage?.(bytes);
+  }
+}
+
+class FakeTransport implements ChannelTransport {
+  readonly address = { port: 0 };
+  #onConnection: ((conn: ChannelConnection) => void) | undefined;
+  onConnection(listener: (conn: ChannelConnection) => void): void {
+    this.#onConnection = listener;
+  }
+  close(): Promise<void> {
+    return Promise.resolve();
+  }
+  accept(conn: ChannelConnection): void {
+    this.#onConnection?.(conn);
+  }
+}
+
+const HANDSHAKE: HandshakeRequest = { token: "s", credential: "cap" };
+
+function makeHub(): { hub: AgenticHub; transport: FakeTransport } {
+  const transport = new FakeTransport();
+  const hub = new AgenticHub({
+    transport,
+    authenticator: sharedSecretAuthenticator({ secret: "s", requireCredential: false }),
+    sweepIntervalMs: 0,
+  });
+  return { hub, transport };
+}
+
+function field(payload: unknown, key: string): unknown {
+  return typeof payload === "object" && payload !== null ? Reflect.get(payload, key) : undefined;
+}
+
+function decodedFrames(conn: FakeConnection): Frame[] {
+  return conn.sent.map((bytes) => decodeFrame(bytes));
+}
+
+test("the relay family attaches via the S1 registerFamilyHandler seam and routes end-to-end", async () => {
+  const { hub, transport } = makeHub();
+  registerRelayFamily(hub, { defaultCredit: 100 });
+  assert.ok(hub.router.has("relay"));
+
+  const producer = new FakeConnection("p", HANDSHAKE);
+  const consumer = new FakeConnection("c", HANDSHAKE);
+  transport.accept(producer);
+  transport.accept(consumer);
+  await tick(); // let async auth + registration settle
+
+  consumer.receive(
+    encodeFrame({ lane: "control", family: "relay", seq: 1, payload: { op: "subscribe", stream: "t", from: 0, credit: 100 } }),
+  );
+  producer.receive(
+    encodeFrame({ lane: "bulk", family: "relay", seq: 1, payload: { op: "produce", stream: "t", incarnation: 1, chunk: "hello" } }),
+  );
+  await tick();
+
+  const frames = decodedFrames(consumer);
+  const ack = frames.find((f) => field(f.payload, "op") === "subscribed");
+  assert.ok(ack, "consumer received the control-lane subscribed ack");
+  assert.equal(ack.lane, "control");
+  const data = frames.filter((f) => f.lane === "bulk" && field(f.payload, "op") === undefined);
+  assert.equal(data.length, 1);
+  assert.equal(field(data[0]?.payload, "stream"), "t");
+  assert.equal(field(data[0]?.payload, "offset"), 0);
+  assert.equal(field(data[0]?.payload, "chunk"), "hello");
+
+  await hub.close();
+});
+
+test("registering the relay family twice is rejected by the seam (one owner per family)", () => {
+  const { hub } = makeHub();
+  registerRelayFamily(hub);
+  assert.throws(() => registerRelayFamily(hub), DuplicateFamilyHandlerError);
+});
+
+test("a consumer that disconnects is pruned; the producer keeps flowing to the rest", async () => {
+  const { hub, transport } = makeHub();
+  const relay = registerRelayFamily(hub, { defaultCredit: 100 });
+
+  const producer = new FakeConnection("p", HANDSHAKE);
+  const consumer = new FakeConnection("c", HANDSHAKE);
+  transport.accept(producer);
+  transport.accept(consumer);
+  await tick();
+
+  consumer.receive(
+    encodeFrame({ lane: "control", family: "relay", seq: 1, payload: { op: "subscribe", stream: "t", from: 0, credit: 100 } }),
+  );
+  await tick();
+  assert.equal(relay.subscriberCount, 1);
+
+  consumer.close(); // hub removes it from the registry on close
+  await tick();
+  producer.receive(
+    encodeFrame({ lane: "bulk", family: "relay", seq: 2, payload: { op: "produce", stream: "t", incarnation: 1, chunk: "x" } }),
+  );
+  await tick();
+  assert.equal(relay.subscriberCount, 0); // pruned lazily on the produce frame
+
+  await hub.close();
+});