@earendil-works/chord 1.4.0 → 1.5.1

package/dist/link/ipc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc.js","sourceRoot":"","sources":["../../src/link/ipc.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,iFAAiF;AAEjF,OAAO,EAAa,OAAO,EAAE,MAAM,WAAW,CAAC;AAgB/C;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAa;IACpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,OAAQ,SAAQ,OAAO;IAC5B,uCAAuC;IACvC,KAAK,CAAsB;IAClB,UAAU,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAChD,IAAI,OAAO,YAAY,UAAU;YAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC,CAAC;IACO,aAAa,GAAG,GAAS,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACxC,OAAO,GAAG,CAAC,KAAmB,EAAQ,EAAE;QAChD,IAAI,KAAK,KAAK,IAAI;YAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC,CAAC;IAEF,YAAY,IAAa;QACxB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO;QACR,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpC,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,CAAC,OAAmB;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,IAAI,CAAC;YACJ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACR,IAAI,CAAC,IAAI,EAAE,CAAC;QACb,CAAC;IACF,CAAC;IAED,KAAK;QACJ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,oEAAoE;QACpE,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IAED,kDAAkD;IAClD,IAAI;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,EAAE,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,EAAE,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QACvD,IAAI,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;CACD","sourcesContent":["// IPC links (§3): a link over a Node IPC channel, a forked child (`fork` with `serialization: \"advanced\"`) or\n// `process` in the child, typed structurally so Chord imports nothing from Node.\n\nimport { type Link, LinkEnd } from \"./link.ts\";\n\n/**\n * The part of a Node IPC channel a link uses: a `ChildProcess` or the child's `process`. `send` returning `false` is\n * backpressure (the message is queued by Node), not a failure.\n */\nexport interface IpcPort {\n\tsend(message: Uint8Array, callback: (error: Error | null) => void): boolean;\n\ton(event: \"message\", listener: (message: unknown) => void): unknown;\n\ton(event: \"disconnect\", listener: () => void): unknown;\n\tremoveListener(event: \"message\", listener: (message: unknown) => void): unknown;\n\tremoveListener(event: \"disconnect\", listener: () => void): unknown;\n\tdisconnect(): void;\n\treadonly connected: boolean;\n}\n\n/**\n * A link over `port`: each message one `Uint8Array` (V8 serialization keeps it one). It listens from the moment it is\n * made and queues messages until its listener is set, so a child makes it before awaiting its start message; messages\n * that are no `Uint8Array` (the app's own, such as that start message) are not the link's and are skipped. A thrown\n * `send`, an error in its callback or `disconnect` closes the link once; its listeners are removed then.\n */\nexport function ipcLink(port: IpcPort): Link {\n\treturn new IpcLink(port);\n}\n\nclass IpcLink extends LinkEnd {\n\t/** The port while the link is open. */\n\t#port: IpcPort | undefined;\n\treadonly #onMessage = (message: unknown): void => {\n\t\tif (message instanceof Uint8Array) this.deliver(message);\n\t};\n\treadonly #onDisconnect = (): void => this.#end();\n\treadonly #onSent = (error: Error | null): void => {\n\t\tif (error !== null) this.#end();\n\t};\n\n\tconstructor(port: IpcPort) {\n\t\tsuper();\n\t\tthis.#port = port;\n\t\tif (!port.connected) {\n\t\t\tthis.#end();\n\t\t\treturn;\n\t\t}\n\t\tport.on(\"message\", this.#onMessage);\n\t\tport.on(\"disconnect\", this.#onDisconnect);\n\t}\n\n\tsend(message: Uint8Array): void {\n\t\tconst port = this.#port;\n\t\tif (port === undefined) return;\n\t\ttry {\n\t\t\tport.send(message, this.#onSent);\n\t\t} catch {\n\t\t\tthis.#end();\n\t\t}\n\t}\n\n\tclose(): void {\n\t\tconst port = this.#port;\n\t\tif (port === undefined) return;\n\t\tthis.#end();\n\t\t// Disconnecting a channel that is gone already would emit an error.\n\t\tif (port.connected) port.disconnect();\n\t}\n\n\t/** Detaches from the port and closes this end. */\n\t#end(): void {\n\t\tconst port = this.#port;\n\t\tthis.#port = undefined;\n\t\tport?.removeListener(\"message\", this.#onMessage);\n\t\tport?.removeListener(\"disconnect\", this.#onDisconnect);\n\t\tthis.ended();\n\t}\n}\n"]}

package/dist/link/link.d.ts

@@ -0,0 +1,34 @@
+/** An ordered, bidirectional channel of `Uint8Array` messages between two hosts. Adapters only move bytes. */
+export interface Link {
+    /** Sends one message; a no-op once closed. */
+    send(message: Uint8Array): void;
+    /**
+     * Sets the one listener for incoming messages; messages that arrived earlier are delivered to it first. On a closed
+     * link it is not kept.
+     */
+    onMessage(listener: (message: Uint8Array) => void): void;
+    /** Closes both ends; messages not delivered yet are dropped. */
+    close(): void;
+    /** Sets the one listener for the close of either end; it runs at once when the link is closed already. */
+    onClose(listener: () => void): void;
+}
+/** Two ends of one link: what one sends, the other receives asynchronously (a microtask later), in order. */
+export declare function memoryLinkPair(): [Link, Link];
+/**
+ * What every link end shares: the one message listener (messages that arrived before it are queued for it), the one
+ * close listener, and closing once. Subclasses move the bytes: `deliver` what arrived, `ended` when the transport
+ * closed, and implement `send` and `close`.
+ */
+export declare abstract class LinkEnd implements Link {
+    #private;
+    abstract send(message: Uint8Array): void;
+    abstract close(): void;
+    get closed(): boolean;
+    onMessage(listener: (message: Uint8Array) => void): void;
+    onClose(listener: () => void): void;
+    /** A message arrived; dropped once closed. */
+    protected deliver(message: Uint8Array): void;
+    /** Closes this end (once): nothing is delivered any more, and nothing the listeners reach is kept. */
+    protected ended(): void;
+}
+//# sourceMappingURL=link.d.ts.map

package/dist/link/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/link/link.ts"],"names":[],"mappings":"AAEA,8GAA8G;AAC9G,MAAM,WAAW,IAAI;IACpB,8CAA8C;IAC9C,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IACzD,gEAAgE;IAChE,KAAK,IAAI,IAAI,CAAC;IACd,0GAA0G;IAC1G,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACpC;AAED,6GAA6G;AAC7G,wBAAgB,cAAc,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAM7C;AAED;;;;GAIG;AACH,8BAAsB,OAAQ,YAAW,IAAI;;IAO5C,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAEzC,QAAQ,CAAC,KAAK,IAAI,IAAI,CAAC;IAEvB,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CASvD;IAED,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAGlC;IAED,8CAA8C;IAC9C,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAI3C;IAED,sGAAsG;IACtG,SAAS,CAAC,KAAK,IAAI,IAAI,CAQtB;CACD"}

package/dist/link/link.js

@@ -0,0 +1,87 @@
+// Links (§3): an ordered, bidirectional channel of messages between two hosts, and the in-memory pair.
+/** Two ends of one link: what one sends, the other receives asynchronously (a microtask later), in order. */
+export function memoryLinkPair() {
+    const a = new MemoryLink();
+    const b = new MemoryLink();
+    a.peer = b;
+    b.peer = a;
+    return [a, b];
+}
+/**
+ * What every link end shares: the one message listener (messages that arrived before it are queued for it), the one
+ * close listener, and closing once. Subclasses move the bytes: `deliver` what arrived, `ended` when the transport
+ * closed, and implement `send` and `close`.
+ */
+export class LinkEnd {
+    #closed = false;
+    #listener;
+    /** Messages that arrived before the listener was set. */
+    #queued = [];
+    #closeListener;
+    get closed() {
+        return this.#closed;
+    }
+    onMessage(listener) {
+        // A closed end delivers nothing: keeping the listener would keep its owner.
+        if (this.#closed)
+            return;
+        this.#listener = listener;
+        // A listener may close the link: what is still queued then is dropped.
+        for (const message of this.#queued.splice(0)) {
+            if (this.#closed)
+                return;
+            listener(message);
+        }
+    }
+    onClose(listener) {
+        if (this.#closed)
+            listener();
+        else
+            this.#closeListener = listener;
+    }
+    /** A message arrived; dropped once closed. */
+    deliver(message) {
+        if (this.#closed)
+            return;
+        if (this.#listener === undefined)
+            this.#queued.push(message);
+        else
+            this.#listener(message);
+    }
+    /** Closes this end (once): nothing is delivered any more, and nothing the listeners reach is kept. */
+    ended() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const listener = this.#closeListener;
+        this.#listener = undefined;
+        this.#closeListener = undefined;
+        this.#queued = [];
+        listener?.();
+    }
+}
+/**
+ * One end of a memory link. Closing it closes this end at once and the peer a microtask later, as a transport would.
+ * Portable: `queueMicrotask` only.
+ */
+class MemoryLink extends LinkEnd {
+    peer;
+    send(message) {
+        if (this.closed)
+            return;
+        const peer = this.peer;
+        queueMicrotask(() => peer.deliver(message));
+    }
+    close() {
+        if (this.closed)
+            return;
+        const peer = this.peer;
+        this.#end();
+        queueMicrotask(() => peer.#end());
+    }
+    #end() {
+        this.peer = undefined;
+        this.ended();
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/link/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../src/link/link.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAiBvG,6GAA6G;AAC7G,MAAM,UAAU,cAAc;IAC7B,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;IAC3B,MAAM,CAAC,GAAG,IAAI,UAAU,EAAE,CAAC;IAC3B,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IACX,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IACX,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAgB,OAAO;IAC5B,OAAO,GAAG,KAAK,CAAC;IAChB,SAAS,CAA8C;IACvD,yDAAyD;IACzD,OAAO,GAAiB,EAAE,CAAC;IAC3B,cAAc,CAA2B;IAMzC,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,SAAS,CAAC,QAAuC;QAChD,4EAA4E;QAC5E,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,uEAAuE;QACvE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,IAAI,IAAI,CAAC,OAAO;gBAAE,OAAO;YACzB,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;IACF,CAAC;IAED,OAAO,CAAC,QAAoB;QAC3B,IAAI,IAAI,CAAC,OAAO;YAAE,QAAQ,EAAE,CAAC;;YACxB,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;IACrC,CAAC;IAED,8CAA8C;IACpC,OAAO,CAAC,OAAmB;QACpC,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;YACxD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,sGAAsG;IAC5F,KAAK;QACd,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,QAAQ,EAAE,EAAE,CAAC;IACd,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,UAAW,SAAQ,OAAO;IAC/B,IAAI,CAAyB;IAE7B,IAAI,CAAC,OAAmB;QACvB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAK,CAAC;QACxB,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK;QACJ,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAK,CAAC;QACxB,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,IAAI;QACH,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,IAAI,CAAC,KAAK,EAAE,CAAC;IACd,CAAC;CACD","sourcesContent":["// Links (§3): an ordered, bidirectional channel of messages between two hosts, and the in-memory pair.\n\n/** An ordered, bidirectional channel of `Uint8Array` messages between two hosts. Adapters only move bytes. */\nexport interface Link {\n\t/** Sends one message; a no-op once closed. */\n\tsend(message: Uint8Array): void;\n\t/**\n\t * Sets the one listener for incoming messages; messages that arrived earlier are delivered to it first. On a closed\n\t * link it is not kept.\n\t */\n\tonMessage(listener: (message: Uint8Array) => void): void;\n\t/** Closes both ends; messages not delivered yet are dropped. */\n\tclose(): void;\n\t/** Sets the one listener for the close of either end; it runs at once when the link is closed already. */\n\tonClose(listener: () => void): void;\n}\n\n/** Two ends of one link: what one sends, the other receives asynchronously (a microtask later), in order. */\nexport function memoryLinkPair(): [Link, Link] {\n\tconst a = new MemoryLink();\n\tconst b = new MemoryLink();\n\ta.peer = b;\n\tb.peer = a;\n\treturn [a, b];\n}\n\n/**\n * What every link end shares: the one message listener (messages that arrived before it are queued for it), the one\n * close listener, and closing once. Subclasses move the bytes: `deliver` what arrived, `ended` when the transport\n * closed, and implement `send` and `close`.\n */\nexport abstract class LinkEnd implements Link {\n\t#closed = false;\n\t#listener: ((message: Uint8Array) => void) | undefined;\n\t/** Messages that arrived before the listener was set. */\n\t#queued: Uint8Array[] = [];\n\t#closeListener: (() => void) | undefined;\n\n\tabstract send(message: Uint8Array): void;\n\n\tabstract close(): void;\n\n\tget closed(): boolean {\n\t\treturn this.#closed;\n\t}\n\n\tonMessage(listener: (message: Uint8Array) => void): void {\n\t\t// A closed end delivers nothing: keeping the listener would keep its owner.\n\t\tif (this.#closed) return;\n\t\tthis.#listener = listener;\n\t\t// A listener may close the link: what is still queued then is dropped.\n\t\tfor (const message of this.#queued.splice(0)) {\n\t\t\tif (this.#closed) return;\n\t\t\tlistener(message);\n\t\t}\n\t}\n\n\tonClose(listener: () => void): void {\n\t\tif (this.#closed) listener();\n\t\telse this.#closeListener = listener;\n\t}\n\n\t/** A message arrived; dropped once closed. */\n\tprotected deliver(message: Uint8Array): void {\n\t\tif (this.#closed) return;\n\t\tif (this.#listener === undefined) this.#queued.push(message);\n\t\telse this.#listener(message);\n\t}\n\n\t/** Closes this end (once): nothing is delivered any more, and nothing the listeners reach is kept. */\n\tprotected ended(): void {\n\t\tif (this.#closed) return;\n\t\tthis.#closed = true;\n\t\tconst listener = this.#closeListener;\n\t\tthis.#listener = undefined;\n\t\tthis.#closeListener = undefined;\n\t\tthis.#queued = [];\n\t\tlistener?.();\n\t}\n}\n\n/**\n * One end of a memory link. Closing it closes this end at once and the peer a microtask later, as a transport would.\n * Portable: `queueMicrotask` only.\n */\nclass MemoryLink extends LinkEnd {\n\tpeer: MemoryLink | undefined;\n\n\tsend(message: Uint8Array): void {\n\t\tif (this.closed) return;\n\t\tconst peer = this.peer!;\n\t\tqueueMicrotask(() => peer.deliver(message));\n\t}\n\n\tclose(): void {\n\t\tif (this.closed) return;\n\t\tconst peer = this.peer!;\n\t\tthis.#end();\n\t\tqueueMicrotask(() => peer.#end());\n\t}\n\n\t#end(): void {\n\t\tthis.peer = undefined;\n\t\tthis.ended();\n\t}\n}\n"]}

package/dist/link/message.d.ts

@@ -0,0 +1,262 @@
+import { type Schema } from "@earendil-works/pi-schema";
+import type { Context } from "../context/index.ts";
+import { type Static } from "../contracts/index.ts";
+/** An error that may come from plugin code: a ChordError's JSON (checked by L1), or a plugin's code and message. */
+declare const wireError: Schema<{
+    kind: "chord";
+    error: unknown;
+} | {
+    kind: "plugin";
+    code: string;
+    message: string;
+    details?: unknown;
+}>;
+/** The members of a hold that failed with this message (W1). */
+declare const failed: Schema<{
+    member: number;
+    error: {
+        kind: "chord";
+        error: unknown;
+    } | {
+        kind: "plugin";
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}[]>;
+/**
+ * The longest name a message carries (a type's, a host kind's): a relay records them in its spans unparsed, so a peer
+ * cannot hand it an unbounded string (slice 9 review M1).
+ */
+export declare const NAME_LENGTH = 256;
+/** An address as a hold names it: its host kind and params, checked against the kind where it is routed. */
+declare const address: Schema<{
+    kind: string;
+    params: unknown;
+}>;
+/** The most keys a trace carrier has, and the longest key or value (R5). */
+export declare const CARRIER: {
+    readonly keys: 8;
+    readonly length: 256;
+};
+/** The longest activation chain a hold carries (Q5): a longer one keeps its last entries. */
+export declare const CHAIN = 32;
+/** A `retry`'s hop budget as the first host sends it (dependency model §3.7, audit A5): one less per host after it. */
+export declare const RETRY_HOPS = 16;
+/** The kinds of a `failed` message's cause, in their codes' order (the binary codec's byte, the text codec's letter). */
+export declare const CAUSE_KINDS: ["transient", "broken", "waiting"];
+/** The protocol's messages, one tagged union. Parts are opaque here (the owners parse them). */
+declare const MESSAGE: Schema<{
+    kind: "hello";
+    protocol: number;
+    incarnation: string;
+    calls: number;
+} | {
+    kind: "hold";
+    origin?: number | undefined;
+    hold: number;
+    type: string;
+    version: number;
+    fingerprint: string;
+    params: string | import("./part.ts").DeflatedPart | Uint8Array<ArrayBufferLike>;
+    address: {
+        kind: string;
+        params: unknown;
+    };
+    principal?: {
+        kind: string;
+    } | undefined;
+    incarnation?: string | undefined;
+    chain?: string[] | undefined;
+    limit?: number | undefined;
+    trace?: Record<string, string> | undefined;
+} | {
+    kind: "release";
+    origin?: number | undefined;
+    hold: number;
+} | {
+    kind: "call";
+    origin?: number | undefined;
+    call: number;
+    hold: number;
+    method: number;
+    args?: string | import("./part.ts").DeflatedPart | Uint8Array<ArrayBufferLike> | undefined;
+    segments?: readonly Uint8Array<ArrayBufferLike>[] | undefined;
+    trace?: Record<string, string> | undefined;
+    old?: true | undefined;
+} | {
+    kind: "abort";
+    origin?: number | undefined;
+    call: number;
+} | {
+    kind: "retry";
+    origin?: number | undefined;
+    hold: number;
+    hops: number;
+} | {
+    kind: "bound";
+    origin?: number | undefined;
+    holds: {
+        hold: number;
+        variant: number;
+        members: {
+            member: number;
+            value: string | import("./part.ts").DeflatedPart | Uint8Array<ArrayBufferLike>;
+        }[];
+        failed: {
+            member: number;
+            error: {
+                kind: "chord";
+                error: unknown;
+            } | {
+                kind: "plugin";
+                code: string;
+                message: string;
+                details?: unknown;
+            };
+        }[];
+    }[];
+} | {
+    kind: "state";
+    origin?: number | undefined;
+    holds: {
+        hold: number;
+        members: {
+            member: number;
+            ops: string | import("./part.ts").DeflatedPart | Uint8Array<ArrayBufferLike>;
+        }[];
+        failed: {
+            member: number;
+            error: {
+                kind: "chord";
+                error: unknown;
+            } | {
+                kind: "plugin";
+                code: string;
+                message: string;
+                details?: unknown;
+            };
+        }[];
+        retired: number[];
+    }[];
+} | {
+    kind: "ack";
+    origin?: number | undefined;
+} | {
+    kind: "closed";
+    origin: number;
+} | {
+    kind: "revoke";
+    revocation: unknown;
+} | {
+    kind: "ping";
+} | {
+    kind: "pong";
+} | {
+    kind: "failed";
+    origin?: number | undefined;
+    hold: number;
+    cause: {
+        kind: "broken" | "transient" | "waiting";
+        error: {
+            kind: "chord";
+            error: unknown;
+        } | {
+            kind: "plugin";
+            code: string;
+            message: string;
+            details?: unknown;
+        };
+    };
+    retryIn?: number | undefined;
+} | {
+    kind: "loading";
+    origin?: number | undefined;
+    hold: number;
+} | {
+    kind: "result";
+    origin?: number | undefined;
+    call: number;
+    value?: string | import("./part.ts").DeflatedPart | Uint8Array<ArrayBufferLike> | undefined;
+    segments?: readonly Uint8Array<ArrayBufferLike>[] | undefined;
+} | {
+    kind: "error";
+    origin?: number | undefined;
+    call: number;
+    error: {
+        kind: "chord";
+        error: unknown;
+    } | {
+        kind: "plugin";
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+} | {
+    kind: "gone";
+    origin?: number | undefined;
+    hold: number;
+    error: {
+        kind: "chord";
+        error: unknown;
+    } | {
+        kind: "plugin";
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}>;
+/**
+ * A protocol message. `args` absent: a method without arguments; `value` absent: `null`. A `state` entry's `retired`
+ * list is read-only (the schema's type is mutable): entries without retirements share `NO_RETIRED`.
+ */
+export type Message = Exclude<WireMessage, WireState> | (Omit<WireState, "holds"> & {
+    readonly holds: readonly StateEntry[];
+});
+type WireMessage = Static<typeof MESSAGE>;
+type WireState = Extract<WireMessage, {
+    readonly kind: "state";
+}>;
+/** An error as it crosses a link. */
+export type WireError = Static<typeof wireError>;
+/** A message that may carry an origin (every kind but `hello`, `revoke`, `ping` and `pong`). */
+export type OriginMessage = Exclude<Message, {
+    readonly kind: "hello" | "revoke" | "ping" | "pong";
+}>;
+/** A message for a provider side: the direction from the consumer (`closed` is the link's). */
+export type ProviderMessage = Extract<Message, {
+    readonly kind: "hold" | "release" | "call" | "abort" | "retry" | "ack";
+}>;
+/** A message for a consumer side: the direction from the provider. */
+export type ConsumerMessage = Extract<Message, {
+    readonly kind: "bound" | "state" | "failed" | "loading" | "result" | "error" | "gone";
+}>;
+/** One hold's entry of a `bound` message. */
+export type BoundEntry = Extract<Message, {
+    readonly kind: "bound";
+}>["holds"][number];
+/** One hold's entry of a `state` message. */
+export type StateEntry = Omit<WireState["holds"][number], "retired"> & {
+    readonly retired: readonly number[];
+};
+/** The `retired` list of a state entry without retirements, shared (no allocation per message). */
+export declare const NO_RETIRED: readonly number[];
+/** An address as a `hold` carries it. */
+export type WireAddress = Static<typeof address>;
+/** A member of a hold that failed, by index, as `bound` and `state` list it. */
+export type FailedMember = Static<typeof failed>[number];
+/** How a link turns messages into bytes and back; both ends of a link use the same one. */
+export interface Codec {
+    readonly name: string;
+    encode(message: Message): Uint8Array;
+    /** Throws on bytes that are no message of this codec (a protocol error); the envelope is checked afterwards. */
+    decode(bytes: Uint8Array): Message;
+}
+/**
+ * Checks a decoded message's envelope with the compiled schema (the wire is a trust boundary, after any codec): kinds,
+ * ids and indexes, lists and error shapes; not the parts. Throws on a mismatch (a protocol error). Counted in
+ * `chord.link.checks`.
+ */
+export declare function checkMessage(message: unknown, context: Context): Message;
+export {};
+//# sourceMappingURL=message.d.ts.map

package/dist/link/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/link/message.ts"],"names":[],"mappings":"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"}

package/dist/link/message.js

@@ -0,0 +1,156 @@
+// Messages (§22, R1, R4, 2b): the one `Message` type every link carries, defined as a schema and checked after every
+// decode, and the codecs that turn it into bytes.
+import { map, obj as openObj } from "@earendil-works/pi-schema";
+import { arr, int, lit, obj, oneOf, opt, str, union, unknown } from "../contracts/index.js";
+import { validatorFor } from "../data/internal.js";
+import { chordMetrics } from "../telemetry.js";
+/** A link-local id, chosen by its origin: a counter, unique per link, direction and origin while in use. */
+const id = int({ min: 0 });
+/**
+ * Whose work a message is (decision "Relay flow control per origin"): a relay's number for one downstream link (and
+ * the origin that link's messages carried), never reused on a link; absent for the sender's own work. Holds, calls,
+ * windows and acks are keyed by (origin, id), and replies carry the origin of what they answer.
+ */
+const origin = int({ min: 1 });
+/** A name as an index into the hold's bound version (each variant's names sorted). */
+const index = int({ min: 0 });
+/** An error that may come from plugin code: a ChordError's JSON (checked by L1), or a plugin's code and message. */
+const wireError = union([
+    obj({ kind: lit("chord"), error: unknown() }),
+    obj({ kind: lit("plugin"), code: str(), message: str(), details: opt(unknown()) }),
+]);
+/** The members of a hold that failed with this message (W1). */
+const failed = arr(obj({ member: index, error: wireError }));
+/** A part's envelope: the codec built it, so any value passes (its content is the owner's to parse). */
+const part = unknown();
+/**
+ * The byte segments of a payload part whose method's schema has a `bytes()` leaf, referenced from its JSON by
+ * `{"$bytes": i}`; absent for every other payload. Built by the codec, like the part.
+ */
+const segments = opt(unknown());
+/**
+ * The longest name a message carries (a type's, a host kind's): a relay records them in its spans unparsed, so a peer
+ * cannot hand it an unbounded string (slice 9 review M1).
+ */
+export const NAME_LENGTH = 256;
+/** A type's or a host kind's name. */
+const name = str({ max: NAME_LENGTH });
+/** An address as a hold names it: its host kind and params, checked against the kind where it is routed. */
+const address = obj({ kind: name, params: unknown() });
+/** A principal on a hold: JSON with a `kind`, honoured only on a parent link. */
+const principal = openObj({ kind: str() }, { open: true });
+/** A uuidv7 as text. */
+const incarnation = str({ pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" });
+/** The most keys a trace carrier has, and the longest key or value (R5). */
+export const CARRIER = { keys: 8, length: 256 };
+/**
+ * The caller's trace carrier on a `hold` or `call` (R5, slice 9): an adapter's opaque string record, bounded, of
+ * printable ASCII only (keys without spaces), as W3C's headers and Chord's adapters are; anything else fails this schema
+ * as any malformed header does, so no control character becomes a stored trace or span id (review M2). The provider
+ * extracts it with its own adapter (absent or unknown: the adapter's root).
+ */
+const trace = opt({
+    ...map(str({ max: CARRIER.length, pattern: "^[\\x20-\\x7e]*$" })),
+    propertyNames: { maxLength: CARRIER.length, pattern: "^[\\x21-\\x7e]+$" },
+    maxProperties: CARRIER.keys,
+});
+/** The longest activation chain a hold carries (Q5): a longer one keeps its last entries. */
+export const CHAIN = 32;
+/** A `retry`'s hop budget as the first host sends it (dependency model §3.7, audit A5): one less per host after it. */
+export const RETRY_HOPS = 16;
+/** The kinds of a `failed` message's cause, in their codes' order (the binary codec's byte, the text codec's letter). */
+export const CAUSE_KINDS = ["transient", "broken", "waiting"];
+/** The protocol's messages, one tagged union. Parts are opaque here (the owners parse them). */
+const MESSAGE = union([
+    // `calls`: how many concurrent calls this side accepts (the call window).
+    obj({ kind: lit("hello"), protocol: int({ min: 0 }), incarnation, calls: int({ min: 1 }) }),
+    obj({
+        kind: lit("hold"),
+        origin: opt(origin),
+        hold: id,
+        type: name,
+        version: int({ min: 1 }),
+        fingerprint: str({ pattern: "^[0-9a-f]{16}$" }),
+        params: part,
+        // The address the caller computed with the type's `hostAddress`: it routes the hold.
+        address,
+        // Whom the hold acts for and the origin's incarnation; read only on a parent link.
+        principal: opt(principal),
+        incarnation: opt(incarnation),
+        // The instance ids of the activations waiting for this hold (Q5); read only on a trusted link.
+        chain: opt(arr(incarnation, { max: CHAIN })),
+        // The decoded limit per part of the link the hold was admitted on (Q2); read only on a parent link.
+        limit: opt(int({ min: 0 })),
+        trace,
+    }),
+    obj({ kind: lit("release"), origin: opt(origin), hold: id }),
+    obj({
+        kind: lit("call"),
+        origin: opt(origin),
+        call: id,
+        hold: id,
+        method: index,
+        args: opt(part),
+        segments,
+        trace,
+        // Old work of a reload (decision "Reload restarts every affected object"): honoured only from a trusted link.
+        old: opt(lit(true)),
+    }),
+    obj({ kind: lit("abort"), origin: opt(origin), call: id }),
+    // Asks the provider for an attempt of a failed hold's object now (`ref.retry()`); `hops` is its budget: the host
+    // there passes it on to its remote dependencies with one less, never at 0, so a waiting ring of hosts stops. Relays
+    // forward it as it is.
+    obj({ kind: lit("retry"), origin: opt(origin), hold: id, hops: int({ min: 1, max: RETRY_HOPS }) }),
+    // Binds several holds at once (first bindings, re-holds), applied in one batch.
+    obj({
+        kind: lit("bound"),
+        origin: opt(origin),
+        holds: arr(obj({ hold: id, variant: index, members: arr(obj({ member: index, value: part })), failed })),
+    }),
+    obj({
+        kind: lit("state"),
+        origin: opt(origin),
+        // `retired`: the members whose document was retired since the hold's last message (decision "One retirement
+        // mechanism"); a `bound` snapshot carries no flag.
+        holds: arr(obj({ hold: id, members: arr(obj({ member: index, ops: part })), failed, retired: arr(index) })),
+    }),
+    // One per applied `bound` or `state` message of its origin (the window).
+    obj({ kind: lit("ack"), origin: opt(origin) }),
+    // A relay's downstream link closed: the origin's holds are released and its calls aborted.
+    obj({ kind: lit("closed"), origin }),
+    // A revocation from the parent, applied with this host's own `revokedBy` (no origin).
+    obj({ kind: lit("revoke"), revocation: unknown() }),
+    obj({ kind: lit("ping") }),
+    obj({ kind: lit("pong") }),
+    obj({
+        kind: lit("failed"),
+        origin: opt(origin),
+        hold: id,
+        // A failure cause's error in the wire error format (a ChordError, checked by L1's envelope check, or a plugin's).
+        // `waiting`: not the object's fault (no provider, no fitting version, a dependency failed); an event wakes it.
+        cause: obj({ kind: oneOf(...CAUSE_KINDS), error: wireError }),
+        // The rest of the object's backoff window in milliseconds: when it retries by itself (absent: broken, waiting).
+        retryIn: opt(int({ min: 0 })),
+    }),
+    // The failed object of a hold started a new attempt.
+    obj({ kind: lit("loading"), origin: opt(origin), hold: id }),
+    obj({ kind: lit("result"), origin: opt(origin), call: id, value: opt(part), segments }),
+    obj({ kind: lit("error"), origin: opt(origin), call: id, error: wireError }),
+    obj({ kind: lit("gone"), origin: opt(origin), hold: id, error: wireError }),
+]);
+/** The `retired` list of a state entry without retirements, shared (no allocation per message). */
+export const NO_RETIRED = [];
+const MESSAGE_SCHEMA = { schema: MESSAGE };
+/**
+ * Checks a decoded message's envelope with the compiled schema (the wire is a trust boundary, after any codec): kinds,
+ * ids and indexes, lists and error shapes; not the parts. Throws on a mismatch (a protocol error). Counted in
+ * `chord.link.checks`.
+ */
+export function checkMessage(message, context) {
+    chordMetrics(context.telemetry.metrics).counter("chord.link.checks").add(1);
+    if (!validatorFor(MESSAGE_SCHEMA, context).check(message))
+        throw new Error("message: fails the message schema");
+    // The check above establishes the type.
+    return message;
+}
+//# sourceMappingURL=message.js.map

package/dist/link/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/link/message.ts"],"names":[],"mappings":"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","sourcesContent":["// Messages (§22, R1, R4, 2b): the one `Message` type every link carries, defined as a schema and checked after every\n// decode, and the codecs that turn it into bytes.\n\nimport { map, obj as openObj, type Schema } from \"@earendil-works/pi-schema\";\nimport type { Context } from \"../context/index.ts\";\nimport { arr, int, lit, obj, oneOf, opt, type Static, str, union, unknown } from \"../contracts/index.ts\";\nimport { validatorFor } from \"../data/internal.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\nimport type { Part } from \"./part.ts\";\n\n/** A link-local id, chosen by its origin: a counter, unique per link, direction and origin while in use. */\nconst id = int({ min: 0 });\n\n/**\n * Whose work a message is (decision \"Relay flow control per origin\"): a relay's number for one downstream link (and\n * the origin that link's messages carried), never reused on a link; absent for the sender's own work. Holds, calls,\n * windows and acks are keyed by (origin, id), and replies carry the origin of what they answer.\n */\nconst origin = int({ min: 1 });\n\n/** A name as an index into the hold's bound version (each variant's names sorted). */\nconst index = int({ min: 0 });\n\n/** An error that may come from plugin code: a ChordError's JSON (checked by L1), or a plugin's code and message. */\nconst wireError = union([\n\tobj({ kind: lit(\"chord\"), error: unknown() }),\n\tobj({ kind: lit(\"plugin\"), code: str(), message: str(), details: opt(unknown()) }),\n]);\n\n/** The members of a hold that failed with this message (W1). */\nconst failed = arr(obj({ member: index, error: wireError }));\n\n/** A part's envelope: the codec built it, so any value passes (its content is the owner's to parse). */\nconst part = unknown() as Schema<Part>;\n\n/**\n * The byte segments of a payload part whose method's schema has a `bytes()` leaf, referenced from its JSON by\n * `{\"$bytes\": i}`; absent for every other payload. Built by the codec, like the part.\n */\nconst segments = opt(unknown() as Schema<readonly Uint8Array[]>);\n\n/**\n * The longest name a message carries (a type's, a host kind's): a relay records them in its spans unparsed, so a peer\n * cannot hand it an unbounded string (slice 9 review M1).\n */\nexport const NAME_LENGTH = 256;\n\n/** A type's or a host kind's name. */\nconst name = str({ max: NAME_LENGTH });\n\n/** An address as a hold names it: its host kind and params, checked against the kind where it is routed. */\nconst address = obj({ kind: name, params: unknown() });\n\n/** A principal on a hold: JSON with a `kind`, honoured only on a parent link. */\nconst principal = openObj({ kind: str() }, { open: true });\n\n/** A uuidv7 as text. */\nconst incarnation = str({ pattern: \"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$\" });\n\n/** The most keys a trace carrier has, and the longest key or value (R5). */\nexport const CARRIER = { keys: 8, length: 256 } as const;\n\n/**\n * The caller's trace carrier on a `hold` or `call` (R5, slice 9): an adapter's opaque string record, bounded, of\n * printable ASCII only (keys without spaces), as W3C's headers and Chord's adapters are; anything else fails this schema\n * as any malformed header does, so no control character becomes a stored trace or span id (review M2). The provider\n * extracts it with its own adapter (absent or unknown: the adapter's root).\n */\nconst trace = opt({\n\t...map(str({ max: CARRIER.length, pattern: \"^[\\\\x20-\\\\x7e]*$\" })),\n\tpropertyNames: { maxLength: CARRIER.length, pattern: \"^[\\\\x21-\\\\x7e]+$\" },\n\tmaxProperties: CARRIER.keys,\n} as Schema<Record<string, string>>);\n\n/** The longest activation chain a hold carries (Q5): a longer one keeps its last entries. */\nexport const CHAIN = 32;\n\n/** A `retry`'s hop budget as the first host sends it (dependency model §3.7, audit A5): one less per host after it. */\nexport const RETRY_HOPS = 16;\n\n/** The kinds of a `failed` message's cause, in their codes' order (the binary codec's byte, the text codec's letter). */\nexport const CAUSE_KINDS: [\"transient\", \"broken\", \"waiting\"] = [\"transient\", \"broken\", \"waiting\"];\n\n/** The protocol's messages, one tagged union. Parts are opaque here (the owners parse them). */\nconst MESSAGE = union([\n\t// `calls`: how many concurrent calls this side accepts (the call window).\n\tobj({ kind: lit(\"hello\"), protocol: int({ min: 0 }), incarnation, calls: int({ min: 1 }) }),\n\tobj({\n\t\tkind: lit(\"hold\"),\n\t\torigin: opt(origin),\n\t\thold: id,\n\t\ttype: name,\n\t\tversion: int({ min: 1 }),\n\t\tfingerprint: str({ pattern: \"^[0-9a-f]{16}$\" }),\n\t\tparams: part,\n\t\t// The address the caller computed with the type's `hostAddress`: it routes the hold.\n\t\taddress,\n\t\t// Whom the hold acts for and the origin's incarnation; read only on a parent link.\n\t\tprincipal: opt(principal),\n\t\tincarnation: opt(incarnation),\n\t\t// The instance ids of the activations waiting for this hold (Q5); read only on a trusted link.\n\t\tchain: opt(arr(incarnation, { max: CHAIN })),\n\t\t// The decoded limit per part of the link the hold was admitted on (Q2); read only on a parent link.\n\t\tlimit: opt(int({ min: 0 })),\n\t\ttrace,\n\t}),\n\tobj({ kind: lit(\"release\"), origin: opt(origin), hold: id }),\n\tobj({\n\t\tkind: lit(\"call\"),\n\t\torigin: opt(origin),\n\t\tcall: id,\n\t\thold: id,\n\t\tmethod: index,\n\t\targs: opt(part),\n\t\tsegments,\n\t\ttrace,\n\t\t// Old work of a reload (decision \"Reload restarts every affected object\"): honoured only from a trusted link.\n\t\told: opt(lit(true)),\n\t}),\n\tobj({ kind: lit(\"abort\"), origin: opt(origin), call: id }),\n\t// Asks the provider for an attempt of a failed hold's object now (`ref.retry()`); `hops` is its budget: the host\n\t// there passes it on to its remote dependencies with one less, never at 0, so a waiting ring of hosts stops. Relays\n\t// forward it as it is.\n\tobj({ kind: lit(\"retry\"), origin: opt(origin), hold: id, hops: int({ min: 1, max: RETRY_HOPS }) }),\n\t// Binds several holds at once (first bindings, re-holds), applied in one batch.\n\tobj({\n\t\tkind: lit(\"bound\"),\n\t\torigin: opt(origin),\n\t\tholds: arr(obj({ hold: id, variant: index, members: arr(obj({ member: index, value: part })), failed })),\n\t}),\n\tobj({\n\t\tkind: lit(\"state\"),\n\t\torigin: opt(origin),\n\t\t// `retired`: the members whose document was retired since the hold's last message (decision \"One retirement\n\t\t// mechanism\"); a `bound` snapshot carries no flag.\n\t\tholds: arr(obj({ hold: id, members: arr(obj({ member: index, ops: part })), failed, retired: arr(index) })),\n\t}),\n\t// One per applied `bound` or `state` message of its origin (the window).\n\tobj({ kind: lit(\"ack\"), origin: opt(origin) }),\n\t// A relay's downstream link closed: the origin's holds are released and its calls aborted.\n\tobj({ kind: lit(\"closed\"), origin }),\n\t// A revocation from the parent, applied with this host's own `revokedBy` (no origin).\n\tobj({ kind: lit(\"revoke\"), revocation: unknown() }),\n\tobj({ kind: lit(\"ping\") }),\n\tobj({ kind: lit(\"pong\") }),\n\tobj({\n\t\tkind: lit(\"failed\"),\n\t\torigin: opt(origin),\n\t\thold: id,\n\t\t// A failure cause's error in the wire error format (a ChordError, checked by L1's envelope check, or a plugin's).\n\t\t// `waiting`: not the object's fault (no provider, no fitting version, a dependency failed); an event wakes it.\n\t\tcause: obj({ kind: oneOf(...CAUSE_KINDS), error: wireError }),\n\t\t// The rest of the object's backoff window in milliseconds: when it retries by itself (absent: broken, waiting).\n\t\tretryIn: opt(int({ min: 0 })),\n\t}),\n\t// The failed object of a hold started a new attempt.\n\tobj({ kind: lit(\"loading\"), origin: opt(origin), hold: id }),\n\tobj({ kind: lit(\"result\"), origin: opt(origin), call: id, value: opt(part), segments }),\n\tobj({ kind: lit(\"error\"), origin: opt(origin), call: id, error: wireError }),\n\tobj({ kind: lit(\"gone\"), origin: opt(origin), hold: id, error: wireError }),\n]);\n\n/**\n * A protocol message. `args` absent: a method without arguments; `value` absent: `null`. A `state` entry's `retired`\n * list is read-only (the schema's type is mutable): entries without retirements share `NO_RETIRED`.\n */\nexport type Message =\n\t| Exclude<WireMessage, WireState>\n\t| (Omit<WireState, \"holds\"> & { readonly holds: readonly StateEntry[] });\n\ntype WireMessage = Static<typeof MESSAGE>;\n\ntype WireState = Extract<WireMessage, { readonly kind: \"state\" }>;\n\n/** An error as it crosses a link. */\nexport type WireError = Static<typeof wireError>;\n\n/** A message that may carry an origin (every kind but `hello`, `revoke`, `ping` and `pong`). */\nexport type OriginMessage = Exclude<Message, { readonly kind: \"hello\" | \"revoke\" | \"ping\" | \"pong\" }>;\n\n/** A message for a provider side: the direction from the consumer (`closed` is the link's). */\nexport type ProviderMessage = Extract<\n\tMessage,\n\t{ readonly kind: \"hold\" | \"release\" | \"call\" | \"abort\" | \"retry\" | \"ack\" }\n>;\n\n/** A message for a consumer side: the direction from the provider. */\nexport type ConsumerMessage = Extract<\n\tMessage,\n\t{ readonly kind: \"bound\" | \"state\" | \"failed\" | \"loading\" | \"result\" | \"error\" | \"gone\" }\n>;\n\n/** One hold's entry of a `bound` message. */\nexport type BoundEntry = Extract<Message, { readonly kind: \"bound\" }>[\"holds\"][number];\n\n/** One hold's entry of a `state` message. */\nexport type StateEntry = Omit<WireState[\"holds\"][number], \"retired\"> & { readonly retired: readonly number[] };\n\n/** The `retired` list of a state entry without retirements, shared (no allocation per message). */\nexport const NO_RETIRED: readonly number[] = [];\n\n/** An address as a `hold` carries it. */\nexport type WireAddress = Static<typeof address>;\n\n/** A member of a hold that failed, by index, as `bound` and `state` list it. */\nexport type FailedMember = Static<typeof failed>[number];\n\n/** How a link turns messages into bytes and back; both ends of a link use the same one. */\nexport interface Codec {\n\treadonly name: string;\n\tencode(message: Message): Uint8Array;\n\t/** Throws on bytes that are no message of this codec (a protocol error); the envelope is checked afterwards. */\n\tdecode(bytes: Uint8Array): Message;\n}\n\nconst MESSAGE_SCHEMA = { schema: MESSAGE };\n\n/**\n * Checks a decoded message's envelope with the compiled schema (the wire is a trust boundary, after any codec): kinds,\n * ids and indexes, lists and error shapes; not the parts. Throws on a mismatch (a protocol error). Counted in\n * `chord.link.checks`.\n */\nexport function checkMessage(message: unknown, context: Context): Message {\n\tchordMetrics(context.telemetry.metrics).counter(\"chord.link.checks\").add(1);\n\tif (!validatorFor(MESSAGE_SCHEMA, context).check(message)) throw new Error(\"message: fails the message schema\");\n\t// The check above establishes the type.\n\treturn message as Message;\n}\n"]}