dsh-diff-approval 0.29.1 → 0.30.1

package/lib/types/comment-lines.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Where a comment's quote sits in a file's CURRENT content: the rule that turns the lines a comment
+ * was WRITTEN on into the lines it is about now.
+ *
+ * Pure and free of both Node and the DOM, so the two halves of the plugin import the very same rule:
+ * the host resolves each comment against the entry content it hangs off and ships the figures on the
+ * list read, and the browser half draws them. The panel's own row-level re-anchor
+ * (`src/client/discussion.ts`) is this same rule seen through the diff's rows — with one row per
+ * line, a removed line among them, and the quote's context taken from the rows — and it stays the
+ * browser's business: where a card is DRAWN is a layout fact. What a reader is TOLD (the list's
+ * label, the card's own chip, the jump's target line) comes from here, once, so two panes cannot
+ * name two lines for one comment.
+ *
+ * The two models can disagree in one situation, and it is worth knowing which: the host has the
+ * file's own lines, while the client's rows also carry the lines this file DELETED. A quote whose
+ * recorded `quoteContext` was captured across a deleted row therefore matches a context window the
+ * host cannot reproduce, and the host answers `undefined` where the client would re-anchor. The
+ * caller then falls back to `record.anchor` — the line the comment was written on — which is what an
+ * outdated thread shows anyway: the number stays honest rather than drifting.
+ *
+ * What the two may NOT disagree about is how far a match is allowed to be from the stored line: a
+ * look-alike elsewhere in the file is refused by both, through the one bound they share
+ * (`REANCHOR_MAX_LINES`), so the list's figure, the card's chip and the card's place cannot name two
+ * different lines for one comment.
+ * @module dsh-diff-approval/comment-lines
+ */
+/** The new-file lines one comment's quote settles on now (1-based, inclusive). */
+export interface CommentLineRange {
+    /** First new-file line the quote occupies in this content. */
+    start: number;
+    /** Last one. A one-line quote has `end === start`. */
+    end: number;
+}
+/**
+ * The record fields resolution reads: everything a re-anchor needs and nothing else.
+ *
+ * Structurally satisfied by `CommentRecord`, so a caller passes the record itself. The reader's own
+ * words, the questions asked and the timestamps play no part in where the code is.
+ */
+export interface CommentLineSource {
+    /** The lines the annotation was made on, as new-file numbers. */
+    anchor: {
+        startLine: number;
+        endLine: number;
+    };
+    /** The anchored lines as they read when the comment was written. */
+    quote: string;
+    /**
+     * `quote` with one line of context on each side, as it read then, when the record kept one. It is
+     * what tells a genuine move of the quoted code from another line elsewhere in the file that
+     * happens to read the same — without it a comment on a blank line or a closing brace followed that
+     * line wherever it appeared.
+     */
+    quoteContext?: string | undefined;
+}
+/**
+ * One file's content lines, numbered exactly as the diff numbers them.
+ *
+ * Both line endings are normalized first (`\r\n` and a lone `\r` become `\n`), and a single trailing
+ * newline is a line TERMINATOR rather than an extra empty line — the same convention the browser
+ * half's whole-file diff splits on (its `contentLines`), so line 1 here is the line the diff calls
+ * line 1 and the two cannot drift by a trailing newline.
+ *
+ * @param text - the file's content.
+ * @returns its lines, without the terminating newline; an empty file has none.
+ */
+export declare function commentFileLines(text: string): string[];
+/**
+ * How far a comment's quoted code may sit from the line the comment was written on and still count as
+ * that code having MOVED, in lines.
+ *
+ * A comment is re-anchored by its quote, and a quote is not unique: two declarations in one file can
+ * read exactly alike. The recorded context tells such places apart only as far as it reaches — one
+ * line each side — which two identically-shaped fields (`UPROPERTY` line, field, blank line) defeat
+ * completely. Distance is the other half of the answer, and the half that does not depend on what the
+ * record happened to keep: this code MOVING is a shift of a few lines, the insert or delete directly
+ * above it that every edit produces, while a match tens or hundreds of lines away is another place in
+ * the file that reads the same. The report's two cases bracket the number: the same declaration moved
+ * four lines when four lines above it were deleted, and a declaration that had been DELETED matched an
+ * identically-shaped one 74 lines below. Thirty keeps the first and refuses the second.
+ *
+ * Thirty is a screenful of code rather than a fact about the code: farther than that the reader is
+ * looking at another part of the file, and following it is a teleport rather than a correction — the
+ * comment ends up shown against code it was never written about, which is the bug this bound fixes.
+ * Any bound between the two real cases separates them; this one leaves a genuine shift of a
+ * function-sized block room to be followed, and nothing more.
+ *
+ * Both halves compare against this one number: the host in the file's own lines, the browser half in
+ * the rows of its diff model (a row is a line, or a line the file no longer has). A row distance is
+ * never smaller than the line distance it stands for, so a match the browser half refuses is one the
+ * host refused too, and the two panes cannot name a line the other will not draw.
+ */
+export declare const REANCHOR_MAX_LINES = 30;
+/**
+ * Whether a match that far from where the comment was written is that code having moved.
+ *
+ * The rule the two halves share, so neither can widen or narrow the bound on its own (see
+ * `REANCHOR_MAX_LINES` for the number and for what it separates). The bound is inclusive: at exactly
+ * the limit the code is taken to have moved.
+ *
+ * @param stored - the line (the host's content) or row (the browser half's model) the comment names.
+ * @param found - the line or row the quote was found on.
+ * @returns whether that match is close enough to be the same code.
+ */
+export declare function reanchorWithinLimit(stored: number, found: number): boolean;
+/**
+ * Where one comment's quote sits in a file's current content, or `undefined` when it is nowhere.
+ *
+ * The rule, in the order it is applied — the same order the browser half's `remapDiscussion` applies
+ * it in, so the same file and the same record produce the same number in both halves:
+ *
+ * 1. The lines the comment names have to exist in this file at all. When even the anchor's first
+ *    line is past the end, nothing here can be re-anchored: `undefined`.
+ * 2. The anchor's own line still reads the quote: the comment has not moved. The stored range is the
+ *    answer, `endLine` included — a range whose quote covers a different number of lines (a removed
+ *    row was quoted among them) still belongs to the reader's own numbers.
+ * 3. Otherwise the quote is followed: every window of as many lines as the quote has is compared to
+ *    it, the recorded context has to agree where the record carries one, and the occurrence CLOSEST
+ *    to the stored anchor wins — that is where the reader last saw the code. An equal distance keeps
+ *    the earlier occurrence, which is the first window an ascending scan meets.
+ * 4. The occurrence also has to be NEAR the stored anchor (see `REANCHOR_MAX_LINES`): a window
+ *    farther than that from the line the comment was written on is not this code having moved but
+ *    another place in the file that reads the same — however exactly its recorded context agrees.
+ * 5. Nothing matched: `undefined`. The caller falls back to `record.anchor`, the line the comment was
+ *    written on — the same answer the code view gives an outdated thread.
+ *
+ * @param text - the entry's current content (the file as it reads now).
+ * @param comment - the stored comment's anchor and quote.
+ * @returns the new-file line range the quote occupies now, or `undefined` when it is gone.
+ */
+export declare function resolveCommentLines(text: string, comment: CommentLineSource): CommentLineRange | undefined;

package/lib/types/comments.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Durable comment threads, one JSON file per session under
+ * `<commentsDir>/<sessionId>.json`, beside the pending-entry storage but never in
+ * the same file: a comment that outlived its entry is exactly the leak this
+ * module exists to prevent, so a pending write that fails must not be able to
+ * take comments with it (or the other way round).
+ *
+ * A comment belongs to ONE pending entry (`entryId`, which is the entry's path —
+ * the store's global identity) and to ONE session. It carries the annotation and
+ * the identity of the turn that answered it (`messageId`, `turn`); it does NOT
+ * carry the answer's text, because the session transcript stays the single source
+ * of truth for what the agent said — a client reads the answer out of the
+ * transcript by that id. Saves rewrite the whole session file, staged as a sibling
+ * temp file and atomically renamed, so a crash leaves either the old or the new
+ * file. A missing file reads as empty; unknown versions and non-JSON content throw.
+ * @module dsh-diff-approval/src/comments
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { CommentRecord } from './types.ts';
+/**
+ * The comment directory that belongs to a pending-storage root.
+ *
+ * The plugin's own state directory is `<dshHome>/diff-approval`, and inside it the
+ * pending file lives in `workspaces/` and comments in `comments/` — siblings, so a
+ * write that fails on one side cannot take the other with it. Any OTHER root is a
+ * self-contained state directory (a deployment's chosen location, a test's temp
+ * dir) and keeps its comments INSIDE it: the sibling of an arbitrary directory can
+ * be shared by two instances that were each pointed somewhere different, and two
+ * instances writing one comment file is a leak rather than a layout choice.
+ *
+ * @param storageRoot - the resolved pending-storage root.
+ * @returns the directory holding the comments that belong to that root.
+ */
+export declare function commentsDirFor(storageRoot: string): string;
+/**
+ * How a caller hears about the two ways a comment file can go wrong.
+ *
+ * The store reads and writes plain JSON files and owns no logger, so both halves are
+ * callbacks: the host wires them to `ctx.logger` and to the list read the panel draws,
+ * which is what turns "the write failed" from a fact only the filesystem knew into
+ * something the reader is told (and something a test can assert without a disk).
+ */
+export interface CommentStoreOptions {
+    /**
+     * One session's comments could not be read, and that file was skipped. Called once per
+     * skipped file, with the file's path, because the caller's warning has to name it.
+     */
+    onLoadSkipped?: (file: string, error: unknown) => void;
+    /**
+     * A save failed (`message` is the reason) or a session's failure cleared (`undefined`).
+     * Called only when the report CHANGES, so a writer retrying every second cannot bury
+     * the log; the same value also rides the list read as `persistError()`. One session's
+     * healthy write does not clear another's failure — see `persistError`.
+     */
+    onPersistError?: (message: string | undefined) => void;
+}
+/**
+ * File-backed comment threads, one file per session.
+ *
+ * Every mutation is applied to memory synchronously and schedules that session's
+ * file write on its own chain, so a caller removing an entry can drop its comments
+ * in the same tick as the entry itself without awaiting anything — the same
+ * fire-and-forget persistence the pending store uses.
+ */
+export declare class CommentStore {
+    private readonly root;
+    private readonly options;
+    private readonly byId;
+    private readonly tails;
+    private revision;
+    /** Files `loadAll` could not read, in the order it met them (see `skippedFiles`). */
+    private readonly skipped;
+    /**
+     * The save failure of every session that has one, keyed by that session's file and in the
+     * order the failures happened (see `persistError`). Empty while every write works.
+     */
+    private readonly persistFailures;
+    /**
+     * Sessions whose unreadable file could not even be moved aside, keyed by that file: the
+     * reason their writes are refused rather than allowed to truncate the bytes (see `save`).
+     */
+    private readonly unmovable;
+    /**
+     * @param root - directory holding one `<sessionId>.json` per session.
+     * @param options - the error seam (see {@link CommentStoreOptions}).
+     */
+    constructor(root: string, options?: CommentStoreOptions);
+    /**
+     * Load every session's comments. A malformed row is skipped rather than
+     * failing the load: one bad comment must not cost the whole workspace's
+     * comments (or the plugin's activation).
+     *
+     * A file that cannot be READ is skipped the same way, because the alternative is
+     * worse in both directions: the old all-or-nothing load threw, the caller logged
+     * once and carried on with an EMPTY store, and the next save then wrote that
+     * emptiness back over every good file. One unreadable file therefore cost every
+     * session's comments. Skipping keeps the other sessions' threads, and the skipped
+     * file is moved aside (`.corrupt`) rather than dropped: it is not deleted — the
+     * bytes may be the only copy — but it is also not left where the next save for
+     * that session would silently overwrite it, which would destroy them for good.
+     *
+     * When even that fails — the file cannot be moved aside — that session's writes are
+     * refused from then on (see `save`) rather than allowed to truncate the only copy.
+     * "Skipped but still writable" is exactly the shape that turns a read failure into
+     * data loss: the store would answer "added", write the memory-only view over bytes
+     * nobody could read, and lose what the skip had just refused to guess at.
+     * @returns how many comments were loaded.
+     */
+    loadAll(): Promise<number>;
+    /**
+     * The files a load skipped, so the caller can say what went missing instead of
+     * reporting a session whose comments silently vanished.
+     * @returns the skipped files' paths, in load order.
+     */
+    skippedFiles(): string[];
+    /**
+     * The failure the reader has to be told about, or `undefined` while every write works.
+     * This is what rides the list read so the panel can say the threads are memory-only;
+     * a later successful save retracts it, mirroring the pending half's own report.
+     *
+     * Per SESSION, not one global slot: a deployment where one session's file cannot be
+     * written and another's can is the ordinary case (a locked file, a full quota, a
+     * directory that vanished), and letting the healthy write retract the broken one's
+     * report would say the threads are safe while that session's live in memory only —
+     * the same "a failure that looks like a success" trap, one session over. A session's
+     * own success is what retracts its own entry (see `reportPersist`).
+     * @returns the most recent outstanding failure's message, or undefined.
+     */
+    persistError(): string | undefined;
+    /**
+     * Record a skipped file: keep it for the caller, name it, and move it aside so a later
+     * save for that session writes a fresh file rather than overwriting the unreadable
+     * bytes. A quarantine that itself fails is still a skip — the store must not be the
+     * reason a single bad file takes the whole load down — but that session's file is then
+     * the only copy of its threads, so its writes are refused (see `save`) instead of being
+     * allowed to truncate it.
+     * @param file - the file that could not be read.
+     * @param error - why it could not be read.
+     */
+    private skip;
+    /** One session's comments, oldest first (the order threads are read in). */
+    list(sessionId: SessionId): CommentRecord[];
+    /** A comment by id, whatever session it belongs to. */
+    get(id: string): CommentRecord | undefined;
+    /**
+     * A counter bumped on every change, so a poller can tell "nothing new" from
+     * "re-read": the list endpoint ships the session's comments anyway, and this is
+     * what says whether anything moved since the last read.
+     */
+    commentsRevision(): number;
+    /**
+     * Record one annotation.
+     *
+     * Writing a comment that is already here is the SAME comment written again — a client
+     * retrying a request whose response was dropped, or a second client sending the id it
+     * was handed — so the questions already asked in it are kept and only the annotation's
+     * own fields move. Overwriting the whole record would erase the identity of a question
+     * that is in flight, and its answer could then never be matched back to this thread;
+     * `createdAt` is kept for the same reason, since it is what a list read orders by.
+     *
+     * @param record - the comment to store.
+     * @returns the stored comment, which is the existing one when the id was already here.
+     */
+    add(record: CommentRecord): CommentRecord;
+    /**
+     * Record several annotations at once, as ONE write per affected session.
+     *
+     * This is what putting a batch of restored comments back needs and what a loop of `add` calls
+     * cannot give it: each `add` saves its session's file, so an undo that restored ten threads wrote
+     * that file ten times — ten chances for a transient failure to leave the store and the disk
+     * disagreeing about an action the reader already watched happen. The records are stored by the SAME
+     * rule as `add` (a new id verbatim, an existing one merged with its `createdAt` and its questions
+     * kept), which is what lets a restore be an ordinary write rather than a special case: a snapshot
+     * that came back as a new comment, with a fresh id and no questions, would be a look-alike of the
+     * reader's thread.
+     *
+     * A batch that carries nothing changes nothing, so a no-op restore does not rewrite a file.
+     *
+     * @param records - the comments to store, in the caller's order.
+     * @returns the stored record for each input, index-aligned: what landed, which is not always what
+     *   was handed over (a merge keeps the fields the existing comment owns). A count would drop that,
+     *   and a caller needing it would have to `get` each id back and race a later change.
+     */
+    addMany(records: readonly CommentRecord[]): CommentRecord[];
+    /**
+     * The record as the store keeps it: a new id VERBATIM, an id already here merged.
+     *
+     * The one place the merge rule lives, so `add` and `addMany` cannot drift: writing a comment that
+     * is already here is the same comment written again — a client retrying a request whose response
+     * was dropped, or a second client sending the id it was handed — so the questions already asked in
+     * it are kept and only the annotation's own fields move. Overwriting the whole record would erase
+     * the identity of a question that is in flight, and its answer could then never be matched back to
+     * this thread; `createdAt` is kept for the same reason, since it is what a list read orders by.
+     * @param record - the comment as the caller wrote it.
+     * @returns the record to store under its id.
+     */
+    private mergeOf;
+    /**
+     * Drop one comment.
+     * @param sessionId - the session the caller believes the comment belongs to.
+     * @param id - the comment to drop.
+     * @returns whether it was there (and belonged to that session).
+     */
+    remove(sessionId: SessionId, id: string): boolean;
+    /**
+     * Drop several comments of one session in ONE write.
+     *
+     * This is what a batch action needs and what a loop of `remove` calls cannot give it: each
+     * `remove` saves the session's file, so ending ten comments wrote that file ten times — ten
+     * chances for a transient failure to leave the store and the disk disagreeing about an action
+     * the reader asked for once. The save happens only when something was actually dropped, so a
+     * batch that matches nothing does not rewrite the file.
+     *
+     * An id of another session, or one that is not here at all, is skipped rather than refused:
+     * a batch is one request and the comments it names are the ones it can act on, and a comment
+     * another client already ended is the state the caller was asking for anyway.
+     *
+     * @param sessionId - the session the caller believes the comments belong to.
+     * @param ids - the comments to drop; a repeated id is one comment.
+     * @returns the ids that were dropped, in the order given.
+     */
+    removeMany(sessionId: SessionId, ids: readonly string[]): string[];
+    /**
+     * Every comment one pending entry carries, oldest first.
+     *
+     * The read half of `removeForEntry` and kept beside it, because they are two answers about the same
+     * fact: which comments an entry owns. A caller that is about to drop the entry asks this first, so
+     * the undo pair can carry them back; the two must agree on that set, or a restore would put back
+     * fewer (or more) threads than the drop took.
+     * @param entryId - the entry id (= path).
+     * @returns that entry's comments, in list order.
+     */
+    forEntry(entryId: string): CommentRecord[];
+    /**
+     * Drop every comment of one pending entry. This is what "a comment dies with
+     * its entry" means, and the entry knows nothing about comments, so the caller
+     * runs it beside the entry's own removal.
+     * @param entryId - the entry id (= path) that left the list.
+     * @returns how many comments went with it.
+     */
+    removeForEntry(entryId: string): number;
+    /**
+     * The orphan sweep: drop every comment whose entry is not in `entryIds`.
+     *
+     * The explicit `removeForEntry` is the primary path; this is the backstop that
+     * catches a comment left behind by a crash between the two writes. Run it when
+     * the store loads and on every list read, and the one race it could lose — an
+     * entry re-added after its comments were already swept — cannot happen: entries
+     * only leave through this host, so an entry absent at load time was removed
+     * while the host was running, and the sweep at load runs before anything can
+     * add it back.
+     * @param entryIds - every entry id the pending store currently holds.
+     * @returns how many orphaned comments were dropped.
+     */
+    retain(entryIds: ReadonlySet<string>): number;
+    /**
+     * Record one question asked in a thread. The answer itself is never stored, and the
+     * request id is minted by the caller before it submits, so this runs as part of the
+     * ask rather than waiting for the session to answer. A thread keeps its questions in
+     * order: the first is the annotation's own, and each follow-up appends.
+     *
+     * The reader's own words are stored WITH the question (`text`), because they exist
+     * nowhere else: the transcript holds the prompt, which is those words wrapped in the
+     * marker, the reference and the rules, and a thread that showed the prompt would show
+     * the scaffolding rather than the question.
+     *
+     * @param sessionId - the session the comment belongs to.
+     * @param id - the comment that was asked in.
+     * @param requestId - the identity the submission carries into the transcript.
+     * @param turn - the turn that claimed it, when that is already known.
+     * @param text - the reader's own words, without the prompt's wrapper.
+     * @returns whether the comment existed.
+     */
+    recordAsk(sessionId: SessionId, id: string, requestId: string, turn: number | undefined, text: string): boolean;
+    /**
+     * Record the turn that claimed one question, as the agent's inbox reported it. Two
+     * questions claimed by the same turn were answered together, which is a fact the
+     * panel can state instead of guessing from transcript positions.
+     * @param sessionId - the session the submission belongs to.
+     * @param requestId - the request identity the inbox reported back.
+     * @param turn - the turn that claimed it.
+     * @returns how many threads the patch touched.
+     */
+    recordTurnForRequest(sessionId: SessionId, requestId: string, turn: number): number;
+    /**
+     * Record that the session dropped one question before a turn claimed it: nothing is
+     * coming, and the reader is told rather than left waiting.
+     * @param sessionId - the session the submission belongs to.
+     * @param requestId - the request identity the inbox reported back.
+     * @returns how many threads the patch touched.
+     */
+    markDroppedForRequest(sessionId: SessionId, requestId: string): number;
+    /**
+     * Record that a turn is over, so the questions it claimed stop looking pending.
+     *
+     * The turn number is the only handle the stopping event carries — no message, no
+     * request id — so the questions that were claimed by that turn are the ones patched
+     * (see `recordTurnForRequest`, which wrote the number down when the inbox claimed
+     * them). A question whose turn is over and that the transcript shows no answer for
+     * was cut off; the client says so instead of waiting forever. Nothing here decides
+     * that: whether an answer exists is read from the transcript on each list read, so a
+     * turn that stopped AFTER writing its answer keeps showing the answer.
+     *
+     * @param sessionId - the session whose turn ended.
+     * @param turn - the turn that stopped.
+     * @returns how many threads the patch touched.
+     */
+    markTurnEnded(sessionId: SessionId, turn: number): number;
+    /**
+     * Apply one patch to every comment it matches, and schedule the affected sessions'
+     * writes. The one mutation seam, so no caller has to remember to bump the revision
+     * or to save: a patch that matches nothing changes nothing.
+     * @param match - which comments to patch.
+     * @param patch - the change to apply.
+     * @returns how many comments changed.
+     */
+    private patch;
+    /**
+     * Wait for every scheduled write to settle.
+     *
+     * The mutators return as soon as a change is in memory — that is what lets an
+     * entry's removal take its comments with it in the same tick — so this is how a
+     * caller that must not lose the write (a dispose path, a test asserting the file)
+     * waits for the disk.
+     * @returns resolution after every session file's write chain has drained.
+     */
+    settled(): Promise<void>;
+    /**
+     * Write one session's comments, serialized against that file's own writes.
+     *
+     * A rejected write is reported, not swallowed: the mutation already answered
+     * "added" and the panel is drawing the thread from memory, so a silent failure means
+     * the reader keeps writing into a thread that a restart will erase. The report rides
+     * the list read (`persistError`) and the caller's logger, and a later write that works
+     * retracts it the way the pending half retracts its own.
+     *
+     * A session whose file could not be read at load AND could not be moved aside is not
+     * written at all: the only copy of that session's threads is the bytes the load could
+     * not parse, and the store's memory holds just what has been added since. Writing the
+     * memory-only view would TRUNCATE that copy — turning a read failure into a permanent
+     * loss — so the save is refused and reported instead, which is what tells the reader
+     * those comments are memory-only.
+     * @param sessionId - the session whose file to rewrite.
+     */
+    private save;
+    /**
+     * Publish the write state of one session's file, once per distinct report. Kept as its own
+     * step so both the success and the failure of the chain above land in one place — the
+     * retraction is what arms a later failure to be reported again.
+     *
+     * Keyed per file, so a healthy session's write cannot retract a broken one's report (see
+     * `persistError`); the callback sees the aggregate, which is what rides the list read.
+     * @param file - the session file the write was for.
+     * @param message - the failure's text, or undefined when the write worked.
+     */
+    private reportPersist;
+}

package/lib/types/index.d.ts

@@ -35,9 +35,11 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import type { DiffApprovalOpenAction } from './types.ts';
-export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalBlockRange, DiffApprovalBlockTarget, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalRefreshOutcome, DiffApprovalRefreshValue, PendingEntry, PendingEntryKind, PendingFileDiff, } from './types.ts';
+export type { DiffApprovalActionOutcome, DiffApprovalActionValue, DiffApprovalBlockRange, DiffApprovalBlockTarget, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalRefreshOutcome, DiffApprovalRefreshValue, CommentAnchor, CommentQuoteLine, CommentRecord, DiffApprovalCommentAddValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, PendingEntry, PendingEntryKind, PendingFileDiff, } from './types.ts';
 export { PendingDiffStore } from './pending.ts';
 export { PendingPersistence, defaultStorageDir } from './persist.ts';
+export { CommentStore, commentsDirFor } from './comments.ts';
+export { CommentAsker, answerForRequest } from './comment-ask.ts';
 export { defaultOpenPath } from './open.ts';
 /** Stable Cordis plugin name. */
 export declare const name = "diff-approval";
@@ -45,7 +47,10 @@ export declare const name = "diff-approval";
  * Services required before the review surface activates. `webServer` rides with
  * `connection` (both come from the web bundle), and is named explicitly because
  * the channel's owner context must be able to resolve it — see
- * `ConnectionServiceSurface`.
+ * `ConnectionServiceSurface`. `sessionController` and `agents` are what a comment is
+ * asked through and what reports the turn that claimed it: both come from the same
+ * base composition this plugin already requires for `sessions`, so a host that could
+ * list pending changes at all has them.
  */
 export declare const inject: string[];
 /** The connection RPC channel this plugin serves. */

package/lib/types/pending.d.ts

@@ -18,6 +18,29 @@ import type { PendingEntry } from './types.ts';
  */
 export declare class PendingDiffStore {
     private readonly entries;
+    /**
+     * The content version of each entry: bumped whenever its tracked `newText` moves, and never for a
+     * change that leaves the content alone (a block keep advances `oldText` only).
+     *
+     * It is what lets derived, content-dependent state — the lines a comment's quote resolves to, read
+     * off `newText` — be cached and refreshed when the content moved rather than recomputed on every
+     * read. The versions come from one monotonic counter and are never reused, so an entry that leaves
+     * the list and comes back cannot hand back the number a stale cache was keyed to.
+     */
+    private readonly contentVersions;
+    /** The last version handed out; only ever climbs (see `contentVersions`). */
+    private contentVersionCounter;
+    /** Note that one path's tracked content moved, and give it a fresh version. */
+    private bumpContent;
+    /**
+     * The version of one path's tracked content, or 0 while it has none.
+     *
+     * Two calls that return the same number describe the same `newText`: a caller caching something
+     * derived from that content may serve its copy until the number changes.
+     * @param path - the file path (the global entry key).
+     * @returns the path's content version.
+     */
+    contentVersion(path: string): number;
     /**
      * Merge one captured operation into its file's entry. A no-op (equal before
      * and after) folds nothing.