@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.4

package/src/transcript-note.ts

@@ -0,0 +1,189 @@
+/**
+ * Transcript-note materialization for the vault↔scribe auto-transcribe path
+ * (vault#353, design 2026-05-21 Part 2, design question 3).
+ *
+ * When the transcription worker resolves an audio attachment, it asks this
+ * module to create (or update) a sibling `<attachment-path>.transcript.md`
+ * note. The note's frontmatter links back to the original audio attachment
+ * via `transcript_of`, lets vault graph queries surface the relation, and
+ * captures success / failure state in a single uniform shape.
+ *
+ * Design Q3's exact shape:
+ *
+ *   ---
+ *   title: Transcript of <attachment-name>
+ *   tags: [transcript, capture]
+ *   created_at: <iso>
+ *   transcript_of: <attachment-path>
+ *   transcript_status: complete | failed
+ *   transcript_provider: <name or unset>
+ *   transcript_duration_ms: <wall-clock ms>
+ *   transcript_error: <error-message — failed only>
+ *   ---
+ *
+ *   <transcript text — empty body when failed>
+ *
+ * The `transcript_status` values are uniform: `complete` for success and
+ * `failed` for any terminal failure (provider missing, scribe 5xx, timeout,
+ * etc.). The cause is in `transcript_error`. This matches the design's
+ * "same failure substrate" stance — no first-boot-specific branch, just
+ * different error strings.
+ *
+ * ## Retry semantics
+ *
+ * When the retry endpoint re-runs transcription on an already-failed
+ * transcript note, the same note is updated in place — `transcript_of`,
+ * `path`, and `id` all stay constant. Callers identify the transcript by
+ * note path (`<attachment-path>.transcript.md`) and call `upsertTranscriptNote`
+ * to overwrite. The transcript-of relation is materialized as both a
+ * frontmatter scalar AND a vault link (via `links.add` on create) so graph
+ * queries can find it without parsing frontmatter.
+ */
+
+import type { Store, Note } from "../core/src/types.ts";
+
+export type TranscriptStatus = "complete" | "failed";
+
+export interface TranscriptNoteInput {
+  /**
+   * Path of the source audio attachment (relative to the vault assets dir).
+   * Used to derive the transcript note's path and the `transcript_of`
+   * frontmatter scalar.
+   */
+  attachmentPath: string;
+  /**
+   * Attachment row id of the source audio. Stamped onto the transcript note
+   * frontmatter (`transcript_attachment_id`) so the retry endpoint can find
+   * the original audio in one DB lookup without walking links or paths.
+   */
+  attachmentId: string;
+  /**
+   * The note that owns the audio attachment. The transcript-of relation
+   * (vault link) is established to this note so graph queries can find the
+   * transcript from either side.
+   */
+  attachmentNoteId: string;
+  /** Outcome — `complete` (transcript text available) or `failed`. */
+  status: TranscriptStatus;
+  /**
+   * Transcript body. Required when `status === "complete"`; ignored otherwise.
+   * Failure transcript notes have an empty body — the error string is in
+   * frontmatter, not in the note body, so failures don't read like content.
+   */
+  text?: string;
+  /** Error cause for `status === "failed"`. Required for failed status. */
+  error?: string;
+  /** Scribe-reported provider (e.g. "groq", "whisper"). Optional. */
+  provider?: string;
+  /** Wall-clock duration of the scribe call. Optional; 0 if unknown. */
+  durationMs?: number;
+  /** Created-at override (defaults to `new Date()`). */
+  createdAt?: Date;
+}
+
+/**
+ * Compute the canonical transcript-note path for an audio attachment.
+ *
+ * Example: `inbox/Voice 2026-05-21 09-13.m4a` → `inbox/Voice 2026-05-21 09-13.m4a.transcript`
+ *
+ * The `.md` extension is implicit in the vault path normalization (paths are
+ * stored without `.md` per vault convention; on export to portable markdown,
+ * `.md` is appended).
+ */
+export function transcriptPathFor(attachmentPath: string): string {
+  return `${attachmentPath}.transcript`;
+}
+
+/**
+ * Build the body+metadata for a transcript note from the worker's input.
+ * Pure — no Store calls — so unit tests can assert shape without a DB.
+ * Exposed for tests and for any future caller that wants to materialize a
+ * transcript note independently of the worker.
+ */
+export function buildTranscriptNote(input: TranscriptNoteInput): {
+  path: string;
+  content: string;
+  metadata: Record<string, unknown>;
+  tags: string[];
+  createdAt: string;
+} {
+  const created = (input.createdAt ?? new Date()).toISOString();
+  const filename = input.attachmentPath.split("/").pop() ?? input.attachmentPath;
+  const metadata: Record<string, unknown> = {
+    title: `Transcript of ${filename}`,
+    transcript_of: input.attachmentPath,
+    transcript_attachment_id: input.attachmentId,
+    transcript_status: input.status,
+  };
+  if (input.provider) metadata.transcript_provider = input.provider;
+  if (typeof input.durationMs === "number") {
+    metadata.transcript_duration_ms = input.durationMs;
+  }
+  if (input.status === "failed") {
+    metadata.transcript_error = input.error ?? "unknown error";
+  }
+  const body = input.status === "complete" ? (input.text ?? "") : "";
+  return {
+    path: transcriptPathFor(input.attachmentPath),
+    content: body,
+    metadata,
+    tags: ["transcript", "capture"],
+    createdAt: created,
+  };
+}
+
+/**
+ * Create or update the transcript note at `<attachmentPath>.transcript.md`.
+ *
+ * - If no note exists at that path, creates one with the standard shape,
+ *   establishes a `transcript_of` link to the attachment-owning note, and
+ *   returns the new note.
+ * - If a transcript note already exists (retry path), overwrites its content
+ *   + metadata in place, preserves the existing note id, and returns the
+ *   updated note. Links are NOT re-created — the existing relation survives.
+ *
+ * Errors from the Store (path collision with a non-transcript note, etc.)
+ * bubble up; the worker catches them and logs.
+ */
+export async function upsertTranscriptNote(
+  store: Store,
+  input: TranscriptNoteInput,
+): Promise<Note> {
+  const built = buildTranscriptNote(input);
+  const existing = await store.getNoteByPath(built.path);
+  if (existing) {
+    await store.updateNote(existing.id, {
+      content: built.content,
+      metadata: built.metadata,
+      // Preserve the original created_at; the retry doesn't reset it.
+      skipUpdatedAt: false,
+    });
+    // Re-apply tags via tagNote — updateNote() doesn't accept a tags field
+    // (the engine treats tag mutation as a separate op). tagNote upserts
+    // existing tags (no duplicates), so it's safe to call even when tags
+    // are unchanged from the prior write.
+    await store.tagNote(existing.id, built.tags);
+    const updated = await store.getNote(existing.id);
+    return updated ?? existing;
+  }
+  const created = await store.createNote(built.content, {
+    path: built.path,
+    tags: built.tags,
+    metadata: built.metadata,
+    created_at: built.createdAt,
+  });
+  // Materialize the transcript-of relation as a typed link too, so graph
+  // queries (find-path, neighborhood) surface the transcript without
+  // walking frontmatter. The relation is named "transcript_of" so it
+  // matches the frontmatter scalar; if the target note has been deleted
+  // by the time we get here (race during retry), skip silently — the
+  // frontmatter scalar still carries the relation for query-by-path.
+  try {
+    await store.createLink(created.id, input.attachmentNoteId, "transcript_of");
+  } catch {
+    // Target may be missing or the link constraint may reject — failure
+    // here doesn't invalidate the transcript itself, which is still
+    // queryable via the `transcript_of` frontmatter scalar + path.
+  }
+  return created;
+}

package/src/transcription-registry.ts

@@ -0,0 +1,22 @@
+/**
+ * Process-singleton holder for the active TranscriptionWorker (vault#353).
+ *
+ * Mirrors `mirror-registry.ts`: `server.ts` constructs the worker on boot
+ * (when scribe is discoverable), and the REST retry endpoint
+ * (`/api/notes/:id/retry-transcription`) picks it up here to call `kick()`
+ * for an event-driven re-run. Absent the worker (no scribe), the retry
+ * endpoint still flips the attachment back to `pending` so the sweep would
+ * pick it up — but it'll just sit there until scribe shows up.
+ */
+
+import type { TranscriptionWorker } from "./transcription-worker.ts";
+
+let activeWorker: TranscriptionWorker | null = null;
+
+export function setTranscriptionWorker(worker: TranscriptionWorker | null): void {
+  activeWorker = worker;
+}
+
+export function getTranscriptionWorker(): TranscriptionWorker | null {
+  return activeWorker;
+}

package/src/transcription-worker.test.ts

@@ -867,3 +867,253 @@ describe("transcription worker — hook-driven", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// vault#353 — auto-origin path: materialize <attachment-path>.transcript.md
+// notes on success AND on terminal failure (so the retry endpoint has a
+// surface to act on). The legacy `transcribe_stub`-patching path remains
+// unchanged; these tests pin the new behavior for attachments stamped with
+// `transcribe_origin: "auto"`.
+// ---------------------------------------------------------------------------
+
+describe("transcription worker — auto-origin (vault#353)", () => {
+  test("success: materializes <path>.transcript with frontmatter + body", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "auto-1" });
+    seedAudio("memos/auto-1.webm");
+    await store.addAttachment(owner.id, "memos/auto-1.webm", "audio/webm", {
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+
+    const worker = makeWorker({
+      fetchImpl: mkFetchMock([{ text: "this is the spoken text" }]),
+    });
+    try {
+      const processed = await worker.tick();
+      expect(processed).toBe(1);
+    } finally {
+      await worker.stop();
+    }
+
+    // The transcript note exists, with the expected shape.
+    const transcript = await store.getNoteByPath("memos/auto-1.webm.transcript");
+    expect(transcript).not.toBeNull();
+    expect(transcript!.content).toBe("this is the spoken text");
+    expect(transcript!.tags).toContain("transcript");
+    expect((transcript!.metadata as any)?.transcript_status).toBe("complete");
+    expect((transcript!.metadata as any)?.transcript_of).toBe("memos/auto-1.webm");
+    expect(typeof (transcript!.metadata as any)?.transcript_duration_ms).toBe("number");
+
+    // Source note is NOT touched (no stub patching on auto-origin).
+    const sourceNote = await store.getNote("auto-1");
+    expect(sourceNote!.content).toBe("# Voice memo\n");
+
+    // Attachment row also reflects success — sweep + retry hit the same row.
+    const [att] = await store.getAttachments(owner.id);
+    expect(att.metadata?.transcribe_status).toBe("done");
+  });
+
+  test("missing_provider 400: terminal failure on first try → failed transcript note", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "auto-mp" });
+    seedAudio("memos/auto-mp.webm");
+    await store.addAttachment(owner.id, "memos/auto-mp.webm", "audio/webm", {
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+
+    // Custom fetchImpl that returns the structured 400 missing_provider
+    // payload (scribe#47 shape).
+    const fetchImpl: typeof fetch = (async () => {
+      return new Response(
+        JSON.stringify({
+          error: "no transcription provider configured",
+          error_code: "missing_provider",
+        }),
+        { status: 400, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const worker = makeWorker({ fetchImpl, maxAttempts: 5 });
+    try {
+      await worker.tick();
+    } finally {
+      await worker.stop();
+    }
+
+    const transcript = await store.getNoteByPath("memos/auto-mp.webm.transcript");
+    expect(transcript).not.toBeNull();
+    expect(transcript!.content).toBe("");
+    expect((transcript!.metadata as any)?.transcript_status).toBe("failed");
+    expect((transcript!.metadata as any)?.transcript_error).toContain("missing_provider");
+
+    // 4xx is terminal — attempts tracked but status went straight to failed,
+    // not parked in pending with backoff.
+    const [att] = await store.getAttachments(owner.id);
+    expect(att.metadata?.transcribe_status).toBe("failed");
+    expect((att.metadata as any)?.transcribe_error_code).toBe("missing_provider");
+  });
+
+  test("5xx timeout: retries with backoff (NOT terminal on first failure)", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "auto-503" });
+    seedAudio("memos/auto-503.webm");
+    await store.addAttachment(owner.id, "memos/auto-503.webm", "audio/webm", {
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+
+    const worker = makeWorker({
+      fetchImpl: mkFetchMock([{ error: "upstream timeout", status: 503 }]),
+      maxAttempts: 3,
+    });
+    try {
+      await worker.tick();
+    } finally {
+      await worker.stop();
+    }
+
+    // 5xx is retriable — attachment goes back to pending with backoff.
+    // The transcript note is NOT materialized yet (the failure isn't terminal
+    // and we don't want to surface intermediate failures to the user).
+    const [att] = await store.getAttachments(owner.id);
+    expect(att.metadata?.transcribe_status).toBe("pending");
+    expect(att.metadata?.transcribe_backoff_until).toBeTruthy();
+
+    const transcript = await store.getNoteByPath("memos/auto-503.webm.transcript");
+    expect(transcript).toBeNull();
+  });
+
+  test("audio gone: terminal failure → failed transcript note materialized", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "auto-gone" });
+    // No seedAudio call — the file is missing.
+    await store.addAttachment(owner.id, "memos/auto-gone.webm", "audio/webm", {
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+
+    const worker = makeWorker({
+      fetchImpl: mkFetchMock([{ text: "should never run" }]),
+    });
+    try {
+      await worker.tick();
+    } finally {
+      await worker.stop();
+    }
+
+    const transcript = await store.getNoteByPath("memos/auto-gone.webm.transcript");
+    expect(transcript).not.toBeNull();
+    expect((transcript!.metadata as any)?.transcript_status).toBe("failed");
+    expect((transcript!.metadata as any)?.transcript_error).toBe("audio file not found");
+  });
+
+  test("legacy stub flow unchanged: no transcript note materialized for transcribe_stub-only", async () => {
+    await store.createNote(
+      "# Voice\n\n_Transcript pending._\n",
+      { id: "legacy-1", metadata: { transcribe_stub: true } },
+    );
+    seedAudio("memos/legacy-1.webm");
+    await store.addAttachment("legacy-1", "memos/legacy-1.webm", "audio/webm", {
+      transcribe_status: "pending",
+      // Legacy path: NO transcribe_origin: "auto".
+    });
+
+    const worker = makeWorker({
+      fetchImpl: mkFetchMock([{ text: "stub-patched" }]),
+    });
+    try {
+      await worker.tick();
+    } finally {
+      await worker.stop();
+    }
+
+    // The note body was patched in place (legacy behavior).
+    const note = await store.getNote("legacy-1");
+    expect(note!.content).toBe("# Voice\n\nstub-patched\n");
+
+    // No transcript note was created.
+    const transcript = await store.getNoteByPath("memos/legacy-1.webm.transcript");
+    expect(transcript).toBeNull();
+  });
+
+  test("retry path: failed transcript is overwritten in place on success", async () => {
+    const owner = await store.createNote("# Voice memo\n", { id: "auto-retry" });
+    seedAudio("memos/auto-retry.webm");
+    await store.addAttachment(owner.id, "memos/auto-retry.webm", "audio/webm", {
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+
+    // Pass 1: missing_provider failure → failed transcript note materialized.
+    const fetch400: typeof fetch = (async () => {
+      return new Response(
+        JSON.stringify({ error: "missing", error_code: "missing_provider" }),
+        { status: 400, headers: { "content-type": "application/json" } },
+      );
+    }) as typeof fetch;
+    const worker1 = makeWorker({ fetchImpl: fetch400 });
+    try { await worker1.tick(); } finally { await worker1.stop(); }
+
+    const failed = await store.getNoteByPath("memos/auto-retry.webm.transcript");
+    expect(failed).not.toBeNull();
+    const failedId = failed!.id;
+    expect((failed!.metadata as any)?.transcript_status).toBe("failed");
+
+    // Pass 2: re-enqueue by flipping the attachment back to pending (this is
+    // what the retry endpoint does) + give scribe a successful response.
+    const [att] = await store.getAttachments(owner.id);
+    await store.setAttachmentMetadata(att.id, {
+      ...(att.metadata ?? {}),
+      transcribe_status: "pending",
+      transcribe_origin: "auto",
+    });
+    const worker2 = makeWorker({
+      fetchImpl: mkFetchMock([{ text: "second time's the charm" }]),
+    });
+    try { await worker2.tick(); } finally { await worker2.stop(); }
+
+    const success = await store.getNoteByPath("memos/auto-retry.webm.transcript");
+    expect(success).not.toBeNull();
+    // Same note id — updated in place, not a fresh row.
+    expect(success!.id).toBe(failedId);
+    expect(success!.content).toBe("second time's the charm");
+    expect((success!.metadata as any)?.transcript_status).toBe("complete");
+    expect((success!.metadata as any)?.transcript_error).toBeUndefined();
+  });
+
+  test("concurrent uploads: 5 audio files yield 5 transcript notes (no path collision)", async () => {
+    const owners: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const note = await store.createNote(`# Voice ${i}\n`, { id: `concurrent-${i}` });
+      owners.push(note.id);
+      seedAudio(`memos/concurrent-${i}.webm`);
+      await store.addAttachment(note.id, `memos/concurrent-${i}.webm`, "audio/webm", {
+        transcribe_status: "pending",
+        transcribe_origin: "auto",
+      });
+    }
+
+    // Same transcript body to each. The worker drains FIFO.
+    const worker = makeWorker({
+      fetchImpl: mkFetchMock([
+        { text: "transcript-0" },
+        { text: "transcript-1" },
+        { text: "transcript-2" },
+        { text: "transcript-3" },
+        { text: "transcript-4" },
+      ]),
+    });
+    try {
+      const processed = await worker.tick();
+      expect(processed).toBe(5);
+    } finally {
+      await worker.stop();
+    }
+
+    // 5 transcript notes — one per audio file. The bodies map to FIFO order;
+    // we just assert each note exists with `complete` status.
+    for (let i = 0; i < 5; i++) {
+      const t = await store.getNoteByPath(`memos/concurrent-${i}.webm.transcript`);
+      expect(t).not.toBeNull();
+      expect((t!.metadata as any)?.transcript_status).toBe("complete");
+    }
+  });
+});