@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/document-engine.js

@@ -1,282 +0,0 @@
-/**
- * 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 { extractErrorMessage } from "./error-message.js";
-/** 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 = extractErrorMessage(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", extractErrorMessage(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.
-        // BOTH pending sets: an update carrying a delete set for structs never seen leaves
-        // pendingStructs null and pendingDs populated, and retains just the same.
-        if (shadow.store.pendingStructs !== null || shadow.store.pendingDs !== null) {
-            return this.#refuse("document_update_unresolved_dependencies", shadow.store.pendingStructs
-                ? `depends on ${shadow.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`
-                : "carries a delete set referring to operations this document has never seen", 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", extractErrorMessage(err), update);
-        }
-        if (doc.store.pendingStructs !== null || doc.store.pendingDs !== null) {
-            return this.#refuse("document_update_unresolved_dependencies", doc.store.pendingStructs
-                ? `depends on ${doc.store.pendingStructs.missing.size} client(s) whose earlier operations are absent`
-                : "carries a delete set referring to operations this document has never seen", 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

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

package/dist/document-flag.d.ts

@@ -1,58 +0,0 @@
-/**
- * 074-DOCSFLAG — whether the collaborative-document layer exists in this process.
- *
- * ONE value, default OFF, gating all five document surfaces: the 14 IPC handler registrations, the
- * 15 MCP tools, the 14 CLI commands and their help, the 14 vocabulary entries, and the reconcile
- * sweep timer. Not five toggles — five toggles is five states nobody can reason about.
- *
- * ⚠️ THIS IS A GATE, NOT A REMOVAL. Nothing is deleted. Every line of the document layer stays
- * where it is and its tests keep running; with the flag ON behaviour is byte-identical to before
- * this flag existed. The flag flips when the base protocol is solid.
- *
- * ── WHY AN ENVIRONMENT VARIABLE AND NOT THE GATEWAY CONFIG STORE ──────────────────────────────
- *
- * Three separate OS processes have to agree on this answer, and two of them cannot reach a database:
- *
- *   - the DAEMON reads it once at startup, and could read any store;
- *   - the CLI renders `cello --help` in a fresh short-lived process, before it has spoken to a
- *     daemon at all — help must be right when no daemon is running;
- *   - the MCP SHIM (`@cello-protocol/connect`) declares its tool list at module load and has
- *     `@cello-protocol/daemon` as a DEV dependency only, on purpose: it is a thin standalone
- *     package. It cannot import this module, let alone open the daemon's SQLCipher database.
- *
- * So the value is an environment variable, and the shim reads the same variable by name with its
- * own three-line parser.
- *
- * ⚠️ THIS PARAGRAPH USED TO NAME A TEST CALLED `documents-flag-parity`, WHICH DOES NOT EXIST. Found by
- * review, and rewritten rather than deleted because the wrong name is the evidence that the protection
- * was asserted before it was located. **The protection is real and it lives in
- * `docsflag-2-mcp-tools.test.ts`**: that test imports `DOCUMENTS_FLAG_ENV` from here and uses it to set
- * the spawned shim's environment, so renaming this constant makes the ON case advertise nothing and the
- * OFF case inherit the suite's ambient value — both red. Measured, not assumed: the rename was run.
- *
- * What IS taken from the config store's posture: **the tightest value is the default.** Absent
- * reads as off, an unparseable value reads as off, and only an explicit affirmative turns the layer
- * on. There is no value that means "on" by accident.
- *
- * ── WHAT THIS IS NOT ──────────────────────────────────────────────────────────────────────────
- *
- * Not a security control, and it must not be described as one. An operator who can set an
- * environment variable can also edit the source — the document code is on their disk. What the
- * flag removes is the ADVERTISEMENT: with it off, an agent reading its tool list finds no document
- * verb to call, and an operator who turns it on has opted in deliberately.
- */
-/** The one variable name. Read by the daemon, the CLI and (by literal) the MCP shim. */
-export declare const DOCUMENTS_FLAG_ENV = "CELLO_DOCUMENTS";
-/**
- * Is the collaborative-document layer enabled in this process?
- *
- * Takes the environment as an argument so a test can answer the question for a given environment
- * without mutating the real one. Callers in production pass nothing.
- */
-export declare function documentsEnabled(env?: Record<string, string | undefined>): boolean;
-/**
- * The word the daemon logs at startup, so "are documents on?" is one grep rather than an inference
- * from the absence of something (074-DOCSFLAG clause 9).
- */
-export declare function documentLayerState(env?: Record<string, string | undefined>): "on" | "off";
-//# sourceMappingURL=document-flag.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"document-flag.d.ts","sourceRoot":"","sources":["../src/document-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAQpD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAI/F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,KAAK,CAEzF"}

package/dist/document-flag.js

@@ -1,70 +0,0 @@
-/**
- * 074-DOCSFLAG — whether the collaborative-document layer exists in this process.
- *
- * ONE value, default OFF, gating all five document surfaces: the 14 IPC handler registrations, the
- * 15 MCP tools, the 14 CLI commands and their help, the 14 vocabulary entries, and the reconcile
- * sweep timer. Not five toggles — five toggles is five states nobody can reason about.
- *
- * ⚠️ THIS IS A GATE, NOT A REMOVAL. Nothing is deleted. Every line of the document layer stays
- * where it is and its tests keep running; with the flag ON behaviour is byte-identical to before
- * this flag existed. The flag flips when the base protocol is solid.
- *
- * ── WHY AN ENVIRONMENT VARIABLE AND NOT THE GATEWAY CONFIG STORE ──────────────────────────────
- *
- * Three separate OS processes have to agree on this answer, and two of them cannot reach a database:
- *
- *   - the DAEMON reads it once at startup, and could read any store;
- *   - the CLI renders `cello --help` in a fresh short-lived process, before it has spoken to a
- *     daemon at all — help must be right when no daemon is running;
- *   - the MCP SHIM (`@cello-protocol/connect`) declares its tool list at module load and has
- *     `@cello-protocol/daemon` as a DEV dependency only, on purpose: it is a thin standalone
- *     package. It cannot import this module, let alone open the daemon's SQLCipher database.
- *
- * So the value is an environment variable, and the shim reads the same variable by name with its
- * own three-line parser.
- *
- * ⚠️ THIS PARAGRAPH USED TO NAME A TEST CALLED `documents-flag-parity`, WHICH DOES NOT EXIST. Found by
- * review, and rewritten rather than deleted because the wrong name is the evidence that the protection
- * was asserted before it was located. **The protection is real and it lives in
- * `docsflag-2-mcp-tools.test.ts`**: that test imports `DOCUMENTS_FLAG_ENV` from here and uses it to set
- * the spawned shim's environment, so renaming this constant makes the ON case advertise nothing and the
- * OFF case inherit the suite's ambient value — both red. Measured, not assumed: the rename was run.
- *
- * What IS taken from the config store's posture: **the tightest value is the default.** Absent
- * reads as off, an unparseable value reads as off, and only an explicit affirmative turns the layer
- * on. There is no value that means "on" by accident.
- *
- * ── WHAT THIS IS NOT ──────────────────────────────────────────────────────────────────────────
- *
- * Not a security control, and it must not be described as one. An operator who can set an
- * environment variable can also edit the source — the document code is on their disk. What the
- * flag removes is the ADVERTISEMENT: with it off, an agent reading its tool list finds no document
- * verb to call, and an operator who turns it on has opted in deliberately.
- */
-/** The one variable name. Read by the daemon, the CLI and (by literal) the MCP shim. */
-export const DOCUMENTS_FLAG_ENV = "CELLO_DOCUMENTS";
-/**
- * The values that turn the layer ON. Everything else — absent, empty, `"0"`, `"off"`, a typo — is
- * off, because the default is the tightest value and a misread must never loosen.
- */
-const AFFIRMATIVE = new Set(["1", "true", "on", "yes"]);
-/**
- * Is the collaborative-document layer enabled in this process?
- *
- * Takes the environment as an argument so a test can answer the question for a given environment
- * without mutating the real one. Callers in production pass nothing.
- */
-export function documentsEnabled(env = process.env) {
-    const raw = env[DOCUMENTS_FLAG_ENV];
-    if (typeof raw !== "string")
-        return false;
-    return AFFIRMATIVE.has(raw.trim().toLowerCase());
-}
-/**
- * The word the daemon logs at startup, so "are documents on?" is one grep rather than an inference
- * from the absence of something (074-DOCSFLAG clause 9).
- */
-export function documentLayerState(env) {
-    return documentsEnabled(env) ? "on" : "off";
-}
-//# sourceMappingURL=document-flag.js.map

package/dist/document-flag.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-flag.js","sourceRoot":"","sources":["../src/document-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0C,OAAO,CAAC,GAAG;IACpF,MAAM,GAAG,GAAG,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAwC;IACzE,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9C,CAAC"}