@cello-protocol/protocol-types 0.0.43 → 0.0.45

package/dist/cbor.d.ts

@@ -1,3 +1,19 @@
+/**
+ * `setSizeLimits` EXISTS at runtime in cbor-x 1.6.4 and is absent from the shipped `.d.ts`.
+ * Verified, not assumed: `Object.keys(require("cbor-x"))` includes it.
+ *
+ * Declared here rather than cast away, so the call below is type-checked against the shape we
+ * actually rely on. If a future cbor-x removes the function, this declaration keeps compiling and
+ * the call becomes a no-op — which is why the limits have their own test rather than resting on the
+ * import succeeding.
+ */
+declare module "cbor-x" {
+    function setSizeLimits(limits: {
+        maxArraySize?: number;
+        maxMapSize?: number;
+        maxObjectSize?: number;
+    }): void;
+}
 /**
  * Encode to CBOR: byte strings for bytes, maps for objects. Valid RFC 8949.
  *

package/dist/cbor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cbor.d.ts","sourceRoot":"","sources":["../src/cbor.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAErD;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAErD"}
+{"version":3,"file":"cbor.d.ts","sourceRoot":"","sources":["../src/cbor.ts"],"names":[],"mappings":"AAsBA;;;;;;;;GAQG;AACH,OAAO,QAAQ,QAAQ,CAAC;IACtB,SAAgB,aAAa,CAAC,MAAM,EAAE;QACpC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,IAAI,CAAC;CACV;AA6DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAErD;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAErD"}

package/dist/cbor.js

@@ -19,6 +19,62 @@
  * tolerance is for data that predates this module — it is not a licence to write a second format.
  */
 import { Encoder, decode } from "cbor-x";
+import { setSizeLimits } from "cbor-x";
+/**
+ * DECODER SIZE LIMITS — a security boundary, not a tuning knob.
+ *
+ * Without them, a few bytes of hostile CBOR cost seconds and gigabytes. MEASURED on this decoder:
+ * `9f b0` (indefinite-length array header, then a map header, no data) took **5.0 s**; `a1 9f` —
+ * THREE bytes, a one-pair map whose first key is an indefinite array — took **9.6 s and 1.1 GB**;
+ * `9f 26` was independently measured at 10 s / 1.6 GB. Any code path that hands peer-controlled
+ * bytes to `decodeCbor` is therefore a denial of service, and every decoder in this package is on
+ * one: the daemon's session content path, the directory's `seal_submission`, the relay.
+ *
+ * A CALLER-SIDE GUARD CANNOT FIX THIS, and one was tried. Inspecting the header byte is sound about
+ * the outermost container and says nothing about what is nested inside it — a valid map header
+ * followed by an indefinite array is admitted by any header check, including one requiring the real
+ * frames' own `b9 000a` prefix. The bound has to be on the decoder.
+ *
+ * ── WHY 250,000 AND NOT SOMETHING TIGHTER ─────────────────────────────────────────────────────
+ *
+ * The bound is set by the LARGEST LEGITIMATE STRUCTURE, not by the attack. `ae-channel.ts` in
+ * trustless-cello declares `MAX_WIRE_ITEMS = 250_000` as the anti-hostile-peer bound for
+ * directory-to-directory replication, and it decodes BEFORE applying it — so a tighter global cap
+ * here silently supersedes it. A first attempt at 65,536 did exactly that: at 65,537 rows in any
+ * replicated table (`agent_profiles`, `conversation_seals`, `seal_notarizations`, …, none of which
+ * the AE store paginates) replication would have stopped permanently and been reported as a PEER
+ * protocol violation. That is the same shape of failure this repo already ate on 2026-08-01.
+ *
+ * Refusing real data is the worse direction. A slow decode is a nuisance; a directory that cannot
+ * replicate, blaming its peer, is an outage nobody can diagnose from the message.
+ *
+ * The limit is EXCLUSIVE — cbor-x throws "Array length exceeds N" at exactly N, not above it — so a
+ * cap of 250,000 would refuse a frame carrying exactly `MAX_WIRE_ITEMS`, which is the boundary the
+ * AE channel is most likely to sit on because that is its own declared maximum. 262,144 (2^18) is
+ * the next round number clear of it, and the margin is the point rather than the roundness.
+ *
+ * Measured: a legitimate 250,000-element frame decodes in ~30 ms; the three-byte hostile inputs
+ * above are 3–4 ms; byte strings are not counted at all, so a 1 MB Yjs update is unaffected.
+ *
+ * ── WHAT THIS DOES *NOT* CLOSE ────────────────────────────────────────────────────────────────
+ *
+ * A size limit is not a completeness argument, and saying otherwise was the previous version of
+ * this comment. cbor-x pre-allocates `new Array(declaredCount)` BEFORE reading any element, so
+ * NESTED definite-length arrays each sitting just under the cap still allocate: measured, 15 KB of
+ * such input costs ~230 ms and ~2.3 GB before V8's stack depth stops it. The missing invariant is
+ * "a container cannot declare more elements than there are bytes left to fill it", which cbor-x
+ * does not enforce and this cannot express.
+ *
+ * So every caller that hands PEER-CONTROLLED bytes to `decodeCbor` must also bound the INPUT
+ * LENGTH — that is what makes the nesting depth finite. This limit reduces the per-byte
+ * amplification by roughly 43,000×; the input cap is what closes the class.
+ *
+ * Process-global to cbor-x, which is the right blast radius for the part it does cover: the decode
+ * functions are public API of this package, so a limit attached to one caller would leave every
+ * other caller unguarded. `maxObjectSize` is passed for symmetry and is inert — cbor-x 1.6.4
+ * accepts it and never reads it; plain-object key counts are bounded by `maxMapSize`.
+ */
+setSizeLimits({ maxArraySize: 262_144, maxMapSize: 262_144, maxObjectSize: 262_144 });
 const ENCODER = new Encoder({ tagUint8Array: false, useRecords: false });
 /**
  * Encode to CBOR: byte strings for bytes, maps for objects. Valid RFC 8949.

package/dist/cbor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cbor.js","sourceRoot":"","sources":["../src/cbor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAe,CAAC;AAC7C,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}
+{"version":3,"file":"cbor.js","sourceRoot":"","sources":["../src/cbor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAkBzC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,aAAa,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;AAEtF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAe,CAAC;AAC7C,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/document-ack.d.ts

@@ -0,0 +1,111 @@
+/**
+ * DOD-DOC-INBOUND-2 — the document ACK (§16.4).
+ *
+ * The frame that closes DELIVERY-2's loop. Until it exists, a sent envelope's outcome is
+ * `admitted: null` forever: the worker knows the content left and nothing more, so it re-sends on
+ * the ack timeout and eventually stalls the document at the unacked ceiling.
+ *
+ * ── WHY A REJECTION IS AN ACK ─────────────────────────────────────────────────────────────────
+ *
+ * `admitted: false` is not a failure to acknowledge — it is an acknowledgement that says no. The
+ * peer has DECIDED, so the sender must stop retrying and supersede instead (§3.2). Modelling
+ * rejection as "no ack" would leave the sender redelivering an envelope the peer has already ruled
+ * on, re-triggering their gate and their retry counter until the document stalls for reasons the
+ * operator cannot see.
+ *
+ * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
+ *
+ * The ack settles an envelope permanently: an acked envelope stops being redelivered and, if the
+ * ack says rejected, the sender rolls back local work. Both are consequences an unauthenticated
+ * party must not be able to cause. An unsigned ack lets anyone who can reach the channel silence a
+ * delivery — the content is dropped from the pending set and neither operator ever learns it was
+ * never applied, which is exactly the silent divergence the two-layer design exists to prevent.
+ *
+ * The signature covers the ENVELOPE HASH, so an ack cannot be moved to a different envelope, and
+ * the DOCUMENT ID, so it cannot be moved to a different document. It does not cover `admitted`
+ * alone for the same reason a signature never covers one field: the whole statement is the claim.
+ *
+ * ── CONTRACT FOR THE CONSUMER: SETTLE ONCE ────────────────────────────────────────────────────
+ *
+ * Nothing here binds an ack to the acker's chain, and nothing at the type level stops one acker
+ * producing a valid ADMISSION and a valid REJECTION for the same envelope. Envelopes have
+ * `verifyDocumentChainLink` because per-sender ordering matters; acks have no equivalent. So the
+ * consumer must settle an envelope ONCE and treat a second, contradicting ack as an ERROR with both
+ * signatures retained — never as an update. Applying the later one would let a peer that admitted
+ * an envelope later claim it refused it, and the sender would roll back work the peer already has.
+ */
+/** Domain tag in slot 0. Distinct from the update and proposal domains. */
+export declare const DOCUMENT_ACK_DOMAIN = "CELLO-DOCUMENT-ACK-v1";
+/**
+ * The ack frame version, ON THE WIRE.
+ *
+ * The `-v1` in the domain string never travels — it lives inside the preimage — so a V2 acker's
+ * frame would decode cleanly as V1 and fail SIGNATURE VERIFICATION, sending an operator to key
+ * management and peer identity for a version-skew bug. The update envelope refuses `epoch_id` and
+ * `update_encoding` by value for exactly this reason: skew that is not SAID becomes silent loss or
+ * a misattributed error.
+ */
+export declare const DOCUMENT_ACK_VERSION = 1;
+/**
+ * A rejection reason is peer-controlled text bound for an operator's screen and the policy log.
+ * Capped because unbounded peer-controlled display text is not something to hand onward untouched.
+ */
+export declare const MAX_REJECTION_REASON_LENGTH = 200;
+export interface DocumentAck {
+    type: "document_ack";
+    /** Always `DOCUMENT_ACK_VERSION` in V1. Carried on the wire so skew is DETECTED, not misread. */
+    ack_version: number;
+    document_id: string;
+    /** The envelope this settles. */
+    envelope_hash: string;
+    /** Who is answering — the party that received the update. */
+    acker_agent_id: string;
+    /**
+     * `true` admitted, `false` rejected. BOTH settle the envelope; see the header. There is no third
+     * value on the wire, because an ack that does not say which is not an answer.
+     */
+    admitted: boolean;
+    /** Present iff `admitted` is false. The §3.2 reason, so the sender can supersede deliberately. */
+    rejection_reason?: string;
+    acked_at_ms: number;
+    /** Ed25519 (RFC 8032) over `buildDocumentAckTbs`. */
+    signature: Uint8Array;
+}
+/**
+ * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
+ *
+ * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
+ * deterministic for maps, so a map preimage would make the signature depend on the order the acker
+ * happened to build the object in, and two honest implementations would disagree.
+ *
+ * `rejection_reason` is encoded as `null` when absent rather than omitted, so the slot is always
+ * occupied and no field's meaning depends on whether the one before it was present.
+ *
+ * An earlier version of this comment claimed omission would be "silently absorbed by the next
+ * field". That is FALSE for this encoder and worth correcting rather than deleting, because a wrong
+ * fact about the wire is what the next structure's justification gets built on: a 6-element array
+ * begins `0x86` and a 7-element one `0x87`, so a missing slot is loud, in byte 0. Measured.
+ * `cbor.ts` says the same thing — arrays are minimal and order-fixed. The explicit null is still
+ * right; the reason is stable slot indices, not collision avoidance.
+ */
+export declare function buildDocumentAckTbs(ack: DocumentAck, opts?: {
+    preHash?: boolean;
+}): Uint8Array;
+/**
+ * The cross-field rules, checked on ENCODE as well as decode.
+ *
+ * On encode too, because a locally-built contradictory ack would otherwise be signed and shipped
+ * and fail only on the remote decode: the sender sees a silent stall, the peer sees the error, and
+ * the two never meet. The rule belongs where the object is built, not only where it is read.
+ */
+export declare function assertDocumentAckConsistent(ack: DocumentAck): void;
+export declare function encodeDocumentAck(ack: DocumentAck): Uint8Array;
+/**
+ * Decode and validate. Refuses rather than defaulting on every field.
+ *
+ * The one that matters most: `admitted` must be a real boolean. Coerced, a truthy string like
+ * `"false"` would settle a REJECTED envelope as admitted — the sender would stop retrying, never
+ * roll back, and both parties would believe content was applied that the receiver refused.
+ */
+export declare function decodeDocumentAck(bytes: Uint8Array): DocumentAck;
+//# sourceMappingURL=document-ack.d.ts.map

package/dist/document-ack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-ack.d.ts","sourceRoot":"","sources":["../src/document-ack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAI/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,kGAAkG;IAClG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CAsBZ;AAOD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAmBlE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CAa9D;AAWD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAuFhE"}

package/dist/document-ack.js

@@ -0,0 +1,228 @@
+/**
+ * DOD-DOC-INBOUND-2 — the document ACK (§16.4).
+ *
+ * The frame that closes DELIVERY-2's loop. Until it exists, a sent envelope's outcome is
+ * `admitted: null` forever: the worker knows the content left and nothing more, so it re-sends on
+ * the ack timeout and eventually stalls the document at the unacked ceiling.
+ *
+ * ── WHY A REJECTION IS AN ACK ─────────────────────────────────────────────────────────────────
+ *
+ * `admitted: false` is not a failure to acknowledge — it is an acknowledgement that says no. The
+ * peer has DECIDED, so the sender must stop retrying and supersede instead (§3.2). Modelling
+ * rejection as "no ack" would leave the sender redelivering an envelope the peer has already ruled
+ * on, re-triggering their gate and their retry counter until the document stalls for reasons the
+ * operator cannot see.
+ *
+ * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
+ *
+ * The ack settles an envelope permanently: an acked envelope stops being redelivered and, if the
+ * ack says rejected, the sender rolls back local work. Both are consequences an unauthenticated
+ * party must not be able to cause. An unsigned ack lets anyone who can reach the channel silence a
+ * delivery — the content is dropped from the pending set and neither operator ever learns it was
+ * never applied, which is exactly the silent divergence the two-layer design exists to prevent.
+ *
+ * The signature covers the ENVELOPE HASH, so an ack cannot be moved to a different envelope, and
+ * the DOCUMENT ID, so it cannot be moved to a different document. It does not cover `admitted`
+ * alone for the same reason a signature never covers one field: the whole statement is the claim.
+ *
+ * ── CONTRACT FOR THE CONSUMER: SETTLE ONCE ────────────────────────────────────────────────────
+ *
+ * Nothing here binds an ack to the acker's chain, and nothing at the type level stops one acker
+ * producing a valid ADMISSION and a valid REJECTION for the same envelope. Envelopes have
+ * `verifyDocumentChainLink` because per-sender ordering matters; acks have no equivalent. So the
+ * consumer must settle an envelope ONCE and treat a second, contradicting ack as an ERROR with both
+ * signatures retained — never as an update. Applying the later one would let a peer that admitted
+ * an envelope later claim it refused it, and the sender would roll back work the peer already has.
+ */
+import { createHash } from "node:crypto";
+import { encodeCbor, decodeCbor } from "./cbor.js";
+/** Domain tag in slot 0. Distinct from the update and proposal domains. */
+export const DOCUMENT_ACK_DOMAIN = "CELLO-DOCUMENT-ACK-v1";
+/**
+ * The ack frame version, ON THE WIRE.
+ *
+ * The `-v1` in the domain string never travels — it lives inside the preimage — so a V2 acker's
+ * frame would decode cleanly as V1 and fail SIGNATURE VERIFICATION, sending an operator to key
+ * management and peer identity for a version-skew bug. The update envelope refuses `epoch_id` and
+ * `update_encoding` by value for exactly this reason: skew that is not SAID becomes silent loss or
+ * a misattributed error.
+ */
+export const DOCUMENT_ACK_VERSION = 1;
+/**
+ * A rejection reason is peer-controlled text bound for an operator's screen and the policy log.
+ * Capped because unbounded peer-controlled display text is not something to hand onward untouched.
+ */
+export const MAX_REJECTION_REASON_LENGTH = 200;
+const HEX32 = /^[0-9a-f]{64}$/;
+/**
+ * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
+ *
+ * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
+ * deterministic for maps, so a map preimage would make the signature depend on the order the acker
+ * happened to build the object in, and two honest implementations would disagree.
+ *
+ * `rejection_reason` is encoded as `null` when absent rather than omitted, so the slot is always
+ * occupied and no field's meaning depends on whether the one before it was present.
+ *
+ * An earlier version of this comment claimed omission would be "silently absorbed by the next
+ * field". That is FALSE for this encoder and worth correcting rather than deleting, because a wrong
+ * fact about the wire is what the next structure's justification gets built on: a 6-element array
+ * begins `0x86` and a 7-element one `0x87`, so a missing slot is loud, in byte 0. Measured.
+ * `cbor.ts` says the same thing — arrays are minimal and order-fixed. The explicit null is still
+ * right; the reason is stable slot indices, not collision avoidance.
+ */
+export function buildDocumentAckTbs(ack, opts = {}) {
+    assertDocumentAckConsistent(ack);
+    const preimage = encodeCbor([
+        DOCUMENT_ACK_DOMAIN,
+        ack.ack_version,
+        ack.document_id,
+        ack.envelope_hash,
+        ack.acker_agent_id,
+        ack.admitted,
+        normalizeReason(ack.rejection_reason),
+        // BIGINT past 0xffffffff. cbor-x encodes a JS number that large as an IEEE float64 (`fb`)
+        // rather than a uint64 (`1b`) — measured: 1700000000000 gives fb4278bcfe56800000, not
+        // 1b0000018bcfe56800. A millisecond timestamp is always that large, so any implementation
+        // encoding RFC 8949-canonically would compute different TBS bytes and reject a GENUINE ack —
+        // surfacing as a signature failure, which reads as forgery. Three sibling builders carry this
+        // same coercion and primary-transfer.ts names it as a defect it shipped without.
+        typeof ack.acked_at_ms === "number" && ack.acked_at_ms > 0xffffffff
+            ? BigInt(ack.acked_at_ms)
+            : ack.acked_at_ms,
+    ]);
+    if (opts.preHash === false)
+        return preimage;
+    return new Uint8Array(createHash("sha256").update(preimage).digest());
+}
+/** Empty string means ABSENT. See `assertDocumentAckConsistent`. */
+function normalizeReason(reason) {
+    return reason === undefined || reason === "" ? null : reason;
+}
+/**
+ * The cross-field rules, checked on ENCODE as well as decode.
+ *
+ * On encode too, because a locally-built contradictory ack would otherwise be signed and shipped
+ * and fail only on the remote decode: the sender sees a silent stall, the peer sees the error, and
+ * the two never meet. The rule belongs where the object is built, not only where it is read.
+ */
+export function assertDocumentAckConsistent(ack) {
+    const reason = normalizeReason(ack.rejection_reason);
+    if (!ack.admitted && reason === null) {
+        // The sender is being told to stop and supersede. Without the reason it cannot know what to
+        // change — the failure the whole rejection protocol exists to prevent.
+        throw new Error("document_ack_reason: a rejection must carry its reason");
+    }
+    if (ack.admitted && reason !== null) {
+        // A contradiction: whichever field a reader trusts, the other is lying to them.
+        throw new Error(`document_ack_reason: an admission must not carry a rejection reason, and this one carries "${reason}"`);
+    }
+    if (reason !== null && reason.length > MAX_REJECTION_REASON_LENGTH) {
+        throw new Error(`document_ack_reason: a rejection reason may be at most ${MAX_REJECTION_REASON_LENGTH} ` +
+            `characters, and this one is ${reason.length}`);
+    }
+}
+export function encodeDocumentAck(ack) {
+    assertDocumentAckConsistent(ack);
+    return encodeCbor({
+        type: ack.type,
+        ack_version: ack.ack_version,
+        document_id: ack.document_id,
+        envelope_hash: ack.envelope_hash,
+        acker_agent_id: ack.acker_agent_id,
+        admitted: ack.admitted,
+        rejection_reason: normalizeReason(ack.rejection_reason),
+        acked_at_ms: ack.acked_at_ms,
+        signature: ack.signature,
+    });
+}
+function present(map, field) {
+    // `in`, not a nullish check — the same discipline as the update envelope. A defaulted field here
+    // is a claim the acker never made, and this frame's whole job is to carry their claim.
+    if (!(field in map)) {
+        throw new Error(`document_ack_missing_field: ${field} is mandatory and was not present`);
+    }
+    return map[field];
+}
+/**
+ * Decode and validate. Refuses rather than defaulting on every field.
+ *
+ * The one that matters most: `admitted` must be a real boolean. Coerced, a truthy string like
+ * `"false"` would settle a REJECTED envelope as admitted — the sender would stop retrying, never
+ * roll back, and both parties would believe content was applied that the receiver refused.
+ */
+export function decodeDocumentAck(bytes) {
+    const decoded = decodeCbor(bytes);
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+        throw new Error("document_ack_malformed: not a CBOR map");
+    }
+    const map = decoded;
+    const type = present(map, "type");
+    if (type !== "document_ack") {
+        throw new Error(`document_ack_type: expected document_ack, got ${String(type)}`);
+    }
+    const version = present(map, "ack_version");
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+        throw new Error("document_ack_version: must be an integer");
+    }
+    if (version !== DOCUMENT_ACK_VERSION) {
+        // Named as SKEW. Without a wire version this frame decoded cleanly and failed signature
+        // verification instead, sending an operator to key management for a version problem.
+        throw new Error(`document_ack_version: this build speaks ack version ${DOCUMENT_ACK_VERSION} and the frame ` +
+            `declares ${version} — one of the two clients needs upgrading`);
+    }
+    const documentId = present(map, "document_id");
+    if (typeof documentId !== "string" || !HEX32.test(documentId)) {
+        throw new Error(`document_ack_document_id: must be a 32-byte hex digest`);
+    }
+    const envelopeHash = present(map, "envelope_hash");
+    if (typeof envelopeHash !== "string" || !HEX32.test(envelopeHash)) {
+        throw new Error("document_ack_envelope_hash: must be a 32-byte hex digest");
+    }
+    const ackerAgentId = present(map, "acker_agent_id");
+    if (typeof ackerAgentId !== "string" || ackerAgentId.length === 0) {
+        throw new Error("document_ack_acker: acker_agent_id must be a non-empty text string");
+    }
+    const admitted = present(map, "admitted");
+    if (typeof admitted !== "boolean") {
+        throw new Error(`document_ack_admitted: must be a boolean, got ${typeof admitted}`);
+    }
+    const rawReason = present(map, "rejection_reason");
+    if (rawReason !== null && typeof rawReason !== "string") {
+        throw new Error("document_ack_reason: rejection_reason must be a text string or explicit null");
+    }
+    // NORMALIZED ONCE, before the cross-field rules. The empty string meant "absent" on the rejection
+    // branch and "present" on the admission branch, so an honest peer written in a language where a
+    // non-nullable string field defaults to "" — Go, Rust — had its ADMISSION refused as a
+    // contradiction it never expressed. The sender then never settles, retries to the unacked
+    // ceiling, and the document stalls: precisely the failure this frame exists to end.
+    const reason = rawReason === "" ? null : rawReason;
+    const ackedAt = present(map, "acked_at_ms");
+    // BOUNDED. `Number.isInteger(1e300)` is true, and this is the only field available to order two
+    // conflicting acks — leaving it unbounded hands that tiebreak to an attacker-chosen value.
+    if (typeof ackedAt !== "number" || !Number.isSafeInteger(ackedAt) || ackedAt <= 0) {
+        throw new Error(`document_ack_time: acked_at_ms must be a positive safe integer, got ${String(ackedAt)}`);
+    }
+    const signature = present(map, "signature");
+    if (!(signature instanceof Uint8Array)) {
+        throw new Error("document_ack_signature: must be a CBOR byte string");
+    }
+    const ack = {
+        type: "document_ack",
+        ack_version: version,
+        document_id: documentId,
+        envelope_hash: envelopeHash,
+        acker_agent_id: ackerAgentId,
+        admitted,
+        ...(reason === null ? {} : { rejection_reason: reason }),
+        acked_at_ms: ackedAt,
+        // COPIED — cbor-x returns byte strings as views into the buffer it decoded, so a caller reusing
+        // a pooled read buffer would have the signature change after it was verified.
+        signature: new Uint8Array(signature),
+    };
+    // The same cross-field rules the encoder applies. One implementation, so the two surfaces cannot
+    // drift into disagreeing about what a valid ack is.
+    assertDocumentAckConsistent(ack);
+    return ack;
+}
+//# sourceMappingURL=document-ack.js.map

package/dist/document-ack.js.map

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

package/dist/document-control.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DOD-DOC-TOOLS-1 — the document CONTROL frame: close and kill (§16.5).
+ *
+ * A unilateral end, told to the other party.
+ *
+ * ── WHY THE PEER MUST BE TOLD, AND WHY IT IS BEST-EFFORT ──────────────────────────────────────
+ *
+ * `DocumentLifecycle` already ends a document locally without asking anyone — that is deliberate: a
+ * kill is a safety verb, and a safety verb that needs the counterparty's cooperation is not one. But
+ * a peer who is never told keeps publishing into a document that will never answer. Their updates
+ * are refused at the far end forever, and nothing on their screen explains why. So the notification
+ * is REQUIRED to be attempted and ALLOWED to fail, and the operator is told which happened.
+ *
+ * ── CLOSE AND KILL ARE DIFFERENT FRAMES OF THE SAME SHAPE ─────────────────────────────────────
+ *
+ * `close` is "I am done with this, and I expect you are too" — the document settles when both sides
+ * have said it. `kill` is "this is over now", one-sided and immediate. They travel as one frame with
+ * a verb rather than two types because the receiving side's routing, verification and settle-once
+ * rules are identical, and two decoders for one shape is how the rules drift apart.
+ *
+ * The verb is REFUSED BY VALUE on decode. A third verb from a future build must not be admitted as
+ * one of these two — a `kill` silently read as a `close` would leave a killed document waiting for
+ * a reciprocal close that is never coming.
+ *
+ * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
+ *
+ * A kill frame ends a collaboration. Unsigned, anyone reaching the channel could end any document
+ * between any two parties, and each operator would believe the other walked away. The signature
+ * covers the document id — which commits to both parties, the properties and the nonce — and the
+ * verb, because the whole statement is the claim.
+ */
+/** Domain tag in slot 0. Distinct from every other document domain. */
+export declare const DOCUMENT_CONTROL_DOMAIN = "CELLO-DOCUMENT-CONTROL-v1";
+/** The frame version, ON THE WIRE, so skew is DETECTED rather than misread as a bad signature. */
+export declare const DOCUMENT_CONTROL_VERSION = 1;
+/** Peer-controlled display text bound for an operator's screen. Capped for that reason. */
+export declare const MAX_CONTROL_REASON_LENGTH = 200;
+/** The two ways a document ends. Closed set — see the header on refusing a third by value. */
+export declare const DOCUMENT_CONTROL_VERBS: readonly ["close", "kill"];
+export type DocumentControlVerb = (typeof DOCUMENT_CONTROL_VERBS)[number];
+export interface DocumentControl {
+    type: "document_control";
+    control_version: number;
+    document_id: string;
+    /** Who is ending it. */
+    sender_agent_id: string;
+    verb: DocumentControlVerb;
+    /** Optional, and optional for both verbs — an end is a decision, not something one must justify. */
+    reason?: string;
+    sent_at_ms: number;
+    /** Ed25519 (RFC 8032) over `buildDocumentControlTbs`. */
+    signature: Uint8Array;
+}
+export declare function assertDocumentControlConsistent(control: DocumentControl): void;
+/**
+ * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
+ *
+ * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
+ * deterministic for maps, so a map preimage would make the signature depend on the order the sender
+ * happened to build the object in, and two honest implementations would disagree.
+ */
+export declare function buildDocumentControlTbs(control: DocumentControl, opts?: {
+    preHash?: boolean;
+}): Uint8Array;
+export declare function encodeDocumentControl(control: DocumentControl): Uint8Array;
+/**
+ * Decode and validate. Refuses rather than defaulting on every field.
+ *
+ * The one that matters most is `verb`. Defaulted or coerced, a `kill` read as a `close` leaves a
+ * killed document waiting for a reciprocal close that is never coming — the operator sees a
+ * collaboration that will not settle and no reason anywhere for why.
+ */
+export declare function decodeDocumentControl(bytes: Uint8Array): DocumentControl;
+//# sourceMappingURL=document-control.d.ts.map

package/dist/document-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-control.d.ts","sourceRoot":"","sources":["../src/document-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB,4BAA6B,CAAC;AACjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI1E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,SAAS,EAAE,UAAU,CAAC;CACvB;AAMD,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAgB9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CAoBZ;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,CAY1E;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,CAiExE"}