@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/transcription-worker.ts

@@ -25,8 +25,11 @@
  *    (Whisper API shape). Response is `{ text: string }`.
  * 3. On success:
  *    - If `note.metadata.transcribe_stub === true`, replace the
- *      `_Transcript pending._` placeholder with the transcript, or the
- *      whole note body if the placeholder is absent. Clear the stub marker.
+ *      `_Transcript pending._` placeholder (or a prior `_Transcription
+ *      unavailable._` failure marker, on a retry) with the transcript. If
+ *      neither marker is present (user edited the note while pending),
+ *      APPEND the transcript rather than overwriting the body. Clear the
+ *      stub marker.
  *    - Mark `attachment.metadata.transcribe_status = "done"` and record
  *      `transcript` + `transcribe_done_at`.
  *    - If the vault's `audio_retention` is `"until_transcribed"`, unlink
@@ -50,13 +53,13 @@
 
 import { join, normalize } from "path";
 import { existsSync, readFileSync, unlinkSync } from "fs";
-import type { Store, Attachment } from "../core/src/types.ts";
+import type { Store, Attachment, Note } from "../core/src/types.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
 import { appendContextPart, fetchContextEntries, type ContextPayload } from "./context.ts";
 import type { TriggerIncludeContext } from "./config.ts";
 import { upsertTranscriptNote } from "./transcript-note.ts";
 
-/** Placeholder pattern written by Lens's voice-memo stub. */
+/** Placeholder pattern written by the voice-memo capture stub. */
 const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
 
 /**
@@ -65,9 +68,33 @@ const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
  * Lens's now-removed scribe client; owning it here means a failed upload
  * stops reading "Transcript pending" forever regardless of which client
  * uploaded the audio.
+ *
+ * NOTE: the notes-ui status chip (parachute-surface TranscriptionStatus.tsx)
+ * keys off this exact string, so don't change the copy without a coordinated
+ * change there. A friendlier "retry available" copy + chip affordance is a
+ * tracked parachute-surface follow-up.
  */
 const TRANSCRIPT_UNAVAILABLE = "_Transcription unavailable._";
 
+/**
+ * On a successful (re)transcription of a legacy in-body memo, the transcript
+ * replaces whichever marker is currently in the body — the original
+ * `_Transcript pending._` on a first-try success, OR `_Transcription
+ * unavailable._` if a prior attempt failed and we're now retrying. Matching
+ * both means a retried success lands in the same spot a first-try success
+ * would, preserving the surrounding capture body (the `![[memo]]` embed,
+ * the `_Recorded …_` line, the header).
+ *
+ * Deliberately NO `/g` flag — `.replace` swaps only the FIRST match. A
+ * canonical capture body holds exactly one marker, so first-match is the
+ * correct target. `applyFailureMarker`'s includes-guard (no-op when the
+ * marker is already present) prevents markers accumulating across repeated
+ * terminal failures, so the body never carries two of the same marker. A
+ * hand-edited body that somehow contains both markers patches only the
+ * first — accepted (degenerate, operator-induced).
+ */
+const TRANSCRIPT_SUCCESS_TARGET = /_Transcript pending\._|_Transcription unavailable\._/;
+
 /**
  * Default sweep cadence (ms). The sweep is the safety net for backoff-
  * queued items, items that arrived while the server was down, or dispatches
@@ -202,6 +229,100 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
    */
   const inFlightAttachments = new Set<string>();
 
+  /**
+   * Apply a surgical note transform under optimistic concurrency (vault#435).
+   *
+   * The worker's marker/transcript writes are read-modify-write cycles
+   * (`getNote` → transform → `updateNote`). Without a precondition, a user
+   * edit landing between the read and the write is silently clobbered —
+   * the same static-write/stale-read class as vault#208.
+   *
+   * `transform(note)` returns the surgical update to apply (`content` and/or
+   * `metadata`), or `null` when the fresh state means there's nothing to do
+   * (e.g. the stub was cleared, or the marker is already present — the
+   * idempotency guards from #434 live inside the transform, so they re-run
+   * against whatever we re-read). The transform MUST be pure w.r.t. the note
+   * it's handed — it's invoked once per read, and re-invoked on the fresh
+   * read after a conflict.
+   *
+   * Policy on conflict (worker = resilient, never crash the sweep):
+   *   1. First write conflicts → re-read, re-run the transform against fresh
+   *      content, write with the fresh precondition.
+   *   2. Second write also conflicts → fall back to a precondition-less write
+   *      ONLY when `safeWithoutPrecondition(freshNote)` says the transform is
+   *      still safe against the latest content (e.g. the surgical-replace
+   *      target is still present, or an append is always-safe). Otherwise
+   *      skip + log — better to leave the note as the user last left it than
+   *      to blind-overwrite a third concurrent edit.
+   *
+   * All errors are logged + swallowed: a note-write failure must not mask the
+   * attachment-level result we already recorded, nor crash the sweep.
+   */
+  async function applyNoteTransformWithOC(
+    store: Store,
+    noteId: string,
+    op: string,
+    transform: (note: Note) => { content?: string; metadata?: Record<string, unknown> } | null,
+    safeWithoutPrecondition: (note: Note) => boolean,
+  ): Promise<void> {
+    try {
+      const note = await store.getNote(noteId);
+      if (!note) return;
+      const update = transform(note);
+      if (update === null) return;
+
+      try {
+        await store.updateNote(note.id, {
+          ...update,
+          skipUpdatedAt: true,
+          if_updated_at: note.updatedAt,
+        });
+        return;
+      } catch (err: any) {
+        if (!err || err.code !== "CONFLICT") throw err;
+      }
+
+      // Conflict — a user edit landed between read and write. Re-read,
+      // re-apply the same surgical transform against the fresh content, and
+      // write with the fresh precondition.
+      const fresh = await store.getNote(noteId);
+      if (!fresh) return;
+      const reUpdate = transform(fresh);
+      if (reUpdate === null) return;
+
+      try {
+        await store.updateNote(fresh.id, {
+          ...reUpdate,
+          skipUpdatedAt: true,
+          if_updated_at: fresh.updatedAt,
+        });
+        return;
+      } catch (err: any) {
+        if (!err || err.code !== "CONFLICT") throw err;
+      }
+
+      // Double conflict (a third edit raced the retry). Last resort: apply
+      // without a precondition ONLY if the transform is still safe against
+      // the latest content. Otherwise skip — don't clobber the user.
+      const latest = await store.getNote(noteId);
+      if (!latest) return;
+      if (!safeWithoutPrecondition(latest)) {
+        logger.error(
+          `[transcribe] ${op}: note ${noteId} kept changing under us (double conflict); skipping to avoid clobbering a concurrent edit`,
+        );
+        return;
+      }
+      const finalUpdate = transform(latest);
+      if (finalUpdate === null) return;
+      await store.updateNote(latest.id, {
+        ...finalUpdate,
+        skipUpdatedAt: true,
+      });
+    } catch (err) {
+      logger.error(`[transcribe] ${op}: failed to apply to note ${noteId}:`, err);
+    }
+  }
+
   async function processOne(vault: string, attachment: Attachment): Promise<void> {
     // Dedupe: another path (sweep vs hook kick, or a duplicate dispatch)
     // is already working this attachment. Drop — its result is durable
@@ -217,33 +338,58 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
 
   /**
    * On a terminal failure (maxAttempts exhausted, or audio file missing),
-   * swap the stub placeholder for the "unavailable" marker — otherwise
-   * Lens's voice memo sits reading "Transcript pending" forever. Mirrors
-   * the success-path note write in shape: only touches the note when
+   * record the "unavailable" marker on the note — otherwise the voice memo
+   * sits reading "Transcript pending" forever. Only touches the note when
    * `transcribe_stub === true`, clears the stub marker, uses `skipUpdatedAt`
    * so the note's modification time still reflects user intent. Errors
    * are logged and swallowed so a note-write failure doesn't mask the
    * attachment failure we're trying to record.
+   *
+   * Body policy (finding F — never destroy content):
+   *   - Placeholder PRESENT → surgical replace of `_Transcript pending._`
+   *     with the marker. The `![[memo]]` embed + any surrounding text survive.
+   *   - Marker ALREADY PRESENT → no-op (idempotent; a double-terminal-failure
+   *     must not stack markers).
+   *   - Otherwise (placeholder absent — the user edited the note while it was
+   *     pending) → APPEND `\n\n` + marker to the existing content. The old
+   *     code full-replaced the body here, destroying the embed AND the user's
+   *     edits. We append instead so nothing is lost. If the content is empty,
+   *     the marker alone becomes the body (avoids a leading blank line).
    */
   async function applyFailureMarker(store: Store, noteId: string): Promise<void> {
-    const note = await store.getNote(noteId);
-    if (!note) return;
-    const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
-    if (noteMeta.transcribe_stub !== true) return;
-
-    const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
-      ? note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE)
-      : TRANSCRIPT_UNAVAILABLE;
-    const { transcribe_stub: _drop, ...restMeta } = noteMeta;
-    try {
-      await store.updateNote(note.id, {
-        content: body,
-        metadata: restMeta,
-        skipUpdatedAt: true,
-      });
-    } catch (err) {
-      logger.error(`[transcribe] failed to apply failure marker to note ${note.id}:`, err);
-    }
+    // OC-guarded (vault#435): the read-transform-write below is re-run against
+    // fresh content on a conflict so a concurrent user edit isn't clobbered.
+    // The transform is pure w.r.t. the note it's handed; the stub-set and
+    // marker-already-present idempotency guards re-evaluate on the re-read.
+    await applyNoteTransformWithOC(
+      store,
+      noteId,
+      "apply-failure-marker",
+      (note) => {
+        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+        if (noteMeta.transcribe_stub !== true) return null;
+
+        let body: string;
+        if (TRANSCRIPT_PLACEHOLDER.test(note.content)) {
+          body = note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE);
+        } else if (note.content.includes(TRANSCRIPT_UNAVAILABLE)) {
+          // Marker already present — nothing to do. Clear the stub and
+          // return without rewriting the body so we don't stack markers.
+          body = note.content;
+        } else {
+          body = note.content.length > 0
+            ? `${note.content}\n\n${TRANSCRIPT_UNAVAILABLE}`
+            : TRANSCRIPT_UNAVAILABLE;
+        }
+        const { transcribe_stub: _drop, ...restMeta } = noteMeta;
+        return { content: body, metadata: restMeta };
+      },
+      // Last-resort (double-conflict) safety: only blind-write while the note
+      // still carries the stub opt-in. If a racing edit cleared it, the user
+      // opted out — skip rather than re-stamp the marker. The body transform
+      // itself is non-destructive (surgical replace / no-op / append).
+      (note) => ((note.metadata as Record<string, unknown> | undefined)?.transcribe_stub === true),
+    );
   }
 
   /**
@@ -411,26 +557,48 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         logger.error(`[transcribe] failed to write transcript note for attachment ${attachment.id}:`, err);
       }
     } else {
-      // Legacy stub-patching path (Lens voice memo flow).
-      const note = await store.getNote(attachment.noteId);
-      if (note) {
-        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
-        if (noteMeta.transcribe_stub === true) {
-          const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
-            ? note.content.replace(TRANSCRIPT_PLACEHOLDER, transcript)
-            : transcript;
-          const { transcribe_stub: _drop, ...restMeta } = noteMeta;
-          try {
-            await store.updateNote(note.id, {
-              content: body,
-              metadata: restMeta,
-              skipUpdatedAt: true,
-            });
-          } catch (err) {
-            logger.error(`[transcribe] failed to apply transcript to note ${note.id}:`, err);
+      // Legacy stub-patching path (voice memo flow). Only acts when the note
+      // still carries the `transcribe_stub` opt-in — a user edit clearing it
+      // before the transcript arrives opts out of the overwrite. OC-guarded
+      // (vault#435): re-applied against fresh content on a conflict so a
+      // concurrent user edit isn't clobbered.
+      await applyNoteTransformWithOC(
+        store,
+        attachment.noteId,
+        "apply-transcript",
+        (note) => {
+          const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+          if (noteMeta.transcribe_stub !== true) return null;
+          // Body policy (finding F — never destroy content):
+          //   - placeholder OR failure-marker present → surgical replace in
+          //     place (a retried success replaces the `_Transcription
+          //     unavailable._` marker, landing exactly where a first-try
+          //     success would). The embed + surrounding capture body survive.
+          //   - neither present (user edited the note while pending) → APPEND
+          //     the transcript instead of full-replacing the body, so the
+          //     user's edits + the `![[memo]]` embed are preserved. The old
+          //     code full-replaced here, which destroyed both.
+          let body: string;
+          if (TRANSCRIPT_SUCCESS_TARGET.test(note.content)) {
+            // Function replacer, NOT a string — speech-to-text is arbitrary
+            // user content, and String.replace treats `$&`, `$\``, `$'`,
+            // `$1`-`$9` as special patterns in a string replacement. A
+            // transcript containing `$&` would otherwise inject the matched
+            // marker text into the body. `() => transcript` returns the text
+            // verbatim.
+            body = note.content.replace(TRANSCRIPT_SUCCESS_TARGET, () => transcript);
+          } else {
+            body = note.content.length > 0
+              ? `${note.content}\n\n${transcript}`
+              : transcript;
           }
-        }
-      }
+          const { transcribe_stub: _drop, ...restMeta } = noteMeta;
+          return { content: body, metadata: restMeta };
+        },
+        // Last-resort (double-conflict) safety: only blind-write while the
+        // stub opt-in survives. A racing edit that cleared it opts out.
+        (note) => ((note.metadata as Record<string, unknown> | undefined)?.transcribe_stub === true),
+      );
     }
 
     // Always record the transcript on the attachment, even if the note