mixdog 1.3.5 → 1.4.1

package/src/runtime/memory/lib/pg/supervisor.mjs

@@ -30,6 +30,7 @@ import {
 import { withFileLockSync } from '../../../shared/atomic-file.mjs';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
 import { envFlag } from '../../../shared/env.mjs';
+import { createSharedAbortable } from '../../../shared/abort-race.mjs';
 import { ensurePrivateRuntimeRoot, resolveRuntimeRoot } from '../../../shared/runtime-root.mjs';
 
 let _pgProc = null;
@@ -51,7 +52,7 @@ async function _getPgProc() {
 /** @type {{ port: number, pgdata: string, runtimeDir: string, proc: unknown } | null} */
 let _live = null;
 /** Dedup: one ensure coroutine at a time. */
-let _ensureInFlight = null;
+let _ensureShared = null;
 /** Per-process flag — postgresql.conf reconcile attempted once per supervisor. */
 let _v2ReconcileTried = false;
 /** Set by stopOwnedPgForShutdown: this process is exiting, no further ensure. */
@@ -542,7 +543,7 @@ async function tryReusePgInstance({ pgdata, runtimeDir, healthcheckPg, source =
   return null;
 }
 
-// ── Internal: full ensure logic (runs exclusively via _ensureInFlight) ────────
+// ── Internal: full ensure logic (runs exclusively via _ensureShared) ──────────
 
 function _pgdataDir(dataDir) {
   return join(dataDir, 'pgdata');
@@ -555,13 +556,15 @@ export function pgClusterExists(dataDir) {
   return existsSync(join(_pgdataDir(dataDir), 'PG_VERSION'));
 }
 
-async function _doEnsure(dataDir) {
+async function _doEnsure(dataDir, signal) {
   const { healthcheckPg } = await _getPgProc();
   const pgdata = _pgdataDir(dataDir);
 
   // Resolve runtimeDir via runtime-fetcher (cache-hits immediately when already downloaded).
   const { ensureRuntime } = await import('../runtime-fetcher.mjs');
-  const { runtimeDir } = await ensureRuntime(dataDir);
+  const { runtimeDir } = await ensureRuntime(dataDir, { signal });
+  // Cancelled while installing: start no cluster for callers that are gone.
+  signal.throwIfAborted();
 
   // One-shot v2 conf reconcile — idempotent. Covers attach paths (in-process
   // fast path / cross-process active-instance reuse) where startPg is never
@@ -713,10 +716,15 @@ async function _doEnsure(dataDir) {
  * Concurrent calls are deduplicated — exactly one spawn/recover sequence runs
  * at a time; additional callers await the same promise.
  *
+ * `signal` (optional) withdraws this caller: the shared ensure is cancelled
+ * (its runtime install included) only once every caller has withdrawn and
+ * none joined without a signal (createSharedAbortable).
+ *
  * @param {string} dataDir  Mixdog data directory.
+ * @param {{ signal?: AbortSignal }} [opts]
  * @returns {Promise<{ host: string, port: number, runtimeDir: string, pgdataDir: string }>}
  */
-export function ensurePgInstance(dataDir) {
+export function ensurePgInstance(dataDir, { signal = null } = {}) {
   // Once this process began stopping the cluster it owns, nothing may start
   // or re-attach one: a late connection-loss recovery would otherwise bring a
   // postmaster back up right after the stop and leave it running past exit.
@@ -727,12 +735,15 @@ export function ensurePgInstance(dataDir) {
   // in-process fast path — so this is the one place the sweep cannot be
   // skipped. Latched internally, so repeated calls schedule it only once.
   scheduleOrphanTempPostmasterSweep();
-  if (!_ensureInFlight) {
-    _ensureInFlight = _doEnsure(dataDir).finally(() => {
-      _ensureInFlight = null;
+  if (!_ensureShared) {
+    const shared = createSharedAbortable((sharedSignal) => _doEnsure(dataDir, sharedSignal), {
+      onSettled: () => {
+        if (_ensureShared === shared) _ensureShared = null;
+      },
     });
+    _ensureShared = shared;
   }
-  return _ensureInFlight;
+  return _ensureShared.join(signal);
 }
 
 /**
@@ -779,7 +790,7 @@ export async function stopPgForShutdown() {
     return;
   }
   const snap = _live;
-  _ensureInFlight = null;
+  _ensureShared = null;
   try {
     const { stopPg } = await _getPgProc();
     await stopPg({ runtimeDir: snap.runtimeDir, pgdataDir: snap.pgdata });
@@ -865,10 +876,11 @@ export async function stopOwnedPgForShutdown({ timeoutMs = 6_000 } = {}) {
   // publishes its cluster only when it settles; stopping before that would
   // miss the postmaster it is about to own. Bounded: a cold first start can
   // be a download.
-  if (_ensureInFlight) {
+  const inFlight = _ensureShared?.promise;
+  if (inFlight) {
     let timer = null;
     await Promise.race([
-      _ensureInFlight.catch(() => {}),
+      inFlight.catch(() => {}),
       new Promise((resolveWait) => {
         timer = setTimeout(resolveWait, timeoutMs);
         timer.unref?.();

package/src/runtime/memory/lib/runtime-fetcher.mjs

@@ -158,8 +158,9 @@ function runtimePaths(verDir) {
 // Download with retry
 // ---------------------------------------------------------------------------
 
-async function downloadWithRetry(url, destPath, expectedBytes) {
+async function downloadWithRetry(url, destPath, expectedBytes, signal) {
   return downloadToFileWithRetry(url, destPath, {
+    signal,
     maxBytes: expectedBytes,
     expectedBytes,
     label: 'memory runtime download',
@@ -532,11 +533,12 @@ function publishRuntimeDir(runtimeBaseDir, stagingDir, key, sha256) {
  * staging lock, ending with the stale-version GC. Returns the installed
  * runtime-{version} directory.
  */
-async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, version, pkey }) {
+async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, version, pkey, signal }) {
   // tar is only required for the download/extract path. Probe here (not at
   // ensureRuntime entry) so a machine without tar can still reuse an
   // already-extracted, sha-matching cached runtime via the fast path.
   await probeTar();
+  signal?.throwIfAborted();
 
   __mixdogMemoryLog(`[runtime-fetcher] downloading runtime ${version} for ${pkey} (~${size} bytes) …\n`);
 
@@ -566,7 +568,7 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
               `[runtime-fetcher] retrying runtime download from fallback release repo — ${candidateUrl}\n`
             );
           }
-          await downloadWithRetry(candidateUrl, tarPath, size);
+          await downloadWithRetry(candidateUrl, tarPath, size, signal);
           await verifySha256(tarPath, sha256);
           downloadOk = true;
           break;
@@ -575,9 +577,12 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
           try {
             rmSync(tarPath, { force: true });
           } catch {}
+          // A cancelled install tries no fallback repository.
+          signal?.throwIfAborted();
         }
       }
       if (!downloadOk && lastDownloadErr) throw lastDownloadErr;
+      signal?.throwIfAborted();
       await _extractRuntimeTarGz(tarPath, stagingDir, stagingDir);
     } finally {
       try {
@@ -591,6 +596,11 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
       } catch {}
       throw new Error(`[runtime-fetcher] download or verify failed for ${version}`);
     }
+    // Cancelled after the extract: drop the unpublished tree, publish nothing.
+    if (signal?.aborted) {
+      rmSync(stagingDir, { recursive: true, force: true });
+      signal.throwIfAborted();
+    }
 
     // Stamp sha256 inside staging dir.
     writeFileAtomicSync(join(stagingDir, '.version-sha256'), sha256);
@@ -615,6 +625,11 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
     gcRuntimeDir(runtimeBaseDir, key);
   } finally {
     releaseStagingLock(stagingLock);
+    // Publishing is synchronous past the last cancellation check, so an
+    // aborted signal here means nothing was published.
+    if (signal?.aborted) {
+      __mixdogMemoryLog(`[runtime-fetcher] install of ${version} cancelled; its staging was removed\n`);
+    }
   }
 
   __mixdogMemoryLog(`[runtime-fetcher] runtime ready at ${verDir}\n`);
@@ -631,7 +646,10 @@ export const _runtimeLayoutInternals = {
   runtimeInstallKey,
 };
 
-export async function ensureRuntime(dataDir) {
+/** `signal` cancels a download/install in progress: its retry waits end, its
+ *  partial files and staging lock are removed and nothing is published, so the
+ *  next call starts a fresh install. */
+export async function ensureRuntime(dataDir, { signal = null } = {}) {
   const key = resolve(dataDir);
   if (runtimeCache.has(key)) return runtimeCache.get(key);
 
@@ -655,7 +673,7 @@ export async function ensureRuntime(dataDir) {
 
   const verDir =
     cachedRuntimeDir(runtimeBaseDir, version, sha256) ??
-    (await installRuntimeVersion({ runtimeBaseDir, url, sha256, size, version, pkey }));
+    (await installRuntimeVersion({ runtimeBaseDir, url, sha256, size, version, pkey, signal }));
 
   const result = { runtimeDir: verDir, ...runtimePaths(verDir), version };
   runtimeCache.set(key, result);

package/src/runtime/office/authoring/pdf-author-action.mjs

@@ -22,12 +22,7 @@ import {
 } from '../core/office-sessions.mjs';
 import { snapshotPdf } from '../pdf/pdf-adapter.mjs';
 import { inlineOfficeAudit } from '../quality/inline-audit.mjs';
-import {
-  factsGate,
-  parseAuthoringBrief,
-  reviewBriefPromises,
-  reviewSourceGrounding,
-} from './pptx-brief.mjs';
+import { factsGate, parseAuthoringBrief, reviewBriefPromises, reviewSourceGrounding } from './pptx-brief.mjs';
 import { editsReplacedByAuthor, markAuthoredFromHtml } from './html-source-drift.mjs';
 import { hasSlideSections, htmlBriefScript, runPptxHtmlAuthoring } from './pptx-html-runner.mjs';
 import {

package/src/runtime/office/design/design-art-direction.mjs

@@ -236,34 +236,36 @@ export function resolveOfficeArtDirection(
     String(format || '').toLowerCase() === 'xlsx'
       ? DIRECTION_BLUEPRINTS.filter((blueprint) => blueprint.backgroundMode !== 'dark')
       : DIRECTION_BLUEPRINTS;
-  const candidates = blueprints.map((blueprint) => {
-    const palette = directionPalette(baseHue, blueprint);
-    const motif = rawSubject ? `${blueprint.motif} · ${rawSubject}` : blueprint.motif;
-    return {
-      id: blueprint.id,
-      label: blueprint.label,
-      rationale: `${blueprint.label} fits ${purpose} through ${blueprint.motif}.`,
-      motif,
-      palette,
-      typography: { ...blueprint.typography },
-      style: { ...blueprint.style, pageRhythm: [...blueprint.style.pageRhythm] },
-      creativeSystem: creativeSystemOf(blueprint),
-      deck: {
-        backgroundMode: blueprint.backgroundMode,
+  const candidates = blueprints
+    .map((blueprint) => {
+      const palette = directionPalette(baseHue, blueprint);
+      const motif = rawSubject ? `${blueprint.motif} · ${rawSubject}` : blueprint.motif;
+      return {
+        id: blueprint.id,
+        label: blueprint.label,
+        rationale: `${blueprint.label} fits ${purpose} through ${blueprint.motif}.`,
         motif,
-        imageTreatment: blueprint.imageTreatment,
-        layoutBias: [...blueprint.layoutBias],
-        ...creativeSystemOf(blueprint),
-      },
-      score: directionScore(blueprint, {
-        purpose,
-        expressionMode,
-        tone: String(request.tone || ''),
-        requestedId: String(requested.id || ''),
-        seed,
-      }),
-    };
-  }).sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
+        palette,
+        typography: { ...blueprint.typography },
+        style: { ...blueprint.style, pageRhythm: [...blueprint.style.pageRhythm] },
+        creativeSystem: creativeSystemOf(blueprint),
+        deck: {
+          backgroundMode: blueprint.backgroundMode,
+          motif,
+          imageTreatment: blueprint.imageTreatment,
+          layoutBias: [...blueprint.layoutBias],
+          ...creativeSystemOf(blueprint),
+        },
+        score: directionScore(blueprint, {
+          purpose,
+          expressionMode,
+          tone: String(request.tone || ''),
+          requestedId: String(requested.id || ''),
+          seed,
+        }),
+      };
+    })
+    .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
   const selected = candidates[0];
   const hasSubject = Boolean(rawSubject || requested.seed || requested.id);
   const disabled = request.artDirection === false || requested.enabled === false;

package/src/runtime/office/pdf/pdf-writer.mjs

@@ -890,7 +890,12 @@ function drawChartBlock(flow, block, following) {
       });
       flow.y -= rowH;
     });
-    page.drawLine({ start: { x: left, y: top }, end: { x: left, y: flow.y }, thickness: 0.6, color: color(flow.ink.line) });
+    page.drawLine({
+      start: { x: left, y: top },
+      end: { x: left, y: flow.y },
+      thickness: 0.6,
+      color: color(flow.ink.line),
+    });
   } else {
     const baseline = flow.y - size * 1.6 - layout.plotH;
     values.forEach((value, index) => {

package/src/runtime/office/portable/portable-snapshot-docx.mjs

@@ -12,7 +12,13 @@ import {
   xmlDecode,
 } from './portable-xml.mjs';
 import { countDocxPropertyChanges, docxRevisionTree, flattenDocxRevisions } from './docx-revisions.mjs';
-import { docxParagraphSpacing, docxRunFont, nextPageOffset, softBreakFacts, statedRunFont } from './portable-snapshot-shared.mjs';
+import {
+  docxParagraphSpacing,
+  docxRunFont,
+  nextPageOffset,
+  softBreakFacts,
+  statedRunFont,
+} from './portable-snapshot-shared.mjs';
 
 const REVISION_TYPES = Object.freeze({
   ins: 'insertion',

package/src/runtime/office/portable/portable-snapshot-shared.mjs

@@ -123,7 +123,12 @@ export function populatedCellPagination({ options, page, selectedSheets, sheets,
 
 export function statedRunFont(xml) {
   const direct = docxRunFont(xml);
-  return direct.size || direct.bold || direct.name || direct.color || direct.caps !== undefined || direct.letterSpacing !== undefined
+  return direct.size ||
+    direct.bold ||
+    direct.name ||
+    direct.color ||
+    direct.caps !== undefined ||
+    direct.letterSpacing !== undefined
     ? { font: direct }
     : {};
 }

package/src/runtime/office/quality/assurance-rendered.mjs

@@ -152,7 +152,13 @@ export async function reviewRenderedOfficePages(
     // The cover/title page is short by design, and a page followed by a deliberate forced break ends where the
     // author ended it.
     const endsBeforeForcedBreak = forcedBreaks?.has(metric.page + 1) === true;
-    if (flowing && metric.page > 1 && !endsBeforeForcedBreak && metric.page < lastPage && metric.bodyEnd < PAGE_BODY_END_MIN) {
+    if (
+      flowing &&
+      metric.page > 1 &&
+      !endsBeforeForcedBreak &&
+      metric.page < lastPage &&
+      metric.bodyEnd < PAGE_BODY_END_MIN
+    ) {
       const empty = Math.round((1 - metric.bodyEnd) * 100);
       issues.push(
         issue(
@@ -166,7 +172,8 @@ export async function reviewRenderedOfficePages(
       continue;
     }
     // A short chapter is the author's: the page ends before a forced break, or it is the last page and opens with one.
-    const deliberateShort = endsBeforeForcedBreak || (forcedBreaks?.has(metric.page) === true && metric.page >= lastPage);
+    const deliberateShort =
+      endsBeforeForcedBreak || (forcedBreaks?.has(metric.page) === true && metric.page >= lastPage);
     if (
       ['docx', 'pdf'].includes(normalized) &&
       metric.page > 1 &&

package/src/runtime/office/quality/assurance-structure-docx.mjs

@@ -12,7 +12,9 @@ function paragraphSize(paragraph) {
 }
 
 const median = (values) => {
-  const sorted = values.filter((value) => value !== '' && value !== undefined && value !== null).sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+  const sorted = values
+    .filter((value) => value !== '' && value !== undefined && value !== null)
+    .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
   return sorted.length ? sorted[Math.floor(sorted.length / 2)] : undefined;
 };
 // Automatic colour is the effective default, black.

package/src/runtime/office/quality/design-review.mjs

@@ -12,11 +12,7 @@ import {
   saturatedHueFamilies,
 } from '../design/design-discipline.mjs';
 import { authoredBackgroundLadder, isCardGridSlide, isOrnamentalStripe, slideSize } from './design-review-authored.mjs';
-import {
-  reviewBriefPromises,
-  reviewFactCoverage,
-  reviewSourceGrounding,
-} from '../authoring/pptx-brief.mjs';
+import { reviewBriefPromises, reviewFactCoverage, reviewSourceGrounding } from '../authoring/pptx-brief.mjs';
 import { isAdvisoryOfficeIssue } from './quality-pipeline.mjs';
 import { issue } from './assurance-issue.mjs';
 import { isPptxSpecimenSlide, isPptxStatementSlide } from './pptx-slide-roles.mjs';

package/src/runtime/office/quality/document-brief.mjs

@@ -1,11 +1,7 @@
 // A Word document or workbook held to its brief, as an authored deck is: every figure its words show has a fact with
 // a source, and a fact cites where a reader can open it. The brief is the deck's (`design.brief`, key: value lines);
 // the readings are the deck's own (pptx-brief.mjs), over the document's text instead of its slides.
-import {
-  parseAuthoringBrief,
-  reviewFactCoverage,
-  reviewSourceGrounding,
-} from '../authoring/pptx-brief.mjs';
+import { parseAuthoringBrief, reviewFactCoverage, reviewSourceGrounding } from '../authoring/pptx-brief.mjs';
 import { htmlBriefScript } from '../authoring/pptx-html-runner.mjs';
 
 /** The brief a docx/xlsx call names in design.brief (the HTML BRIEF's key: value lines), or null. */

package/src/runtime/office/quality/forced-break-pages.mjs

@@ -25,9 +25,7 @@ const visibleText = (html) =>
 
 // A media query list reaches the printed page unless every query is screen-only.
 const appliesToPrint = (queries) =>
-  queries
-    .split(',')
-    .some((query) => !/^\s*(?:only\s+)?screen\b/i.test(query) && !/^\s*not\s+print\b/i.test(query));
+  queries.split(',').some((query) => !/^\s*(?:only\s+)?screen\b/i.test(query) && !/^\s*not\s+print\b/i.test(query));
 
 // Style rules in source order, flattened out of @media blocks that do not apply in print.
 function cssRules(css, active, rules) {
@@ -38,7 +36,10 @@ function cssRules(css, active, rules) {
     let depth = 1;
     let close = open + 1;
     for (; close < css.length && depth > 0; close += 1) depth += css[close] === '{' ? 1 : css[close] === '}' ? -1 : 0;
-    const head = css.slice(index, open).replace(/^(?:\s*@[^{;]*;)+/, '').trim();
+    const head = css
+      .slice(index, open)
+      .replace(/^(?:\s*@[^{;]*;)+/, '')
+      .trim();
     const inner = css.slice(open + 1, close - 1);
     if (/^@media\b/i.test(head)) cssRules(inner, active && appliesToPrint(head.slice(6)), rules);
     else if (active && head && !head.startsWith('@')) rules.push({ head, body: inner });
@@ -64,7 +65,8 @@ function breakDeclaration(body, rank) {
 }
 
 const beats = (a, b) => {
-  for (let index = 0; index < a.rank.length; index += 1) if (a.rank[index] !== b.rank[index]) return a.rank[index] > b.rank[index];
+  for (let index = 0; index < a.rank.length; index += 1)
+    if (a.rank[index] !== b.rank[index]) return a.rank[index] > b.rank[index];
   return true;
 };
 
@@ -80,7 +82,8 @@ function breakSelectors(html) {
         const classes = match[3].split('.').filter(Boolean);
         const specificity = (match[2] ? 100 : 0) + classes.length * 10 + (match[1] ? 1 : 0);
         const declaration = breakDeclaration(body, [0, specificity, order]);
-        if (declaration) selectors.push({ tag: (match[1] || '').toLowerCase(), id: match[2] || '', classes, declaration });
+        if (declaration)
+          selectors.push({ tag: (match[1] || '').toLowerCase(), id: match[2] || '', classes, declaration });
       }
     }
   }

package/src/runtime/office/quality/quality-pipeline.mjs

@@ -289,7 +289,7 @@ const POLISH_GUIDANCE = Object.freeze({
   theme_background_drift:
     'Use only the ladder backgrounds (paper, paperAlt, dark, darkAlt); recolor the drifting slide.',
   theme_body_backgrounds:
-    'Advisory: body slides use several background colours; keep them to the concept\'s declared palette ladder, or declare the concept or palette in the brief when the colour fields are the design.',
+    "Advisory: body slides use several background colours; keep them to the concept's declared palette ladder, or declare the concept or palette in the brief when the colour fields are the design.",
   excessive_slide_text: "Cut the copy to the reading mode's budget (composition.md §4) or split the slide.",
   decorative_stripe: 'Remove the ornamental bar; a stripe that encodes nothing is decoration (composition.md §10).',
   // Visual critique contract (finalize).

package/src/runtime/session-search/session-search-db.mjs

@@ -6,9 +6,12 @@
  *
  * Rows are append-only: compaction may drop old messages from a session file,
  * but their search rows stay, so earlier conversation remains findable until
- * the session itself is deleted.
+ * the session itself is deleted. The one rewrite: a value marked sensitive
+ * replaces the rows that hold it (replaceSessionSearchMessages).
  */
 
+import { randomBytes } from 'node:crypto';
+
 import { ensurePgInstance, withSchemaBootstrapLock } from '../memory/lib/pg/adapter.mjs';
 import { buildFtsPrefixQuery } from '../memory/lib/memory-text-utils.mjs';
 import {
@@ -91,13 +94,9 @@ export function sessionSearchRows(sessionId, messages) {
   return rows;
 }
 
-/** Idempotent append of a transcript's searchable messages; returns the count
- *  of newly stored rows. Re-sending an already stored message is a no-op. */
-export async function appendSessionSearchMessages(sessionId, messages, { dataDir } = {}) {
-  const rows = sessionSearchRows(sessionId, messages);
+async function insertRows(queryable, rows) {
   if (rows.length === 0) return 0;
-  const db = await getDb(dataDir);
-  const result = await db.query(
+  const result = await queryable.query(
     `INSERT INTO session_search.messages (source_ref, session_id, ordinal, role, ts, content)
      SELECT * FROM unnest($1::text[], $2::text[], $3::int[], $4::text[], $5::bigint[], $6::text[])
      ON CONFLICT (source_ref) DO NOTHING`,
@@ -113,8 +112,73 @@ export async function appendSessionSearchMessages(sessionId, messages, { dataDir
   return Number(result?.rowCount) || 0;
 }
 
-export async function deleteSessionSearchMessages(sessionId, { dataDir } = {}) {
-  const db = await getDb(dataDir);
+/** Idempotent append of a transcript's searchable messages; returns the count
+ *  of newly stored rows. Re-sending an already stored message is a no-op. */
+export async function appendSessionSearchMessages(sessionId, messages, { dataDir, signal } = {}) {
+  const rows = sessionSearchRows(sessionId, messages);
+  if (rows.length === 0) return 0;
+  const db = await getDb(dataDir, { signal });
+  return insertRows(db, rows);
+}
+
+/** In one transaction: every stored row of `sessionId` whose content
+ *  `redactText` changes is deleted, the rows of the transcript as stored
+ *  (`redactedMessages`) are written, and a deleted row that is no message of
+ *  the transcript is written again with its content redacted.
+ *
+ *  A row is matched to its message by the row's own identity
+ *  (stableSessionSourceRef: role, original timestamp or else ordinal, tool
+ *  ids, content): the id `plainMessages` — the same transcript before
+ *  redaction — gives that message. Every other deleted row (its message was
+ *  compacted away, or is under an identity the transcript no longer has) has
+ *  no message to derive an identity from; its replacement gets a fresh random
+ *  id, so no two rows ever merge and no id is derived from the plaintext.
+ *  Returns the count of deleted rows.
+ *
+ *  FOR UPDATE locks only the rows that exist: a write of the same session still
+ *  in flight is not seen, so callers must not overlap it with this one
+ *  (session-search-ingest.mjs runs a session's writes one at a time). */
+export async function replaceSessionSearchMessages(
+  sessionId,
+  plainMessages,
+  redactedMessages,
+  redactText,
+  { dataDir, signal } = {}
+) {
+  const rows = sessionSearchRows(sessionId, redactedMessages);
+  const previous = new Set(sessionSearchRows(sessionId, plainMessages).map((row) => row.sourceRef));
+  const db = await getDb(dataDir, { signal });
+  return db.transaction(async (tx) => {
+    const { rows: stored } = await tx.query(
+      `SELECT source_ref, ordinal, role, ts, content FROM session_search.messages
+       WHERE session_id = $1 FOR UPDATE`,
+      [sessionId]
+    );
+    const changed = stored
+      .map((row) => ({ row, content: redactText(String(row.content)) }))
+      .filter(({ row, content }) => content !== row.content);
+    if (changed.length) {
+      await tx.query(`DELETE FROM session_search.messages WHERE source_ref = ANY($1::text[])`, [
+        changed.map(({ row }) => row.source_ref),
+      ]);
+    }
+    const kept = changed
+      .filter(({ row }) => !previous.has(row.source_ref))
+      .map(({ row, content }) => ({
+        sourceRef: `session:${sessionId}:${randomBytes(12).toString('hex')}`,
+        sessionId,
+        ordinal: Number(row.ordinal),
+        role: row.role,
+        ts: row.ts == null ? null : Number(row.ts),
+        content,
+      }));
+    await insertRows(tx, [...rows, ...kept]);
+    return changed.length;
+  });
+}
+
+export async function deleteSessionSearchMessages(sessionId, { dataDir, signal } = {}) {
+  const db = await getDb(dataDir, { signal });
   await db.query(`DELETE FROM session_search.messages WHERE session_id = $1`, [sessionId]);
   await db.query(`DELETE FROM session_search.backfill WHERE session_id = $1`, [sessionId]);
 }