@cello-protocol/daemon 0.0.119 → 0.0.121

package/dist/document-engine.js

@@ -0,0 +1,275 @@
+/**
+ * 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";
+/** 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 class DocumentUpdateError extends Error {
+    reason;
+    detail;
+    constructor(reason, detail) {
+        super(detail ? `${reason}: ${detail}` : reason);
+        this.name = "DocumentUpdateError";
+        this.reason = reason;
+        this.detail = detail;
+    }
+}
+/** Pre-parse size cap — bytes are refused on LENGTH before Yjs is invoked at all. */
+const MAX_UPDATE_BYTES = 1024 * 1024;
+/**
+ * The minimum valid update. An empty encoded state is two bytes (`[0,0]`), measured — anything
+ * shorter throws a decoder error that says nothing about the protocol.
+ */
+const MIN_UPDATE_BYTES = 2;
+/** The single root text field a V1 text document uses. */
+const TEXT_ROOT = "content";
+export class DocumentEngine {
+    #logger;
+    constructor(logger) {
+        this.#logger = logger;
+    }
+    /** The pre-parse cap, exposed so callers and tests agree on one number. */
+    get maxUpdateBytes() {
+        return MAX_UPDATE_BYTES;
+    }
+    /**
+     * 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 = "") {
+        const doc = new Y.Doc();
+        if (startingContent.length > 0)
+            doc.getText(TEXT_ROOT).insert(0, startingContent);
+        return 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) {
+        return doc.getText(TEXT_ROOT).toString();
+    }
+    insertIntoTextRoot(doc, index, text) {
+        doc.getText(TEXT_ROOT).insert(index, text);
+    }
+    /** The full state, or just what a peer holding `sinceStateVector` is missing (§7). */
+    encodeState(doc, sinceStateVector) {
+        return Y.encodeStateAsUpdate(doc, sinceStateVector);
+    }
+    encodeStateVector(doc) {
+        return Y.encodeStateVector(doc);
+    }
+    snapshot(doc) {
+        return { binary: Y.encodeStateAsUpdate(doc), stateVector: Y.encodeStateVector(doc) };
+    }
+    /**
+     * 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) {
+        const doc = new Y.Doc();
+        try {
+            Y.applyUpdate(doc, binary);
+        }
+        catch (err) {
+            // This is the one method that reads bytes off disk, and it used to be a bare applyUpdate —
+            // so a corrupt `document_snapshots` row surfaced as "Unexpected end of array", the exact
+            // lib0 string this module says must never be a reason. It named Yjs internals and pointed
+            // an operator at the wrong subsystem.
+            const detail = err instanceof Error ? err.message : String(err);
+            this.#logger.error("document.snapshot.malformed", { detail });
+            throw new DocumentUpdateError("document_snapshot_malformed", detail);
+        }
+        if (doc.store.pendingStructs !== null) {
+            // A snapshot that decodes but is incomplete would otherwise restore SHORT and silent.
+            this.#logger.error("document.snapshot.incomplete", {
+                missing: doc.store.pendingStructs.missing.size,
+            });
+            // Its OWN class. An incomplete snapshot is not "an incoming update depends on absent
+            // structs" — same symptom, different fault, and one reason per class is this module's rule.
+            throw new DocumentUpdateError("document_snapshot_incomplete", `snapshot is missing operations from ${doc.store.pendingStructs.missing.size} client(s)`);
+        }
+        return 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, update) {
+        return this.#applyChecked(doc, new Y.Doc(), update);
+    }
+    #applyChecked(doc, shadow, update) {
+        if (update.length > MAX_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_large", `${update.length} bytes exceeds the ${MAX_UPDATE_BYTES}-byte cap`, update);
+        }
+        if (update.length < MIN_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_small", `${update.length} bytes is below the ${MIN_UPDATE_BYTES}-byte minimum for a Yjs update`, update);
+        }
+        // Trial it on scratch state first. Yjs has no atomic-apply mode, and an update that resolves
+        // only partially would otherwise leave the caller's document in a state nobody chose.
+        try {
+            Y.applyUpdate(shadow, Y.encodeStateAsUpdate(doc));
+            Y.applyUpdate(shadow, update);
+        }
+        catch (err) {
+            return this.#refuse("document_update_malformed", err instanceof Error ? err.message : String(err), update);
+        }
+        // THE ACCEPT CLASS. Yjs returned success — that is not evidence the update integrated. A
+        // non-empty pending set means it is waiting on structs that never arrived; admitting it would
+        // retain them indefinitely while contributing nothing (measured, DOD-DOC-FUZZ-1).
+        //
+        // PRECONDITION THIS IMPLIES: a sender's envelopes must be delivered in chain order. Yjs would
+        // otherwise BUFFER an out-of-order update and resolve it on the next state-vector exchange;
+        // this refuses instead. That is right for replay, where a gap means a corrupt log — a live
+        // receive path wanting buffer-and-re-request semantics needs its own entry point, not this one.
+        if (shadow.store.pendingStructs !== null) {
+            return this.#refuse("document_update_unresolved_dependencies", `depends on ${shadow.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`, update);
+        }
+        Y.applyUpdate(doc, update);
+        return { ok: true };
+    }
+    /**
+     * Apply straight to `doc`, checking the pending set afterwards.
+     *
+     * No trial copy, because atomicity buys nothing here: `replay` throws on the first failure and
+     * the half-built document is discarded whole. Trialling each envelope would cost a full
+     * encode/decode of a growing document per envelope — the fold is O(n·|doc|) either way, but
+     * this halves the constant and removes the aliasing hazard entirely.
+     */
+    #applyDirect(doc, update) {
+        if (update.length > MAX_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_large", `${update.length} bytes exceeds the ${MAX_UPDATE_BYTES}-byte cap`, update);
+        }
+        if (update.length < MIN_UPDATE_BYTES) {
+            return this.#refuse("document_update_too_small", `${update.length} bytes is below the ${MIN_UPDATE_BYTES}-byte minimum for a Yjs update`, update);
+        }
+        try {
+            Y.applyUpdate(doc, update);
+        }
+        catch (err) {
+            return this.#refuse("document_update_malformed", err instanceof Error ? err.message : String(err), update);
+        }
+        if (doc.store.pendingStructs !== null) {
+            return this.#refuse("document_update_unresolved_dependencies", `depends on ${doc.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`, update);
+        }
+        return { ok: true };
+    }
+    /** Every refusal is logged, not merely returned — a return value nobody reads is not observable. */
+    #refuse(reason, detail, update) {
+        this.#logger.warn("document.update.refused", { reason, detail, bytes: update.length });
+        return { ok: false, reason, detail };
+    }
+    /** `applyUpdate` for callers that want the failure to be unmissable. */
+    applyUpdateOrThrow(doc, update) {
+        const res = this.applyUpdate(doc, update);
+        if (!res.ok)
+            throw new DocumentUpdateError(res.reason, res.detail);
+    }
+    /**
+     * 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) {
+        const doc = new Y.Doc();
+        let applied = 0;
+        for (const e of envelopes) {
+            if (e.payload === null) {
+                // A withdrawal or rejection RECORD legitimately carries no payload — it is audit, not
+                // content. An `update` row with no payload is different: it is a PURGED operation whose
+                // bytes are gone (§16.7-12), and folding around it would produce a document that reads
+                // as complete while missing an operation. Purge is V2, so this cannot happen yet — which
+                // is exactly why it must refuse now rather than become a silent skip later.
+                if (e.kind === "update") {
+                    this.#logger.error("document.replay.failed", {
+                        documentId: e.documentId,
+                        envelopeHash: e.envelopeHash,
+                        reason: "document_envelope_purged",
+                    });
+                    throw new DocumentUpdateError("document_envelope_purged", `envelope ${e.envelopeHash.slice(0, 16)}… is an update whose payload has been purged — ` +
+                        `the document cannot be rebuilt without it`);
+                }
+                continue;
+            }
+            const res = this.#applyDirect(doc, e.payload);
+            if (!res.ok) {
+                this.#logger.error("document.replay.failed", {
+                    documentId: e.documentId,
+                    envelopeHash: e.envelopeHash,
+                    reason: res.reason,
+                    detail: res.detail,
+                });
+                throw new DocumentUpdateError(res.reason, `envelope ${e.envelopeHash.slice(0, 16)}…: ${res.detail ?? ""}`);
+            }
+            applied++;
+        }
+        this.#logger.info("document.replay.completed", { envelopes: envelopes.length, applied });
+        return { binary: Y.encodeStateAsUpdate(doc), stateVector: Y.encodeStateVector(doc) };
+    }
+}
+//# sourceMappingURL=document-engine.js.map

package/dist/document-engine.js.map

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

package/dist/document-store.d.ts

@@ -0,0 +1,181 @@
+/**
+ * DOD-DOC-STORE-1 — the daemon's three document tables (§16.7-12).
+ *
+ * TWO LAYERS, NOT ONE (§14). Storing only a merged Yjs binary would discard the signed envelope
+ * chain that makes a seal verifiable, so both are kept:
+ *
+ *   `document_envelopes`  — the IMMUTABLE log: signatures, provenance, the per-document chain.
+ *                           This is the truth.
+ *   `document_snapshots`  — a MATERIALIZATION for fast start. Disposable by construction:
+ *                           delete it and it rebuilds from the log, byte-identical.
+ *
+ * The distinction is load-bearing rather than stylistic. Live Yjs state deliberately does NOT
+ * survive a daemon restart — CELLO's invariant is daemon-up-is-CELLO-on — and that is only safe
+ * because the log makes rebuilding a lookup rather than an archaeology exercise.
+ *
+ * THIS MODULE PERSISTS; IT DOES NOT APPLY. Replay is INJECTED (`rebuildSnapshot`), so the store
+ * owns *what to replay and in what order* while the engine (DOD-DOC-ENGINE-1) owns *how to
+ * apply*. That keeps `yjs` out of this file's imports entirely and keeps the P0/P1 boundary
+ * honest — a store that quietly grew a Y.Doc would be the engine wearing a store's name.
+ *
+ * WHAT IS NEVER STORED HERE: a Yjs clientID. §14's one-line rule is "let Yjs mint its own per
+ * live Y.Doc; never derive it from agent identity, never persist and restore one." DOD-DOC-FUZZ-1
+ * measured the cost of getting this wrong — two live docs sharing a clientID means the colliding
+ * writer silently wins, the honest client's update is accepted-and-dropped, and the result is a
+ * splice of two authors with an EMPTY pending set and no error on any path. So the snapshot
+ * stores a binary and a state vector, and nothing that could be restored into a live document as
+ * an identity.
+ *
+ * KEYED ON STABLE IDS ONLY. `agent_id` and `document_id`, never `agent_name` — it is a mutable
+ * display label and reusable after retirement. The M7 session tables join on `agent_name`; that
+ * is a known defect (`DOD-AGENT-ID-JOINKEY-1`), not a precedent to copy.
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/** Lifecycle states a document can hold (§3.5). `stalled` is DOD-DOC-REJECT-1's terminal state. */
+export type DocumentStatus = "active" | "closed" | "killed" | "stalled";
+/**
+ * What an envelope IS, as opposed to what it says. A withdrawal or a rejection is a NEW ROW that
+ * references an earlier envelope — never an edit to it. The log is append-only, so the only way
+ * to say "that one no longer counts" is to add a record saying so.
+ */
+export type DocumentEnvelopeKind = "update" | "withdrawal" | "rejection";
+export interface DocumentProperties {
+    /** V1 accepts only `authenticated` — the Tier-2 seam (§16.1). */
+    assurance_tier?: string;
+    /** V1 accepts only `false` — the Tier-2 seam (§16.1). */
+    schema_enforcement?: boolean;
+    append_only?: boolean;
+    [key: string]: unknown;
+}
+export interface DocumentRow {
+    documentId: string;
+    ownerAgentId: string;
+    peerAgentId: string;
+    documentType: string;
+    properties: DocumentProperties;
+    status: DocumentStatus;
+    createdAtMs: number;
+}
+export interface DocumentEnvelopeRow {
+    /** Content hash of the envelope — the stable identity, and the log's primary key. */
+    envelopeHash: string;
+    documentId: string;
+    /** WHO authored it. The chain is per-sender, so this is what partitions it. */
+    senderAgentId: string;
+    /** The sender's previous envelope for this document, or null at genesis (§9.1). */
+    docPrevHash: string | null;
+    /** Constant 0 in V1 and NEVER omitted — after a compaction an update that does not state its
+     *  epoch cannot be verified unambiguously (§14, §16.1 seam). */
+    epochId: number;
+    signature: Uint8Array;
+    /** The sender's Yjs state vector at publish time (§7). */
+    stateVector: Uint8Array;
+    /** NULLABLE — a purged envelope keeps its hash and signature, proving it existed (§16.7-12). */
+    payload: Uint8Array | null;
+    kind: DocumentEnvelopeKind;
+    /** For a withdrawal or rejection: the envelope it concerns. */
+    referencesEnvelopeHash?: string | null;
+    createdAtMs: number;
+    /** Position in this document's log. Assigned on append; absent until then. */
+    logIndex?: number;
+}
+export interface DocumentSnapshot {
+    binary: Uint8Array;
+    stateVector: Uint8Array;
+    /**
+     * The `log_index` of the last envelope this snapshot reflects. §14 is explicit about why it is
+     * stored rather than derived: with it, "where does the snapshot sit relative to the log" is a
+     * lookup; without it, every rebuild works it out from scratch.
+     *
+     * **-1 means nothing has been applied.** The resume point is ALWAYS `lastAppliedIndex + 1`,
+     * so an empty log yields 0 and `getEnvelopesSince(0)` reads the whole log — the sentinel and
+     * the convention are chosen to agree.
+     */
+    lastAppliedIndex: number;
+}
+/** Thrown when a read path refuses to materialize over a chain that does not verify. */
+export declare class DocumentChainError extends Error {
+    readonly reason: "document_chain_broken" | "document_chain_forked";
+    readonly detail: string;
+    constructor(reason: "document_chain_broken" | "document_chain_forked", detail: string);
+}
+export type ChainVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "document_chain_broken" | "document_chain_forked";
+    detail: string;
+};
+/**
+ * Injected by the engine: fold an ordered envelope list into a materialized state.
+ *
+ * Takes ROWS, not bare payloads. The engine has to distinguish an update from a withdrawal or a
+ * rejection to fold correctly — a withdrawn envelope's payload must not be applied — and it
+ * cannot do that from `Uint8Array[]`. The store supplies the WHOLE log in order — withdrawal and
+ * rejection records included, payload-free though they are; deciding what counts is the engine's
+ * call, not the store's.
+ */
+export type ReplayFn = (envelopes: DocumentEnvelopeRow[]) => {
+    binary: Uint8Array;
+    stateVector: Uint8Array;
+};
+export declare class DocumentStore {
+    #private;
+    constructor(db: DaemonDatabase, logger: Logger);
+    createDocument(row: DocumentRow): void;
+    getDocument(ownerAgentId: string, documentId: string): DocumentRow | null;
+    listDocuments(ownerAgentId: string): DocumentRow[];
+    setDocumentStatus(ownerAgentId: string, documentId: string, status: DocumentStatus): void;
+    /**
+     * Append an envelope at the next log position.
+     *
+     * IMMUTABLE AT A HASH: the conflict clause is scoped to the envelope hash ALONE, so a
+     * re-delivery — or a peer replaying the same hash with different bytes — cannot overwrite what
+     * was recorded. Returns whether a new row was written, so the caller can tell a genuine append
+     * from a duplicate rather than inferring it.
+     *
+     * Scoped deliberately, not written as a bare `OR IGNORE`: that form suppresses CHECK, UNIQUE
+     * and NOT NULL as well, which on an append-only log means a malformed `kind` or a colliding
+     * `log_index` would be DROPPED and reported to the caller as an already-seen duplicate. Every
+     * constraint except the hash conflict must throw, or `false` means three different things the
+     * caller cannot tell apart.
+     */
+    appendEnvelope(ownerAgentId: string, envelope: DocumentEnvelopeRow): boolean;
+    /**
+     * Envelopes at or after `fromIndex`, in log order. This is what makes `lastAppliedIndex` the
+     * lookup §14 asks for: resume an incremental rebuild at `lastAppliedIndex + 1` without reading
+     * the whole log.
+     */
+    getEnvelopesSince(ownerAgentId: string, documentId: string, fromIndex: number): DocumentEnvelopeRow[];
+    getEnvelopeLog(ownerAgentId: string, documentId: string): DocumentEnvelopeRow[];
+    /**
+     * Verify each sender's `doc_prev_hash` chain independently.
+     *
+     * The log interleaves both parties' envelopes, so there is no single total order to check —
+     * §16.7-5 defines replay set-based per epoch for exactly this reason. What must hold is that
+     * every sender's own links form one unbroken chain from a single genesis.
+     *
+     * A break REFUSES and names the sender and the missing predecessor. Skipping the leaf and
+     * carrying on would leave a document that reads as complete while missing operations, which is
+     * the silent-divergence failure the chain exists to prevent.
+     *
+     * LINKAGE ONLY — the name says so deliberately. This verifies no signature and does not check
+     * that `envelope_hash` hashes the content; neither is possible here (no key, no encoder). A
+     * caller must not read `ok: true` as authenticity — that belongs to the engine.
+     */
+    verifyChainLinkage(ownerAgentId: string, documentId: string): ChainVerdict;
+    getSnapshot(ownerAgentId: string, documentId: string): DocumentSnapshot | null;
+    /** REPLACES — a snapshot is a cache of the log, not a second log. */
+    putSnapshot(ownerAgentId: string, documentId: string, snapshot: DocumentSnapshot): void;
+    deleteSnapshot(ownerAgentId: string, documentId: string): void;
+    /**
+     * Rebuild a snapshot from the envelope log alone, using the caller's replay function.
+     *
+     * Payload-stripped envelopes (purged, or withdrawal/rejection records that carry none)
+     * contribute nothing to replay but STILL COUNT toward `lastAppliedIndex` — otherwise the next
+     * incremental rebuild would start behind them and replay them forever.
+     */
+    rebuildSnapshot(ownerAgentId: string, documentId: string, replay: ReplayFn): DocumentSnapshot;
+}
+//# sourceMappingURL=document-store.d.ts.map

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

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