@earendil-works/chord 1.5.0 → 1.5.1

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"]}

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

@@ -0,0 +1 @@
+{"version":3,"file":"part.d.ts","sourceRoot":"","sources":["../../src/link/part.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;;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"}