@nanobpm/agentic 0.1.0

package/dist/protocol/vocab/schema.js

@@ -0,0 +1,218 @@
+import { isSeatLabel, isSegmentName } from "../token.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const ROLE_KEYS = new Set([
+    "requires",
+    "weight",
+    "seats",
+    "seatsDistinctFamily",
+]);
+const NETWORK_KEYS = new Set(["roles", "subnetworks"]);
+const DOCUMENT_KEYS = new Set(["version", "networks"]);
+function validateRole(role, path, errors) {
+    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, path, errors) {
+    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) {
+    const errors = [];
+    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) {
+    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 = {};
+    for (const [name, network] of Object.entries(networks)) {
+        out[name] = narrowNetwork(network);
+    }
+    return { version, networks: out };
+}
+function narrowNetwork(input) {
+    if (!isPlainObject(input)) {
+        throw new Error("narrowNetwork called on an unvalidated value");
+    }
+    const result = {};
+    if (isPlainObject(input.roles)) {
+        const roles = {};
+        for (const [roleName, role] of Object.entries(input.roles)) {
+            roles[roleName] = narrowRole(role);
+        }
+        result.roles = roles;
+    }
+    if (isPlainObject(input.subnetworks)) {
+        const subnetworks = {};
+        for (const [subName, sub] of Object.entries(input.subnetworks)) {
+            subnetworks[subName] = narrowNetwork(sub);
+        }
+        result.subnetworks = subnetworks;
+    }
+    return result;
+}
+function narrowRole(input) {
+    if (!isPlainObject(input)) {
+        throw new Error("narrowRole called on an unvalidated value");
+    }
+    const role = {};
+    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/dist/relay/incarnation.d.ts

@@ -0,0 +1,17 @@
+export declare class IncarnationFence {
+    #private;
+    /** The current (highest admitted) incarnation for `stream`, or `undefined`. */
+    current(stream: string): number | undefined;
+    /**
+     * 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;
+    /** Forget a stream's incarnation mark (e.g. when the stream is fully torn down). */
+    forget(stream: string): void;
+}

package/dist/relay/incarnation.js

@@ -0,0 +1,50 @@
+/**
+ * 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.js";
+export class IncarnationFence {
+    #current = new Map();
+    /** The current (highest admitted) incarnation for `stream`, or `undefined`. */
+    current(stream) {
+        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, incarnation) {
+        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) {
+        this.#current.delete(stream);
+    }
+}

package/dist/relay/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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/dist/relay/index.js

@@ -0,0 +1,22 @@
+/**
+ * @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.js";
+export { IncarnationFence } from "./incarnation.js";
+export { QosScheduler, compareFrameOrder, lanePriority } from "./scheduler.js";
+export { RelayHub, RelayMessageError, registerRelayFamily, RELAY_FAMILY, } from "./relay-family.js";
+export { addSafeInt, isNonNegInt, isPosInt } from "./validate.js";

package/dist/relay/relay-family.d.ts

@@ -0,0 +1,68 @@
+import type { Frame, MessageFamily } from "../protocol/index.ts";
+import type { AgenticHub } from "../channel/index.ts";
+import { IncarnationFence } from "./incarnation.ts";
+import { ReplayRing } from "./ring.ts";
+/** The relay family key, from the S0 canonical family set (the one source of truth). */
+export declare const RELAY_FAMILY: MessageFamily;
+/**
+ * The minimal connection surface the relay module needs. It is a structural
+ * subset of the hub's `HubConnection`, so the module is unit-testable with a
+ * fake connection and needs no compile dependency on the hub's concrete type.
+ */
+export interface RelayConnection {
+    readonly id: string;
+    /** The shared registry — its `has(id)` is the liveness source of truth. */
+    readonly registry: {
+        has(id: string): boolean;
+    };
+    /** Send one already-built frame back on this connection. */
+    send(frame: Frame): void;
+}
+export interface RelayHubOptions {
+    /** Retained chunks per stream (resume window). Default 1024. */
+    readonly ringCapacity?: number;
+    /** Max buffered bulk frames per consumer before oldest is shed. Default 1024. */
+    readonly bulkCapacity?: number;
+    /** Bulk credit a consumer starts with before it grants its own. Default 0. */
+    readonly defaultCredit?: number;
+    /** Notified when a producer frame is fenced as a stale incarnation. */
+    readonly onFenced?: (stream: string, incarnation: number, current: number) => void;
+    /** Notified of a malformed relay message or a send failure. */
+    readonly onError?: (err: unknown, connectionId?: string) => void;
+}
+/**
+ * The hub-side relay state machine: per-stream replay rings + incarnation fence,
+ * and per-consumer QoS schedulers. Construct via {@link registerRelayFamily}, or
+ * directly for unit testing and then drive with {@link RelayHub.handle}.
+ */
+export declare class RelayHub {
+    #private;
+    constructor(options?: RelayHubOptions);
+    /** Number of streams with a replay ring. */
+    get streamCount(): number;
+    /** Number of tracked consumer subscribers. */
+    get subscriberCount(): number;
+    /** The replay ring for a stream, if one exists (for inspection/tests). */
+    ring(stream: string): ReplayRing | undefined;
+    /** The incarnation fence (for inspection/tests). */
+    get fence(): IncarnationFence;
+    /** Whether a connection currently has a subscriber record. */
+    hasSubscriber(id: string): boolean;
+    /**
+     * Handle one inbound `relay` frame from `conn`. This is the function attached
+     * to the hub's family seam; it is safe to call directly in tests.
+     */
+    handle(frame: Frame, conn: RelayConnection): void;
+}
+/** Raised (to `onError`) when an inbound relay payload does not match the sub-protocol. */
+export declare class RelayMessageError extends Error {
+    readonly payload: unknown;
+    constructor(payload: unknown);
+}
+/**
+ * Attach the `relay` family to a hub via the S1 registration seam and return the
+ * {@link RelayHub} driving it. This is the canonical entry point; it does NOT
+ * edit any shared dispatch switch — the hub derives routing from this
+ * registration, and a second registration of `relay` is rejected by the seam.
+ */
+export declare function registerRelayFamily(hub: AgenticHub, options?: RelayHubOptions): RelayHub;

package/dist/relay/relay-family.js

@@ -0,0 +1,272 @@
+/**
+ * The `relay` message family — S5's live-terminal relay, attached to the S1 hub
+ * as its OWN module via the `registerFamilyHandler(family, handler)` seam. It
+ * never edits a shared dispatch switch: {@link registerRelayFamily} claims the
+ * `relay` family key (from the S0 {@link MESSAGE_FAMILIES} set) and the hub
+ * derives routing from that registration.
+ *
+ * It composes the three S5 primitives:
+ *  - {@link ReplayRing}      — per-stream resume-from-offset store,
+ *  - {@link IncarnationFence} — fences stale producers off a stream,
+ *  - {@link QosScheduler}    — per-consumer three-lane egress with credit-based
+ *                              backpressure (bulk never blocks control).
+ *
+ * ## Relay sub-protocol (carried in the `relay` family payload)
+ *
+ * Inbound (peer → hub):
+ *  - `{ op: "produce",   stream, incarnation, chunk }` — a producer appends a
+ *    chunk; the hub assigns the authoritative offset and fences stale incarnations.
+ *  - `{ op: "subscribe", stream, from?, credit? }`     — a consumer (re)attaches
+ *    and resumes from `from` (default 0); the retained tail is replayed.
+ *  - `{ op: "credit",    credit }`                    — a consumer grants more
+ *    bulk credit (backpressure) for its whole egress budget.
+ *
+ * Outbound (hub → consumer):
+ *  - a `data` frame is a pure S0 {@link RelayPayload} `{ stream, offset, chunk }`
+ *    on the `bulk` lane;
+ *  - a `subscribed` ack rides the `control` lane and reports `{ gap, nextOffset }`.
+ */
+import { MAX_SEQ } from "../protocol/index.js";
+import { IncarnationFence } from "./incarnation.js";
+import { ReplayRing } from "./ring.js";
+import { QosScheduler } from "./scheduler.js";
+import { isNonNegInt, isPosInt } from "./validate.js";
+/** The relay family key, from the S0 canonical family set (the one source of truth). */
+export const RELAY_FAMILY = "relay";
+const DEFAULT_RING_CAPACITY = 1024;
+const DEFAULT_BULK_CAPACITY = 1024;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * The hub-side relay state machine: per-stream replay rings + incarnation fence,
+ * and per-consumer QoS schedulers. Construct via {@link registerRelayFamily}, or
+ * directly for unit testing and then drive with {@link RelayHub.handle}.
+ */
+export class RelayHub {
+    #rings = new Map();
+    #fence = new IncarnationFence();
+    #subscribers = new Map();
+    #ringCapacity;
+    #bulkCapacity;
+    #defaultCredit;
+    #onFenced;
+    #onError;
+    constructor(options = {}) {
+        this.#ringCapacity = options.ringCapacity ?? DEFAULT_RING_CAPACITY;
+        this.#bulkCapacity = options.bulkCapacity ?? DEFAULT_BULK_CAPACITY;
+        this.#defaultCredit = options.defaultCredit ?? 0;
+        // Validate up-front so misconfiguration fails fast at construction, rather
+        // than throwing lazily from inside #ringFor/#subscriberFor on the first
+        // frame (where the throw would escape handle() and bypass onError).
+        if (!isPosInt(this.#ringCapacity)) {
+            throw new RangeError(`RelayHub ringCapacity must be a positive integer, got ${this.#ringCapacity}`);
+        }
+        if (!isPosInt(this.#bulkCapacity)) {
+            throw new RangeError(`RelayHub bulkCapacity must be a positive integer, got ${this.#bulkCapacity}`);
+        }
+        if (!isNonNegInt(this.#defaultCredit)) {
+            throw new RangeError(`RelayHub defaultCredit must be a non-negative integer, got ${this.#defaultCredit}`);
+        }
+        this.#onFenced = options.onFenced;
+        this.#onError = options.onError;
+    }
+    /** Number of streams with a replay ring. */
+    get streamCount() {
+        return this.#rings.size;
+    }
+    /** Number of tracked consumer subscribers. */
+    get subscriberCount() {
+        return this.#subscribers.size;
+    }
+    /** The replay ring for a stream, if one exists (for inspection/tests). */
+    ring(stream) {
+        return this.#rings.get(stream);
+    }
+    /** The incarnation fence (for inspection/tests). */
+    get fence() {
+        return this.#fence;
+    }
+    /** Whether a connection currently has a subscriber record. */
+    hasSubscriber(id) {
+        return this.#subscribers.has(id);
+    }
+    /**
+     * Handle one inbound `relay` frame from `conn`. This is the function attached
+     * to the hub's family seam; it is safe to call directly in tests.
+     */
+    handle(frame, conn) {
+        this.#pruneDead();
+        const msg = this.#parse(frame.payload);
+        if (msg === null) {
+            this.#onError?.(new RelayMessageError(frame.payload), conn.id);
+            return;
+        }
+        switch (msg.op) {
+            case "produce":
+                this.#onProduce(msg.stream, msg.incarnation, msg.chunk);
+                return;
+            case "subscribe":
+                this.#onSubscribe(conn, msg.stream, msg.from, msg.credit);
+                return;
+            case "credit":
+                this.#onCredit(conn, msg.credit);
+                return;
+        }
+    }
+    #onProduce(stream, incarnation, chunk) {
+        if (!this.#fence.admit(stream, incarnation)) {
+            this.#onFenced?.(stream, incarnation, this.#fence.current(stream) ?? incarnation);
+            return;
+        }
+        const entry = this.#ringFor(stream).append(chunk);
+        for (const sub of this.#subscribers.values()) {
+            if (sub.streams.has(stream)) {
+                this.#emitData(sub, stream, entry.offset, entry.chunk);
+            }
+        }
+    }
+    #onSubscribe(conn, stream, from, credit) {
+        const sub = this.#subscriberFor(conn);
+        sub.streams.add(stream);
+        const ring = this.#ringFor(stream);
+        const slice = ring.since(from);
+        // Control-lane ack FIRST — before granting credit. It tells the consumer
+        // where the resume actually started and whether it lost chunks (gap), and it
+        // must ride ahead of the replayed bulk tail. Emitting it before grantCredit
+        // ensures a bulk tail buffered from an earlier subscription on this same
+        // connection cannot flush out ahead of this ack when credit is released.
+        this.#emit(sub, "control", {
+            op: "subscribed",
+            stream,
+            gap: slice.gap,
+            nextOffset: ring.nextOffset,
+        });
+        if (credit > 0) {
+            sub.scheduler.grantCredit(credit);
+        }
+        for (const entry of slice.entries) {
+            this.#emitData(sub, stream, entry.offset, entry.chunk);
+        }
+    }
+    #onCredit(conn, credit) {
+        // A credit grant may arrive before subscribe (pre-loading the consumer's
+        // budget); create the subscriber record so the credit is not lost.
+        const sub = this.#subscriberFor(conn);
+        sub.scheduler.grantCredit(credit);
+    }
+    #emitData(sub, stream, offset, chunk) {
+        const payload = { stream, offset, chunk };
+        this.#enqueue(sub, "bulk", payload);
+    }
+    #emit(sub, lane, payload) {
+        this.#enqueue(sub, lane, payload);
+    }
+    #enqueue(sub, lane, payload) {
+        const frame = { lane, family: RELAY_FAMILY, seq: sub.seq, payload };
+        sub.seq = sub.seq >= MAX_SEQ ? 0 : sub.seq + 1;
+        try {
+            sub.scheduler.enqueue(frame);
+        }
+        catch (err) {
+            this.#onError?.(err, sub.conn.id);
+        }
+    }
+    #ringFor(stream) {
+        let ring = this.#rings.get(stream);
+        if (ring === undefined) {
+            ring = new ReplayRing({ capacity: this.#ringCapacity });
+            this.#rings.set(stream, ring);
+        }
+        return ring;
+    }
+    #subscriberFor(conn) {
+        let sub = this.#subscribers.get(conn.id);
+        if (sub === undefined) {
+            sub = {
+                conn,
+                scheduler: new QosScheduler({
+                    sink: (frame) => conn.send(frame),
+                    credit: this.#defaultCredit,
+                    bulkCapacity: this.#bulkCapacity,
+                }),
+                streams: new Set(),
+                seq: 0,
+            };
+            this.#subscribers.set(conn.id, sub);
+        }
+        return sub;
+    }
+    /**
+     * Drop subscriber records whose connection is no longer live (the S1 registry
+     * removed it on close). The hub does not surface a per-family close hook, so
+     * the registry's `has(id)` is the liveness source of truth and cleanup is
+     * lazy — run on every inbound frame.
+     */
+    #pruneDead() {
+        for (const [id, sub] of this.#subscribers) {
+            if (!sub.conn.registry.has(id)) {
+                sub.scheduler.clear();
+                this.#subscribers.delete(id);
+            }
+        }
+    }
+    #parse(payload) {
+        if (!isPlainObject(payload)) {
+            return null;
+        }
+        const op = payload.op;
+        if (op === "produce") {
+            if (!nonEmptyString(payload.stream) || !isNonNegInt(payload.incarnation) || typeof payload.chunk !== "string") {
+                return null;
+            }
+            return { op, stream: payload.stream, incarnation: payload.incarnation, chunk: payload.chunk };
+        }
+        if (op === "subscribe") {
+            if (!nonEmptyString(payload.stream)) {
+                return null;
+            }
+            const from = payload.from === undefined ? 0 : payload.from;
+            if (!isNonNegInt(from)) {
+                return null;
+            }
+            const credit = payload.credit === undefined ? 0 : payload.credit;
+            if (!isNonNegInt(credit)) {
+                return null;
+            }
+            return { op, stream: payload.stream, from, credit };
+        }
+        if (op === "credit") {
+            if (!isNonNegInt(payload.credit)) {
+                return null;
+            }
+            return { op, credit: payload.credit };
+        }
+        return null;
+    }
+}
+/** Raised (to `onError`) when an inbound relay payload does not match the sub-protocol. */
+export class RelayMessageError extends Error {
+    payload;
+    constructor(payload) {
+        super("malformed relay message payload");
+        this.name = "RelayMessageError";
+        this.payload = payload;
+    }
+}
+/**
+ * Attach the `relay` family to a hub via the S1 registration seam and return the
+ * {@link RelayHub} driving it. This is the canonical entry point; it does NOT
+ * edit any shared dispatch switch — the hub derives routing from this
+ * registration, and a second registration of `relay` is rejected by the seam.
+ */
+export function registerRelayFamily(hub, options = {}) {
+    const relay = new RelayHub(options);
+    hub.registerFamilyHandler(RELAY_FAMILY, (frame, ctx) => {
+        relay.handle(frame, ctx);
+    });
+    return relay;
+}