@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/document-notify.d.ts

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

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