@north-light/api 0.3.580 → 0.3.587

package/dist/core/providers/token-cache.d.ts

@@ -0,0 +1,54 @@
+import type { GrantRecord } from '../grants/mirror.js';
+/** A token is reused only while `now < exp − REUSE_MARGIN_S`. */
+export declare const REUSE_MARGIN_S = 30;
+/** What a mint is for; also the cache key's parts. */
+export interface OutboundTokenRequest {
+    /** The provider's registered endpoint URL (the token's `aud`). */
+    audience: string;
+    sub: string;
+    grantee: string;
+    initiating_app: string;
+    /** `<provider>:<group>` strings; order does not matter. */
+    scope: readonly string[];
+}
+/** A minted token. `exp` is epoch seconds (the JWT's own claim). `payer` is the principal the directory
+ *  charges for calls under it (its `payer` claim; `sub` when the claim is absent). */
+export interface CachedToken {
+    access_token: string;
+    jti: string;
+    exp: number;
+    payer: string;
+}
+export declare function tokenCacheDir(): string;
+/** JSON of `[aud, sub, grantee, initiating_app, sorted scopes]`. */
+export declare function cacheKey(request: OutboundTokenRequest): string;
+/** The cached token for `key` while it is still reusable, else null (a stale or unreadable file is removed). */
+export declare function cachedToken(key: string, nowMs?: number): CachedToken | null;
+/** The discard epoch of the pair and providers a key names (it only ever grows); pass it back to `storeToken`. */
+export declare function discardEpoch(key: string): number;
+/** Store a freshly minted token, unless its pair was discarded since `epoch` was read. Returns whether it was stored. */
+export declare function storeToken(key: string, token: CachedToken, epoch?: number): boolean;
+/** Discard the one token for `key` (a provider answered 401, D3-TOK-18). */
+export declare function discardFile(key: string): void;
+/** Discard every cached token for (`sub`, `grantee`). Returns how many went. */
+export declare function discardFor(sub: string, grantee: string, nowMs?: number): number;
+/** The grant-change hook (D3-TOK-20, CRD-16), called with the re-read state of one grant whose row changed: discard every cached
+ *  token of its (`sub`, `grantee`), every token of `sub` naming a provider that no active grant of `sub` (`subGrants`, all of
+ *  them) resolves, and, when the changed grant is a connection grant (`app:<provider>`) that is not active, every token of `sub`
+ *  naming that provider whatever its grantee — a person's own calls mint as (`sub`, `sub`), a pair a connection grant never names.
+ *  It is idempotent, so a repeated or replayed notification discards nothing more. */
+export declare function discardTokensForGrant(changed: {
+    sub: string;
+    grantee: string;
+    active: boolean;
+}, subGrants: readonly GrantRecord[], nowMs?: number): {
+    pairs: number;
+    providers: number;
+    tokens: number;
+};
+/** The catch-up form of `discardTokensForGrant`, for a changed grant whose row is gone (its `sub` and `grantee` unknown) and for
+ *  the pass after the listen connection restarted: discard every token of an `app:` (`sub`, `grantee`) with no active grant, and
+ *  every token naming a provider that no active grant of its `sub` resolves and that is not a connected `app:<provider>`. */
+export declare function discardOrphanedTokens(grants: readonly GrantRecord[], nowMs?: number): {
+    tokens: number;
+};

package/dist/core/providers/token-cache.js

@@ -0,0 +1,203 @@
+// The daemon's outbound provider token cache (contract 3 "Outbound token",
+// "Cache"; D3-TOK-9, D3-TOK-20, CRD-15).
+//
+// One token per (audience, `sub`, `grantee`, `initiating_app`, scope set), kept
+// in the runtime's secrets directory — only the daemon's code reads it; a
+// token never reaches a broker process (D3-TOK-15). A token is reused until 30
+// seconds before its `exp`. Tokens are discarded on a provider 401
+// (`discardFile`, R4) and, whenever a grant row changes (`discardTokensForGrant`,
+// called by the `grant-effects` handler of every process), by two rules:
+//   - pair: every token of the changed grant's (`sub`, `grantee`).
+//   - provider: for each provider that `sub` has a token for and no active
+//     grant of `sub` resolves any more, or whose connection grant (`sub`
+//     to `app:<provider>`) is not active, every token of `sub` — whatever
+//     its grantee — whose scope names that provider. A person's own calls mint
+//     as (`sub`, `sub`), a pair the connection grant's change never names, so
+//     this rule is what keeps a disconnect from leaving a token that still
+//     reaches the provider's server.
+//
+// This module does no network I/O and imports nothing from the mint, so the
+// grant-sync hook can use it without an import cycle.
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../canvas/paths.js';
+import { atomicWriteJson } from '../fs-utils.js';
+/** A token is reused only while `now < exp − REUSE_MARGIN_S`. */
+export const REUSE_MARGIN_S = 30;
+export function tokenCacheDir() {
+    return join(crtrHome(), 'secrets', 'outbound-tokens');
+}
+/** JSON of `[aud, sub, grantee, initiating_app, sorted scopes]`. */
+export function cacheKey(request) {
+    return JSON.stringify([request.audience, request.sub, request.grantee, request.initiating_app, [...new Set(request.scope)].sort()]);
+}
+function fileFor(key) {
+    return join(tokenCacheDir(), `${createHash('sha256').update(key).digest('hex')}.json`);
+}
+function partsOf(key) {
+    try {
+        const parts = JSON.parse(key);
+        if (!Array.isArray(parts) || typeof parts[1] !== 'string' || typeof parts[2] !== 'string')
+            return null;
+        const scopes = Array.isArray(parts[4]) ? parts[4] : [];
+        const providers = scopes.flatMap((scope) => typeof scope === 'string' ? [providerOf(scope)] : []).filter((id) => id !== null);
+        return { sub: parts[1], grantee: parts[2], providers: [...new Set(providers)] };
+    }
+    catch {
+        return null;
+    }
+}
+function pairKey(sub, grantee) { return JSON.stringify([sub, grantee]); }
+function providerKey(sub, provider) { return JSON.stringify([sub, provider]); }
+/** The provider a `<provider>:<group>` scope string names. */
+function providerOf(scope) {
+    const colon = scope.indexOf(':');
+    return colon > 0 ? scope.slice(0, colon) : null;
+}
+function readFile(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof value.key !== 'string' || typeof value.access_token !== 'string' || typeof value.jti !== 'string' || typeof value.exp !== 'number')
+            return null;
+        // A file written before the payer claim existed holds a token whose payer is its sub.
+        const payer = typeof value.payer === 'string' && value.payer ? value.payer : (partsOf(value.key)?.sub ?? '');
+        if (!payer)
+            return null;
+        return { ...value, payer };
+    }
+    catch {
+        return null;
+    }
+}
+function usable(token, nowMs) {
+    return nowMs < (token.exp - REUSE_MARGIN_S) * 1000;
+}
+/** The cached token for `key` while it is still reusable, else null (a stale or unreadable file is removed). */
+export function cachedToken(key, nowMs = Date.now()) {
+    const path = fileFor(key);
+    const file = readFile(path);
+    if (!file || file.key !== key || !usable(file, nowMs)) {
+        rmSync(path, { force: true });
+        return null;
+    }
+    return { access_token: file.access_token, jti: file.jti, exp: file.exp, payer: file.payer };
+}
+// A discard for a (`sub`, `grantee`) bumps its epoch. A mint that started
+// before the discard does not store its token, so no token requested before a
+// grant sync outlives the sync that discarded the pair (D3-TOK-20). A discard
+// of a (`sub`, provider) bumps the epoch of every key of that `sub` that names
+// the provider, whatever its grantee. A mint in flight has no file to find, so a grant change of a `sub` bumps that `sub`'s
+// epoch too: a mint that began before it stores nothing, and the next call mints again.
+const discardEpochs = new Map();
+const subEpochs = new Map();
+/** The discard epoch of the pair and providers a key names (it only ever grows); pass it back to `storeToken`. */
+export function discardEpoch(key) {
+    const parts = partsOf(key);
+    if (parts === null)
+        return 0;
+    return (discardEpochs.get(pairKey(parts.sub, parts.grantee)) ?? 0) + (subEpochs.get(parts.sub) ?? 0);
+}
+/** Store a freshly minted token, unless its pair was discarded since `epoch` was read. Returns whether it was stored. */
+export function storeToken(key, token, epoch = discardEpoch(key)) {
+    if (discardEpoch(key) !== epoch)
+        return false;
+    mkdirSync(tokenCacheDir(), { recursive: true, mode: 0o700 });
+    atomicWriteJson(fileFor(key), { key, ...token }, { mode: 0o600 });
+    return true;
+}
+/** Discard the one token for `key` (a provider answered 401, D3-TOK-18). */
+export function discardFile(key) {
+    rmSync(fileFor(key), { force: true });
+}
+/** One pass over the cache: remove every file `matches` names, every expired file, and every unreadable file. Returns how many
+ *  matching tokens went. */
+function sweep(matches, nowMs) {
+    let names;
+    try {
+        names = readdirSync(tokenCacheDir());
+    }
+    catch {
+        return 0;
+    }
+    let discarded = 0;
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const path = join(tokenCacheDir(), name);
+        const file = readFile(path);
+        const parts = file ? partsOf(file.key) : null;
+        if (file && parts !== null && matches(parts)) {
+            rmSync(path, { force: true });
+            discarded++;
+        }
+        else if (!file || nowMs >= file.exp * 1000)
+            rmSync(path, { force: true });
+    }
+    return discarded;
+}
+/** Discard every cached token for (`sub`, `grantee`). Returns how many went. */
+export function discardFor(sub, grantee, nowMs = Date.now()) {
+    const pair = pairKey(sub, grantee);
+    discardEpochs.set(pair, (discardEpochs.get(pair) ?? 0) + 1);
+    return sweep((parts) => parts.sub === sub && parts.grantee === grantee, nowMs);
+}
+/** Every provider `<provider>:<group>` scope an active grant of `grants` resolves, in either mode. */
+function resolvedProviders(grants) {
+    const resolved = new Set();
+    for (const grant of grants) {
+        if (grant.status !== 'active')
+            continue;
+        for (const { scope } of grant.resolved_scopes) {
+            const provider = providerOf(scope);
+            if (provider !== null)
+                resolved.add(provider);
+        }
+    }
+    return resolved;
+}
+/** The grant-change hook (D3-TOK-20, CRD-16), called with the re-read state of one grant whose row changed: discard every cached
+ *  token of its (`sub`, `grantee`), every token of `sub` naming a provider that no active grant of `sub` (`subGrants`, all of
+ *  them) resolves, and, when the changed grant is a connection grant (`app:<provider>`) that is not active, every token of `sub`
+ *  naming that provider whatever its grantee — a person's own calls mint as (`sub`, `sub`), a pair a connection grant never names.
+ *  It is idempotent, so a repeated or replayed notification discards nothing more. */
+export function discardTokensForGrant(changed, subGrants, nowMs = Date.now()) {
+    const resolved = resolvedProviders(subGrants.filter((grant) => grant.sub === changed.sub));
+    const connection = changed.grantee.startsWith('app:') && !changed.active ? changed.grantee.slice('app:'.length) : null;
+    const unserved = (provider) => !resolved.has(provider) || provider === connection;
+    const pair = pairKey(changed.sub, changed.grantee);
+    discardEpochs.set(pair, (discardEpochs.get(pair) ?? 0) + 1);
+    subEpochs.set(changed.sub, (subEpochs.get(changed.sub) ?? 0) + 1);
+    const providers = new Set();
+    const tokens = sweep((parts) => {
+        if (parts.sub !== changed.sub)
+            return false;
+        const dropped = parts.providers.filter(unserved);
+        for (const provider of dropped)
+            providers.add(provider);
+        return parts.grantee === changed.grantee || dropped.length > 0;
+    }, nowMs);
+    return { pairs: 1, providers: providers.size, tokens };
+}
+/** The catch-up form of `discardTokensForGrant`, for a changed grant whose row is gone (its `sub` and `grantee` unknown) and for
+ *  the pass after the listen connection restarted: discard every token of an `app:` (`sub`, `grantee`) with no active grant, and
+ *  every token naming a provider that no active grant of its `sub` resolves and that is not a connected `app:<provider>`. */
+export function discardOrphanedTokens(grants, nowMs = Date.now()) {
+    const activeGrants = grants.filter((grant) => grant.status === 'active');
+    const pairs = new Set(activeGrants.map((grant) => pairKey(grant.sub, grant.grantee)));
+    const resolvedFor = new Set(activeGrants.flatMap((grant) => grant.resolved_scopes.flatMap(({ scope }) => {
+        const provider = providerOf(scope);
+        return provider === null ? [] : [providerKey(grant.sub, provider)];
+    })));
+    const subs = new Set();
+    const tokens = sweep((parts) => {
+        const orphanPair = parts.grantee.startsWith('app:') && !pairs.has(pairKey(parts.sub, parts.grantee));
+        const dropped = parts.providers.some((provider) => !resolvedFor.has(providerKey(parts.sub, provider)));
+        if (orphanPair || dropped)
+            subs.add(parts.sub);
+        return orphanPair || dropped;
+    }, nowMs);
+    for (const sub of subs)
+        subEpochs.set(sub, (subEpochs.get(sub) ?? 0) + 1);
+    return { tokens };
+}

package/dist/core/remote-canvas-target.d.ts

@@ -0,0 +1,4 @@
+import type { Scope, RemoteCanvasTarget } from '../types.js';
+import type { RelayTarget } from './broker-client/index.js';
+export declare function getRemoteCanvasTarget(name: string, scope?: Scope): RemoteCanvasTarget | undefined;
+export declare function resolveRemoteCanvasTarget(name: string, scope?: Scope): RelayTarget;

package/dist/core/remote-canvas-target.js

@@ -0,0 +1,30 @@
+// remote-target.ts — resolves a named `remoteCanvas.targets.<name>`
+// config entry (see `RemoteCanvasTarget`, `src/types.ts`) into a `RelayTarget`
+// ready for `RelayTransport` (`src/core/broker-client/transport-relay.ts`).
+//
+// The raw bearer token NEVER lives in config.json — only a ref
+// (`relayTokenRef`) into the 0600 secrets store (`src/core/secrets.ts`),
+// resolved here at connect time via `getRelayToken`. Targets are registered
+// and the token stored via `crtr canvas config add` (`--relay-token -` reads
+// it from stdin, the preferred form to keep it out of shell history).
+import { usage } from './errors.js';
+import { readConfig } from './config.js';
+import { getRelayToken } from './secrets.js';
+export function getRemoteCanvasTarget(name, scope = 'user') {
+    return readConfig(scope).remoteCanvas.targets[name];
+}
+export function resolveRemoteCanvasTarget(name, scope = 'user') {
+    const cfg = readConfig(scope);
+    const target = cfg.remoteCanvas.targets[name];
+    if (target === undefined) {
+        const known = Object.keys(cfg.remoteCanvas.targets);
+        throw usage(`no remote canvas target named '${name}'` +
+            (known.length > 0 ? ` — configured: ${known.join(', ')}` : ' — none configured yet') +
+            `. Add one with \`crtr canvas config add ${name} --preview <url> --relay-token -\`.`);
+    }
+    const relayToken = getRelayToken(target.relayTokenRef, scope);
+    if (relayToken === undefined || relayToken === '') {
+        throw usage(`target '${name}' has no stored relay token — add it with \`crtr canvas config add ${name} --relay-token -\`.`);
+    }
+    return { previewEndpoint: target.previewEndpoint, relayToken };
+}

package/dist/core/review/comments.d.ts

@@ -0,0 +1,69 @@
+import { type CanvasDb } from '../canvas/db.js';
+import { type CommentAnchor, type CommentAuthorKind, type CommentStatus, type ReviewComment, type ReviewCommentEvent } from './types.js';
+interface Actor {
+    kind: CommentAuthorKind;
+    node_id: string | null;
+}
+interface CommentMutationArgs {
+    actor: Actor;
+    operation_id: string;
+    if_revision?: number;
+}
+export declare function createComment(args: {
+    review_id: string;
+    text: string;
+    anchor: CommentAnchor;
+    line_text: string;
+    doc_hash: string;
+    actor: Actor;
+    operation_id: string;
+}): Promise<{
+    comment: ReviewComment;
+    changed: true;
+}>;
+export declare function editComment(commentIdValue: string, args: {
+    text: string;
+    actor: Actor;
+    operation_id: string;
+    if_revision?: number;
+}): Promise<{
+    comment: ReviewComment;
+    changed: boolean;
+}>;
+export declare function resolveComment(commentIdValue: string, args: CommentMutationArgs): Promise<{
+    comment: ReviewComment;
+    changed: boolean;
+}>;
+export declare function reopenComment(commentIdValue: string, args: CommentMutationArgs): Promise<{
+    comment: ReviewComment;
+    changed: boolean;
+}>;
+export declare function deleteComment(commentIdValue: string, args: CommentMutationArgs): Promise<{
+    comment: ReviewComment;
+    changed: boolean;
+}>;
+export declare function listComments(reviewId: string, opts?: {
+    status?: CommentStatus | 'all';
+}): Promise<ReviewComment[]>;
+export declare function getComment(commentIdValue: string): Promise<ReviewComment | null>;
+export declare function listCommentEvents(commentIdValue: string): Promise<ReviewCommentEvent[]>;
+export declare function listReviewEvents(reviewId: string, opts: {
+    since_seq?: number;
+    limit?: number;
+}): Promise<{
+    events: ReviewCommentEvent[];
+    next_since_seq: number;
+}>;
+export declare function snapshotCommentsLocked(db: CanvasDb, reviewId: string): Promise<{
+    comments: import('../human/types.js').FeedbackComment[];
+    total: number;
+    unresolved: number;
+}>;
+export declare function appendDeliveryEvent(args: {
+    review_id: string;
+    comment_id: string;
+    kind: 'notified' | 'notify_failed';
+    payload: unknown;
+    operation_id: string;
+}): Promise<void>;
+export {};

package/dist/core/review/comments.js

@@ -0,0 +1,296 @@
+import { randomBytes } from 'node:crypto';
+import { withCanvasWrite, openDb } from '../canvas/db.js';
+import { nowIso } from '../fs-utils.js';
+import { signalReviewActivity } from './signal.js';
+import { COMMENT_EVENTS_PAGE_DEFAULT, COMMENT_EVENTS_PAGE_MAX, COMMENT_LINE_TEXT_MAX, COMMENT_TEXT_MAX, LIVE_COMMENTS_MAX, ReviewOperationError, } from './types.js';
+function commentFromRow(row) {
+    return {
+        comment_id: row.comment_id,
+        review_id: row.review_id,
+        status: row.status,
+        revision: row.revision,
+        text: row.text,
+        anchor: {
+            line: row.anchor_line,
+            end_line: row.anchor_end_line,
+            ...(row.anchor_col_start === null ? {} : { col_start: row.anchor_col_start }),
+            ...(row.anchor_col_end === null ? {} : { col_end: row.anchor_col_end }),
+            ...(row.anchor_quote === null ? {} : { quote: row.anchor_quote }),
+        },
+        anchor_state: row.anchor_state,
+        anchor_line_text: row.anchor_line_text,
+        anchor_doc_hash: row.anchor_doc_hash,
+        author: { kind: row.author_kind, node_id: row.author_node_id },
+        updated_by: { kind: row.updated_by_kind, node_id: row.updated_by_node_id },
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        resolved_at: row.resolved_at,
+        deleted_at: row.deleted_at,
+        created_seq: row.created_seq,
+    };
+}
+function eventFromRow(row) {
+    return {
+        seq: row.seq,
+        review_id: row.review_id,
+        comment_id: row.comment_id,
+        kind: row.kind,
+        state_change: row.state_change === 0 ? 0 : 1,
+        revision_after: row.revision_after,
+        actor: { kind: row.actor_kind, node_id: row.actor_node_id },
+        at: row.at,
+        operation_id: row.operation_id,
+        ...(row.payload === null ? {} : { payload: JSON.parse(row.payload) }),
+    };
+}
+function json(value) {
+    return JSON.stringify(value);
+}
+function commentId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (/^0+$/.test(id));
+    return id;
+}
+function trimText(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        throw new Error('comment text must not be empty');
+    const received = Buffer.byteLength(trimmed, 'utf8');
+    if (received > COMMENT_TEXT_MAX) {
+        throw new ReviewOperationError('text_too_long', 'comment text exceeds the maximum length', {
+            limit: COMMENT_TEXT_MAX,
+            received,
+        });
+    }
+    return trimmed;
+}
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, 'utf8') <= maxBytes)
+        return text;
+    const marker = '… [truncated]';
+    const markerBytes = Buffer.byteLength(marker, 'utf8');
+    const bytes = Buffer.from(text, 'utf8');
+    let end = Math.max(0, maxBytes - markerBytes);
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return `${bytes.subarray(0, end).toString('utf8')}${marker}`;
+}
+async function getStoredComment(db, commentIdValue) {
+    return await db.prepare('SELECT * FROM review_comments WHERE comment_id = ?').get(commentIdValue) ?? null;
+}
+async function requireStoredComment(db, commentIdValue) {
+    const row = await getStoredComment(db, commentIdValue);
+    if (row === null) {
+        throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: commentIdValue });
+    }
+    return row;
+}
+async function assertReviewExists(db, reviewId) {
+    const row = await db.prepare("SELECT request_id FROM human_requests WHERE request_id = ? AND kind = 'review' AND state = 'open'").get(reviewId);
+    if (row === undefined) {
+        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+    }
+}
+function assertRevision(row, expected) {
+    if (expected !== undefined && expected !== row.revision) {
+        throw new ReviewOperationError('stale_comment', 'comment revision is stale', {
+            revision: row.revision,
+            text: row.text,
+        });
+    }
+}
+async function appendStateEvent(db, args) {
+    const inserted = await db.prepare(`
+    INSERT INTO review_comment_events
+      (review_id, comment_id, kind, state_change, revision_after, actor_kind, actor_node_id, at, operation_id, payload)
+    VALUES (?, ?, ?, 1, ?, ?, ?, ?, ?, ?)
+    RETURNING seq
+  `).get(args.row.review_id, args.row.comment_id, args.kind, args.row.revision, args.actor.kind, args.actor.node_id, args.at, args.operation_id, json(args.payload));
+    return Number(inserted.seq);
+}
+async function updateComment(db, row, fields, actor, at) {
+    const revision = row.revision + 1;
+    await db.prepare(`
+    UPDATE review_comments
+    SET status = ?, revision = ?, text = ?, updated_by_kind = ?, updated_by_node_id = ?,
+        updated_at = ?, resolved_at = ?, deleted_at = ?
+    WHERE comment_id = ?
+  `).run(fields.status ?? row.status, revision, fields.text ?? row.text, actor.kind, actor.node_id, at, fields.resolved_at === undefined ? row.resolved_at : fields.resolved_at, fields.deleted_at === undefined ? row.deleted_at : fields.deleted_at, row.comment_id);
+    return { ...row, ...fields, revision, updated_by_kind: actor.kind, updated_by_node_id: actor.node_id, updated_at: at };
+}
+function completeMutation(result) {
+    if (result.changed)
+        signalReviewActivity();
+    return result;
+}
+export async function createComment(args) {
+    const result = await withCanvasWrite(async (db) => {
+        await assertReviewExists(db, args.review_id);
+        const live = await db.prepare("SELECT COUNT(*) AS count FROM review_comments WHERE review_id = ? AND status != 'deleted'").get(args.review_id);
+        if (Number(live.count) >= LIVE_COMMENTS_MAX) {
+            throw new ReviewOperationError('comment_limit_reached', 'review comment limit reached', {
+                limit: LIVE_COMMENTS_MAX,
+                live: Number(live.count),
+            });
+        }
+        const text = trimText(args.text);
+        const lineText = truncateUtf8(args.line_text, COMMENT_LINE_TEXT_MAX);
+        const at = nowIso();
+        let id = commentId();
+        while (await getStoredComment(db, id) !== null)
+            id = commentId();
+        const inserted = await db.prepare(`
+      INSERT INTO review_comments
+        (comment_id, review_id, status, revision, text, anchor_line, anchor_end_line,
+         anchor_col_start, anchor_col_end, anchor_quote, anchor_line_text, anchor_doc_hash, anchor_state,
+         author_kind, author_node_id, updated_by_kind, updated_by_node_id, created_at,
+         updated_at, resolved_at, deleted_at, created_seq)
+      VALUES (?, ?, 'open', 1, ?, ?, ?, ?, ?, ?, ?, ?, 'live', ?, ?, ?, ?, ?, ?, NULL, NULL, 0)
+    `).run(id, args.review_id, text, args.anchor.line, args.anchor.end_line, args.anchor.col_start ?? null, args.anchor.col_end ?? null, args.anchor.quote ?? null, lineText, args.doc_hash, args.actor.kind, args.actor.node_id, args.actor.kind, args.actor.node_id, at, at);
+        if (inserted.changes !== 1)
+            throw new Error('failed to insert review comment');
+        const row = (await getStoredComment(db, id));
+        const seq = await appendStateEvent(db, {
+            row,
+            kind: 'created',
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: { text, anchor: args.anchor, line_text: lineText, doc_hash: args.doc_hash },
+        });
+        await db.prepare('UPDATE review_comments SET created_seq = ? WHERE comment_id = ?').run(seq, id);
+        return { comment: commentFromRow({ ...row, created_seq: seq }), changed: true };
+    });
+    signalReviewActivity();
+    return result;
+}
+export async function editComment(commentIdValue, args) {
+    const result = await withCanvasWrite(async (db) => {
+        const row = await requireStoredComment(db, commentIdValue);
+        if (row.status === 'deleted')
+            throw new ReviewOperationError('comment_deleted', 'comment is a deleted tombstone', { comment_id: row.comment_id, deleted_at: row.deleted_at });
+        const text = trimText(args.text);
+        if (row.text === text)
+            return { comment: commentFromRow(row), changed: false };
+        assertRevision(row, args.if_revision);
+        const at = nowIso();
+        const previousAnchor = commentFromRow(row).anchor;
+        const updated = await updateComment(db, row, { text }, args.actor, at);
+        await appendStateEvent(db, {
+            row: updated,
+            kind: 'edited',
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: {
+                previous_text: row.text,
+                text,
+                previous_anchor: previousAnchor,
+                anchor: commentFromRow(updated).anchor,
+            },
+        });
+        return { comment: commentFromRow(updated), changed: true };
+    });
+    return completeMutation(result);
+}
+async function transitionComment(commentIdValue, args, target, kind) {
+    const result = await withCanvasWrite(async (db) => {
+        const row = await requireStoredComment(db, commentIdValue);
+        if (row.status === 'deleted') {
+            if (target === 'deleted')
+                return { comment: commentFromRow(row), changed: false };
+            throw new ReviewOperationError('comment_deleted', 'comment is a deleted tombstone', { comment_id: row.comment_id, deleted_at: row.deleted_at });
+        }
+        if (row.status === target)
+            return { comment: commentFromRow(row), changed: false };
+        assertRevision(row, args.if_revision);
+        const at = nowIso();
+        const updated = await updateComment(db, row, {
+            status: target,
+            resolved_at: target === 'resolved' ? at : target === 'open' ? null : undefined,
+            deleted_at: target === 'deleted' ? at : undefined,
+        }, args.actor, at);
+        await appendStateEvent(db, {
+            row: updated,
+            kind,
+            actor: args.actor,
+            operation_id: args.operation_id,
+            at,
+            payload: {
+                previous_status: row.status,
+                status: target,
+                previous_text: row.text,
+                text: updated.text,
+                previous_anchor: commentFromRow(row).anchor,
+                anchor: commentFromRow(updated).anchor,
+            },
+        });
+        return { comment: commentFromRow(updated), changed: true };
+    });
+    return completeMutation(result);
+}
+export async function resolveComment(commentIdValue, args) {
+    return await transitionComment(commentIdValue, args, 'resolved', 'resolved');
+}
+export async function reopenComment(commentIdValue, args) {
+    return await transitionComment(commentIdValue, args, 'open', 'reopened');
+}
+export async function deleteComment(commentIdValue, args) {
+    return await transitionComment(commentIdValue, args, 'deleted', 'deleted');
+}
+export async function listComments(reviewId, opts) {
+    const db = await openDb();
+    const status = opts?.status;
+    const rows = status === undefined
+        ? await db.prepare("SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(reviewId)
+        : status === 'all'
+            ? await db.prepare('SELECT * FROM review_comments WHERE review_id = ? ORDER BY anchor_line, created_seq').all(reviewId)
+            : await db.prepare('SELECT * FROM review_comments WHERE review_id = ? AND status = ? ORDER BY anchor_line, created_seq').all(reviewId, status);
+    return rows.map(commentFromRow);
+}
+export async function getComment(commentIdValue) {
+    const row = await getStoredComment(await openDb(), commentIdValue);
+    return row === null ? null : commentFromRow(row);
+}
+export async function listCommentEvents(commentIdValue) {
+    const rows = await (await openDb()).prepare('SELECT * FROM review_comment_events WHERE comment_id = ? ORDER BY seq').all(commentIdValue);
+    return rows.map(eventFromRow);
+}
+export async function listReviewEvents(reviewId, opts) {
+    const since = opts.since_seq ?? 0;
+    const limit = Math.min(Math.max(opts.limit ?? COMMENT_EVENTS_PAGE_DEFAULT, 1), COMMENT_EVENTS_PAGE_MAX);
+    const rows = await (await openDb()).prepare('SELECT * FROM review_comment_events WHERE review_id = ? AND seq > ? ORDER BY seq LIMIT ?').all(reviewId, since, limit);
+    const events = rows.map(eventFromRow);
+    return { events, next_since_seq: events.length === 0 ? since : events[events.length - 1].seq };
+}
+export async function snapshotCommentsLocked(db, reviewId) {
+    const rows = await db.prepare("SELECT * FROM review_comments WHERE review_id = ? AND status != 'deleted' ORDER BY anchor_line, created_seq").all(reviewId);
+    const comments = rows.map((row) => ({
+        id: row.comment_id,
+        line: row.anchor_line,
+        endLine: row.anchor_end_line,
+        ...(row.anchor_quote === null ? {} : { quote: row.anchor_quote }),
+        ...(row.anchor_col_start === null ? {} : { colStart: row.anchor_col_start }),
+        ...(row.anchor_col_end === null ? {} : { colEnd: row.anchor_col_end }),
+        lineText: row.anchor_line_text,
+        comment: row.text,
+        createdAt: row.created_at,
+    }));
+    return { comments, total: rows.length, unresolved: rows.filter((row) => row.status === 'open').length };
+}
+export async function appendDeliveryEvent(args) {
+    await withCanvasWrite(async (db) => {
+        await assertReviewExists(db, args.review_id);
+        const row = await requireStoredComment(db, args.comment_id);
+        if (row.review_id !== args.review_id)
+            throw new ReviewOperationError('unknown_comment', 'comment was not found', { received: args.comment_id });
+        await db.prepare(`
+      INSERT INTO review_comment_events
+        (review_id, comment_id, kind, state_change, revision_after, actor_kind, actor_node_id, at, operation_id, payload)
+      VALUES (?, ?, ?, 0, NULL, 'system', NULL, ?, ?, ?)
+    `).run(args.review_id, args.comment_id, args.kind, nowIso(), args.operation_id, json(args.payload));
+    });
+    signalReviewActivity();
+}