@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/document-engine.js

@@ -0,0 +1,282 @@
+/**
+ * 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

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

package/dist/document-flag.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,70 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}