@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/document-amendment-store.js.map

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

package/dist/document-delivery-transport.d.ts

@@ -0,0 +1,168 @@
+/**
+ * DOD-DOC-DELIVERY-2 — the transport behind `DocumentDeliveryTransport` (§16.4).
+ *
+ * DELIVERY-1 built the scheduler and the bookkeeping against an injected seam. This is the seam's
+ * implementation: the first NON-HANDLER consumer of the session machinery, which is what makes it
+ * interesting — every other caller of `SessionNegotiator` runs because an agent asked for
+ * something, and this one runs because a document has a pending envelope and nobody is watching.
+ *
+ * ── REUSE BEFORE OPEN, AND WHY THAT ORDER ─────────────────────────────────────────────────────
+ *
+ * §16.4: "the daemon uses the most recent active session with that peer or opens one". Reuse first,
+ * because opening is the expensive half — a directory negotiation, a dial, and a seal — and a
+ * backlog of pending envelopes for one peer would otherwise pay it per envelope. It is also the
+ * behaviour an operator expects when they are mid-conversation about the document: the change lands
+ * in the same sealed record as the discussion. (SYNC-D10: the explicit session hint is deleted —
+ * the daemon's reuse-most-recent choice is the whole rule.)
+ *
+ * ── WHAT AN ACK IS HERE, AND WHAT IT IS NOT ───────────────────────────────────────────────────
+ *
+ * `sendContent` reports that the content left, or was PARKED at the relay for an offline peer. That
+ * is a transport fact. The DoD's ack is a different one — "the peer's daemon confirms admission (or
+ * rejection)" — and it can only come from the peer's inbound document handler, which is its own
+ * line. So this adapter returns `admitted: null`: SENT, not acked.
+ *
+ * That third state is not hedging; both two-valued answers are dishonest here. `true` would mark
+ * the envelope acknowledged in the log while the peer may never have applied it, and the log being
+ * right about what the peer holds is the entire reason pending is derived from it. `false` would
+ * count a send that WORKED as a failure and re-send content already in flight — the
+ * permanent-redelivery shape this milestone has already fixed once. The worker records the envelope
+ * as delivered, leaves it unacked, and asks again on the capped backoff.
+ */
+import { DiscoveryUnavailableError } from "./document-reachability.js";
+import type { DiscoveryOutcome } from "./cross-node-negotiation.js";
+import type { Logger } from "./types.js";
+export interface DocumentTransportDeps {
+    /**
+     * Take this frame's position in OUR OWN session tree, after it has gone out — the `0x04` doc leaf.
+     *
+     * `cello_send` does this and the document path did not, and the consequence is not a missing
+     * audit record: the tree is the sequence space both sides count in, so a sender that skips it
+     * falls one behind per frame and the peer silently drops what it has already consumed.
+     */
+    /** DOD-M12B-INDEX-1: `assignedSeq` is the relay's position for this frame — the leaf goes THERE,
+     *  not at the tail. A document leaf rides the same session sequence counter a message does, so it
+     *  is subject to exactly the same divergence. Undefined when no relay answered. */
+    appendLeaf(agentName: string, sessionId: string, contentHash: Uint8Array, frameBytes: Uint8Array, correlationId: string, assignedSeq?: number): {
+        placed: boolean;
+        leafIndex: number | null;
+    };
+    /** The agent this worker delivers for. One worker per attended agent. */
+    agentName: string;
+    /** `runDiscoveryLookup`, supplied by the composition root — it lives in a closure there. */
+    lookupPeer(peerAgentId: string, correlationId: string): Promise<DiscoveryOutcome>;
+    /**
+     * Close and SEAL a session this adapter opened. §16.4: the autonomous session "still happens
+     * because it carries signing, encryption, and the seal" — an opened session left running is a
+     * live node the operator did not start and that never produces the sealed record the whole
+     * design exists for.
+     */
+    sealSession(agentName: string, sessionId: string, correlationId: string): Promise<void>;
+    /** Active sessions with this peer, most recent LAST. */
+    activeSessionsWith(agentName: string, peerAgentId: string): string[];
+    /** The existing initiate path: negotiate, dial, create the session node. */
+    openSession(agentName: string, peerAgentId: string, correlationId: string): Promise<{
+        ok: true;
+        sessionId: string;
+    } | {
+        ok: false;
+        reason: string;
+        guidance?: string;
+    }>;
+    /**
+     * `SessionNodeManager.contentHashForSession` — the ONE place that decides how this session's
+     * outbound content is hashed, returning the hash and its algorithm together (`DOD-M15-SEALWIRE-1`
+     * part B2b). Injected rather than imported so this module keeps its single dependency on the
+     * manager, and so a test cannot compute a hash the manager would not.
+     */
+    contentHashForSession(agentName: string, sessionId: string, content: Uint8Array): Promise<{
+        hash: Uint8Array;
+        alg: string;
+    }>;
+    /** `SessionNodeManager.sendContent`. */
+    sendContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, correlationId: string, 
+    /**
+     * The witnessed DOMAIN — see the note on `DOCUMENT_LEAF_KIND` below.
+     *
+     * ⚠️ REQUIRED, like its two neighbours, and this interface is why. A function of LOWER arity is
+     * assignable to one of higher arity, so an adapter that drops a trailing argument type-checks
+     * silently — which is exactly how this parameter was lost for a whole release
+     * (*"0.0.145 shipped the fix everywhere except here"*). Optional parameters make that assignment
+     * invisible twice over. Required, a dropped argument is a compile error.
+     */
+    leafKind: number, 
+    /** `DOD-M15-SEALWIRE-1` part B2b — the algorithm `contentHash` was produced under. */
+    contentHashAlg: string): Promise<{
+        ok: true;
+        delivered: true;
+        relayRefusal?: string;
+        sequenceNumber?: number;
+    } | {
+        ok: true;
+        delivered: false;
+        parked: true;
+        relayRefusal?: string;
+        sequenceNumber?: number;
+    } | {
+        ok: false;
+        reason: string;
+        error: string;
+        sequenceNumber?: number;
+    }>;
+    logger: Logger;
+}
+/**
+ * Everything this transport sends is document-domain traffic, so 0x04 is the default rather than
+ * something each call site remembers. A refusal overrides it with 0x05 — the two are distinguished
+ * for the same reason, and only the caller knows which it is holding.
+ *
+ * WHY IT MATTERS AT ALL. The seal certificate is built by the DIRECTORY from the leaves the RELAY
+ * witnessed, never from the sender's local tree. `seal-legibility.ts` excludes doc/reject leaves
+ * from `final_message` and from `answered`, and says why: a document update is applied MECHANICALLY
+ * by the peer's daemon with no agent involved, so counting one as a reply would let a peer's daemon
+ * satisfy the unanswered-tail check on its operator's behalf. Both exclusions were dead code while
+ * this path submitted every document leaf as a MESSAGE.
+ */
+export declare const DOCUMENT_LEAF_KIND = 4;
+/**
+ * The document frame carrier (SYNC-P4: D1/D2/D4 deleted — this used to live in the delivery
+ * worker's module). Two capabilities survive: a reachability probe, and putting already-encoded
+ * bytes on a session the transport opens or reuses then seals. There is no `deliver` and no ack
+ * wait — content confirmation is the peer's position at the next reconcile exchange.
+ */
+export interface DocumentDeliveryTransport {
+    /**
+     * Is the peer reachable right now? `discovery_lookup` today. Returns false rather than throwing
+     * for an ordinary "not online"; a throw means the LOOKUP failed, which is a different fact and
+     * must not be recorded as the peer being away.
+     */
+    isPeerReachable(peerAgentId: string, correlationId: string): Promise<{
+        reachable: boolean;
+        unknownAgent: boolean;
+    }>;
+    /**
+     * Send already-encoded bytes to a peer over the open-or-reuse-then-seal path. `documentId` is
+     * for the log line only. `parked: true` means the relay took it because the peer had no live
+     * counterparty — it is NOT with them yet, and only the next exchange proves anything landed.
+     */
+    sendBytes(input: {
+        peerAgentId: string;
+        documentId: string;
+        bytes: Uint8Array;
+        correlationId: string;
+        /** The witnessed leaf DOMAIN. Defaults to the document kind (0x04); a refusal passes 0x05. */
+        leafKind?: number;
+    }): Promise<{
+        ok: true;
+        sessionId: string;
+        sessionOpened: boolean;
+        parked?: boolean;
+    } | {
+        ok: false;
+        reason: string;
+        detail?: string;
+    }>;
+}
+export declare function createDocumentDeliveryTransport(deps: DocumentTransportDeps): DocumentDeliveryTransport;
+export { DiscoveryUnavailableError };
+//# sourceMappingURL=document-delivery-transport.d.ts.map

package/dist/document-delivery-transport.d.ts.map

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

package/dist/document-delivery-transport.js

@@ -0,0 +1,206 @@
+/**
+ * DOD-DOC-DELIVERY-2 — the transport behind `DocumentDeliveryTransport` (§16.4).
+ *
+ * DELIVERY-1 built the scheduler and the bookkeeping against an injected seam. This is the seam's
+ * implementation: the first NON-HANDLER consumer of the session machinery, which is what makes it
+ * interesting — every other caller of `SessionNegotiator` runs because an agent asked for
+ * something, and this one runs because a document has a pending envelope and nobody is watching.
+ *
+ * ── REUSE BEFORE OPEN, AND WHY THAT ORDER ─────────────────────────────────────────────────────
+ *
+ * §16.4: "the daemon uses the most recent active session with that peer or opens one". Reuse first,
+ * because opening is the expensive half — a directory negotiation, a dial, and a seal — and a
+ * backlog of pending envelopes for one peer would otherwise pay it per envelope. It is also the
+ * behaviour an operator expects when they are mid-conversation about the document: the change lands
+ * in the same sealed record as the discussion. (SYNC-D10: the explicit session hint is deleted —
+ * the daemon's reuse-most-recent choice is the whole rule.)
+ *
+ * ── WHAT AN ACK IS HERE, AND WHAT IT IS NOT ───────────────────────────────────────────────────
+ *
+ * `sendContent` reports that the content left, or was PARKED at the relay for an offline peer. That
+ * is a transport fact. The DoD's ack is a different one — "the peer's daemon confirms admission (or
+ * rejection)" — and it can only come from the peer's inbound document handler, which is its own
+ * line. So this adapter returns `admitted: null`: SENT, not acked.
+ *
+ * That third state is not hedging; both two-valued answers are dishonest here. `true` would mark
+ * the envelope acknowledged in the log while the peer may never have applied it, and the log being
+ * right about what the peer holds is the entire reason pending is derived from it. `false` would
+ * count a send that WORKED as a failure and re-send content already in flight — the
+ * permanent-redelivery shape this milestone has already fixed once. The worker records the envelope
+ * as delivered, leaves it unacked, and asks again on the capped backoff.
+ */
+// `wireContentHash` is no longer imported here: every outbound hash in this file now comes from
+// `SessionNodeManager.contentHashForSession`, which returns the hash and its ALGORITHM together
+// (`DOD-M15-SEALWIRE-1` part B2b). A direct call would be a hash computed without deciding — or
+// recording — how it was made, which is the state that made a version skew look like a tamper.
+import { reachabilityFromDiscovery, DiscoveryUnavailableError } from "./document-reachability.js";
+import { LEAF_KIND_DOC } from "./session-relay-client.js";
+import { createSessionSuspects, TERMINAL_ISH_REFUSALS } from "./delivery-session-suspects.js";
+/**
+ * Everything this transport sends is document-domain traffic, so 0x04 is the default rather than
+ * something each call site remembers. A refusal overrides it with 0x05 — the two are distinguished
+ * for the same reason, and only the caller knows which it is holding.
+ *
+ * WHY IT MATTERS AT ALL. The seal certificate is built by the DIRECTORY from the leaves the RELAY
+ * witnessed, never from the sender's local tree. `seal-legibility.ts` excludes doc/reject leaves
+ * from `final_message` and from `answered`, and says why: a document update is applied MECHANICALLY
+ * by the peer's daemon with no agent involved, so counting one as a reply would let a peer's daemon
+ * satisfy the unanswered-tail check on its operator's behalf. Both exclusions were dead code while
+ * this path submitted every document leaf as a MESSAGE.
+ */
+export const DOCUMENT_LEAF_KIND = LEAF_KIND_DOC;
+export function createDocumentDeliveryTransport(deps) {
+    // DOD-MP-SESSION-RETIRE-1 (remaining half) — sessions this worker has stopped REUSING because
+    // they keep answering terminally. Per transport instance, in memory, destroying nothing: see
+    // delivery-session-suspects.ts for why `relay_session_gone` is handled here and not by retiring.
+    const suspects = createSessionSuspects();
+    /**
+     * One place that decides what a send outcome says about the SESSION.
+     *
+     * A refusal is obvious. The subtle case is a send that SUCCEEDED while the relay refused the
+     * leaf: the content reached the peer directly and the session's record stopped growing. That is
+     * a fact about the session, not about the peer, and reading `ok` alone both hid it and cleared
+     * the evidence of every earlier occurrence.
+     */
+    function noteSendOutcome(sessionId, sent) {
+        if (!sent.ok) {
+            if (TERMINAL_ISH_REFUSALS.has(sent.reason))
+                suspects.noteFailure(sessionId, sent.reason);
+            return;
+        }
+        if (sent.relayRefusal !== undefined && TERMINAL_ISH_REFUSALS.has(sent.relayRefusal)) {
+            suspects.noteFailure(sessionId, sent.relayRefusal);
+            return;
+        }
+        suspects.noteSuccess(sessionId);
+    }
+    /**
+     * Acquire a session with the peer — the most recent active one, else a fresh dial (SYNC-D10).
+     *
+     * ONE implementation for every document frame kind. A proposal that opened its own session by a
+     * separate code path would drift on which session gets reused and on whether a session this
+     * daemon opened is sealed, and both are unrecoverable after the fact.
+     */
+    async function acquireSession(peerAgentId, correlationId) {
+        const active = deps.activeSessionsWith(deps.agentName, peerAgentId);
+        // Most recent LAST — activeSessionsWith is ordered oldest-first by the daemon's adapter.
+        //
+        // DOD-MP-SESSION-RETIRE-1 — a session that has answered terminally more than once is skipped
+        // rather than retired. If it really is finished, delivery routes around it instead of
+        // resubmitting into it forever; if the relay merely bounced and lost its memory, the cost is
+        // one extra session and the old one is untouched. Nothing is destroyed on an ambiguous signal.
+        const reusable = active.filter((id) => !suspects.isSuspect(id));
+        if (reusable.length > 0) {
+            return { ok: true, sessionId: reusable[reusable.length - 1], sessionOpened: false };
+        }
+        if (active.length > 0) {
+            deps.logger.warn("document.delivery.session.bypassed", {
+                peerAgentId,
+                skipped: active.length,
+                correlationId,
+                impact: "every open session with this holder has refused terminally more than once — opening a " +
+                    "fresh one; the old sessions are left intact",
+            });
+        }
+        const opened = await deps.openSession(deps.agentName, peerAgentId, correlationId);
+        if (!opened.ok) {
+            // The upstream reason verbatim. `document_delivery_threw` is reserved for a genuine
+            // programming fault; a dial that was refused should say it was refused.
+            return { ok: false, reason: opened.reason, detail: opened.guidance };
+        }
+        return { ok: true, sessionId: opened.sessionId, sessionOpened: true };
+    }
+    return {
+        async isPeerReachable(peerAgentId, correlationId) {
+            // The PASS's correlation id, threaded through. A per-peer constant was fabricated here, so
+            // every `directory.discovery.lookup` this worker ever emitted carried the same string and
+            // none of them joined to the pass — breaking the thread at exactly the hop an operator needs
+            // when nothing is syncing.
+            const outcome = await deps.lookupPeer(peerAgentId, correlationId);
+            // Throws on everything that is not an answer about the peer — see document-reachability.ts.
+            // The worker treats the throw as `lookup_failed` and keeps it out of the offline-peer count.
+            // The unknown-agent bit is RETURNED rather than logged here, so the worker can announce it
+            // against the document it belongs to.
+            return reachabilityFromDiscovery(outcome);
+        },
+        async sendBytes(input) {
+            const { peerAgentId, documentId, bytes, correlationId } = input;
+            const session = await acquireSession(peerAgentId, correlationId);
+            if (!session.ok)
+                return session;
+            // THE WIRE HASH, domain-separated. This was `sha256(bytes)`, and the receiver recomputes
+            // `sha256(0x00 || bytes)` for every frame — so the send reported success, `parked: false`,
+            // and the peer discarded it at the authenticity check before the document layer was ever
+            // consulted. Found by two real daemons; no in-process test could see it, because both sides
+            // of those compute the hash with the same function.
+            // B2b: one decision point for the hash AND its algorithm. This site is the reason that matters
+            // — it is one of the two that got the ORIGINAL hash expression wrong, and the failure was
+            // invisible from here (see the paragraph above). Four sites independently deciding whether to
+            // salt would be that same defect with a worse outcome: a message hashed one way and labelled
+            // another is refused by every peer, including a correct one.
+            const { hash, alg } = await deps.contentHashForSession(deps.agentName, session.sessionId, bytes);
+            const sent = await deps.sendContent(deps.agentName, session.sessionId, bytes, hash, correlationId, input.leafKind ?? DOCUMENT_LEAF_KIND, alg);
+            // DOD-MP-SESSION-RETIRE-1 — a working send breaks the run; a terminal-ish answer extends it.
+            //
+            // `relayRefusal` IS CHECKED FIRST, and that is the whole unit. The fully-sealed case answers
+            // `relay_session_gone`, which is deliberately not terminal — so the send warns, delivers
+            // directly, and returns SUCCESS for a leaf the relay never witnessed. Reading `ok` alone made
+            // the counter unreachable AND made every such send clear it, so a session whose record was
+            // permanently gone stayed in rotation forever.
+            noteSendOutcome(session.sessionId, sent);
+            if (!sent.ok) {
+                // Sealed even on a send failure, for the same reason as below: a session this daemon opened
+                // and walked away from is a live node the operator never started. A failed send is exactly
+                // when that is most likely to happen.
+                if (session.sessionOpened)
+                    await deps.sealSession(deps.agentName, session.sessionId, correlationId);
+                return { ok: false, reason: sent.reason, detail: sent.error };
+            }
+            // APPEND OUR OWN LEAF, exactly as `cello_send` does after a successful send.
+            //
+            // Not bookkeeping. The daemon's session tree is the sequence space both sides count in, and a
+            // sender that puts content on the wire without taking its leaf position leaves its own chain
+            // one behind for every frame it sends. The peer then sees a sequence it has already consumed
+            // and drops the frame — silently, because a duplicate is a normal event, so nothing is logged
+            // anywhere and the send reports success with `parked: false`.
+            //
+            // It hid behind an accident: with no prior traffic every frame is sequence 0, so the FIRST
+            // document frame in a fresh session arrives and everything after it does not. Adding one
+            // ordinary message before the exchange moved the failure earlier, which is what named the
+            // cause.
+            // THE FRAME BYTES, not the hash. When the leaf cannot be placed yet the bytes are held, and a
+            // hold is released by writing its content to the transcript — so handing this the hash would
+            // put 32 bytes of digest in the operator's transcript as a message they sent, and annex the
+            // same 32 bytes into the sealed record.
+            const placed = deps.appendLeaf(deps.agentName, session.sessionId, hash, bytes, correlationId, sent.sequenceNumber);
+            deps.logger.info("document.frame.sent", {
+                documentId,
+                // Whether the leaf is IN the chain yet. This hook is delivery-critical — a sender that skips
+                // its leaf falls one behind per frame and the peer silently drops what it has already
+                // consumed — so "sent" must not read the same when the leaf is merely held.
+                leafCommitted: placed.placed,
+                leafIndex: placed.leafIndex,
+                sessionId: session.sessionId,
+                sessionOpened: session.sessionOpened,
+                bytes: bytes.length,
+                parked: sent.delivered === false,
+                correlationId,
+            });
+            if (session.sessionOpened)
+                await deps.sealSession(deps.agentName, session.sessionId, correlationId);
+            // `parked` SURVIVES THE RETURN. It was computed one line above, logged, and discarded — and a
+            // caller that reads `ok` alone cannot tell "the holder has it" from "the relay is holding it
+            // because the holder had no live counterparty". For an amendment that difference is the whole
+            // fact: there is no ack frame, so a caller which clears its debt on `ok` loses the membership
+            // change the moment the relay parks it.
+            return {
+                ok: true,
+                sessionId: session.sessionId,
+                sessionOpened: session.sessionOpened,
+                parked: sent.delivered === false,
+            };
+        },
+    };
+}
+export { DiscoveryUnavailableError };
+//# sourceMappingURL=document-delivery-transport.js.map

package/dist/document-delivery-transport.js.map

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

package/dist/document-engine.d.ts

@@ -0,0 +1,134 @@
+/**
+ * DOD-DOC-ENGINE-1 — the daemon's Y.Doc lifecycle.
+ *
+ * The engine owns HOW to apply; the store (DOD-DOC-STORE-1) owns what to replay and in what
+ * order. `replay` takes whole envelope rows rather than payload bytes so it can tell a
+ * payload-free AUDIT record (a withdrawal or rejection, which is expected and skipped) from a
+ * payload-free PURGED update (an operation whose bytes are gone, which must refuse). That is the
+ * only thing `kind` is read for — `referencesEnvelopeHash` is pure audit at replay time, never
+ * read, because a withdrawal excludes nothing (§16.4; see `replay`).
+ *
+ * EVERY GUARD BELOW IS A RESPONSE TO A MEASUREMENT, not to a guess. DOD-DOC-FUZZ-1 fuzzed
+ * `Y.applyUpdate` and found:
+ *
+ *   - Malformed input THROWS — so a wrapped apply genuinely contains it, and V1 needs no sandbox.
+ *   - But the dangerous class is what Yjs ACCEPTS. An update whose dependencies the receiver
+ *     lacks returns success, contributes nothing, and is RETAINED forever in
+ *     `doc.store.pendingStructs` — a peer streams those until the daemon dies, and a try/catch
+ *     sees only success. Hence the pending-set check after every apply.
+ *   - An empty or one-byte update throws a lib0 DECODER error ("Unexpected end of array"), which
+ *     names Yjs internals rather than a protocol fault. Hence a floor as well as a cap.
+ *   - Yjs does not bound nesting depth at all, and the size cap bounds it poorly (~16 bytes per
+ *     level, so roughly 65,000 levels fit in 1 MiB). Structural limits are DOD-DOC-GATE-1's job;
+ *     the engine's contract is only that a bad update is a typed error, never a crash.
+ *
+ * ONE TYPED REASON PER FAILURE CLASS. A lib0 string like "Integer out of Range" describes where
+ * the decoder gave up, not what the peer did wrong, so it travels as `detail` and never as the
+ * reason an operator or a policy log sees.
+ */
+import * as Y from "yjs";
+import type { DocumentEnvelopeRow } from "./document-store.js";
+import type { Logger } from "./types.js";
+export type DocumentUpdateFailure = "document_update_too_large" | "document_update_too_small" | "document_update_malformed" | "document_update_unresolved_dependencies" | "document_snapshot_malformed" | "document_snapshot_incomplete" | "document_envelope_purged";
+export type DocumentUpdateResult = {
+    ok: true;
+}
+/** `detail` is the underlying cause — never the reason itself. */
+ | {
+    ok: false;
+    reason: DocumentUpdateFailure;
+    detail?: string;
+};
+/** Thrown by the *OrThrow variants and by `replay`, where returning a verdict would let a caller
+ *  persist a state that was never fully applied. */
+export declare class DocumentUpdateError extends Error {
+    readonly reason: DocumentUpdateFailure;
+    readonly detail?: string;
+    constructor(reason: DocumentUpdateFailure, detail?: string);
+}
+export declare class DocumentEngine {
+    #private;
+    constructor(logger: Logger);
+    /** The pre-parse cap, exposed so callers and tests agree on one number. */
+    get maxUpdateBytes(): number;
+    /**
+     * A fresh live document.
+     *
+     * Yjs mints its own random clientID and NOTHING here touches it (§14). Deriving it from agent
+     * identity, or persisting and restoring one, means two live docs can share it — and
+     * DOD-DOC-FUZZ-1 measured that outcome: the colliding writer silently wins, the honest client's
+     * update is accepted-and-dropped, and the document becomes a splice of two authors with an
+     * empty pending set and no error on any path.
+     */
+    createDocument(startingContent?: string): Y.Doc;
+    /**
+     * Read the single text root a text-typed document uses.
+     *
+     * Named for the root it reads, not for "the document's content". `DocumentRow.documentType`
+     * admits markdown, json and xml; on the latter two the data does not live in this root, and an
+     * unnamed `readText` would return "" — indistinguishable from an empty document. Structured
+     * types get their own accessors when a unit needs them.
+     */
+    readTextRoot(doc: Y.Doc): string;
+    insertIntoTextRoot(doc: Y.Doc, index: number, text: string): void;
+    /** The full state, or just what a peer holding `sinceStateVector` is missing (§7). */
+    encodeState(doc: Y.Doc, sinceStateVector?: Uint8Array): Uint8Array;
+    encodeStateVector(doc: Y.Doc): Uint8Array;
+    snapshot(doc: Y.Doc): {
+        binary: Uint8Array;
+        stateVector: Uint8Array;
+    };
+    /**
+     * Materialize a document from a snapshot binary.
+     *
+     * The restored document mints a FRESH clientID — the binary carries the operations, never an
+     * identity to resume under. See `createDocument` for what sharing one costs.
+     */
+    restore(binary: Uint8Array): Y.Doc;
+    /**
+     * Apply one update, with every guard the fuzz pass motivated.
+     *
+     * Never throws and never leaves the document half-integrated: an update that cannot be fully
+     * resolved is applied to a THROWAWAY doc first, so the caller's document is untouched when the
+     * answer is no.
+     */
+    /**
+     * Apply one update to a caller's live document, leaving it untouched if the answer is no.
+     *
+     * The trial runs on a FRESH scratch document every time. Reusing one across calls is unsound:
+     * `Y.applyUpdate` MERGES, it does not reset, so a scratch doc seeded from an empty document
+     * still holds the previous trial's operations — and with that residue present, an update whose
+     * dependencies the target lacks reports an EMPTY pending set. The one guard that catches the
+     * accept class would go green on exactly the input it exists to refuse. (Measured, not
+     * reasoned: a shadow holding "AAA" re-seeded from an empty doc still reads "AAA".)
+     */
+    applyUpdate(doc: Y.Doc, update: Uint8Array): DocumentUpdateResult;
+    /** `applyUpdate` for callers that want the failure to be unmissable. */
+    applyUpdateOrThrow(doc: Y.Doc, update: Uint8Array): void;
+    /**
+     * Fold an ordered envelope log into a materialized state — the `ReplayFn` the store injects.
+     *
+     * **A WITHDRAWAL EXCLUDES NOTHING.** §16.4 is explicit: withdrawing rolls the change back with
+     * a *Yjs undo* and writes a record "beside the original envelope — marked withdrawn, never
+     * deleted, so the log stays intact". Rejection resolves the same way, by supersession —
+     * "inverses, not erasure" (§3.2). So the undo is itself an ordinary update in the log, and
+     * replay simply applies every payload in order.
+     *
+     * An earlier version of this method excluded the referenced envelope instead, which is
+     * unsound in a CRDT log and was measured to be so: Yjs operations are causally chained, so
+     * dropping any but the LAST envelope leaves every later one depending on structs that never
+     * arrive — the document rebuilds until the next daemon restart and is permanently unopenable
+     * after it. It also let ANY sender suppress ANY other sender's content by appending a
+     * payload-free row, since nothing upstream checks authorship of a reference. Both problems
+     * dissolve when the log is simply replayed, which is what the spec said to do.
+     *
+     * REFUSES rather than skipping. A payload that will not apply means the log is corrupt, and
+     * folding the rest would produce a document that reads as complete while missing operations —
+     * the silent divergence the whole two-layer design exists to prevent.
+     */
+    replay(envelopes: readonly DocumentEnvelopeRow[]): {
+        binary: Uint8Array;
+        stateVector: Uint8Array;
+    };
+}
+//# sourceMappingURL=document-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-engine.d.ts","sourceRoot":"","sources":["../src/document-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,MAAM,MAAM,qBAAqB,GAC7B,2BAA2B,GAC3B,2BAA2B,GAC3B,2BAA2B,GAC3B,yCAAyC,GACzC,6BAA6B,GAC7B,8BAA8B,GAC9B,0BAA0B,CAAC;AAE/B,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE;AACd,kEAAkE;GAChE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;oDACoD;AACpD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;CAM3D;AAcD,qBAAa,cAAc;;gBAGb,MAAM,EAAE,MAAM;IAI1B,2EAA2E;IAC3E,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,eAAe,SAAK,GAAG,CAAC,CAAC,GAAG;IAM3C;;;;;;;OAOG;IACH,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,MAAM;IAIhC,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjE,sFAAsF;IACtF,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE,UAAU,GAAG,UAAU;IAIlE,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,UAAU;IAIzC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE;IAIrE;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,CAAC,GAAG;IA4BlC;;;;;;OAMG;IACH;;;;;;;;;OASG;IACH,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,oBAAoB;IAmFjE,wEAAwE;IACxE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAKxD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,GAAG;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE;CA6CnG"}