@openparachute/vault 0.7.3-rc.5 → 0.7.3-rc.7

package/core/src/search-query.test.ts

@@ -4,6 +4,7 @@ import {
   escapeFtsToken,
   buildLiteralSearchQuery,
   isValidSearchMode,
+  extractLiteralBoostTerms,
 } from "./search-query.js";
 
 describe("escapeFtsToken", () => {
@@ -147,3 +148,44 @@ describe("isValidSearchMode / SEARCH_MODES", () => {
     expect(isValidSearchMode(["literal"])).toBe(false);
   });
 });
+
+describe("extractLiteralBoostTerms (search title-boost input, title axis)", () => {
+  it("lowercases and whitespace-splits", () => {
+    expect(extractLiteralBoostTerms("Budget Review")).toEqual(["budget", "review"]);
+  });
+
+  it("collapses whitespace runs", () => {
+    expect(extractLiteralBoostTerms("widgets    gadgets")).toEqual(["widgets", "gadgets"]);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    expect(extractLiteralBoostTerms("  widgets  ")).toEqual(["widgets"]);
+  });
+
+  it("strips literal quote characters a caller typed, unlike buildLiteralSearchQuery", () => {
+    // buildLiteralSearchQuery treats a manually-typed `"` as ordinary
+    // content (escaped into the FTS phrase); the boost-term extractor
+    // strips it instead, since a title-string comparison shouldn't
+    // require the title to contain a literal quote mark.
+    expect(extractLiteralBoostTerms(`"eleven-day capping delay"`)).toEqual([
+      "eleven-day",
+      "capping",
+      "delay",
+    ]);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(extractLiteralBoostTerms("eleven-day")).toEqual(["eleven-day"]);
+    expect(extractLiteralBoostTerms("18.6")).toEqual(["18.6"]);
+    expect(extractLiteralBoostTerms("didn't")).toEqual(["didn't"]);
+  });
+
+  it("returns an empty array for blank/whitespace-only input", () => {
+    expect(extractLiteralBoostTerms("")).toEqual([]);
+    expect(extractLiteralBoostTerms("   ")).toEqual([]);
+  });
+
+  it("sanitizes control characters as separators, matching buildLiteralSearchQuery", () => {
+    expect(extractLiteralBoostTerms("hello\x00world")).toEqual(["hello", "world"]);
+  });
+});

package/core/src/search-query.ts

@@ -153,3 +153,30 @@ export function buildLiteralSearchQuery(raw: string): LiteralSearchQuery {
   const tokens = cleaned.trim().split(/\s+/).filter(Boolean);
   return { query: tokens.map(escapeFtsToken).join(" "), isEmpty: false };
 }
+
+/**
+ * Extract lowercase whitespace-delimited terms from raw literal-mode search
+ * text, for the search title-boost post-rank (title axis, ratified
+ * 2026-07-17) — NOT used to build the FTS5 MATCH query itself (that's
+ * `buildLiteralSearchQuery`, above). Sanitizes control characters the same
+ * way, plus strips any literal `"` a caller typed (kept as ordinary content
+ * by `buildLiteralSearchQuery`, but a display-title substring check
+ * shouldn't require the title to contain a literal quote mark).
+ *
+ * This is a heuristic re-rank signal, not a second index — it deliberately
+ * does not attempt FTS5-tokenizer parity (stemming, unicode normalization).
+ * It only needs to answer "does the note's first line plausibly contain the
+ * query," not reproduce FTS5's match semantics exactly. Restricted to
+ * literal-mode callers by convention (see `core/src/notes.ts` `searchNotes`)
+ * — `search_mode: "advanced"` text carries FTS5 boolean/column/prefix
+ * operators (`AND`, `path:`, `foo*`) that would leak into the term list as
+ * false "content" if tokenized the same naive way.
+ */
+export function extractLiteralBoostTerms(raw: string): string[] {
+  const cleaned = raw.replace(CONTROL_CHARS, " ").toLowerCase();
+  return cleaned
+    .trim()
+    .split(/\s+/)
+    .map((t) => t.replace(/^"+|"+$/g, ""))
+    .filter(Boolean);
+}

package/core/src/search-title-boost.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Search title-boost (title axis, ratified 2026-07-17): literal-mode
+ * search results whose `displayTitle` (first non-empty content line, NOT
+ * `path`) contains every query term are post-ranked ahead of body-only
+ * matches. No-migration — an in-memory re-rank of the already-fetched
+ * page, not a `notes_fts` schema change (see `applySearchTitleBoost` /
+ * `boostTitleMatches` in `notes.ts`).
+ *
+ * This is a DIFFERENT axis from the existing `path`-weighted bm25 ranking
+ * covered in `search-fts-v25.test.ts` — a note's title here is its first
+ * CONTENT line, not its `path`.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("search title-boost", () => {
+  it("ranks a first-line (title) match above a body-only match", async () => {
+    // Body-only match: "budget" appears only deep in the body, first line
+    // is unrelated.
+    await store.createNote(
+      "Weekly Standup\nlots of unrelated notes here, but somewhere we discuss the budget in passing",
+      { path: "standup-notes" },
+    );
+    // First-line (title) match: "Budget" is the first line itself.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "budget-review" });
+
+    const hits = await store.searchNotes("budget");
+    expect(hits.length).toBeGreaterThanOrEqual(2);
+    expect(hits[0].path).toBe("budget-review");
+  });
+
+  it("requires ALL query terms to be present in the first line to boost (a partial title match doesn't qualify)", async () => {
+    // "budget" is in the title but "review" is only in the body — a
+    // PARTIAL title match, which stays in the body-only tier.
+    await store.createNote("Budget notes\nsee the quarterly review for details", { path: "partial" });
+    // Both "budget" and "review" are in the title — a FULL title match.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "full-match" });
+
+    const hits = await store.searchNotes("budget review");
+    expect(hits.map((n) => n.path)).toEqual(["full-match", "partial"]);
+  });
+
+  it("ties (both notes in the same tier) keep the existing relevance order", async () => {
+    // Two title-matching notes plus one body-only note. Comparing literal
+    // mode (boosted) against advanced mode with the same plain-word query
+    // (identical FTS5 syntax, so identical underlying bm25 order, but no
+    // boost pass) isolates the boost's effect: within the title-match
+    // tier, the boost must preserve whatever relative order the
+    // underlying relevance ranking already gave — a stable sort, not a
+    // fresh comparator that could reshuffle ties.
+    await store.createNote("Project Widget\nfirst, mentions widget again for relevance", { path: "w1" });
+    await store.createNote("Project Widget\nsecond", { path: "w2" });
+    await store.createNote("Unrelated\nbody-only mention of widget project", { path: "body-only" });
+
+    const boosted = await store.searchNotes("widget project");
+    const rawOrder = await store.searchNotes("widget project", { mode: "advanced" });
+
+    const titleTierBoosted = boosted.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    const titleTierRaw = rawOrder.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    expect(titleTierBoosted).toEqual(titleTierRaw);
+    // The title-match tier precedes the body-only note in the boosted result.
+    expect(boosted.map((n) => n.path).indexOf("body-only")).toBeGreaterThan(
+      Math.max(...["w1", "w2"].map((p) => boosted.map((n) => n.path).indexOf(p))),
+    );
+  });
+
+  it("does not disturb ordering when an explicit sort is requested", async () => {
+    await store.createNote("Zebra body-only mention of gadget", { path: "z" });
+    await store.createNote("Gadget Launch\nfirst line title match", { path: "a" });
+
+    const asc = await store.searchNotes("gadget", { sort: "asc" });
+    // created_at ASC means "z" (created first) comes before "a" — the
+    // title-boost must NOT override an explicit sort.
+    expect(asc.map((n) => n.path)).toEqual(["z", "a"]);
+  });
+
+  it("does not apply the boost under search_mode: advanced (raw FTS5 syntax, not naively tokenizable)", async () => {
+    await store.createNote("Body only mentions gadget in passing text here", { path: "body-only" });
+    await store.createNote("Gadget\nfirst line title match", { path: "title-match" });
+
+    const advanced = await store.searchNotes("gadget", { mode: "advanced" });
+    const literal = await store.searchNotes("gadget");
+
+    // Literal mode boosts the title match to the front.
+    expect(literal[0].path).toBe("title-match");
+    // Advanced mode is unaffected by the boost — order comes from bm25
+    // relevance alone (title-match still likely ranks first via the
+    // EXISTING path-weighted bm25, but that's a different mechanism; the
+    // test here just confirms advanced mode doesn't throw and returns
+    // both notes, not that ordering matches/mismatches literal mode).
+    expect(advanced.map((n) => n.path).sort()).toEqual(["body-only", "title-match"]);
+  });
+
+  it("a query with no results is unaffected (empty array in, empty array out)", async () => {
+    const hits = await store.searchNotes("nonexistent_term_xyz");
+    expect(hits).toEqual([]);
+  });
+});

package/core/src/types.ts

@@ -400,6 +400,12 @@ export interface NoteIndex {
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;
+  /** Derived from the first non-empty line of content (title axis, ratified
+   *  2026-07-17) — NEVER stored, computed fresh at read time by
+   *  `computeDisplayTitle`. `null` when content has no non-empty line.
+   *  Surfaces decide how to render a `null` title (e.g. a timestamp/path
+   *  fallback); core just reports the honest content-derived value. */
+  displayTitle: string | null;
   /** Opt-in link degree (see `Note.linkCount`). */
   linkCount?: number;
   /** Full-text search relevance score (see `Note.score`). Carried onto the

package/core/src/vault-projection.ts

@@ -272,6 +272,42 @@ function sqliteToUserType(t: string): string {
   return t.toLowerCase();
 }
 
+// ---------------------------------------------------------------------------
+// Attachments orientation block (attachment-tickets design, Wave 0+1)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Attachments orientation block, rendered into the connect-time
+ * markdown brief (`projectionToMarkdown`) so every agent learns, every
+ * session, how to move file bytes into/out of this vault without spending
+ * its own context on them (bytes never ride MCP either way).
+ *
+ * `ticketsEnabled` reflects whether THIS door has wired an
+ * `AttachmentTicketProvider` (bun: always, as of this PR; cloud: not yet
+ * — its mirror is a separate PR). An unwired door omits BOTH the ticket
+ * tools from `tools/list` (see `generateMcpTools`'s `attachmentTickets`
+ * opt) AND the ticket-tool sentences here — the brief never dangles a
+ * pointer at a tool the agent can't actually call.
+ *
+ * Kept as a single dense paragraph (not its own multi-line list) to stay
+ * inside the connect-time brief's token budget — see
+ * `projectionToMarkdown`'s doc comment.
+ */
+export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean }): string {
+  const sentences: string[] = [
+    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP).",
+  ];
+  if (opts.ticketsEnabled) {
+    sentences.push(
+      "To move bytes, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+    );
+  }
+  sentences.push(
+    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer`. Audio attached with `transcribe: true` is transcribed automatically.",
+  );
+  return sentences.join(" ");
+}
+
 // ---------------------------------------------------------------------------
 // Markdown rendering — for getServerInstruction
 // ---------------------------------------------------------------------------
@@ -302,6 +338,13 @@ export function projectionToMarkdown(args: {
    * known and always surfaced. See `chooseHubOrigin` (src/mcp-install.ts).
    */
   coordinates?: { hubOrigin: string; hubOriginKnown: boolean };
+  /**
+   * Attachments orientation (see `attachmentsInstructionBlock`). Omitted
+   * defaults to `{ ticketsEnabled: false }` — safe-by-default so a caller
+   * that hasn't wired ticket support yet (or a test fixture) never
+   * accidentally advertises tools it can't back.
+   */
+  attachments?: { ticketsEnabled: boolean };
 }): string {
   const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;
@@ -418,6 +461,11 @@ export function projectionToMarkdown(args: {
   lines.push("");
   lines.push("If schema or tags change during this session, call `vault-info` to refresh the full projection. Call `list-tags { include_schema: true }` for tag-only details.");
 
+  lines.push("");
+  lines.push("## Attachments");
+  lines.push("");
+  lines.push(attachmentsInstructionBlock(args.attachments ?? { ticketsEnabled: false }));
+
   // Scripting pointer block: the connect-time brief used to dead-end on
   // querying — an agent had no path to "how do I script/automate against this
   // vault." Point at the guide rather than inlining it, to keep this brief

package/package.json

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

package/src/attachment-tickets.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Attachment tickets — end-to-end lifecycle (mint via the real MCP tool
+ * call path, spend via the real unauthenticated `/vault/<name>/tickets/<id>`
+ * route dispatched through `routing.ts`'s `route()`). Covers the Wave 1
+ * security posture: single-use, TTL/expiry, size-cap, wrong-vault scoping,
+ * uniform 404, upload→row+transcribe, download streaming + path
+ * confinement, and the connect-time instructions block.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const testDir = join(
+  tmpdir(),
+  `vault-attachment-tickets-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+);
+process.env.PARACHUTE_HOME = testDir;
+// Deliberately NOT setting ASSETS_DIR (unlike storage.test.ts, which wants a
+// single shared assets root for its own reasons): that env var is global to
+// the whole `bun test` process (all files share one Node process), so
+// setting it here would leak into every OTHER test file's assetsDir() calls
+// too. Each vault below gets a unique, unset-ASSETS_DIR-default assets dir
+// (`vaultDir(name)/assets`) scoped under this file's own unique
+// PARACHUTE_HOME — fully isolated without needing the override.
+
+const { route } = await import("./routing.ts");
+const { handleScopedMcp } = await import("./mcp-http.ts");
+const { getServerInstruction } = await import("./mcp-tools.ts");
+const { writeVaultConfig } = await import("./config.ts");
+const { getVaultStore } = await import("./vault-store.ts");
+const { getSharedAttachmentTicketProvider } = await import("./attachment-tickets.ts");
+const { attachmentsInstructionBlock } = await import("../core/src/vault-projection.ts");
+
+/** `route()` takes the pathname as a separate arg (server.ts derives it from `req.url`) — this wrapper matches that call shape everywhere below. */
+async function routeReq(req: Request): Promise<Response> {
+  return route(req, new URL(req.url).pathname);
+}
+
+function freshVault(prefix: string): string {
+  const name = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  return name;
+}
+
+/** Bypasses `authenticateVaultRequest` the same way vault.test.ts's scope-tier tests do — a fabricated already-resolved auth object. */
+function mcpAuth(scopes: string[]) {
+  return {
+    permission: scopes.includes("vault:write") || scopes.includes("vault:admin") ? "full" : "read",
+    scopes,
+    legacyDerived: false,
+    scoped_tags: null,
+  } as any;
+}
+
+async function callTool(vaultName: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const req = new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const res = await handleScopedMcp(req, vaultName, mcpAuth(["vault:read", "vault:write"]));
+  const body = (await res.json()) as any;
+  if (body.error) {
+    const err = new Error(body.error.message);
+    Object.assign(err, body.error.data ?? {});
+    throw err;
+  }
+  return JSON.parse(body.result.content[0].text);
+}
+
+describe("attachment tickets — upload lifecycle", () => {
+  test("mint → spend → row registered with size + original_name; second spend of the same ticket 404s", async () => {
+    const vaultName = freshVault("tickets-upload");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# Target\n", { path: "target" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "photo.png",
+      size_bytes: 5,
+      mime_type: "image/png",
+    });
+    expect(mint.method).toBe("PUT");
+    expect(mint.url).toContain(`/vault/${vaultName}/tickets/`);
+    expect(mint.max_bytes).toBe(5);
+
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const spendRes = await routeReq(
+      new Request(mint.url, { method: "PUT", headers: { "content-type": "image/png" }, body: bytes }),
+    );
+    expect(spendRes.status).toBe(201);
+    const attachment = (await spendRes.json()) as any;
+    expect(attachment.noteId).toBe(note.id);
+    expect(attachment.mimeType).toBe("image/png");
+    expect(attachment.metadata.original_name).toBe("photo.png");
+    expect(attachment.metadata.size).toBe(5);
+
+    const rows = await store.getAttachments(note.id);
+    expect(rows.length).toBe(1);
+    expect(rows[0]!.id).toBe(attachment.id);
+
+    // Single-use: the ticket is gone after one spend — uniform 404, no
+    // oracle distinguishing "spent" from "never existed".
+    const secondRes = await routeReq(
+      new Request(mint.url, { method: "PUT", headers: { "content-type": "image/png" }, body: new Uint8Array([9]) }),
+    );
+    expect(secondRes.status).toBe(404);
+    const secondBody = (await secondRes.json()) as any;
+    expect(secondBody.error_type).toBe("not_found");
+    expect(typeof secondBody.how_to).toBe("string");
+
+    // A second upload wasn't registered.
+    expect((await store.getAttachments(note.id)).length).toBe(1);
+  });
+
+  test("POST also spends an upload ticket (accepted alongside the advertised PUT)", async () => {
+    const vaultName = freshVault("tickets-upload-post");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "a.txt",
+      size_bytes: 3,
+    });
+    const res = await routeReq(
+      new Request(mint.url, { method: "POST", headers: { "content-type": "text/plain" }, body: new Uint8Array([1, 2, 3]) }),
+    );
+    expect(res.status).toBe(201);
+  });
+
+  test("size-cap: an upload exceeding the ticket's declared size_bytes is rejected 413 and no row is created", async () => {
+    const vaultName = freshVault("tickets-size-cap");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "small.bin",
+      size_bytes: 3,
+    });
+    const res = await routeReq(
+      new Request(mint.url, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]),
+      }),
+    );
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as any;
+    expect(body.error_type).toBe("file_too_large");
+    expect(body.limit).toBe(3);
+    expect(typeof body.how_to).toBe("string");
+    expect((await store.getAttachments(note.id)).length).toBe(0);
+  });
+
+  test("a mismatched Content-Length header alone is rejected 413 before the body is even read", async () => {
+    const vaultName = freshVault("tickets-cl-cap");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "small.bin",
+      size_bytes: 3,
+    });
+    const res = await routeReq(
+      new Request(mint.url, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream", "content-length": "1000000" },
+        body: new Uint8Array([1, 2, 3]),
+      }),
+    );
+    expect(res.status).toBe(413);
+  });
+
+  test("expiry: a ticket past its expires_at is rejected 404 even though it was never spent", async () => {
+    const vaultName = freshVault("tickets-expiry");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+
+    const provider = getSharedAttachmentTicketProvider();
+    const id = "e".repeat(64);
+    await provider.put({
+      id,
+      kind: "upload",
+      vaultName,
+      createdAt: Date.now() - 1000,
+      expiresAt: Date.now() - 1, // already expired
+      noteId: note.id,
+      filename: "late.bin",
+      mimeType: "application/octet-stream",
+      sizeBytes: 10,
+    });
+
+    const res = await routeReq(
+      new Request(`http://localhost:1940/vault/${vaultName}/tickets/${id}`, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Uint8Array([1]),
+      }),
+    );
+    expect(res.status).toBe(404);
+    expect((await store.getAttachments(note.id)).length).toBe(0);
+  });
+
+  test("wrong-vault scope: a ticket minted for vault A can't be spent against vault B's URL", async () => {
+    const vaultA = freshVault("tickets-vault-a");
+    const vaultB = freshVault("tickets-vault-b");
+    const storeA = getVaultStore(vaultA);
+    const note = await storeA.createNote("# T\n", { path: "t" });
+
+    const mint = await callTool(vaultA, "request-attachment-upload", {
+      note: note.id,
+      filename: "a.bin",
+      size_bytes: 3,
+    });
+    const ticketId = mint.url.split("/tickets/")[1] as string;
+
+    const crossVaultRes = await routeReq(
+      new Request(`http://localhost:1940/vault/${vaultB}/tickets/${ticketId}`, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Uint8Array([1, 2, 3]),
+      }),
+    );
+    expect(crossVaultRes.status).toBe(404);
+
+    // `take()` deletes on lookup regardless of which vault asked — a
+    // wrong-vault spend attempt still burns the ticket (single-use is
+    // enforced by the delete, vault-match is a SEPARATE check layered on
+    // top). Documenting this: the ticket is gone even for the correct
+    // vault after the cross-vault probe above.
+    const correctRes = await routeReq(
+      new Request(mint.url, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Uint8Array([1, 2, 3]),
+      }),
+    );
+    expect(correctRes.status).toBe(404);
+  });
+
+  test("transcribe: true rides through to the attachment row and stamps the note's transcribe_stub", async () => {
+    const vaultName = freshVault("tickets-transcribe");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# Voice memo\n", { path: "memo" });
+
+    const mint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "memo.wav",
+      size_bytes: 4,
+      transcribe: true,
+    });
+    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.transcribe_status).toBe("pending");
+    expect(attachment.metadata.transcribe_origin).toBe("legacy");
+
+    const updatedNote = await store.getNote(note.id);
+    expect((updatedNote!.metadata as any)?.transcribe_stub).toBe(true);
+  });
+
+  test("blocked extension is refused at MINT — no ticket is ever created", async () => {
+    const vaultName = freshVault("tickets-blocked-ext");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+    await expect(
+      callTool(vaultName, "request-attachment-upload", { note: note.id, filename: "evil.svg", size_bytes: 10 }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("attachment tickets — download lifecycle", () => {
+  test("mint → spend streams the exact bytes with the attachment's content-type", async () => {
+    const vaultName = freshVault("tickets-download");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+
+    const uploadMint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "data.bin",
+      size_bytes: 4,
+      mime_type: "application/octet-stream",
+    });
+    const uploadRes = await routeReq(
+      new Request(uploadMint.url, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Uint8Array([10, 20, 30, 40]),
+      }),
+    );
+    const attachment = (await uploadRes.json()) as any;
+
+    const downloadMint = await callTool(vaultName, "request-attachment-download", {
+      attachment_id: attachment.id,
+    });
+    expect(downloadMint.method).toBe("GET");
+    expect(downloadMint.mime_type).toBe("application/octet-stream");
+
+    const downloadRes = await routeReq(new Request(downloadMint.url, { method: "GET" }));
+    expect(downloadRes.status).toBe(200);
+    expect(downloadRes.headers.get("content-type")).toBe("application/octet-stream");
+    expect(downloadRes.headers.get("x-content-type-options")).toBe("nosniff");
+    const body = new Uint8Array(await downloadRes.arrayBuffer());
+    expect(Array.from(body)).toEqual([10, 20, 30, 40]);
+
+    // Single-use on the download side too.
+    const secondRes = await routeReq(new Request(downloadMint.url, { method: "GET" }));
+    expect(secondRes.status).toBe(404);
+  });
+
+  test("path confinement: an attachment row pointing outside assetsDir can't be walked to via a download ticket", async () => {
+    const vaultName = freshVault("tickets-confinement");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+    // A row with a traversal path could only arrive via a bug elsewhere
+    // (tickets themselves never accept a caller-supplied path) — this pins
+    // the download spend route's OWN confinement guard as defense-in-depth.
+    const attachment = await store.addAttachment(note.id, "../../../../etc/passwd", "text/plain");
+
+    const downloadMint = await callTool(vaultName, "request-attachment-download", {
+      attachment_id: attachment.id,
+    });
+    const res = await routeReq(new Request(downloadMint.url, { method: "GET" }));
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("attachment tickets — discoverability", () => {
+  test("attachmentsInstructionBlock teaches the ticket tools when enabled, and omits them when not", () => {
+    const enabled = attachmentsInstructionBlock({ ticketsEnabled: true });
+    expect(enabled).toContain("request-attachment-upload");
+    expect(enabled).toContain("request-attachment-download");
+    expect(enabled).toContain("curl_example");
+
+    const disabled = attachmentsInstructionBlock({ ticketsEnabled: false });
+    expect(disabled).not.toContain("request-attachment-upload");
+    // The REST fallback recipe is always present, wired or not.
+    expect(disabled).toContain("/storage/upload");
+  });
+
+  test("bun's connect-time getServerInstruction includes the Attachments section and teaches the ticket tools", async () => {
+    const vaultName = freshVault("tickets-instructions");
+    const md = await getServerInstruction(vaultName);
+    expect(md).toContain("## Attachments");
+    expect(md).toContain("request-attachment-upload");
+  });
+});