@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/document-notify.d.ts

@@ -0,0 +1,228 @@
+/**
+ * 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 type { DocumentStore } from "./document-store.js";
+import type { Logger } from "./types.js";
+/**
+ * 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 declare const DIFFABLE_DOCUMENT_TYPES: readonly string[];
+export type DiffableDocumentType = string;
+export interface DocumentNotice {
+    documentId: string;
+    pending: number;
+    noticedAtMs: number;
+}
+export interface DiffStats {
+    documentId: string;
+    linesAdded: number;
+    linesRemoved: number;
+    /** 1-based inclusive line ranges the change touches. Ranges, never the lines themselves. */
+    ranges: Array<{
+        start: number;
+        end: number;
+    }>;
+    /** For JSON: the key paths touched. Empty for line-oriented types. */
+    keyPaths: string[];
+    /**
+     * Whether the peer's change touches a region this operator also edited. The one field here that
+     * is a judgement rather than a count, and the reason an agent reads stats before deciding.
+     */
+    overlap: boolean | null;
+    /** Whether `keyPaths` was computed at all — an empty list is otherwise read as "none changed". */
+    keyPathsComputed: boolean;
+    /** The document exceeded the LCS limit, so the numbers above are bounds, not a measurement. */
+    truncated: boolean;
+}
+export type DiffResult = {
+    ok: true;
+    documentType: DiffableDocumentType;
+    diff: string;
+    /**
+     * Set when the renderer could not do what the type asked for. A notice inside the diff STRING
+     * is readable by a human and invisible to a caller branching on the result — and it travels
+     * as screened content, which is the wrong channel for a fact about the renderer.
+     */
+    fallback?: "unparseable_json_line_diff";
+} | {
+    ok: false;
+    reason: string;
+    detail: string;
+};
+export declare class DocumentNotifications {
+    #private;
+    constructor(store: DocumentStore, logger: Logger);
+    /**
+     * 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: string, documentId: string, text: string, nowMs: number): void;
+    /**
+     * 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: string, documentId: string): string[];
+    /**
+     * The paths this agent has asked to be nudged about, for one document. Empty means none — never
+     * "all"; see `matchWatchedPaths`.
+     */
+    watches(agentId: string, documentId: string): string[];
+    /** Replace the watch list. An empty list REMOVES the row, so "watching nothing" holds no state. */
+    setWatches(agentId: string, documentId: string, paths: readonly string[]): void;
+    /** Every document this agent is watching, for the surface that lists them. */
+    allWatches(agentId: string): Array<{
+        documentId: string;
+        paths: string[];
+    }>;
+    /**
+     * 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: string, documentId: string): boolean;
+    /** Record that a nudge fired, so it does not fire again until the next read. */
+    markNudged(agentId: string, documentId: string, nowMs: number): void;
+    markWritten(agentId: string, documentId: string, text: string): void;
+    /**
+     * 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: string, documentId: string): number[] | null;
+    /**
+     * 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: string, documentId: string): string | null;
+    /**
+     * 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: string, documentId: string): number;
+    /**
+     * 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: string, documentId: string, pending: number, nowMs: number): void;
+    /** The derived inbox section. Read-only — fetching is what clears, and that is explicit. */
+    pending(agentId: string): DocumentNotice[];
+    /**
+     * 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: string, documentId: string): boolean;
+    /**
+     * 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: string, before: string, after: string, 
+    /**
+     * 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: readonly number[] | null, documentType?: string): DiffStats;
+    /**
+     * 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: string, before: string, after: string, documentId: string): DiffResult;
+}
+/** 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 declare function changedKeyPaths(before: string, after: string): string[] | null;
+//# sourceMappingURL=document-notify.d.ts.map

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

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