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

package/src/vault.test.ts

@@ -1575,6 +1575,177 @@ describe("HTTP /notes", async () => {
     expect(body.map((n) => n.content)).toEqual(["modified"]);
   });
 
+  // ---- Cursor pagination (vault#313) ----
+  //
+  // Opaque cursors for since-last-checked agent loops. The full engine
+  // semantics live in core.test.ts; these tests pin the HTTP plumbing:
+  // wrapped {notes, next_cursor} envelope when ?cursor= is set, structured
+  // 400s on bad cursor, and end-to-end resume across calls.
+  test("GET /notes?cursor=... returns {notes, next_cursor} envelope", async () => {
+    await store.createNote("a", { id: "cur-rest-a" });
+    await store.createNote("b", { id: "cur-rest-b" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-01T00:00:00.000Z", "cur-rest-a");
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-02T00:00:00.000Z", "cur-rest-b");
+
+    // Mint a starting cursor via the store (we don't expose a "first cursor"
+    // endpoint — the first call's response carries the cursor). Simulate
+    // the first call by querying without a cursor and reading
+    // next_cursor from a follow-up call shape.
+    const seed = await store.queryNotesPaged({});
+    const cursor = seed.next_cursor;
+
+    // No new writes after seed → second call is empty but still returns
+    // an envelope.
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(cursor)}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body).toHaveProperty("notes");
+    expect(body).toHaveProperty("next_cursor");
+    expect(Array.isArray(body.notes)).toBe(true);
+    expect(body.notes).toHaveLength(0);
+    expect(typeof body.next_cursor).toBe("string");
+  });
+
+  test("GET /notes (no cursor) returns legacy flat-array shape", async () => {
+    await store.createNote("a", { id: "noCur-a" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+  });
+
+  test("GET /notes?cursor=<stale> returns 400 cursor_query_mismatch", async () => {
+    await store.createNote("a", { tags: ["x"], id: "cm-a" });
+    await store.createNote("b", { tags: ["y"], id: "cm-b" });
+    const seed = await store.queryNotesPaged({ tags: ["x"] });
+
+    // Reuse on a different tag — engine raises cursor_query_mismatch.
+    const res = await handleNotes(
+      mkReq("GET", `/notes?tag=y&cursor=${encodeURIComponent(seed.next_cursor)}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("cursor_query_mismatch");
+  });
+
+  test("GET /notes?cursor=<garbage> returns 400 cursor_invalid", async () => {
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=not-a-real-cursor`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("cursor_invalid");
+  });
+
+  test("GET /notes?cursor=...&near[note_id]=x rejects with INVALID_QUERY", async () => {
+    const a = await store.createNote("anchor", { id: "n1" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&near[note_id]=${a.id}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&search=... rejects with INVALID_QUERY (vault#355 reviewer)", async () => {
+    // REST used to silently drop the cursor and route into the FTS branch.
+    // MCP rejects this combo explicitly at core/src/mcp.ts — REST now does
+    // the same. Surface parity, no silent corruption.
+    await store.createNote("the quick brown fox", { id: "s1" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&search=fox`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&sort=desc rejects with INVALID_QUERY", async () => {
+    // Descending iteration with a watermark cursor would skip newly-written
+    // rows. queryNotesPaged surfaces this as a QueryError; the REST handler
+    // catches and translates to 400. Asserts the surface parity with MCP
+    // even though the guard sits at the core layer.
+    await store.createNote("a", { id: "sd-a" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&sort=desc`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&order_by=... rejects with INVALID_QUERY", async () => {
+    // Cursor pagination forces order by updated_at; order_by is mutually
+    // exclusive. Same surface-parity assertion as the sort=desc test.
+    await store.createNote("a", { id: "ob-a" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&order_by=created_at`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?search=fox (without cursor) still works after the cursor+search guard", async () => {
+    // Sanity check: the cursor+search guard must not regress plain FTS.
+    await store.createNote("the quick brown fox", { id: "ss-a" });
+    const res = await handleNotes(mkReq("GET", "/notes?search=fox"), store, "");
+    expect(res.status).toBe(200);
+    const body = await res.json() as any[];
+    expect(body).toHaveLength(1);
+    expect(body[0].id).toBe("ss-a");
+  });
+
+  test("GET /notes?cursor=... resumes correctly across calls (end-to-end)", async () => {
+    // Three notes spread across distinct updated_at watermarks. First
+    // call returns the first batch, second call (with cursor) returns
+    // only the note written after the cursor was minted.
+    const a = await store.createNote("first", { id: "e2e-a" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-01T00:00:00.000Z", a.id);
+    const b = await store.createNote("second", { id: "e2e-b" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-02T00:00:00.000Z", b.id);
+
+    const seed = await store.queryNotesPaged({});
+    expect(seed.notes.map((n) => n.id).sort()).toEqual(["e2e-a", "e2e-b"]);
+
+    // Write a third note that lands AFTER the cursor's watermark.
+    const c = await store.createNote("third", { id: "e2e-c" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-03T00:00:00.000Z", c.id);
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&include_content=true`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.notes.map((n: any) => n.id)).toEqual(["e2e-c"]);
+  });
+
   test("GET /notes?has_links=false returns only orphaned notes", async () => {
     const a = await store.createNote("src", { id: "qa" });
     const b = await store.createNote("tgt", { id: "qb" });
@@ -2543,6 +2714,182 @@ describe("HTTP /notes", async () => {
       expect(body.map((n) => n.content)).toEqual(["new"]);
     });
   });
+
+  // -------------------------------------------------------------------------
+  // POST /notes/:id/retry-transcription — vault#353 design Q5.
+  //
+  // The endpoint re-enqueues a failed transcript by flipping the matching
+  // attachment back to `transcribe_status: pending`. The worker (or sweep)
+  // picks it up. These tests exercise the request shape + error branches;
+  // the actual re-transcription is covered in transcription-worker.test.ts's
+  // auto-origin section.
+  // -------------------------------------------------------------------------
+  describe("POST /notes/:id/retry-transcription", async () => {
+    async function seedFailedTranscript(opts: {
+      audioPath?: string;
+      noteId?: string;
+      transcriptId?: string;
+      omitAttachmentId?: boolean;
+    } = {}): Promise<{ owner: { id: string }; attachmentId: string; transcriptId: string; audioPath: string }> {
+      const audioPath = opts.audioPath ?? `${opts.noteId ?? "src"}/voice.webm`;
+      const ownerId = opts.noteId ?? "src-note";
+      const owner = await store.createNote("# Voice\n", { id: ownerId });
+      const att = await store.addAttachment(owner.id, audioPath, "audio/webm", {
+        transcribe_status: "failed",
+        transcribe_origin: "auto",
+        transcribe_error: "no transcription provider configured",
+      });
+      // Seed the failed transcript note exactly as the worker would have.
+      const transcriptMeta: Record<string, unknown> = {
+        transcript_of: audioPath,
+        transcript_status: "failed",
+        transcript_error: "missing_provider: no transcription provider configured",
+      };
+      if (!opts.omitAttachmentId) transcriptMeta.transcript_attachment_id = att.id;
+      await store.createNote("", {
+        id: opts.transcriptId ?? "transcript-1",
+        path: `${audioPath}.transcript`,
+        tags: ["transcript", "capture"],
+        metadata: transcriptMeta,
+      });
+      // Audio file present on disk so the retry doesn't 404 on audio_missing.
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, audioPath.split("/").slice(0, -1).join("/")), { recursive: true });
+      writeFileSync(join(assetsRoot, audioPath), Buffer.from([1, 2, 3]));
+      process.env.ASSETS_DIR = assetsRoot;
+      return { owner: { id: ownerId }, attachmentId: att.id, transcriptId: opts.transcriptId ?? "transcript-1", audioPath };
+    }
+
+    test("happy path: flips attachment to pending and returns 202", async () => {
+      const { attachmentId, transcriptId } = await seedFailedTranscript();
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${transcriptId}/retry-transcription`),
+        store,
+        `/${transcriptId}/retry-transcription`,
+        "default",
+      );
+      expect(res.status).toBe(202);
+      const body = await res.json() as any;
+      expect(body.status).toBe("queued");
+      expect(body.attachment_id).toBe(attachmentId);
+      expect(body.transcript_note_id).toBe(transcriptId);
+
+      // Attachment metadata reset.
+      const att = await store.getAttachment(attachmentId);
+      expect(att?.metadata?.transcribe_status).toBe("pending");
+      expect(att?.metadata?.transcribe_origin).toBe("auto");
+      // Stale failure state cleared.
+      expect(att?.metadata?.transcribe_error).toBeUndefined();
+      expect(att?.metadata?.transcribe_attempts).toBeUndefined();
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("404 when transcript note doesn't exist", async () => {
+      const res = await handleNotes(
+        mkReq("POST", "/notes/no-such-id/retry-transcription"),
+        store,
+        "/no-such-id/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(404);
+    });
+
+    test("400 invalid_target when target is not a transcript note", async () => {
+      await store.createNote("regular note", { id: "regular" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/regular/retry-transcription"),
+        store,
+        "/regular/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("invalid_target");
+    });
+
+    test("400 not_failed when transcript already succeeded", async () => {
+      const audioPath = "memo/done.webm";
+      const owner = await store.createNote("voice", { id: "src-done" });
+      const att = await store.addAttachment(owner.id, audioPath, "audio/webm");
+      await store.createNote("the spoken words", {
+        id: "transcript-done",
+        path: `${audioPath}.transcript`,
+        metadata: {
+          transcript_of: audioPath,
+          transcript_attachment_id: att.id,
+          transcript_status: "complete",
+        },
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-done/retry-transcription"),
+        store,
+        "/transcript-done/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("not_failed");
+      expect(body.transcript_status).toBe("complete");
+    });
+
+    test("400 missing_attachment_id when frontmatter lacks the id", async () => {
+      await seedFailedTranscript({
+        transcriptId: "transcript-no-id",
+        noteId: "src-no-id",
+        omitAttachmentId: true,
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-no-id/retry-transcription"),
+        store,
+        "/transcript-no-id/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("missing_attachment_id");
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("404 attachment_missing when the attachment row no longer exists", async () => {
+      const owner = await store.createNote("voice", { id: "src-stale" });
+      await store.createNote("", {
+        id: "transcript-stale",
+        path: "memo/stale.webm.transcript",
+        metadata: {
+          transcript_of: "memo/stale.webm",
+          transcript_attachment_id: "deleted-attachment-id",
+          transcript_status: "failed",
+          transcript_error: "missing_provider",
+        },
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-stale/retry-transcription"),
+        store,
+        "/transcript-stale/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(404);
+      const body = await res.json() as any;
+      expect(body.error).toBe("attachment_missing");
+    });
+
+    test("405 on GET (must POST)", async () => {
+      await seedFailedTranscript({
+        transcriptId: "transcript-405",
+        noteId: "src-405",
+        audioPath: "memo/405.webm",
+      });
+      const res = await handleNotes(
+        mkReq("GET", "/notes/transcript-405/retry-transcription"),
+        store,
+        "/transcript-405/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(405);
+      delete process.env.ASSETS_DIR;
+    });
+  });
 });
 
 describe("HTTP GET /notes?format=graph", async () => {