@cello-protocol/protocol-types 0.0.44 → 0.0.45

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

@@ -0,0 +1,98 @@
+/**
+ * DOD-DOC-TOOLS-1 — the PROPOSAL ack (§16.3).
+ *
+ * The consent decision, told to the party who asked for it.
+ *
+ * ── WHY THIS EXISTS ───────────────────────────────────────────────────────────────────────────
+ *
+ * Without it the proposer is never told the answer. `cello_doc_list` had to INFER acceptance from
+ * "the peer has published into it", which conflates three different situations — refused, never
+ * received, and accepted-but-untouched — into one absent flag. Two of those want the operator to
+ * act and one does not, and the surface could not tell them apart. A protocol that asks for consent
+ * and never reports it is not asking; it is announcing.
+ *
+ * ── WHY IT IS SEPARATE FROM `document_ack` ────────────────────────────────────────────────────
+ *
+ * `document_ack` settles an ENVELOPE, identified by its hash in the log. A proposal is not in the
+ * envelope log — there is no document yet, which is the whole point — so an ack shaped around an
+ * envelope hash would carry a hash of nothing, and its consumer looks the envelope up. Overloading
+ * the frame would mean one decoder branching on whether the thing it references exists, which is
+ * how a settle-once rule gets applied to the wrong table.
+ *
+ * ── WHY IT IS SIGNED, AND WHAT THE SIGNATURE COVERS ───────────────────────────────────────────
+ *
+ * A refusal ack tells the proposer to stop: no retry, no document. Unsigned, anyone reaching the
+ * channel could make a proposal appear refused by a party who never saw it, and the two operators
+ * would each believe the other had walked away. The signature covers the DOCUMENT ID — which
+ * commits to the proposer, the peer, the properties and the nonce — so an ack cannot be moved to
+ * another proposal, and the decision itself, because the whole statement is the claim.
+ *
+ * ── SETTLE ONCE ───────────────────────────────────────────────────────────────────────────────
+ *
+ * Nothing here orders two acks from one acker, and the same rule `document_ack` states applies: a
+ * second, CONTRADICTING ack is an error with both signatures retained, never an update. A peer that
+ * accepted must not be able to later claim it refused — the proposer would tear down a document the
+ * peer is still editing.
+ */
+/** Domain tag in slot 0. Distinct from the update, ack, proposal and rejection domains. */
+export declare const DOCUMENT_PROPOSAL_ACK_DOMAIN = "CELLO-DOCUMENT-PROPOSAL-ACK-v1";
+/**
+ * The frame version, ON THE WIRE.
+ *
+ * The `-v1` in the domain never travels, so a V2 acker's frame would decode cleanly as V1 and fail
+ * SIGNATURE verification — sending an operator to key management for a version-skew bug. Skew that
+ * is not SAID becomes silent loss or a misattributed error.
+ */
+export declare const DOCUMENT_PROPOSAL_ACK_VERSION = 1;
+/** A refusal reason is peer-controlled text bound for an operator's screen. Capped for that reason. */
+export declare const MAX_PROPOSAL_REFUSAL_REASON_LENGTH = 200;
+export interface DocumentProposalAck {
+    type: "document_proposal_ack";
+    ack_version: number;
+    /** The proposal being answered. Hash of the proposal's own preimage — see `documentIdFromProposal`. */
+    document_id: string;
+    /** Who decided — the party the proposal was addressed to. */
+    acker_agent_id: string;
+    /**
+     * `true` accepted, `false` refused. Both are ANSWERS; there is no third value, because an ack
+     * that does not say which is not a decision.
+     */
+    accepted: boolean;
+    /** Present iff `accepted` is false. The operator's words, or the machine reason that auto-refused. */
+    refusal_reason?: string;
+    decided_at_ms: number;
+    /** Ed25519 (RFC 8032) over `buildDocumentProposalAckTbs`. */
+    signature: 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 at the remote decode: the acker sees success, the proposer sees an error, and the two
+ * never meet. The rule belongs where the object is built, not only where it is read.
+ */
+export declare function assertDocumentProposalAckConsistent(ack: DocumentProposalAck): 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 acker
+ * happened to build the object in, and two honest implementations would disagree.
+ *
+ * `refusal_reason` occupies its slot as `null` when absent, so no field's meaning depends on
+ * whether the one before it was present.
+ */
+export declare function buildDocumentProposalAckTbs(ack: DocumentProposalAck, opts?: {
+    preHash?: boolean;
+}): Uint8Array;
+export declare function encodeDocumentProposalAck(ack: DocumentProposalAck): Uint8Array;
+/**
+ * Decode and validate. Refuses rather than defaulting on every field.
+ *
+ * The one that matters most is `accepted`. Coerced, a truthy string like `"false"` would record a
+ * REFUSED proposal as accepted, and the proposer would keep a document, keep publishing into it,
+ * and keep delivering to a peer who declined — every update refused at the far end for a reason
+ * neither operator can see.
+ */
+export declare function decodeDocumentProposalAck(bytes: Uint8Array): DocumentProposalAck;
+//# sourceMappingURL=document-proposal-ack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-proposal-ack.d.ts","sourceRoot":"","sources":["../src/document-proposal-ack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,2FAA2F;AAC3F,eAAO,MAAM,4BAA4B,mCAAmC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,uGAAuG;AACvG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAItD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,sGAAsG;IACtG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,SAAS,EAAE,UAAU,CAAC;CACvB;AAOD;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAsBlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,mBAAmB,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CAoBZ;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,mBAAmB,GAAG,UAAU,CAY9E;AAWD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,CAgEhF"}

package/dist/document-proposal-ack.js

@@ -0,0 +1,203 @@
+/**
+ * DOD-DOC-TOOLS-1 — the PROPOSAL ack (§16.3).
+ *
+ * The consent decision, told to the party who asked for it.
+ *
+ * ── WHY THIS EXISTS ───────────────────────────────────────────────────────────────────────────
+ *
+ * Without it the proposer is never told the answer. `cello_doc_list` had to INFER acceptance from
+ * "the peer has published into it", which conflates three different situations — refused, never
+ * received, and accepted-but-untouched — into one absent flag. Two of those want the operator to
+ * act and one does not, and the surface could not tell them apart. A protocol that asks for consent
+ * and never reports it is not asking; it is announcing.
+ *
+ * ── WHY IT IS SEPARATE FROM `document_ack` ────────────────────────────────────────────────────
+ *
+ * `document_ack` settles an ENVELOPE, identified by its hash in the log. A proposal is not in the
+ * envelope log — there is no document yet, which is the whole point — so an ack shaped around an
+ * envelope hash would carry a hash of nothing, and its consumer looks the envelope up. Overloading
+ * the frame would mean one decoder branching on whether the thing it references exists, which is
+ * how a settle-once rule gets applied to the wrong table.
+ *
+ * ── WHY IT IS SIGNED, AND WHAT THE SIGNATURE COVERS ───────────────────────────────────────────
+ *
+ * A refusal ack tells the proposer to stop: no retry, no document. Unsigned, anyone reaching the
+ * channel could make a proposal appear refused by a party who never saw it, and the two operators
+ * would each believe the other had walked away. The signature covers the DOCUMENT ID — which
+ * commits to the proposer, the peer, the properties and the nonce — so an ack cannot be moved to
+ * another proposal, and the decision itself, because the whole statement is the claim.
+ *
+ * ── SETTLE ONCE ───────────────────────────────────────────────────────────────────────────────
+ *
+ * Nothing here orders two acks from one acker, and the same rule `document_ack` states applies: a
+ * second, CONTRADICTING ack is an error with both signatures retained, never an update. A peer that
+ * accepted must not be able to later claim it refused — the proposer would tear down a document the
+ * peer is still editing.
+ */
+import { createHash } from "node:crypto";
+import { encodeCbor, decodeCbor } from "./cbor.js";
+/** Domain tag in slot 0. Distinct from the update, ack, proposal and rejection domains. */
+export const DOCUMENT_PROPOSAL_ACK_DOMAIN = "CELLO-DOCUMENT-PROPOSAL-ACK-v1";
+/**
+ * The frame version, ON THE WIRE.
+ *
+ * The `-v1` in the domain never travels, so a V2 acker's frame would decode cleanly as V1 and fail
+ * SIGNATURE verification — sending an operator to key management for a version-skew bug. Skew that
+ * is not SAID becomes silent loss or a misattributed error.
+ */
+export const DOCUMENT_PROPOSAL_ACK_VERSION = 1;
+/** A refusal reason is peer-controlled text bound for an operator's screen. Capped for that reason. */
+export const MAX_PROPOSAL_REFUSAL_REASON_LENGTH = 200;
+const HEX32 = /^[0-9a-f]{64}$/;
+/** Empty string means ABSENT — see `assertDocumentProposalAckConsistent`. */
+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 at the remote decode: the acker sees success, the proposer sees an error, and the two
+ * never meet. The rule belongs where the object is built, not only where it is read.
+ */
+export function assertDocumentProposalAckConsistent(ack) {
+    const reason = normalizeReason(ack.refusal_reason);
+    if (!ack.accepted && reason === null) {
+        // A refusal with no reason leaves the proposer unable to propose anything better. That is the
+        // failure that makes people give up on a protocol rather than adjust to it.
+        throw new Error("document_proposal_ack_reason: a refusal must carry its reason");
+    }
+    if (ack.accepted && reason !== null) {
+        // A contradiction: whichever field a reader trusts, the other is lying to them.
+        throw new Error(`document_proposal_ack_reason: an acceptance must not carry a refusal reason, and this one carries "${reason}"`);
+    }
+    if (reason !== null && reason.length > MAX_PROPOSAL_REFUSAL_REASON_LENGTH) {
+        throw new Error(`document_proposal_ack_reason: a refusal reason may be at most ` +
+            `${MAX_PROPOSAL_REFUSAL_REASON_LENGTH} characters, and this one is ${reason.length}`);
+    }
+    if (!HEX32.test(ack.document_id)) {
+        throw new Error(`document_proposal_ack_document_id: expected 64 lowercase hex characters`);
+    }
+}
+/**
+ * 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.
+ *
+ * `refusal_reason` occupies its slot as `null` when absent, so no field's meaning depends on
+ * whether the one before it was present.
+ */
+export function buildDocumentProposalAckTbs(ack, opts = {}) {
+    assertDocumentProposalAckConsistent(ack);
+    const preimage = encodeCbor([
+        DOCUMENT_PROPOSAL_ACK_DOMAIN,
+        ack.ack_version,
+        ack.document_id,
+        ack.acker_agent_id,
+        ack.accepted,
+        normalizeReason(ack.refusal_reason),
+        // BIGINT past 0xffffffff. cbor-x encodes a JS number that large as an IEEE float64 (`fb`)
+        // rather than a uint64 (`1b`), so an implementation encoding RFC 8949-canonically would compute
+        // different TBS bytes and reject a GENUINE ack — surfacing as a signature failure, which reads
+        // as forgery. A millisecond timestamp is always that large. Four sibling builders carry this
+        // same coercion.
+        typeof ack.decided_at_ms === "number" && ack.decided_at_ms > 0xffffffff
+            ? BigInt(ack.decided_at_ms)
+            : ack.decided_at_ms,
+    ]);
+    if (opts.preHash === false)
+        return preimage;
+    return new Uint8Array(createHash("sha256").update(preimage).digest());
+}
+export function encodeDocumentProposalAck(ack) {
+    assertDocumentProposalAckConsistent(ack);
+    return encodeCbor({
+        type: ack.type,
+        ack_version: ack.ack_version,
+        document_id: ack.document_id,
+        acker_agent_id: ack.acker_agent_id,
+        accepted: ack.accepted,
+        refusal_reason: normalizeReason(ack.refusal_reason),
+        decided_at_ms: ack.decided_at_ms,
+        signature: ack.signature,
+    });
+}
+function present(map, field) {
+    // `in`, not a nullish check. A defaulted field is a claim the acker never made, and carrying
+    // their claim is this frame's entire job.
+    if (!(field in map)) {
+        throw new Error(`document_proposal_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 is `accepted`. Coerced, a truthy string like `"false"` would record a
+ * REFUSED proposal as accepted, and the proposer would keep a document, keep publishing into it,
+ * and keep delivering to a peer who declined — every update refused at the far end for a reason
+ * neither operator can see.
+ */
+export function decodeDocumentProposalAck(bytes) {
+    const decoded = decodeCbor(bytes);
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+        throw new Error("document_proposal_ack_malformed: not a CBOR map");
+    }
+    const map = decoded;
+    if (present(map, "type") !== "document_proposal_ack") {
+        throw new Error(`document_proposal_ack_type: expected document_proposal_ack`);
+    }
+    const ackVersion = present(map, "ack_version");
+    if (typeof ackVersion !== "number" || !Number.isInteger(ackVersion)) {
+        throw new Error("document_proposal_ack_version: must be an integer");
+    }
+    if (ackVersion !== DOCUMENT_PROPOSAL_ACK_VERSION) {
+        // REFUSED BY VALUE, and said out loud. A frame from a future build would otherwise decode
+        // cleanly and fail signature verification, sending whoever reads the error to key management.
+        throw new Error(`document_proposal_ack_version_unsupported: this build speaks version ` +
+            `${DOCUMENT_PROPOSAL_ACK_VERSION} and the ack declares ${ackVersion} — the peer is running a ` +
+            `newer CELLO and one of you needs to upgrade`);
+    }
+    const documentId = present(map, "document_id");
+    if (typeof documentId !== "string" || !HEX32.test(documentId)) {
+        throw new Error("document_proposal_ack_document_id: expected 64 lowercase hex characters");
+    }
+    const ackerAgentId = present(map, "acker_agent_id");
+    if (typeof ackerAgentId !== "string" || ackerAgentId.length === 0) {
+        throw new Error("document_proposal_ack_acker: must be a non-empty string");
+    }
+    const accepted = present(map, "accepted");
+    if (typeof accepted !== "boolean") {
+        throw new Error("document_proposal_ack_accepted: must be a boolean, never a coerced value");
+    }
+    const refusalReason = present(map, "refusal_reason");
+    if (refusalReason !== null && typeof refusalReason !== "string") {
+        throw new Error("document_proposal_ack_reason: must be a string or null");
+    }
+    const decidedAt = present(map, "decided_at_ms");
+    if (typeof decidedAt !== "number" || !Number.isFinite(decidedAt)) {
+        throw new Error("document_proposal_ack_decided_at: must be a finite number");
+    }
+    const signature = present(map, "signature");
+    if (!(signature instanceof Uint8Array) || signature.length !== 64) {
+        throw new Error("document_proposal_ack_signature: expected 64 bytes");
+    }
+    const ack = {
+        type: "document_proposal_ack",
+        ack_version: ackVersion,
+        document_id: documentId,
+        acker_agent_id: ackerAgentId,
+        accepted,
+        ...(refusalReason !== null && refusalReason !== "" ? { refusal_reason: refusalReason } : {}),
+        decided_at_ms: decidedAt,
+        // COPIED out of the decode buffer. cbor-x returns byte strings as VIEWS into the input, so
+        // retaining one pins the whole frame and lets a later reuse of that buffer mutate a signature
+        // already verified.
+        signature: Uint8Array.from(signature),
+    };
+    assertDocumentProposalAckConsistent(ack);
+    return ack;
+}
+//# sourceMappingURL=document-proposal-ack.js.map

package/dist/document-proposal-ack.js.map

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

package/dist/document-proposal.d.ts

@@ -0,0 +1,127 @@
+/**
+ * DOD-DOC-HANDSHAKE-1 — the document PROPOSAL envelope (§16.3).
+ *
+ * A distinct wire type from `document-envelope.ts`'s UPDATE envelope. The two share the word
+ * "envelope" and nothing else: this one is proposed once, consented to once, and its hash becomes
+ * the `document_id` that every subsequent update names.
+ *
+ * **`document_id` is the hash of this envelope** — globally unique with no minting authority and
+ * no coordination round. That is the property that makes the whole scheme federated, and it is why
+ * the proposal must be canonically encodable: two parties that hash it differently are on two
+ * different documents while believing they are on one.
+ *
+ * ── THE SEAM (§3.4, §11.1) ────────────────────────────────────────────────────────────────────
+ *
+ * Three properties are DECLARED in V1 but support exactly one value each, and the pattern is
+ * deliberate — §3.3 chose it for `schema_enforcement` and §16.1 generalized it. Declaring a field
+ * that only accepts one value looks redundant until you need the second value: the field is
+ * already on the wire and already signed, so V2 is a validation change rather than a wire break
+ * that strands every document created before it.
+ *
+ * Refused at BOTH ends — at proposal and again at accept. Not belt-and-braces: the proposer and
+ * the accepter run different builds. A V2 peer proposing `topology: "mesh"` to a V1 peer must be
+ * refused by the V1 accepter, and a V1 proposer must not be able to emit a value it cannot honour.
+ * One-sided validation means whichever side is newer silently decides for both.
+ *
+ * ── THE FEATURE VERSION (§16.7-8) ─────────────────────────────────────────────────────────────
+ *
+ * Alpha owes no backward compatibility, so this is not a negotiation — it is the difference
+ * between a human answer and a timeout. A peer whose client predates documents does not understand
+ * the proposal at all, and without a version the symptom is silence: the proposal is never
+ * answered and the operator sees a hang. `documentFeatureIncompatibility` turns that into "your
+ * peer's client doesn't support shared documents yet — ask them to upgrade".
+ */
+/** Domain tag in slot 0 of the to-be-signed array. Distinct from the UPDATE envelope's domain. */
+export declare const DOCUMENT_PROPOSAL_DOMAIN = "CELLO-DOCUMENT-PROPOSAL-v1";
+/**
+ * The document feature version this build speaks. Bumped when the document wire changes in a way
+ * a peer must understand; see `documentFeatureIncompatibility` for what a mismatch produces.
+ */
+export declare const DOCUMENT_FEATURE_VERSION = 1;
+/** §6 — Tier 1. Tier 2 (attested) is V2; the field exists so V2 is a validation change. */
+export declare const ASSURANCE_TIER_V1 = "authenticated";
+/** §11 — the pairwise two-document form. Mesh is deferred (§11.1). */
+export declare const TOPOLOGY_V1 = "hub-and-spoke";
+export type DocumentConsentState = "pending" | "accepted" | "refused";
+/**
+ * The properties agreed at handshake (§3.4). **Immutable after accept** — a property change is an
+ * epoch event and therefore V2 (§16.3), so no mutate call exists in V1. That is not an omission to
+ * fill in later: mutating a property after acceptance would silently change the rules the other
+ * party consented to, which is the one thing the handshake exists to prevent.
+ */
+export interface DocumentProperties {
+    /** Only `authenticated` in V1. */
+    assurance_tier: string;
+    /** Only `false` in V1 — the schema-as-first-update path (§3.3) is V2. */
+    schema_enforcement: boolean;
+    /** Only `hub-and-spoke` in V1. */
+    topology: string;
+    /** Receiver-local append-only enforcement (§16.7-1). Freely settable — not a seam field. */
+    append_only: boolean;
+}
+export interface DocumentProposalEnvelope {
+    type: "document_proposal";
+    /** Which build proposed this. A peer that cannot read it answers with a human-readable refusal. */
+    feature_version: number;
+    proposer_agent_id: string;
+    peer_agent_id: string;
+    /** Free-form label chosen by the proposer, e.g. "markdown". Not a seam field. */
+    document_type: string;
+    properties: DocumentProperties;
+    /**
+     * The epoch-zero template (§16.3 step 1), or null. A Yjs update in the pinned encoding, so both
+     * sides mint byte-identical starting state rather than each building their own from a template
+     * string — two "identical" documents built independently do not converge.
+     */
+    starting_content: Uint8Array | null;
+    /** Distinguishes two otherwise identical proposals, so each gets its own document_id. */
+    nonce: Uint8Array;
+    proposed_at_ms: number;
+    /** Ed25519 (RFC 8032) over `buildDocumentProposalTbs`. */
+    signature: Uint8Array;
+}
+/**
+ * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
+ *
+ * The properties are flattened into their own slots rather than nested as a map. `encodeCbor` is
+ * not deterministic for maps — keys follow insertion order — so a nested `properties` object would
+ * make the signature depend on the order the proposer happened to build it in, and two honest
+ * builds of the same proposal would produce different `document_id`s. For this envelope that is
+ * worse than a bad signature: the id IS the hash, so the two parties would be on two documents.
+ */
+export declare function buildDocumentProposalTbs(env: DocumentProposalEnvelope, opts?: {
+    preHash?: boolean;
+}): Uint8Array;
+/**
+ * `document_id` = the hash of the proposal envelope (§16.3).
+ *
+ * Over the same preimage that is signed, and therefore NOT over the signature — so the id a party
+ * computes is the id of the thing whose signature it verified, and re-signing cannot change the
+ * identity of an already-accepted document.
+ */
+export declare function documentIdFromProposal(env: DocumentProposalEnvelope): string;
+/**
+ * Refuse any seam value this build cannot honour, at proposal AND at accept.
+ *
+ * Returns the reason, or null when the properties are acceptable. A REASON rather than a boolean
+ * because the operator on the refusing side has to be able to tell "your peer asked for mesh
+ * topology, which this version does not support" from a generic refusal — a handshake that fails
+ * without saying which property failed is indistinguishable from the peer being unreachable.
+ */
+export declare function seamViolation(props: DocumentProperties): string | null;
+/**
+ * A human answer for a version mismatch, or null when the peer is compatible.
+ *
+ * Deliberately phrased for the operator rather than for a log: the alternative to this string is a
+ * proposal that is never answered, which surfaces as a hang and gets diagnosed as a network fault.
+ */
+export declare function documentFeatureIncompatibility(peerFeatureVersion: number | null): string | null;
+export declare function encodeDocumentProposal(env: DocumentProposalEnvelope): Uint8Array;
+/**
+ * Decode and validate. Does NOT check the seam — `seamViolation` is called separately at both the
+ * proposal and the accept step, because a decoder that refused seam values would make a
+ * V2 proposal undecodable and therefore unanswerable, which is exactly the silent hang the feature
+ * version exists to replace.
+ */
+export declare function decodeDocumentProposal(input: Uint8Array): DocumentProposalEnvelope;
+//# sourceMappingURL=document-proposal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-proposal.d.ts","sourceRoot":"","sources":["../src/document-proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,sEAAsE;AACtE,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAE3C,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,mGAAmG;IACnG,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC,yFAAyF;IACzF,KAAK,EAAE,UAAU,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,wBAAwB,EAC7B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CA4BZ;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,wBAAwB,GAAG,MAAM,CAI5E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAoBtE;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAoB/F;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,wBAAwB,GAAG,UAAU,CAkBhF;AA6BD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,wBAAwB,CA8DlF"}