@openparachute/vault 0.7.3 → 0.7.4-rc.2

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.3",
+  "version": "0.7.4-rc.2",
   "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/embeddings-routes.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit coverage for the semantic-search (embeddings) opt-in toggle surface
+ * (0.7.3 fast-follow). Fully sandboxed — a throwaway `PARACHUTE_HOME` so the
+ * config read/write path operates on a scratch `config.yaml`, and the running
+ * "active" state is injected (never touches the real process-shared provider
+ * memo or downloads a model).
+ *
+ * The snapshot builder is pure over (env, persisted, active) so most of the
+ * matrix (env override wins, restart-required gap, default-off) is exercised
+ * without any I/O; the handler tests verify the config write path + 400s.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { readGlobalConfig, writeGlobalConfig } from "./config.ts";
+import {
+  buildEmbeddingsSnapshot,
+  handleEmbeddingsGet,
+  handleEmbeddingsPut,
+  EMBEDDING_MODEL_DOWNLOAD_MB,
+  type EmbeddingsSettingsSnapshot,
+} from "./embeddings-routes.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-embed-routes-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  // Seed a config.yaml so readGlobalConfig has a file (port only — embeddings unset).
+  writeGlobalConfig({ port: 1940 });
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+// An env with no EMBEDDINGS_ENABLED — the common self-host case.
+const NO_ENV: NodeJS.ProcessEnv = {};
+
+describe("buildEmbeddingsSnapshot", () => {
+  test("default: persisted unset, no env, not active → all off, no restart", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: undefined, active: false });
+    expect(snap).toEqual({
+      enabled: false,
+      env_override: null,
+      env_forced: false,
+      effective: false,
+      active: false,
+      restart_required: false,
+      model_download_mb: EMBEDDING_MODEL_DOWNLOAD_MB,
+    });
+  });
+
+  test("persisted on but not yet active → effective on, restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: false });
+    expect(snap.enabled).toBe(true);
+    expect(snap.effective).toBe(true);
+    expect(snap.active).toBe(false);
+    expect(snap.restart_required).toBe(true);
+  });
+
+  test("persisted on and active → no restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: true });
+    expect(snap.restart_required).toBe(false);
+  });
+
+  test("env override ON wins over persisted OFF", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "true" },
+      persistedEnabled: false,
+      active: true,
+    });
+    expect(snap.enabled).toBe(false); // toggle still reflects persisted
+    expect(snap.env_override).toBe(true);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(true); // env forces on
+    expect(snap.restart_required).toBe(false); // active matches env-forced effective
+  });
+
+  test("env override OFF wins over persisted ON (with a pending restart while still active)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "false" },
+      persistedEnabled: true,
+      active: true,
+    });
+    expect(snap.enabled).toBe(true); // persisted intent preserved
+    expect(snap.env_override).toBe(false);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(false); // env forces off
+    expect(snap.active).toBe(true);
+    expect(snap.restart_required).toBe(true); // running still on, env wants off
+  });
+
+  test("unrecognized env value defers to persisted (no force)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "maybe" },
+      persistedEnabled: true,
+      active: false,
+    });
+    expect(snap.env_override).toBeNull();
+    expect(snap.env_forced).toBe(false);
+    expect(snap.effective).toBe(true);
+  });
+});
+
+describe("handleEmbeddingsGet", () => {
+  test("reflects the persisted config.yaml value", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = handleEmbeddingsGet(false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.effective).toBe(true);
+    expect(body.active).toBe(false);
+    expect(body.restart_required).toBe(true);
+  });
+
+  test("unset persisted → enabled false", async () => {
+    const res = handleEmbeddingsGet(false);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(false);
+  });
+});
+
+describe("handleEmbeddingsPut", () => {
+  function putReq(body: unknown): Request {
+    return new Request("http://x/vault/default/.parachute/embeddings", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    });
+  }
+
+  test("enabling persists embeddings_enabled: true via the config write path", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.restart_required).toBe(true); // persisted on, injected active=false
+    // The setting is actually on disk (config write path reused, not hand-rolled).
+    expect(readGlobalConfig().embeddings_enabled).toBe(true);
+  });
+
+  test("disabling persists embeddings_enabled: false", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = await handleEmbeddingsPut(putReq({ enabled: false }), true);
+    expect(res.status).toBe(200);
+    expect(readGlobalConfig().embeddings_enabled).toBe(false);
+  });
+
+  test("preserves other config fields on write (round-trips through serialize)", async () => {
+    writeGlobalConfig({ port: 1940, discovery: "disabled", autostart: true });
+    await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    const cfg = readGlobalConfig();
+    expect(cfg.embeddings_enabled).toBe(true);
+    expect(cfg.discovery).toBe("disabled");
+    expect(cfg.autostart).toBe(true);
+    expect(cfg.port).toBe(1940);
+  });
+
+  test("non-boolean enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: "yes" }), false);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field?: string };
+    expect(body.field).toBe("enabled");
+  });
+
+  test("missing enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({}), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("non-object body → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("[]"), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("invalid JSON → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("{not json"), false);
+    expect(res.status).toBe(400);
+  });
+});

package/src/embeddings-routes.ts

@@ -0,0 +1,178 @@
+/**
+ * HTTP surface for the semantic-search (embeddings) opt-in toggle.
+ *
+ *   GET  /vault/<name>/.parachute/embeddings — read the persisted setting +
+ *                                              the running/effective/env state
+ *   PUT  /vault/<name>/.parachute/embeddings — flip the persisted setting
+ *
+ * The 0.7.3 fast-follow: 0.7.3 shipped the persisted `embeddings_enabled`
+ * config.yaml setting + `resolveEmbeddingsEnabled` (env override → persisted
+ * → off), but the ONLY way to flip it was hand-editing config.yaml or setting
+ * an env var. This module gives the vault admin SPA a real toggle over that
+ * setting.
+ *
+ * URL note: same reasoning as `mirror-routes.ts` — the admin SPA's static
+ * bundle owns `/vault/<name>/admin/*` (vault#252), so the API surface lives
+ * under the `.parachute/` module-protocol namespace (sibling to
+ * `.parachute/config`, `.parachute/mirror`, `.parachute/usage`).
+ *
+ * Auth: `vault:admin`, gated upstream in `routing.ts` (this module is the
+ * after-auth handler). `embeddings_enabled` is host-global config that affects
+ * every vault on the server, but it's reached through the same per-vault admin
+ * surface every other settings page uses; the UI copy names the host-wide
+ * scope.
+ *
+ * **Activation is restart-to-apply, not hot.** The embedding provider is
+ * resolved ONCE at boot (`getSharedEmbeddingProvider`) and captured into every
+ * open store (`Store.embeddingProvider` + `embeddingDisabledReason`, baked at
+ * construction) and into the embedding worker (`EmbeddingWorker.provider`, a
+ * private readonly field). Re-resolving the provider mid-run would mean
+ * mutating readonly fields across the worker AND every already-open store AND
+ * resetting a deliberately-once module memo — not clean. So this endpoint
+ * PERSISTS the setting and reports `restart_required` when the persisted
+ * change hasn't taken effect in the running process yet. Hot-reconfigure is a
+ * possible follow-up.
+ *
+ * **The `EMBEDDINGS_ENABLED` env var still wins.** It's the low-level override
+ * (`true`/`1` on, `false`/`0` off, else defer). When it's forcing a value the
+ * snapshot carries `env_override` so the UI can flag that the persisted toggle
+ * is advisory until the env var is removed — the toggle never lies about
+ * what's actually in force.
+ */
+
+import { readGlobalConfig, writeGlobalConfig } from "./config.ts";
+import { embeddingsEnabledEnvOverride, resolveEmbeddingsEnabled } from "./embedding/select.ts";
+import { isSharedEmbeddingProviderActive } from "./vault-store.ts";
+
+/**
+ * Approximate size of the bundled ONNX model (`bge-small-en-v1.5`, q8) that
+ * lazy-downloads on the FIRST embed after enabling. Surfaced so the UI can
+ * warn before the operator flips the switch. (The npm dependency ships ~270MB
+ * of runtime, but the model weights fetched on first use are ~34MB.)
+ */
+export const EMBEDDING_MODEL_DOWNLOAD_MB = 34;
+
+const CORS = { "Access-Control-Allow-Origin": "*" } as const;
+
+/**
+ * The wire shape the admin SPA reads/writes. Both GET and PUT return this so
+ * the SPA reuses one decoder.
+ */
+export interface EmbeddingsSettingsSnapshot {
+  /**
+   * The persisted `embeddings_enabled` in config.yaml — the value the toggle
+   * reflects. `false` when unset (semantic search is opt-in, default off).
+   */
+  enabled: boolean;
+  /**
+   * The `EMBEDDINGS_ENABLED` env override, tri-state: `true` (forced on),
+   * `false` (forced off), or `null` (no env var — defers to `enabled`). When
+   * non-null the env var wins over the persisted setting.
+   */
+  env_override: boolean | null;
+  /**
+   * Convenience flag: `true` exactly when `env_override` is non-null. The UI
+   * shows an advisory banner ("an env var is forcing this") when set.
+   */
+  env_forced: boolean;
+  /**
+   * What a fresh boot would resolve: env override, else persisted, else off.
+   * This is the state the running process will land in on next restart.
+   */
+  effective: boolean;
+  /**
+   * Whether semantic search is LIVE in the running process right now (the
+   * boot-resolved provider is present). Distinct from `effective`: a flip of
+   * the persisted setting changes `effective` immediately but not `active`.
+   */
+  active: boolean;
+  /**
+   * `true` when `active !== effective` — the operator's intended state is
+   * persisted but the running process hasn't picked it up. Restart to apply.
+   */
+  restart_required: boolean;
+  /** First-enable model-download size hint (MB) for the UI copy. */
+  model_download_mb: number;
+}
+
+/**
+ * Build the snapshot from the persisted setting + env + running state. Pure
+ * over its inputs (env + persisted + active) so it's unit-testable without a
+ * live server; the `active` reading is injected (defaults to the real
+ * process-shared provider state).
+ */
+export function buildEmbeddingsSnapshot(opts?: {
+  env?: NodeJS.ProcessEnv;
+  persistedEnabled?: boolean;
+  active?: boolean;
+}): EmbeddingsSettingsSnapshot {
+  const env = opts?.env ?? process.env;
+  const persisted = opts?.persistedEnabled ?? false;
+  const active = opts?.active ?? isSharedEmbeddingProviderActive();
+  const override = embeddingsEnabledEnvOverride(env);
+  const effective = resolveEmbeddingsEnabled(env, persisted);
+  return {
+    enabled: persisted,
+    env_override: override ?? null,
+    env_forced: override !== undefined,
+    effective,
+    active,
+    restart_required: active !== effective,
+    model_download_mb: EMBEDDING_MODEL_DOWNLOAD_MB,
+  };
+}
+
+/**
+ * `GET /vault/<name>/.parachute/embeddings` — return the current settings
+ * snapshot. Always 200 (auth enforced upstream). `activeOverride` is a test
+ * seam; production passes nothing and the running provider state is read.
+ */
+export function handleEmbeddingsGet(activeOverride?: boolean): Response {
+  const persisted = readGlobalConfig().embeddings_enabled;
+  const snapshot = buildEmbeddingsSnapshot({ persistedEnabled: persisted, active: activeOverride });
+  return Response.json(snapshot, { headers: CORS });
+}
+
+/**
+ * `PUT /vault/<name>/.parachute/embeddings` — persist a new
+ * `embeddings_enabled` value. Body: `{ "enabled": boolean }`.
+ *
+ * Reuses the config write path (`writeGlobalConfig` — never hand-rolls YAML),
+ * so the serialize logic that already knows how to persist `embeddings_enabled`
+ * is the single source of truth. Persists even when the env var is forcing a
+ * value (the operator's persisted intent is recorded; the env override still
+ * wins for `effective`/`active`, and the snapshot says so). Returns the same
+ * shape as GET, reflecting the new persisted value + the unchanged running
+ * state (so `restart_required` is honest right after the write).
+ */
+export async function handleEmbeddingsPut(req: Request, activeOverride?: boolean): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch (err) {
+    return Response.json(
+      { error: "Invalid JSON body", message: (err as Error).message ?? String(err) },
+      { status: 400 },
+    );
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return Response.json(
+      { error: "Invalid body", field: "enabled", message: "Expected a JSON object { enabled: boolean }." },
+      { status: 400 },
+    );
+  }
+  const enabled = (body as { enabled?: unknown }).enabled;
+  if (typeof enabled !== "boolean") {
+    return Response.json(
+      { error: "Invalid body", field: "enabled", message: "`enabled` must be a boolean." },
+      { status: 400 },
+    );
+  }
+
+  const config = readGlobalConfig();
+  config.embeddings_enabled = enabled;
+  writeGlobalConfig(config);
+
+  const snapshot = buildEmbeddingsSnapshot({ persistedEnabled: enabled, active: activeOverride });
+  return Response.json(snapshot, { headers: CORS });
+}

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/routing.test.ts

@@ -2716,6 +2716,135 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/embeddings — semantic-search (embeddings) opt-in
+// toggle admin surface (0.7.3 fast-follow, vault#624).
+//
+// Pins the auth gate + GET/PUT dispatch at the routing layer: the endpoint is
+// `vault:admin`-only (a host-global setting reached through the same per-vault
+// admin surface as the sibling `.parachute/mirror` / `.parachute/config`
+// pages). Snapshot shape + the env-override / restart-required semantics are
+// covered in embeddings-routes.test.ts; here we pin the *security* property —
+// unauth → 401, read/write → 403, admin → 200 + the flip persists — so it
+// can't silently regress below the rest of the admin surface. Mirrors the
+// `.parachute/mirror` auth+dispatch describe above.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/embeddings — auth + dispatch", () => {
+  const P = "/vault/journal/.parachute/embeddings";
+
+  test("unauthenticated GET → 401", async () => {
+    createVault("journal");
+    const res = await route(new Request(`http://localhost:1940${P}`), P);
+    expect(res.status).toBe(401);
+  });
+
+  test("unauthenticated PUT → 401", async () => {
+    createVault("journal");
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token PUT → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("vault:write token PUT → 403 insufficient_scope (write ranks below admin)", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:write"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("cross-vault admin token → 403 (scope names a different vault)", async () => {
+    createVault("journal");
+    createVault("other");
+    // Audience is `journal` (auth passes) but the admin scope names `other`,
+    // so hasScopeForVault denies it against `journal`.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:other:admin"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+  });
+
+  test("vault:admin token GET → 200 (default off); admin PUT persists the flip", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+
+    // GET reaches the handler (auth + admin scope satisfied) → 200 snapshot,
+    // default-off (config seeded with `port` only).
+    const getRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(getRes.status).toBe(200);
+    const getBody = (await getRes.json()) as { enabled?: boolean };
+    expect(getBody.enabled).toBe(false);
+
+    // PUT flips the persisted setting → 200, echoing the new value.
+    const putRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(putRes.status).toBe(200);
+    const putBody = (await putRes.json()) as { enabled?: boolean };
+    expect(putBody.enabled).toBe(true);
+
+    // A follow-up GET reads the persisted value back → the write stuck.
+    const reGet = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(reGet.status).toBe(200);
+    const reBody = (await reGet.json()) as { enabled?: boolean };
+    expect(reBody.enabled).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
 // alongside the SPA UI. Tests pin the auth gate matches the parent