@openparachute/vault 0.7.3-rc.1 → 0.7.3-rc.10

package/core/src/mcp.ts

@@ -13,6 +13,7 @@ import {
   truncatedResultsWarning,
   computeSearchDidYouMean,
   searchDidYouMeanWarning,
+  embeddingsPendingWarning,
   type QueryWarning,
 } from "./query-warnings.js";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
@@ -44,6 +45,18 @@ import {
   contentRangeRequiresContent,
   MIN_CONTENT_LENGTH,
 } from "./content-range.js";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  sanitizeAttachmentExtension,
+  mimeForAttachmentExtension,
+} from "./attachment/policy.js";
+import {
+  computeTicketTtlMs,
+  generateTicketId,
+  MAX_TICKET_UPLOAD_BYTES,
+  type AttachmentTicket,
+  type AttachmentTicketProvider,
+} from "./attachment/tickets.js";
 
 export interface McpToolDef {
   name: string;
@@ -79,7 +92,7 @@ export interface McpToolDef {
  */
 function structuredError(
   message: string,
-  fields: { error_type: string; field?: string; hint?: string },
+  fields: { error_type: string; field?: string; hint?: string } & Record<string, unknown>,
 ): Error {
   return Object.assign(new Error(message), fields);
 }
@@ -245,6 +258,39 @@ export interface GenerateMcpToolsOpts {
    * path with no extra fetch.
    */
   aggregateVisibility?: (note: Note) => boolean;
+  /**
+   * `AttachmentTicketProvider` seam (vault attachment-tickets design,
+   * Wave 1 — D10 "tools omitted when unwired"). When provided,
+   * `generateMcpTools` appends `request-attachment-upload` /
+   * `request-attachment-download` to the returned tool list. Omitted (a
+   * door that hasn't wired its ticket seam yet) → the two tools are
+   * ABSENT from the list entirely — not merely erroring on call — so an
+   * agent is never shown an affordance the runtime can't back.
+   */
+  attachmentTickets?: {
+    provider: AttachmentTicketProvider;
+    /** This vault's own name — stamped onto every minted ticket so the spend route can cheaply reject a cross-vault replay. */
+    vaultName: string;
+    /**
+     * Absolute base URL for this vault's ticket spend path, no trailing
+     * slash — e.g. `https://host/vault/<name>`. A minted ticket's URL is
+     * `${urlBase}/tickets/<id>`. Resolved by the caller (server layer)
+     * from the incoming request's `X-Forwarded-Host`/proto — core stays
+     * request-unaware.
+     */
+    urlBase: string;
+    /**
+     * OPTIONAL per-note visibility predicate (tag-scope confidentiality —
+     * same intent as `expandVisibility`/`ifExistsVisible` above, kept
+     * separate because it needs to be awaitable). Both ticket tools run
+     * fully async execute() paths (unlike `expandVisibility`/
+     * `ifExistsVisible`, which feed core's SYNCHRONOUS wikilink/if_exists
+     * code and so need the shared pre-resolved-allowlist-holder
+     * machinery), so this can just be awaited inline. Omitted (unscoped /
+     * internal callers) → every note/attachment is visible.
+     */
+    noteVisible?: (note: Note) => boolean | Promise<boolean>;
+  };
 }
 
 /**
@@ -311,7 +357,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     });
   };
 
-  return [
+  const tools: McpToolDef[] = [
 
     // =====================================================================
     // 1. query-notes — the universal read tool
@@ -412,6 +458,16 @@ Response shape (vault#550 — three variants, pick by what you passed):
             description:
               'How `search` text is turned into an FTS5 query (vault#551). "literal" (DEFAULT): escape + phrase-quote the text so punctuation is literal content, not FTS5 syntax — the fix for `search: "didn\'t"` / "eleven-day" / "18.6" silently returning `[]`. "advanced": pass the text through to FTS5 raw, for callers who want boolean (AND/OR/NOT), manual phrase quoting, or prefix (`*`) syntax — a malformed advanced query throws a structured error (`error_type: "invalid_search_syntax"`) instead of silently returning `[]`. Has no effect without `search` (an `ignored_param` warning fires if you pass it without `search`). Omit for the default ("literal").',
           },
+          near_text: {
+            type: "string",
+            description:
+              'EXPERIMENTAL (semantic search MVP — may change or be removed while quality is validated). Free text to rank notes by MEANING rather than keyword — "that idea about music remixes as community building" finds the note even if it never uses those exact words. Requires `semantic: true`; mutually exclusive with `search`/`aggregate`/`cursor`. Composes with every other filter (`tag`, `metadata`, date range, ...) exactly like `search` does — those narrow the candidate set FIRST, then ranking runs over just that set. Long notes are chunked internally and ranked by their BEST-matching section, so a match buried in one part of a long note still surfaces the whole note. Results carry a `score` field — cosine similarity in `[-1, 1]` (typically 0.2–0.9), NOT the same scale as `search`\'s bm25 `score`; only meaningful as a relative ranking within one result set.',
+          },
+          semantic: {
+            type: "boolean",
+            description:
+              'EXPERIMENTAL. Opt into vector ranking via `near_text` (required when true). No embedding provider configured, or the vault hasn\'t finished indexing, is reported HONESTLY — never a silent fallback to keyword search: a provider-less vault throws a structured `semantic_unavailable` error; a mid-backfill vault returns real (possibly partial) results plus an `embeddings_pending` warning naming how many candidate notes aren\'t embedded yet.',
+          },
           metadata: {
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
@@ -499,7 +555,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           include_attachments: { type: "boolean", description: "Include attachment records (default: false)" },
           expand_links: { type: "boolean", description: "Inline [[wikilinks]] in returned content (default: false). Has no effect if content is not included (e.g., default list mode with include_content=false); wikilinks inside fenced or inline code are not expanded." },
           expand_depth: { type: "number", description: "Recursion depth for link expansion (default 1, max 3). Only meaningful in 'full' mode — 'summary' mode does not recurse." },
-          expand_mode: { type: "string", enum: ["full", "summary"], description: "Expansion rendering: 'full' inlines the linked note's content, 'summary' inlines only metadata.summary. Default: 'full'." },
+          expand_mode: { type: "string", enum: ["full", "summary"], description: "Expansion rendering: 'full' inlines the linked note's content, 'summary' inlines metadata.summary — falling back to the note's opening paragraph when no metadata.summary exists. Default: 'full'." },
         },
       },
       execute: async (params) => {
@@ -640,6 +696,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
             "INVALID_QUERY",
           );
         }
+        if (cursorMode && params.semantic) {
+          throw new QueryError(
+            `cursor is incompatible with semantic search — ranking is by similarity, not a stable row order to page through.`,
+            "INVALID_QUERY",
+          );
+        }
         // Tag-expansion axis (vault tag `expand` axis). Validate loudly so a
         // typo'd value doesn't silently fall back to the default.
         let expand: TagExpandMode | undefined;
@@ -679,6 +741,13 @@ Response shape (vault#550 — three variants, pick by what you passed):
               { error_type: "invalid_query", field: "aggregate", hint: "drop `cursor` when using `aggregate`" },
             );
           }
+          if (params.semantic) {
+            throw new QueryError(
+              `aggregate is incompatible with semantic search — a rollup returns groups, not ranked notes.`,
+              "INVALID_QUERY",
+              { error_type: "invalid_query", field: "aggregate", hint: "drop `semantic`/`near_text` when using `aggregate`" },
+            );
+          }
           const aggRaw = params.aggregate as Record<string, unknown>;
           if (typeof aggRaw !== "object" || aggRaw === null || Array.isArray(aggRaw)) {
             throw new QueryError(
@@ -771,7 +840,93 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // before the result reaches the caller, so an out-of-scope tag name
         // never leaks via `did_you_mean`.
         let queryWarnings: QueryWarning[] = [];
-        if (params.search) {
+        // `near_text` only does anything alongside `semantic: true` (mirrors
+        // the `search_mode`-without-`search` ignored_param case above).
+        if (params.near_text !== undefined && !params.semantic) {
+          queryWarnings.push(
+            ignoredParamWarning(
+              "near_text",
+              "`semantic: true` is required to activate near_text — pass both together",
+            ),
+          );
+        }
+        // --- Semantic search (EXPERIMENTAL — semantic search MVP) ---
+        if (params.semantic) {
+          if (params.search) {
+            throw new QueryError(
+              `semantic is incompatible with full-text search — pick one (semantic ranks by meaning via near_text; search ranks by keyword).`,
+              "INVALID_QUERY",
+              {
+                error_type: "invalid_query",
+                field: "semantic",
+                hint: "drop `search` when using `semantic`, or drop `semantic`/`near_text` to use keyword search",
+              },
+            );
+          }
+          if (typeof params.near_text !== "string" || params.near_text.trim() === "") {
+            throw new QueryError(
+              `semantic: true requires \`near_text\` — the free text to rank notes by meaning.`,
+              "INVALID_QUERY",
+              {
+                error_type: "invalid_query",
+                field: "near_text",
+                hint: `pass near_text: "..." alongside semantic: true`,
+              },
+            );
+          }
+          // `search_mode` only shapes `search` text parsing — a stray value
+          // alongside `semantic` is almost certainly a leftover from a
+          // keyword query, so flag it (same policy as the structured-query
+          // branch below).
+          if (searchMode !== undefined) {
+            queryWarnings.push(
+              ignoredParamWarning(
+                "search_mode",
+                "no `search` was provided — search_mode only affects full-text search query parsing",
+              ),
+            );
+          }
+          const tags = normalizeTags(params.tag);
+          const excludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
+          const excludeTags = normalizeTags(excludeTagsRaw);
+          const semanticOpts: QueryOpts = {
+            tags,
+            tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+            expand,
+            excludeTags,
+            hasTags: params.has_tags as boolean | undefined,
+            hasLinks: params.has_links as boolean | undefined,
+            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            path: params.path as string | undefined,
+            pathPrefix: params.path_prefix as string | undefined,
+            extension: params.extension as string | string[] | undefined,
+            // Same `near[]` neighborhood push-down `search`/structured-query
+            // use — a semantic query can be scoped to a graph neighborhood too.
+            ids: nearScope ? [...nearScope] : undefined,
+            metadata: params.metadata as Record<string, unknown> | undefined,
+            createdBy: params.created_by as string | undefined,
+            lastUpdatedBy: params.last_updated_by as string | undefined,
+            createdVia: params.created_via as string | undefined,
+            lastUpdatedVia: params.last_updated_via as string | undefined,
+            dateFrom: params.date_from as string | undefined,
+            dateTo: params.date_to as string | undefined,
+            dateFilter: params.date_filter as
+              | { field?: string; from?: string; to?: string }
+              | undefined,
+            limit: (params.limit as number) ?? 50,
+          };
+          // Uncaught on purpose: `semantic_unavailable` (no/not-ready
+          // provider) propagates to src/mcp-http.ts's QueryError → JSON-RPC
+          // error mapping, same as `invalid_search_syntax` above — never a
+          // silent fallback to keyword search.
+          const semanticResult = await store.semanticSearch(params.near_text, semanticOpts);
+          results = semanticResult.notes;
+          if (semanticResult.pendingCount > 0) {
+            queryWarnings.push(
+              embeddingsPendingWarning(semanticResult.pendingCount, semanticResult.totalCandidates),
+            );
+          }
+        } else if (params.search) {
           // `offset` under full-text search (vault contracts-brief V1.2):
           // `searchNotes` has no offset parameter at all — FTS5 ranks by
           // relevance, not a stable row order, so paging by offset over it
@@ -1245,6 +1400,12 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
               ...updates,
               actor: writeActor,
               via: writeVia,
+              // `tagsForSchemaResolution` (vault#date-field-type review round
+              // 2) — same bug/fix as the update-note handler: `store.tagNote`
+              // below runs AFTER this UPDATE, so without the PROJECTED tag
+              // set here, `date`-field normalization inside store.updateNote
+              // would miss a field newly declared by an incoming tag.
+              tagsForSchemaResolution: [...projectedTags],
             });
           }
 
@@ -1503,7 +1664,7 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
 - For batch: pass a \`notes\` array, each with an \`id\` field.
 - **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
-- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`, \`displayTitle\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present. \`displayTitle\` is the note's first non-empty content line (heading markers stripped, ~120 chars max), \`null\` when content is empty — never stored, computed fresh from content already in hand.
 
 Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
       inputSchema: {
@@ -1577,7 +1738,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           include_content: {
             type: "boolean",
-            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a computed `displayTitle`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
           },
           include_links: {
             type: "boolean",
@@ -1960,10 +2121,18 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             // --- Strict-schema gate (vault#299 Part A) ---
             // Validate the PROSPECTIVE shape (final tags + merged metadata,
             // including a state_transition's `to`) before the write so a
-            // rejection leaves the note untouched.
+            // rejection leaves the note untouched. `projectedTags` is hoisted
+            // out of this block (not just used here) — the `store.updateNote`
+            // call below also needs it, as `tagsForSchemaResolution`, so that
+            // `date`-field normalization sees a tag ADDED in this SAME call
+            // (vault#date-field-type review round 2 — the actual `store.tagNote`
+            // mutation happens AFTER the core UPDATE, so without this the
+            // schema resolution inside `store.updateNote` would still be
+            // looking at the note's stale pre-write tag set).
+            let projectedTags: Set<string>;
             {
               const removeSet = new Set<string>((item.tags as any)?.remove ?? []);
-              const projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
+              projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
               for (const t of ((item.tags as any)?.add as string[] | undefined) ?? []) projectedTags.add(t);
               const baseMeta = updates.metadata ?? ((note.metadata as Record<string, unknown>) ?? {});
               const projectedMeta = stItem !== undefined
@@ -2007,6 +2176,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // updated_at on a no-op).
               updates.actor = writeActor;
               updates.via = writeVia;
+              // `tagsForSchemaResolution` (vault#date-field-type review round
+              // 2) — the PROJECTED final tag set, so `date`-field
+              // normalization inside store.updateNote sees a tag ADDED in
+              // this same call, not just the note's pre-write tags. See the
+              // comment on `projectedTags`'s declaration above.
+              updates.tagsForSchemaResolution = [...projectedTags];
               // store.updateNote routes through noteOps.updateNote, which runs
               // the UPDATE (with optional `AND updated_at IS ?`) atomically and
               // throws ConflictError on mismatch. No mutations have happened
@@ -2270,11 +2445,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object, reference — all seven are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean/reference are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field). `reference` is a DUAL-WRITE type (typed-reference-field): the value is stored + validated exactly like `string` (pass a note id, path, or title), AND create-note/update-note additionally resolve that value to a note and maintain a graph `links` edge from this note to it, with `relationship` set to the field name — kept in sync on every write that changes the field (a new value re-points the link; clearing the field drops it). A target that doesn't resolve yet is queued and backfills automatically, same as a structured `links` entry — see `docs/design/typed-reference-field.md`." },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object, reference, date — all eight are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean/reference/date are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field). `reference` is a DUAL-WRITE type (typed-reference-field): the value is stored + validated exactly like `string` (pass a note id, path, or title), AND create-note/update-note additionally resolve that value to a note and maintain a graph `links` edge from this note to it, with `relationship` set to the field name — kept in sync on every write that changes the field (a new value re-points the link; clearing the field drops it). A target that doesn't resolve yet is queued and backfills automatically, same as a structured `links` entry — see `docs/design/typed-reference-field.md`. `date` stores/validates exactly like `string`, but the value must be an ISO-8601 date (`2026-07-09`) or full timestamp (`2026-07-09T00:00:00.000Z`) — an unparseable value is a type_mismatch (advisory) or a rejected write (`strict: true` / `indexed: true`), same treatment as any other type mismatch. A full timestamp carrying an explicit `±HH:MM` offset is normalized to canonical UTC (`Z`-suffixed) on write — the offset is accepted, but not persisted verbatim — so indexed `date` fields sort/filter correctly under the TEXT comparison `gt`/`gte`/`lt`/`lte`/`date_filter`/`order_by` all use; a bare date (no time component) is left as-is." },
                 description: { type: "string" },
                 enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
                 default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },
-                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean/reference are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
+                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean/reference/date are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
                 strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off. Note: `indexed: true` fields enforce their TYPE constraint regardless of this flag (vault#553)." },
                 required: { type: "boolean", description: "vault#299. The field must be present + non-null on a note with this tag. Advisory unless `strict: true`." },
                 cardinality: { type: "string", enum: ["one", "many"], description: "vault#299. 'one' (scalar, default) or 'many' (array). Advisory unless `strict: true`." },
@@ -2649,6 +2824,202 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     },
 
   ];
+
+  // =====================================================================
+  // 12/13. request-attachment-upload / request-attachment-download —
+  // runtime-lane attachment tickets (Wave 1). Present ONLY when the
+  // server layer wires an AttachmentTicketProvider — see
+  // `GenerateMcpToolsOpts.attachmentTickets`'s doc comment (D10, "tools
+  // omitted when unwired"). Bytes never pass through either tool: the
+  // model gets back a URL + a literal curl_example; a runtime with a
+  // shell spends it directly, outside this MCP session entirely.
+  // =====================================================================
+  const ticketSeam = opts?.attachmentTickets;
+  if (ticketSeam) {
+    tools.push(
+      {
+        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.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            note: { type: "string", description: "Target note ID or path" },
+            filename: { type: "string", description: "Original filename — sanitized for a blocked extension (active-content types: .html/.svg/.xml/.js/.css/…) and used to infer the MIME type when `mime_type` is omitted." },
+            size_bytes: {
+              type: "number",
+              description: `Declared upload size in bytes. Must be > 0 and <= ${MAX_TICKET_UPLOAD_BYTES} (100 MiB — the same ceiling REST's own /storage/upload enforces). The spend endpoint rejects (413) any upload that exceeds this declared size.`,
+            },
+            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." },
+          },
+          required: ["note", "filename", "size_bytes"],
+        },
+        execute: async (params) => {
+          const noteRef = params.note;
+          if (typeof noteRef !== "string" || noteRef.trim() === "") {
+            throw structuredError("`note` is required", {
+              error_type: "missing_required_field",
+              field: "note",
+              how_to: "pass the target note's id or path",
+            });
+          }
+          const filename = params.filename;
+          if (typeof filename !== "string" || filename.trim() === "") {
+            throw structuredError("`filename` is required", {
+              error_type: "missing_required_field",
+              field: "filename",
+              how_to: "pass the original filename you're about to upload",
+            });
+          }
+          const sizeBytes = params.size_bytes;
+          if (typeof sizeBytes !== "number" || !Number.isFinite(sizeBytes) || sizeBytes <= 0) {
+            throw structuredError("`size_bytes` must be a positive number", {
+              error_type: "invalid_query",
+              field: "size_bytes",
+              how_to: "pass the exact byte length of the file you're about to upload",
+            });
+          }
+          if (sizeBytes > MAX_TICKET_UPLOAD_BYTES) {
+            throw structuredError(
+              `size_bytes (${sizeBytes}) exceeds the ${MAX_TICKET_UPLOAD_BYTES} byte (100 MiB) upload cap`,
+              {
+                error_type: "file_too_large",
+                field: "size_bytes",
+                limit: MAX_TICKET_UPLOAD_BYTES,
+                got: sizeBytes,
+                how_to: "REST /storage/upload shares this same 100 MiB ceiling — split the file or upload it out-of-band",
+              },
+            );
+          }
+
+          const note = requireNote(db, noteRef);
+          if (ticketSeam.noteVisible && !(await ticketSeam.noteVisible(note))) {
+            // Uniform not_found — a tag-scoped caller learns nothing about
+            // an out-of-scope note's existence (same posture as every other
+            // scope-gated tool in this file).
+            throw structuredError(`Note not found: "${noteRef}"`, { error_type: "not_found", field: "note" });
+          }
+
+          const ext = sanitizeAttachmentExtension(filename);
+          if (BLOCKED_ATTACHMENT_EXTENSIONS.has(ext)) {
+            throw structuredError(`File type ${ext} not allowed (active/executable content)`, {
+              error_type: "blocked_upload_extension",
+              field: "filename",
+              extension: ext,
+              how_to: "rename with a non-executable extension, or store the content as note text instead",
+            });
+          }
+
+          const mimeType =
+            typeof params.mime_type === "string" && params.mime_type.trim() !== ""
+              ? params.mime_type
+              : mimeForAttachmentExtension(ext);
+
+          const now = Date.now();
+          const expiresAt = now + computeTicketTtlMs(sizeBytes);
+          const id = generateTicketId();
+          const ticket: AttachmentTicket = {
+            id,
+            kind: "upload",
+            vaultName: ticketSeam.vaultName,
+            createdAt: now,
+            expiresAt,
+            noteId: note.id,
+            filename,
+            mimeType,
+            sizeBytes,
+            transcribe: params.transcribe === true,
+          };
+          await ticketSeam.provider.put(ticket);
+
+          const url = `${ticketSeam.urlBase}/tickets/${id}`;
+          return {
+            method: "PUT",
+            url,
+            headers: { "content-type": mimeType },
+            expires_at: new Date(expiresAt).toISOString(),
+            max_bytes: sizeBytes,
+            curl_example: `curl -X PUT -H 'content-type: ${mimeType}' --data-binary @${filename} '${url}'`,
+          };
+        },
+      },
+      {
+        name: "request-attachment-download",
+        requiredVerb: "read",
+        description:
+          "Mint a short-lived, single-use download URL for an existing attachment's bytes. 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. Pass the `attachment_id` from a note's `include_attachments: true` rows (query-notes) or `GET .../attachments`. The ticket's `expires_at` follows the same size-scaled window as upload tickets (10 minutes base, up to 30) and can be spent exactly once.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            attachment_id: { type: "string", description: "The attachment's id (from a note's attachment rows)" },
+          },
+          required: ["attachment_id"],
+        },
+        execute: async (params) => {
+          const attachmentId = params.attachment_id;
+          if (typeof attachmentId !== "string" || attachmentId.trim() === "") {
+            throw structuredError("`attachment_id` is required", {
+              error_type: "missing_required_field",
+              field: "attachment_id",
+              how_to: "pass the attachment id from a note's attachment rows",
+            });
+          }
+
+          const attachment = await store.getAttachment(attachmentId);
+          if (!attachment) {
+            throw structuredError(`Attachment not found: "${attachmentId}"`, {
+              error_type: "not_found",
+              field: "attachment_id",
+            });
+          }
+
+          if (ticketSeam.noteVisible) {
+            const owningNote = await store.getNote(attachment.noteId);
+            // A missing owning note (shouldn't happen — ON DELETE CASCADE —
+            // but never trust it) collapses to the same not_found as an
+            // out-of-scope note: no oracle either way.
+            if (!owningNote || !(await ticketSeam.noteVisible(owningNote))) {
+              throw structuredError(`Attachment not found: "${attachmentId}"`, {
+                error_type: "not_found",
+                field: "attachment_id",
+              });
+            }
+          }
+
+          const metaSize = attachment.metadata?.size;
+          const declaredSize = typeof metaSize === "number" ? metaSize : undefined;
+          const now = Date.now();
+          const expiresAt = now + computeTicketTtlMs(declaredSize);
+          const id = generateTicketId();
+          const ticket: AttachmentTicket = {
+            id,
+            kind: "download",
+            vaultName: ticketSeam.vaultName,
+            createdAt: now,
+            expiresAt,
+            attachmentId: attachment.id,
+            mimeType: attachment.mimeType,
+            sizeBytes: declaredSize,
+          };
+          await ticketSeam.provider.put(ticket);
+
+          const url = `${ticketSeam.urlBase}/tickets/${id}`;
+          return {
+            method: "GET",
+            url,
+            mime_type: attachment.mimeType,
+            ...(declaredSize !== undefined ? { size_bytes: declaredSize } : {}),
+            expires_at: new Date(expiresAt).toISOString(),
+            curl_example: `curl -o downloaded${sanitizeAttachmentExtension(attachment.path) || ""} '${url}'`,
+          };
+        },
+      },
+    );
+  }
+
+  return tools;
 }
 
 // ---------------------------------------------------------------------------

package/core/src/notes.semantic-search.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { semanticSearchNotes } from "./notes.js";
+import { encodeVector, normalize } from "./embedding/vector-codec.js";
+
+const MODEL = "test-model";
+const DIMS = 4;
+
+let db: Database;
+let store: SqliteStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+/** Insert a chunk_ix=0 vector row for a note under the test model. */
+function insertVector(noteId: string, vector: number[]): void {
+  const encoded = encodeVector(normalize(new Float32Array(vector)));
+  db.prepare(
+    `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at)
+     VALUES (?, 0, ?, ?, ?, ?, ?)`,
+  ).run(noteId, encoded, DIMS, MODEL, "hash", new Date().toISOString());
+}
+
+function insertChunkVector(noteId: string, ix: number, vector: number[]): void {
+  const encoded = encodeVector(normalize(new Float32Array(vector)));
+  db.prepare(
+    `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  ).run(noteId, ix, encoded, DIMS, MODEL, `hash-${ix}`, new Date().toISOString());
+}
+
+describe("semanticSearchNotes", () => {
+  it("ranks notes by cosine similarity, highest first", async () => {
+    const a = await store.createNote("note a", { path: "a" });
+    const b = await store.createNote("note b", { path: "b" });
+    const c = await store.createNote("note c", { path: "c" });
+
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    insertVector(a.id, [1, 0, 0, 0]); // identical direction — score ~1
+    insertVector(b.id, [0, 1, 0, 0]); // orthogonal — score ~0
+    insertVector(c.id, [0.9, 0.1, 0, 0]); // close-ish — score high but < a
+
+    const result = semanticSearchNotes(db, query, {}, MODEL);
+    expect(result.notes.map((n) => n.id)).toEqual([a.id, c.id, b.id]);
+    expect(result.notes[0].score).toBeCloseTo(1, 4);
+    expect(result.totalCandidates).toBe(3);
+    expect(result.pendingCount).toBe(0);
+  });
+
+  it("respects limit (top-K)", async () => {
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    const ids: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const n = await store.createNote(`note ${i}`, { path: `n${i}` });
+      ids.push(n.id);
+      insertVector(n.id, [1 - i * 0.01, 0.01 * i, 0, 0]);
+    }
+    const result = semanticSearchNotes(db, query, { limit: 2 }, MODEL);
+    expect(result.notes.length).toBe(2);
+    expect(result.totalCandidates).toBe(5);
+  });
+
+  it("filter-then-rank: structured filters (tags) narrow the candidate set BEFORE ranking", async () => {
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    const tagged = await store.createNote("tagged note", { path: "tagged", tags: ["project"] });
+    const untagged = await store.createNote("untagged note", { path: "untagged" });
+    // untagged has the objectively CLOSER vector, but is filtered out by `tags`.
+    insertVector(tagged.id, [0.5, 0.5, 0, 0]);
+    insertVector(untagged.id, [1, 0, 0, 0]);
+
+    const result = semanticSearchNotes(db, query, { tags: ["project"] }, MODEL);
+    expect(result.notes.map((n) => n.id)).toEqual([tagged.id]);
+    expect(result.totalCandidates).toBe(1);
+  });
+
+  it("pendingCount: candidates with no vector row for the active model are excluded from ranking but counted as pending", async () => {
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    const embedded = await store.createNote("embedded", { path: "embedded" });
+    const notYetEmbedded = await store.createNote("not yet embedded", { path: "pending" });
+    insertVector(embedded.id, [1, 0, 0, 0]);
+    // notYetEmbedded gets no note_vectors row at all.
+
+    const result = semanticSearchNotes(db, query, {}, MODEL);
+    expect(result.notes.map((n) => n.id)).toEqual([embedded.id]);
+    expect(result.totalCandidates).toBe(2);
+    expect(result.pendingCount).toBe(1);
+  });
+
+  it("ignores vectors recorded under a DIFFERENT model", async () => {
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    const note = await store.createNote("note", { path: "n" });
+    const encoded = encodeVector(normalize(new Float32Array([1, 0, 0, 0])));
+    db.prepare(
+      `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at)
+       VALUES (?, 0, ?, ?, 'stale-model', 'hash', ?)`,
+    ).run(note.id, encoded, DIMS, new Date().toISOString());
+
+    const result = semanticSearchNotes(db, query, {}, MODEL);
+    expect(result.notes).toEqual([]);
+    expect(result.pendingCount).toBe(1); // no row under the ACTIVE model
+  });
+
+  it("best-chunk ranking: a long note's best-matching SECTION outranks a note with weak whole-note similarity", async () => {
+    // This is the exact case chunking exists for (P0's dominant miss
+    // pattern: whole-note embedding dilutes long, multi-topic notes).
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+
+    const longNote = await store.createNote("a long multi-section note", { path: "long" });
+    // Section 0 is about something unrelated (poor match); section 2 is a
+    // strong match for the query — best-chunk ranking must pick that up.
+    insertChunkVector(longNote.id, 0, [0, 1, 0, 0]); // orthogonal — weak
+    insertChunkVector(longNote.id, 1, [0.3, 0.3, 0.3, 0.3]); // mediocre
+    insertChunkVector(longNote.id, 2, [1, 0, 0, 0]); // strong match
+
+    const shortNote = await store.createNote("a short weakly-related note", { path: "short" });
+    insertVector(shortNote.id, [0.5, 0.5, 0, 0]); // weak whole-note similarity
+
+    const result = semanticSearchNotes(db, query, {}, MODEL);
+    expect(result.notes.map((n) => n.id)).toEqual([longNote.id, shortNote.id]);
+    expect(result.notes[0].score).toBeCloseTo(1, 4);
+  });
+
+  it("returns nothing (no throw) when the candidate set is empty", () => {
+    const query = normalize(new Float32Array([1, 0, 0, 0]));
+    const result = semanticSearchNotes(db, query, { tags: ["nonexistent"] }, MODEL);
+    expect(result).toEqual({ notes: [], pendingCount: 0, totalCandidates: 0 });
+  });
+});