@earendil-works/chord 1.4.0 → 1.5.0

package/dist/next/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/next/link/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../../src/next/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/next/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/next/link/link.js.map

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

@@ -0,0 +1,249 @@
+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;
+    };
+}[]>;
+/** 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 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;
+} | {
+    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;
+} | {
+    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/next/link/message.d.ts.map

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

package/dist/next/link/message.js

@@ -0,0 +1,123 @@
+// 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 { 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";
+/** 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());
+/** An address as a hold names it: its host kind and params, checked against the kind where it is routed. */
+const address = obj({ kind: str(), 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 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: str(),
+        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 })),
+    }),
+    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 }),
+    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) {
+    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/next/link/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../../src/next/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 { 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 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/** An address as a hold names it: its host kind and params, checked against the kind where it is routed. */\nconst address = obj({ kind: str(), 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 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: str(),\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}),\n\tobj({ kind: lit(\"release\"), origin: opt(origin), hold: id }),\n\tobj({ kind: lit(\"call\"), origin: opt(origin), call: id, hold: id, method: index, args: opt(part), segments }),\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\tcontext.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"]}

package/dist/next/link/part.d.ts

@@ -0,0 +1,80 @@
+import type { Context } from "../../context/index.ts";
+import { ChordError } from "../data/index.ts";
+/**
+ * A part (R1): a value as JSON text at its origin (and after a text decode), its UTF-8 bytes once a binary codec
+ * received it (or at an origin that encoded it already), or those bytes deflated by an origin that compresses. Opaque
+ * on the way: only the end that owns it opens and parses it, while handling its message (a malformed part is a protocol
+ * error then), so a relay forwards it unparsed and still deflated.
+ */
+export type Part = string | Uint8Array | DeflatedPart;
+/** What inflating a deflated part gave: its JSON bytes, more than the decoded limit, or data that is no raw deflate. */
+export type Inflated = {
+    readonly kind: "bytes";
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "too_large";
+} | {
+    readonly kind: "corrupt";
+    readonly error: unknown;
+};
+/**
+ * A JSON part deflated (raw deflate) by its origin. A host without a synchronous compressor inflates it before its
+ * owner handles the message (`inflateAsync`) and keeps the outcome here for the owner to open.
+ */
+export declare class DeflatedPart {
+    readonly bytes: Uint8Array;
+    /** The asynchronous inflate's outcome; `undefined` until one ran. */
+    inflated: Inflated | undefined;
+    constructor(bytes: Uint8Array);
+}
+/**
+ * A synchronous compressor (`createHost({ compression })`; `nodeCompression` for Node). `deflate` is raw deflate at
+ * level 1. `inflate` gives at most `limit` bytes (`Infinity`: no limit; 0 allowed), `too_large` when the output would
+ * be larger, `corrupt` for data that is no raw deflate stream.
+ */
+export interface Compression {
+    deflate(bytes: Uint8Array): Uint8Array;
+    inflate(bytes: Uint8Array, limit: number): Inflated;
+}
+/** A link's limits per part as `accept`, `connect` and `resolve` take them, in bytes. */
+export type PartLimits = {
+    /** A part's size on the wire. */
+    readonly part?: number;
+    /** A part's size after inflating it. */
+    readonly decoded?: number;
+};
+/** A link's limits in force; `Infinity` for none. */
+export type Limits = {
+    readonly part: number;
+    readonly decoded: number;
+};
+/** The limits of a link: the ones set, the defaults of its trust for the others. */
+export declare function linkLimits(trusted: boolean, limits?: PartLimits): Limits;
+/** JSON parts above this many UTF-8 bytes are compressed at their origin (a protocol constant). */
+export declare const COMPRESS_ABOVE: number;
+/**
+ * A JSON part at its origin: deflated when the host compresses, its UTF-8 bytes are above `COMPRESS_ABOVE` and
+ * deflating made it smaller; otherwise the text, or its bytes once they were encoded (never encoded twice). Counts one
+ * deflate (`chord.link.deflates`).
+ */
+export declare function originPart(json: string, compression: Compression | undefined, context: Context): Part;
+/**
+ * The `too_large/part` error of a part whose size on the wire (its UTF-8 bytes; a deflated part's deflated bytes) is
+ * above `limit`; `undefined` within it. Nothing is parsed or inflated.
+ */
+export declare function oversized(part: Part, limit: number): ChordError | undefined;
+/**
+ * The JSON of a part its owner is about to parse: its size checked against `limits.part` first, then its decoded size
+ * against `limits.decoded`, a deflated part inflated within it (synchronously with `compression`, or by the
+ * asynchronous inflate that ran ahead of its owner). Throws `too_large/part` past a limit; throws a plain error for a
+ * deflated part nothing inflated or that is no raw deflate stream (a protocol error). Counts one synchronous inflate
+ * (`chord.link.inflates`).
+ */
+export declare function openPart(part: Part, limits: Limits, compression: Compression | undefined, context: Context): string | Uint8Array;
+/**
+ * Inflates `part` with the web `DecompressionStream` (a host without a synchronous compressor), counting output bytes
+ * and stopping past `limit`; the outcome is kept on the part. `signal` (the link's close) cancels the stream at once,
+ * leaving no outcome. Counts one inflate (`chord.link.inflates`).
+ */
+export declare function inflateAsync(part: DeflatedPart, limit: number, signal: AbortSignal, context: Context): Promise<void>;
+//# sourceMappingURL=part.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"part.d.ts","sourceRoot":"","sources":["../../../src/next/link/part.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;AAEtD,wHAAwH;AACxH,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzD;;;GAGG;AACH,qBAAa,YAAY;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAE/B,YAAY,KAAK,EAAE,UAAU,EAE5B;CACD;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACvC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;CACpD;AAED,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG;IACxB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AASzE,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,UAAe,GAAG,MAAM,CAG5E;AAED,mGAAmG;AACnG,eAAO,MAAM,cAAc,QAAY,CAAC;AAIxC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAQrG;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAI3E;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACvB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,OAAO,EAAE,OAAO,GACd,MAAM,GAAG,UAAU,CAuBrB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAqCf"}