@openparachute/vault 0.7.4-rc.1 → 0.7.4

package/core/src/attachment/tickets.ts

@@ -37,6 +37,15 @@ export interface AttachmentTicket {
   noteId?: string;
   filename?: string;
   transcribe?: boolean;
+  /**
+   * Upload only, voice W2 parity with the REST path's `segment_index`
+   * (`src/routes.ts` POST `/notes/:id/attachments`) — an integer >= 0 lets
+   * one recording split across several ticket-minted attachments on ONE
+   * note, each resolving into its own `(part N)` marker. Only meaningful
+   * alongside `transcribe: true`; validated at mint (`generateMcpTools`'s
+   * `request-attachment-upload`), consumed at spend (`handleTicketSpend`).
+   */
+  segmentIndex?: number;
   /** Download only. */
   attachmentId?: string;
 }

package/core/src/mcp-manifest.ts

@@ -677,7 +677,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       name: "request-attachment-upload",
       requiredVerb: "write",
       description:
-        "Mint a short-lived, single-use upload URL for a note attachment. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Provide the target `note` (id or path), the `filename`, and its exact `size_bytes` — declared here and enforced at spend (a mismatch, or exceeding the 100 MiB REST upload cap, fails the mint or the upload). `mime_type` is inferred from the filename's extension when omitted. Pass `transcribe: true` for an audio file to enqueue it exactly like the REST attach flow does. The ticket's `expires_at` scales with declared size (10 minutes base + 10s per MiB, capped at 30 minutes) and can be spent exactly once — a failed curl means re-minting, not retrying the same URL.",
+        "Mint a short-lived, single-use upload URL for a note attachment. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Provide the target `note` (id or path), the `filename`, and its exact `size_bytes` — declared here and enforced at spend (a mismatch, or exceeding the 100 MiB REST upload cap, fails the mint or the upload). `mime_type` is inferred from the filename's extension when omitted. Pass `transcribe: true` for an audio file to enqueue it exactly like the REST attach flow does; `segment_index` additionally splits one recording across several attachments on the same note (voice W2 — see that field's description). The ticket's `expires_at` scales with declared size (10 minutes base + 10s per MiB, capped at 30 minutes) and can be spent exactly once — a failed curl means re-minting, not retrying the same URL.",
       inputSchema: {
         type: "object",
         properties: {
@@ -689,6 +689,10 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           mime_type: { type: "string", description: "MIME type to store on the attachment row. Inferred from `filename`'s extension when omitted (`application/octet-stream` for an uncurated extension)." },
           transcribe: { type: "boolean", description: "Opt into transcription for an audio attachment — mirrors the REST `POST /notes/:id/attachments` `transcribe` flag." },
+          segment_index: {
+            type: "number",
+            description: "Only meaningful alongside `transcribe: true`. An integer >= 0 that marks this attachment as one part of a multi-part recording linked to the same note — each part resolves into its own `_Transcript pending (part N)._` marker (N = segment_index + 1) instead of overwriting a shared bare marker. A malformed value (non-integer, negative, non-number) is silently ignored, falling back to the un-segmented bare marker.",
+          },
         },
         required: ["note", "filename", "size_bytes"],
       },

package/core/src/mcp.ts

@@ -2558,6 +2558,13 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               ? params.mime_type
               : mimeForAttachmentExtension(ext);
 
+          // Per-segment slots (voice W2), ticket-mint parity with the REST
+          // path's own validation (`src/routes.ts` POST /notes/:id/attachments):
+          // an integer >= 0, else silently dropped — a malformed value falls
+          // back to the un-segmented bare markers rather than erroring the mint.
+          const segIdx = params.segment_index;
+          const validSegment = typeof segIdx === "number" && Number.isInteger(segIdx) && segIdx >= 0;
+
           const now = Date.now();
           const expiresAt = now + computeTicketTtlMs(sizeBytes);
           const id = generateTicketId();
@@ -2572,6 +2579,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             mimeType,
             sizeBytes,
             transcribe: params.transcribe === true,
+            ...(validSegment ? { segmentIndex: segIdx } : {}),
           };
           await ticketSeam.provider.put(ticket);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.4-rc.1",
+  "version": "0.7.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/attachment-tickets.test.ts

@@ -270,6 +270,52 @@ describe("attachment tickets — upload lifecycle", () => {
     expect((updatedNote!.metadata as any)?.transcribe_stub).toBe(true);
   });
 
+  test("segment_index (voice W2): a valid integer >= 0 rides ticket mint through to the attachment row", async () => {
+    const vaultName = freshVault("tickets-segment");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# Voice memo\n\n_Transcript pending (part 2)._", { path: "memo-seg" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "part-2.wav",
+      size_bytes: 4,
+      transcribe: true,
+      segment_index: 1,
+    });
+    const res = await routeReq(
+      new Request(mint.url, { method: "PUT", headers: { "content-type": "audio/wav" }, body: new Uint8Array([1, 2, 3, 4]) }),
+    );
+    expect(res.status).toBe(201);
+    const attachment = (await res.json()) as any;
+    expect(attachment.metadata.segment_index).toBe(1);
+    expect(attachment.metadata.transcribe_status).toBe("pending");
+  });
+
+  test.each([
+    ["negative", -1],
+    ["non-integer", 1.5],
+    ["string", "1"],
+  ])("segment_index (voice W2): an invalid value (%s) is dropped at mint, not stored — same fallback as the REST path", async (_label, bad) => {
+    const vaultName = freshVault(`tickets-segment-bad-${_label}`);
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# Voice memo\n\n_Transcript pending._", { path: "memo-seg-bad" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "bad.wav",
+      size_bytes: 4,
+      transcribe: true,
+      segment_index: bad,
+    });
+    const res = await routeReq(
+      new Request(mint.url, { method: "PUT", headers: { "content-type": "audio/wav" }, body: new Uint8Array([1, 2, 3, 4]) }),
+    );
+    expect(res.status).toBe(201);
+    const attachment = (await res.json()) as any;
+    expect(attachment.metadata.segment_index).toBeUndefined();
+    expect(attachment.metadata.transcribe_status).toBe("pending");
+  });
+
   test("blocked extension is refused at MINT — no ticket is ever created", async () => {
     const vaultName = freshVault("tickets-blocked-ext");
     const store = getVaultStore(vaultName);

package/src/attachment-tickets.ts

@@ -274,6 +274,12 @@ async function handleUploadSpend(
     attMeta.transcribe_status = "pending";
     attMeta.transcribe_requested_at = new Date().toISOString();
     attMeta.transcribe_origin = explicitOptIn ? "legacy" : "auto";
+    // Per-segment slots (voice W2) — already validated at mint (the ticket
+    // only carries `segmentIndex` when it passed the integer->=0 check), so
+    // just thread it through onto the attachment row's metadata.
+    if (ticket.segmentIndex !== undefined) {
+      attMeta.segment_index = ticket.segmentIndex;
+    }
   }
 
   const attachment = await store.addAttachment(ticket.noteId, relativePath, ticket.mimeType, attMeta);

package/src/routes.ts

@@ -2334,7 +2334,12 @@ async function handleNotesInner(
       }
       const parsedBody = await parseJsonBody(req);
       if (!parsedBody.ok) return parsedBody.response;
-      const body = parsedBody.body as { path: string; mimeType: string; transcribe?: boolean };
+      const body = parsedBody.body as {
+        path: string;
+        mimeType: string;
+        transcribe?: boolean;
+        segment_index?: unknown;
+      };
       if (!body.path || !body.mimeType) {
         return json(
           { error: "path and mimeType are required", error_type: "missing_required_field", hint: "pass both `path` and `mimeType`" },
@@ -2365,11 +2370,20 @@ async function handleNotesInner(
         ? readVaultConfig(vault)?.auto_transcribe?.enabled
         : undefined;
       const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType, { perVaultEnabled });
+      // Per-segment slots (voice W2, cloud twin: workers/vault/src/rest/notes.ts
+      // ~791-800): an optional `segment_index` (integer >= 0) lets one recording
+      // split across several attachments on ONE note, each resolving into its
+      // own `(part N)` marker (N = segment_index + 1, see transcription-worker.ts
+      // markersFor). A malformed value is silently ignored — the attachment
+      // still links, it just falls back to the bare, un-segmented markers.
+      const segIdx = body.segment_index;
+      const validSegment = typeof segIdx === "number" && Number.isInteger(segIdx) && segIdx >= 0;
       const attMeta = (explicitOptIn || autoOptIn)
         ? {
             transcribe_status: "pending" as const,
             transcribe_requested_at: new Date().toISOString(),
             transcribe_origin: (explicitOptIn ? "legacy" : "auto") as "legacy" | "auto",
+            ...(validSegment ? { segment_index: segIdx } : {}),
           }
         : undefined;
 

package/src/vault.test.ts

@@ -2913,6 +2913,173 @@ describe("HTTP /notes", async () => {
     });
   });
 
+  describe("POST /notes/:id/attachments with segment_index (voice W2)", async () => {
+    test("valid segment_index (integer >= 0) lands on the attachment's metadata", async () => {
+      await store.createNote("# 🎙️ Voice memo\n\n_Transcript pending (part 1)._", { id: "seg1" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/seg1/attachments", {
+          path: "memos/part-1.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+          segment_index: 0,
+        }),
+        store,
+        "/seg1/attachments",
+      );
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      expect(att.metadata?.segment_index).toBe(0);
+      expect(att.metadata?.transcribe_status).toBe("pending");
+    });
+
+    test.each([
+      ["negative", -1],
+      ["non-integer", 1.5],
+      ["string", "1"],
+    ])("invalid segment_index (%s) is dropped, not stored, same as cloud's fallback", async (_label, bad) => {
+      await store.createNote("# 🎙️ Voice memo\n\n_Transcript pending._", { id: `seg-bad-${_label}` });
+      const res = await handleNotes(
+        mkReq("POST", `/notes/seg-bad-${_label}/attachments`, {
+          path: "memos/bad.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+          segment_index: bad,
+        }),
+        store,
+        `/seg-bad-${_label}/attachments`,
+      );
+      // Malformed segment_index is NOT a request error — it silently falls
+      // back to the un-segmented path (mirrors cloud's notes.ts validSegment
+      // check), so linking still succeeds.
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      expect(att.metadata?.segment_index).toBeUndefined();
+      expect(att.metadata?.transcribe_status).toBe("pending");
+    });
+
+    test("absent segment_index leaves the un-segmented path byte-unchanged", async () => {
+      await store.createNote("# 🎙️ Voice memo\n\n_Transcript pending._", { id: "seg-absent" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/seg-absent/attachments", {
+          path: "memos/bare.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+        }),
+        store,
+        "/seg-absent/attachments",
+      );
+      expect(res.status).toBe(201);
+      const att = await res.json() as any;
+      expect(att.metadata?.segment_index).toBeUndefined();
+      expect(att.metadata?.transcribe_status).toBe("pending");
+    });
+
+    // ---- The join test, not just the door's half ------------------------
+    //
+    // The three tests above post `segment_index` at TOP LEVEL — the shape
+    // both doors have now agreed on (cloud always read it there; self-host
+    // didn't read it at all until this PR). That's a deliberate contract
+    // choice, not a guess at what any client sends: the app was found
+    // nesting it under `metadata` instead, which is the OTHER half of this
+    // bug and is being fixed separately in sibling PR parachute-app#126
+    // ("segment_index rides top-level on the wire"). Top-level is the one
+    // true shape going forward; nested is a bug in the emitter, not a shape
+    // either door should learn to accept.
+    //
+    // What this test proves: given a top-level `segment_index`, self-host
+    // stores it AND the transcription worker resolves the correct per-part
+    // marker from it — the full loop this door owns.
+    // What it does NOT prove: that any real client actually sends this
+    // shape today. app#126 pins the app's emission; this pins the door's
+    // reception. Proving the two actually join — the app's real request
+    // body landing on a running self-host vault and coming out right —
+    // needs a cross-repo conformance test that doesn't exist yet (filed as
+    // vault#629; that gap is exactly how this bug shipped in the first
+    // place, since cloud's own conformance test was green against a shape
+    // the app never sent).
+    test("end-to-end: top-level segment_index on TWO real attachments resolves each part's marker independently", async () => {
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, "memos"), { recursive: true });
+      writeFileSync(join(assetsRoot, "memos/e2e-0.webm"), Buffer.from([1, 2, 3]));
+      writeFileSync(join(assetsRoot, "memos/e2e-1.webm"), Buffer.from([4, 5, 6]));
+      process.env.ASSETS_DIR = assetsRoot;
+
+      await store.createNote(
+        "# 🎙️ Voice memo\n\n_Transcript pending (part 1)._\n\n_Transcript pending (part 2)._\n",
+        { id: "seg-e2e", metadata: { transcribe_stub: true } },
+      );
+
+      // Link both parts through the REAL REST endpoint, exactly as the
+      // (now-fixed) app will call it: top-level segment_index, not nested.
+      const res0 = await handleNotes(
+        mkReq("POST", "/notes/seg-e2e/attachments", {
+          path: "memos/e2e-0.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+          segment_index: 0,
+        }),
+        store,
+        "/seg-e2e/attachments",
+      );
+      const res1 = await handleNotes(
+        mkReq("POST", "/notes/seg-e2e/attachments", {
+          path: "memos/e2e-1.webm",
+          mimeType: "audio/webm",
+          transcribe: true,
+          segment_index: 1,
+        }),
+        store,
+        "/seg-e2e/attachments",
+      );
+      expect(res0.status).toBe(201);
+      expect(res1.status).toBe(201);
+      const att0 = await res0.json() as any;
+      const att1 = await res1.json() as any;
+
+      const worker = startTranscriptionWorker({
+        vaultList: () => ["default"],
+        getStore: () => store as unknown as Store,
+        scribeUrl: "http://scribe.test",
+        resolveAssetsDir: () => process.env.ASSETS_DIR!,
+        pollIntervalMs: 10_000_000,
+        maxAttempts: 3,
+        fetchImpl: (async () => new Response(
+          JSON.stringify({ text: "part text" }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        )) as typeof fetch,
+        logger: { error: () => {}, info: () => {} },
+      });
+      try {
+        // Complete part 2 first, then part 1 — out of order, same as the
+        // original bug report.
+        await worker.kick("default", att1);
+        const midway = await store.getNote("seg-e2e");
+        expect(midway!.content).toBe(
+          "# 🎙️ Voice memo\n\n_Transcript pending (part 1)._\n\npart text\n",
+        );
+        // Shared stub SURVIVES — part 1 still needs the gate open. Before
+        // this fix, an unstored segment_index made every part look
+        // un-segmented, so completing ONE part cleared the stub and locked
+        // the other out (the exact production bug).
+        expect((midway!.metadata as any)?.transcribe_stub).toBe(true);
+
+        await worker.kick("default", att0);
+        const final = await store.getNote("seg-e2e");
+        expect(final!.content).toBe(
+          "# 🎙️ Voice memo\n\npart text\n\npart text\n",
+        );
+        // Segmented notes never auto-clear the shared stub, even once every
+        // part is done (pre-existing worker contract, pinned separately in
+        // transcription-worker.test.ts) — out of scope here, asserted only
+        // so this test doesn't silently rely on behavior this PR didn't add.
+        expect((final!.metadata as any)?.transcribe_stub).toBe(true);
+      } finally {
+        await worker.stop();
+        delete process.env.ASSETS_DIR;
+      }
+    });
+  });
+
   describe("DELETE /notes/:id/attachments/:attId", async () => {
     test("happy path: 204, DB row gone, storage file unlinked", async () => {
       const assetsRoot = join(tmpDir, "assets");