@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/document-notify.js

@@ -0,0 +1,580 @@
+/**
+ * DOD-DOC-NOTIFY-1 — passive notification and the two read calls (§16.5, §4.1).
+ *
+ * ── WHY NO DOORBELL ───────────────────────────────────────────────────────────────────────────
+ *
+ * A document update raises NO doorbell (§11.3 — doorbell-on-update is parked). The notice sits in
+ * the inbox aggregation and the agent finds it the next time it looks. That is the whole design:
+ * a collaborator typing produces a stream of updates, and a doorbell per update would interrupt
+ * the operator's agent continuously for something that has no deadline. The one-line summary the
+ * agent eventually reads carries the same information at none of the cost.
+ *
+ * Following the `contact_rename_notices` precedent: there is no inbox store — the inbox is computed
+ * per call — so a derived section needs its own table and its own getter.
+ *
+ * The notice carries `document_id` and a PENDING COUNT, and nothing else. Not a preview, not the
+ * first line, not the author's words. Content reaches the agent only through the two read calls
+ * below, which are screened; a notification that carried content would be an unscreened path into
+ * the agent's context, which is the whole prompt-injection surface §3.1 exists to close.
+ *
+ * ── THE TWO READ CALLS (§4.1) ─────────────────────────────────────────────────────────────────
+ *
+ * `diffStats` is STRUCTURAL ONLY — counts, ranges, and the overlap flag. It exists so an agent can
+ * decide whether to read without reading, which is exactly what a cautious agent should be able to
+ * do. `diff` is the git-like diff itself and is an ordinary screened read.
+ *
+ * ── SUPPORTED TYPES FOR `diff`, DECIDED IN-UNIT ───────────────────────────────────────────────
+ *
+ * Markdown, plain text, and JSON. Markdown and plain text share one line-diff implementation (a
+ * markdown file IS lines); JSON gets a key-path diff because a line diff over re-serialized JSON
+ * reports the whole document as changed whenever a formatter touches it. Anything else returns a
+ * REFUSAL naming the type rather than a line diff over bytes that are not lines — a diff that is
+ * wrong is worse than no diff, because the agent cannot tell.
+ */
+import { lineRuns, toChunks } from "./line-lcs.js";
+import { diffableDocumentTypes, rootForDocumentType } from "./document-types.js";
+const CREATE_NOTICES_SQL = `
+  CREATE TABLE IF NOT EXISTS document_notices (
+    agent_id     TEXT    NOT NULL,
+    document_id  TEXT    NOT NULL,
+    -- The count, not the content. See the header.
+    pending      INTEGER NOT NULL,
+    noticed_at   INTEGER NOT NULL,
+    PRIMARY KEY (agent_id, document_id)
+  );
+`;
+/**
+ * WHAT THE OPERATOR LAST SAW, so `diff` can answer "what changed since I looked".
+ *
+ * The text itself, not a state vector. A state vector says which OPERATIONS this side has seen,
+ * which is a fact about the CRDT — and the question an agent is asking before it builds on a shared
+ * document is a fact about the TEXT: what words are different from the ones I read. Reconstructing
+ * the old text from a vector means replaying the log to a point, which is both expensive and a
+ * second answer to a question this column answers directly.
+ *
+ * Written by READ, never by write or by an arriving update. It marks what a human or an agent
+ * actually looked at; moving it on an inbound update would erase the very change the diff exists to
+ * show, silently, at the moment it arrived.
+ */
+/**
+ * DOD-DOC-WATCH-1 — the paths an agent asked to be nudged about, per document.
+ *
+ * `paths` is a JSON array rather than a row per path: the list is small, always read and written
+ * whole, and one row per (agent, document) means the ring-once bookkeeping has somewhere obvious to
+ * live. `nudged_at` NULL means a nudge is owed; a read clears it back to NULL.
+ */
+const CREATE_WATCHES_SQL = `
+  CREATE TABLE IF NOT EXISTS document_watches (
+    agent_id     TEXT    NOT NULL,
+    document_id  TEXT    NOT NULL,
+    paths        TEXT    NOT NULL,
+    nudged_at    INTEGER,
+    PRIMARY KEY (agent_id, document_id)
+  );
+`;
+const CREATE_READ_MARKS_SQL = `
+  CREATE TABLE IF NOT EXISTS document_read_marks (
+    agent_id     TEXT    NOT NULL,
+    document_id  TEXT    NOT NULL,
+    seen_text    TEXT    NOT NULL,
+    seen_at      INTEGER NOT NULL,
+    -- The last text WE wrote since that read, or NULL if we have not written since. See the
+    -- myEditedLines comment below for why it exists: it is what makes the overlap flag a computed
+    -- answer rather than a hardcoded null.
+    --
+    -- No backticks in this string. It is a JS template literal, so one would terminate it — which
+    -- is exactly how this shipped broken for a minute.
+    my_text      TEXT,
+    PRIMARY KEY (agent_id, document_id)
+  );
+`;
+/** Born on an existing table. See `PEER_DECISION_COLUMNS` in document-handshake.ts for the pattern. */
+const READ_MARK_COLUMNS = ["ALTER TABLE document_read_marks ADD COLUMN my_text TEXT"];
+/**
+ * The types `cello_doc_diff` renders — DERIVED from the one registry, never listed here.
+ *
+ * This was a hardcoded `["markdown", "text", "json"]` sitting in parallel with the write path's
+ * admitted set, and the two had drifted: `plaintext` was admitted and could not be diffed, so the
+ * verb that says what changed was dead on a type the product offered.
+ */
+export const DIFFABLE_DOCUMENT_TYPES = diffableDocumentTypes();
+export class DocumentNotifications {
+    #store;
+    #logger;
+    constructor(store, logger) {
+        this.#store = store;
+        this.#logger = logger;
+        this.#store.rawDb.exec(CREATE_NOTICES_SQL);
+        this.#store.rawDb.exec(CREATE_READ_MARKS_SQL);
+        this.#store.rawDb.exec(CREATE_WATCHES_SQL);
+        for (const sql of READ_MARK_COLUMNS) {
+            // Birth-gated so a daemon that already holds read marks gains the column instead of losing
+            // them. A failure here is either "already present" — the ordinary case — or a locked
+            // database, and the latter surfaces loudly on the very next SELECT rather than degrading.
+            const has = this.#store.rawDb.prepare("PRAGMA table_info(document_read_marks)").all().some((c) => c.name === "my_text");
+            if (!has)
+                this.#store.rawDb.exec(sql);
+        }
+    }
+    /**
+     * Record what this agent last SAW, so a later diff has a "before".
+     *
+     * REPLACES. A read mark is a bookmark, not a history — keeping every read would make the table
+     * grow with attention rather than with content, and no caller wants the second-most-recent read.
+     */
+    markRead(agentId, documentId, text, nowMs) {
+        this.#store.rawDb
+            .prepare(`INSERT INTO document_read_marks (agent_id, document_id, seen_text, seen_at, my_text)
+         VALUES (?, ?, ?, ?, NULL)
+         ON CONFLICT (agent_id, document_id) DO UPDATE SET
+           seen_text = excluded.seen_text, seen_at = excluded.seen_at,
+           -- CLEARED. A read establishes a new baseline, so edits made before it are no longer
+           -- "mine since I looked" — carrying them forward would report an overlap against work
+           -- the operator has already seen merged.
+           my_text = NULL`)
+            .run(agentId, documentId, text, nowMs);
+        // RE-ARM THE NUDGE. A read is what spends the previous one — see `nudgeOwed`. Without this a
+        // document nudges exactly once in its life and then goes quiet forever, which is worse than not
+        // nudging at all because the operator would trust the silence.
+        this.#store.rawDb
+            .prepare("UPDATE document_watches SET nudged_at = NULL WHERE agent_id = ? AND document_id = ?")
+            .run(agentId, documentId);
+    }
+    /**
+     * Record the text WE just wrote, against the current read mark.
+     *
+     * No-ops when there is no read mark: without a baseline there is nothing to measure our edit
+     * against, and inventing one would make the first diff after a write report the whole document as
+     * a conflict.
+     */
+    /**
+     * Every text this agent demonstrably held for this document — what it last READ and what it last
+     * WROTE, in no particular order, with nulls dropped.
+     *
+     * Used by the stale-write guard to answer "could this author have seen the thing their write
+     * removes?". Both sources are needed: a read establishes a baseline, and a write is text the
+     * author obviously saw because they composed it.
+     */
+    knownTexts(agentId, documentId) {
+        const row = this.#store.rawDb
+            .prepare("SELECT seen_text, my_text FROM document_read_marks WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        return [row?.seen_text ?? null, row?.my_text ?? null].filter((t) => t !== null);
+    }
+    /**
+     * The paths this agent has asked to be nudged about, for one document. Empty means none — never
+     * "all"; see `matchWatchedPaths`.
+     */
+    watches(agentId, documentId) {
+        const row = this.#store.rawDb
+            .prepare("SELECT paths FROM document_watches WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        if (row?.paths === undefined)
+            return [];
+        try {
+            const parsed = JSON.parse(row.paths);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Replace the watch list. An empty list REMOVES the row, so "watching nothing" holds no state. */
+    setWatches(agentId, documentId, paths) {
+        if (paths.length === 0) {
+            this.#store.rawDb
+                .prepare("DELETE FROM document_watches WHERE agent_id = ? AND document_id = ?")
+                .run(agentId, documentId);
+            return;
+        }
+        this.#store.rawDb
+            .prepare(`INSERT INTO document_watches (agent_id, document_id, paths, nudged_at)
+         VALUES (?, ?, ?, NULL)
+         ON CONFLICT (agent_id, document_id) DO UPDATE SET paths = excluded.paths, nudged_at = NULL`)
+            .run(agentId, documentId, JSON.stringify([...paths]));
+    }
+    /** Every document this agent is watching, for the surface that lists them. */
+    allWatches(agentId) {
+        const rows = this.#store.rawDb
+            .prepare("SELECT document_id, paths FROM document_watches WHERE agent_id = ? ORDER BY document_id")
+            .all(agentId);
+        return rows.map((r) => {
+            let paths = [];
+            try {
+                const parsed = JSON.parse(r.paths);
+                if (Array.isArray(parsed))
+                    paths = parsed;
+            }
+            catch {
+                paths = [];
+            }
+            return { documentId: r.document_id, paths };
+        });
+    }
+    /**
+     * Whether a nudge is owed — true only if one has not already fired since this agent last READ.
+     *
+     * RINGS ONCE. A peer editing for ten minutes must produce one nudge, not forty; the Telegram
+     * doorbell coalesces for the identical reason. Reading the document is what re-arms it, because
+     * reading is what makes the earlier nudge spent.
+     */
+    nudgeOwed(agentId, documentId) {
+        const row = this.#store.rawDb
+            .prepare("SELECT nudged_at FROM document_watches WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        return row !== undefined && (row.nudged_at ?? null) === null;
+    }
+    /** Record that a nudge fired, so it does not fire again until the next read. */
+    markNudged(agentId, documentId, nowMs) {
+        this.#store.rawDb
+            .prepare("UPDATE document_watches SET nudged_at = ? WHERE agent_id = ? AND document_id = ?")
+            .run(nowMs, agentId, documentId);
+    }
+    markWritten(agentId, documentId, text) {
+        this.#store.rawDb
+            .prepare("UPDATE document_read_marks SET my_text = ? WHERE agent_id = ? AND document_id = ?")
+            .run(text, agentId, documentId);
+    }
+    /**
+     * The lines WE edited since the last read, 1-based, in the baseline's coordinate space — or null
+     * when we have not written since, which is "not computed" and must stay distinguishable from "no
+     * conflict". `diffStats` requires the distinction for exactly that reason.
+     */
+    /**
+     * WHY THIS EXISTS, stated where the reader will need it:
+     *
+     * At diff time the two texts in hand are the baseline and the current document, and no amount of
+     * comparing them says which of the changes were the PEER's. So `overlap` was hardcoded `null`
+     * while three shipped instruction sheets told agents to branch on it — and `null` is falsy in
+     * JSON, so every one of them got the reassuring answer on every call. That is the precise trap
+     * `diffStats` made its `myEdits` parameter required to prevent, defeated by the one caller.
+     *
+     * Diffing the baseline against what WE last wrote gives our own edited lines in the baseline's
+     * coordinate space, which is the space the diff reports its ranges in. Exact, not inferred.
+     */
+    myEditedLines(agentId, documentId) {
+        const row = this.#store.rawDb
+            .prepare("SELECT seen_text, my_text FROM document_read_marks WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        if (!row || row.my_text === null)
+            return null;
+        const lines = [];
+        const runs = lineRuns(toChunks(row.seen_text), toChunks(row.my_text));
+        if (runs === null) {
+            // Above the LCS limit. Said as "not computed" rather than degraded into a whole-file range,
+            // which would report every diff as an overlap and train the agent to ignore the field.
+            return null;
+        }
+        for (const hunk of runs) {
+            // The hunk's BEFORE range, which is what the diff reports its own ranges in. A pure insertion
+            // has an empty before-range and is attributed to the line it precedes, matching `diffStats`.
+            const start = hunk.aStart + 1;
+            const end = hunk.aEnd === hunk.aStart ? hunk.aStart + 1 : hunk.aEnd;
+            for (let n = start; n <= end; n++)
+                lines.push(n);
+        }
+        return lines;
+    }
+    /**
+     * The text this agent last saw, or null if it has never read this document.
+     *
+     * NULL IS NOT THE EMPTY STRING, and callers must not conflate them. Never-read means the whole
+     * document is new to this agent; last-saw-empty means they read it when it was empty and
+     * everything since is a change they can be shown against that. Returning "" for both would render
+     * a first read of a long document as an enormous diff the agent then treats as "what just
+     * changed".
+     */
+    lastSeen(agentId, documentId) {
+        const row = this.#store.rawDb
+            .prepare("SELECT seen_text FROM document_read_marks WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        return row === undefined ? null : row.seen_text;
+    }
+    /**
+     * How many of the PEER's updates have arrived since this agent last read the document.
+     *
+     * Derived from the envelope log against the read mark's timestamp, never a counter. A counter is
+     * a second tally of a fact the log already holds, and the two disagree the first time a write is
+     * missed or an envelope is redelivered — which happens routinely, since redelivery is how an
+     * offline peer is caught up.
+     *
+     * No read mark means the agent has never read it, so everything the peer has sent is unread.
+     */
+    unreadFromPeer(agentId, documentId) {
+        const mark = this.#store.rawDb
+            .prepare("SELECT seen_at FROM document_read_marks WHERE agent_id = ? AND document_id = ?")
+            .get(agentId, documentId);
+        const since = mark?.seen_at ?? 0;
+        const row = this.#store.rawDb
+            .prepare(`SELECT COUNT(*) AS n FROM document_envelopes
+          WHERE owner_agent_id = ? AND document_id = ? AND sender_agent_id != ?
+            AND kind = 'update' AND created_at > ?`)
+            .get(agentId, documentId, agentId, since);
+        return row?.n ?? 0;
+    }
+    /**
+     * Note that a document has unread updates. Passive — this never pushes anything.
+     *
+     * The count is REPLACED rather than incremented, and is passed in by the caller from the log,
+     * so the notice cannot drift from the document. An incremented counter is a second tally of a
+     * fact the log already holds, and the two disagree the first time a notice write is missed.
+     */
+    notice(agentId, documentId, pending, nowMs) {
+        if (pending <= 0) {
+            // Nothing pending is not a notice with zero in it — it is the absence of a notice. A row
+            // saying "0 unread" is an inbox entry the agent must read to discover it has nothing to read.
+            //
+            // Deleted DIRECTLY rather than through `clear()`: that method's event means "the agent
+            // fetched", and firing it because a count fell to zero reports a fetch that never happened.
+            this.#store.rawDb
+                .prepare("DELETE FROM document_notices WHERE agent_id = ? AND document_id = ?")
+                .run(agentId, documentId);
+            return;
+        }
+        this.#store.rawDb
+            .prepare(`INSERT INTO document_notices (agent_id, document_id, pending, noticed_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (agent_id, document_id)
+           DO UPDATE SET pending = excluded.pending, noticed_at = excluded.noticed_at`)
+            .run(agentId, documentId, pending, nowMs);
+    }
+    /** The derived inbox section. Read-only — fetching is what clears, and that is explicit. */
+    pending(agentId) {
+        const rows = this.#store.rawDb
+            .prepare(`SELECT document_id, pending, noticed_at FROM document_notices
+          WHERE agent_id = ? ORDER BY noticed_at ASC, document_id ASC`)
+            .all(agentId);
+        return rows.map((r) => ({
+            documentId: r["document_id"],
+            pending: r["pending"],
+            noticedAtMs: r["noticed_at"],
+        }));
+    }
+    /**
+     * Cleared by the agent's EXPLICIT fetch, never by the aggregation that displays it.
+     *
+     * Reading the inbox and clearing the notice are different acts: an inbox render that cleared
+     * would drop the notice for an agent that merely glanced at a summary, and the update would then
+     * be unread and unannounced — invisible in both directions.
+     */
+    clear(agentId, documentId) {
+        const info = this.#store.rawDb
+            .prepare("DELETE FROM document_notices WHERE agent_id = ? AND document_id = ?")
+            .run(agentId, documentId);
+        const cleared = Number(info.changes) > 0;
+        // agentId included: this daemon attends several agents, and an event that names only the
+        // document cannot be attributed to one of them.
+        if (cleared)
+            this.#logger.info("document.notice.cleared", { agentId, documentId });
+        return cleared;
+    }
+    /**
+     * Structural counts and ranges — NO content. Lets an agent decide whether to read.
+     *
+     * `before` and `after` are the materialized text of the document at the two points; the caller
+     * holds the engine and therefore the materialization.
+     *
+     * Uses the SHARED line LCS, not a positional walk. The first version compared line i to line i,
+     * which is correct only while the line count is unchanged: inserting one line at the top of a
+     * three-line file reported `+4 -3` with a single range covering the whole document. The counts
+     * being wrong is the smaller half — `overlap` is derived from those ranges, so it became
+     * permanently true, and a flag that always says yes trains the agent to ignore it. Same defect
+     * class WRITE-1 measured, which is why there is now one LCS rather than two.
+     */
+    diffStats(documentId, before, after, 
+    /**
+     * The operator's own edited line numbers. REQUIRED — pass `null` to say "not computed".
+     * Defaulting to `[]` made a caller that simply forgot receive `overlap: false`, the reassuring
+     * answer, indistinguishable from "checked, and there is no conflict". This is the one
+     * judgement field in an otherwise structural result.
+     */
+    myEdits, documentType) {
+        const a = toChunks(before);
+        const b = toChunks(after);
+        const runs = lineRuns(a, b);
+        if (runs === null) {
+            // Above the LCS limit. Said plainly rather than degraded silently into a whole-file range
+            // that would read as a measurement.
+            return {
+                documentId,
+                linesAdded: b.length,
+                linesRemoved: a.length,
+                ranges: [{ start: 1, end: Math.max(a.length, b.length) }],
+                keyPaths: [],
+                keyPathsComputed: false,
+                overlap: myEdits === null ? null : myEdits.length > 0,
+                truncated: true,
+            };
+        }
+        // G3: for a JSON document the DoD asks for KEY ranges, not line ranges. Produced here rather
+        // than left as a permanently-empty array, which reads as "no key paths changed" instead of
+        // "not computed" — the same absent-is-not-fine trap as the overlap default above.
+        let keyPaths = [];
+        let keyPathsComputed = false;
+        // Dispatched on the ROOT, not the type name — a second map-root type must not fall through to
+        // the line path just because it is not called "json".
+        if (documentType !== undefined && rootForDocumentType(documentType) === "map") {
+            const paths = changedKeyPaths(before, after);
+            if (paths !== null) {
+                keyPaths = paths;
+                keyPathsComputed = true;
+            }
+        }
+        let added = 0;
+        let removed = 0;
+        const ranges = [];
+        for (const r of runs) {
+            added += r.bEnd - r.bStart;
+            removed += r.aEnd - r.aStart;
+            // 1-based inclusive, over the BEFORE text — which is the text the operator's own edit line
+            // numbers refer to, and therefore the only coordinate space in which the overlap comparison
+            // means anything. A pure insertion has an empty before-range, so it is reported at the line
+            // it precedes rather than as a zero-width range nobody can act on.
+            ranges.push({ start: r.aStart + 1, end: r.aEnd === r.aStart ? r.aStart + 1 : r.aEnd });
+        }
+        const touched = new Set();
+        for (const r of ranges)
+            for (let n = r.start; n <= r.end; n++)
+                touched.add(n);
+        return {
+            documentId,
+            linesAdded: added,
+            linesRemoved: removed,
+            ranges,
+            keyPaths,
+            keyPathsComputed,
+            overlap: myEdits === null ? null : myEdits.some((line) => touched.has(line)),
+            truncated: false,
+        };
+    }
+    /**
+     * The git-like diff. An ordinary screened read — the caller screens it; this renders it.
+     *
+     * An unsupported type is REFUSED by name rather than line-diffed anyway. A diff that is silently
+     * wrong is worse than no diff, because the agent has no way to tell and will act on it.
+     */
+    diff(documentType, before, after, documentId) {
+        if (!DIFFABLE_DOCUMENT_TYPES.includes(documentType)) {
+            return {
+                ok: false,
+                reason: "document_type_not_diffable",
+                detail: `this build renders diffs for ${DIFFABLE_DOCUMENT_TYPES.join(", ")} and this document is ` +
+                    `"${documentType}" — read the document instead of a diff that would be guesswork`,
+            };
+        }
+        void documentId;
+        if (rootForDocumentType(documentType) === "map") {
+            // A key-path diff, not a line diff. Re-serialized JSON changes shape whenever a formatter
+            // touches it, so a line diff reports the entire document as rewritten for a change of one
+            // value — which is the false "everything changed" alarm that makes an agent stop reading
+            // diffs at all.
+            const parsedPaths = changedKeyPaths(before, after);
+            if (parsedPaths === null) {
+                return {
+                    ok: true,
+                    documentType: "json",
+                    diff: `! this document does not parse as JSON; showing a line diff instead\n${lineDiff(before, after)}`,
+                    fallback: "unparseable_json_line_diff",
+                };
+            }
+            return { ok: true, documentType: "json", diff: jsonDiff(before, after) };
+        }
+        return { ok: true, documentType: documentType, diff: lineDiff(before, after) };
+    }
+}
+function lineDiff(before, after) {
+    // The SHARED LCS, same as diffStats. This renderer kept the positional walk after diffStats moved
+    // off it, which is the worse half to leave behind: inserting one line into a ten-line file
+    // rendered eighteen +/- lines, reporting the entire remainder as rewritten. That is the false
+    // "everything changed" alarm that makes an agent stop reading diffs at all — the exact reasoning
+    // that gave JSON a key-path diff, applied to markdown at last.
+    const a = toChunks(before);
+    const b = toChunks(after);
+    const runs = lineRuns(a, b);
+    if (runs === null)
+        return "! this document is too large to diff line-by-line";
+    const out = [];
+    let ai = 0;
+    for (const r of runs) {
+        for (; ai < r.aStart; ai++)
+            out.push(`  ${strip(a[ai])}`);
+        for (let i = r.aStart; i < r.aEnd; i++)
+            out.push(`- ${strip(a[i])}`);
+        for (let j = r.bStart; j < r.bEnd; j++)
+            out.push(`+ ${strip(b[j])}`);
+        ai = r.aEnd;
+    }
+    for (; ai < a.length; ai++)
+        out.push(`  ${strip(a[ai])}`);
+    return out.join("\n");
+}
+/** Chunks carry their own trailing newline; the rendered diff supplies its own line breaks. */
+function strip(chunk) {
+    return chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk;
+}
+function flatten(value, prefix = "") {
+    const out = new Map();
+    if (value === null || typeof value !== "object") {
+        out.set(prefix || "$", JSON.stringify(value));
+        return out;
+    }
+    for (const [k, v] of Object.entries(value)) {
+        // The separator is ESCAPED in the key. Unescaped, {"a.b": 1} and {"a": {"b": 1}} flatten to the
+        // same path, so a document using dotted keys reports no change where there was one — silently,
+        // which is the exact behaviour this unit refuses everywhere else.
+        const path = prefix ? `${prefix}.${k.replace(/\\/g, "\\\\").replace(/\./g, "\\.")}` : k.replace(/\\/g, "\\\\").replace(/\./g, "\\.");
+        for (const [p, s] of flatten(v, path))
+            out.set(p, s);
+    }
+    return out;
+}
+/** The changed key paths, or null when either side does not parse. */
+/**
+ * Exported so the WATCH matcher (`DOD-DOC-WATCH-1`) computes paths the same way `cello_doc_diff`
+ * renders them. Two implementations would let an agent be nudged about a path the diff never shows,
+ * or shown a path no watch can name — and either makes the feature untrustworthy.
+ */
+export function changedKeyPaths(before, after) {
+    let a;
+    let b;
+    try {
+        a = flatten(JSON.parse(before));
+        b = flatten(JSON.parse(after));
+    }
+    catch {
+        return null;
+    }
+    const paths = new Set();
+    for (const [path, value] of a)
+        if (!b.has(path) || b.get(path) !== value)
+            paths.add(path);
+    for (const [path] of b)
+        if (!a.has(path))
+            paths.add(path);
+    return [...paths].sort();
+}
+function jsonDiff(before, after) {
+    let a;
+    let b;
+    try {
+        a = flatten(JSON.parse(before));
+        b = flatten(JSON.parse(after));
+    }
+    catch {
+        // Deliberately explicit: unparseable JSON gets a stated fallback, not a silent line diff
+        // pretending to be a key diff. The caller sees which it got.
+        return `! this document does not parse as JSON; showing a line diff instead\n${lineDiff(before, after)}`;
+    }
+    const out = [];
+    for (const [path, value] of a) {
+        if (!b.has(path))
+            out.push(`- ${path}: ${value}`);
+        else if (b.get(path) !== value)
+            out.push(`~ ${path}: ${value} -> ${b.get(path)}`);
+    }
+    for (const [path, value] of b)
+        if (!a.has(path))
+            out.push(`+ ${path}: ${value}`);
+    return out.join("\n");
+}
+//# sourceMappingURL=document-notify.js.map

package/dist/document-notify.js.map

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

package/dist/document-profile.d.ts

@@ -0,0 +1,61 @@
+/**
+ * DOD-DOC-PROFILE-1 — the content profile: an ALLOWLIST, agreed at the handshake.
+ *
+ * ── WHY AN ALLOWLIST WHEN A DENYLIST ALREADY EXISTS ───────────────────────────────────────────
+ *
+ * `document-screen.ts` is the denylist: it argues about characters, one at a time, in an open-ended
+ * space, and every argument happens mid-document with whoever is working ambushed by it. A profile
+ * inverts that. Only this character space is permitted, so violations are unambiguous — and the
+ * decision moves to CONSENT, which is the real win. "Do I want a Devanagari document with this
+ * person" is a question an operator can answer once, with a human already engaged, about the whole
+ * document. "What is U+200D doing at offset 412" is not a question anyone can answer.
+ *
+ * ── THE THREE CONSTRAINTS ─────────────────────────────────────────────────────────────────────
+ *
+ *   NAMED AND CLOSED. A free-form profile is a negotiation again, and named profiles are what let
+ *   an operator hold a standing policy — "never auto-accept `unicode-text` from an unendorsed
+ *   contact". A sixth name is a protocol decision, not a caller's choice.
+ *
+ *   CODEPOINT SETS, NOT ADJECTIVES. A profile enforced by a heuristic is a promise we do not keep,
+ *   and "looks like markdown" is a heuristic. Every profile below is a predicate over code points.
+ *
+ *   ENFORCED IN BOTH PLACES, for different reasons (§16.7-14). At authoring, so a stray character
+ *   is caught where it was written and never becomes a rejection round — that is ERGONOMICS. At
+ *   receipt, because the sender's enforcement is unverifiable — that is SECURITY. The second is not
+ *   redundant with the first: a sender's client can be patched, or simply compromised while the
+ *   sender themselves is a good actor.
+ *
+ * ── NARROWING ONLY ────────────────────────────────────────────────────────────────────────────
+ *
+ * Every profile, including the widest, still refuses what `document-screen.ts` refuses. A profile
+ * may only narrow the space, never widen it — otherwise choosing `unicode-text` would be a way to
+ * opt OUT of screening, and a peer could ask for that at consent time in the same breath as asking
+ * for Japanese.
+ */
+/** A violation, in the same machine-readable shape every refusal on this path uses. */
+export interface ProfileViolation {
+    profile: string;
+    codepoints: string[];
+    count: number;
+    offsets: number[];
+}
+/**
+ * The closed set. Each value answers one question: may this code point appear?
+ *
+ * `ascii-markdown` and `ascii-text` are the same space today — markdown's syntax is printable ASCII.
+ * They are kept distinct because the NAME is what an operator consents to and what a future diff
+ * renderer keys on, and collapsing them would make "this is a markdown document" unstateable.
+ */
+export declare const CONTENT_PROFILES: Record<string, (cp: number) => boolean>;
+export declare function isKnownProfile(name: string | undefined): boolean;
+/**
+ * Check text against a profile. Null admits.
+ *
+ * AN UNKNOWN OR ABSENT PROFILE ENFORCES NOTHING, and this is the one fail-open on the document
+ * path. A document agreed before profiles existed carries none, and refusing all of its updates
+ * would break a working document to enforce a rule its two parties never agreed to. The screening
+ * denylist still applies to it — that is the floor, and it is why failing open here is bounded
+ * rather than a hole.
+ */
+export declare function profileViolation(profile: string | undefined, text: string): ProfileViolation | null;
+//# sourceMappingURL=document-profile.d.ts.map