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

package/core/src/mcp.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note, QueryOpts } from "./types.js";
+import type { Store, Note, QueryOpts, Attachment } from "./types.js";
 import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError, validatePath } from "./notes.js";
@@ -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";
@@ -42,8 +43,40 @@ import {
   parseContentRange,
   applyContentRange,
   contentRangeRequiresContent,
+  parseAttachmentContentRange,
+  alignByteWindow,
   MIN_CONTENT_LENGTH,
 } from "./content-range.js";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  ATTACHMENT_MIME_TYPES,
+  sanitizeAttachmentExtension,
+  mimeForAttachmentExtension,
+} from "./attachment/policy.js";
+import {
+  computeTicketTtlMs,
+  generateTicketId,
+  MAX_TICKET_UPLOAD_BYTES,
+  type AttachmentTicket,
+  type AttachmentTicketProvider,
+} from "./attachment/tickets.js";
+import {
+  MAX_ATTACHMENT_IMAGE_BYTES,
+  type AttachmentBytesProvider,
+} from "./attachment/bytes-provider.js";
+
+/**
+ * A single MCP tool-result content block. Mirrors the subset of the MCP SDK's
+ * `CallToolResult.content` shape this codebase actually emits — a plain text
+ * block (the existing, universal shape) or a real image block (`read-attachment`'s
+ * image branch, D3). Kept as a local, minimal type rather than importing the
+ * SDK's own (broader — audio, resource links, ...) union, since core has no
+ * dependency on `@modelcontextprotocol/sdk` today and this is the only shape
+ * any tool here produces.
+ */
+export type McpContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
 
 export interface McpToolDef {
   name: string;
@@ -62,6 +95,17 @@ export interface McpToolDef {
    * future addition that forgets to stamp this gets the safer treatment.
    */
   requiredVerb: "read" | "write" | "admin";
+  /**
+   * OPTIONAL override for how `execute()`'s return value becomes MCP
+   * `content` blocks. Every tool WITHOUT this wraps its result as the single
+   * `JSON.stringify` text block the HTTP layer has always produced
+   * (`src/mcp-http.ts`) — unchanged default behavior. `read-attachment`'s
+   * image branch is the only current user: it needs a REAL `{type:"image"}`
+   * block alongside the row-JSON text block so the model actually SEES the
+   * picture, not just its metadata (D3, attachments-for-agents design "the
+   * one wrapper change").
+   */
+  resultContent?: (result: unknown) => McpContentBlock[];
 }
 
 // ---------------------------------------------------------------------------
@@ -79,7 +123,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);
 }
@@ -153,6 +197,172 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
   return content;
 }
 
+// ---------------------------------------------------------------------------
+// read-attachment helpers (Wave 2 model lane — D2-D5)
+// ---------------------------------------------------------------------------
+
+/** Non-`text/*` mime types `read-attachment` still treats as text (D2's "text/* + TEXT_MIMES allowlist"). `text/csv` and `text/markdown` already match `text/*` via ATTACHMENT_MIME_TYPES, so they need no entry here. */
+const TEXT_MIME_ALLOWLIST = new Set([
+  "application/json",
+  "application/ndjson",
+  "application/x-ndjson",
+  "application/yaml",
+  "application/x-yaml",
+]);
+
+function baseMime(mimeType: string): string {
+  return mimeType.split(";")[0]!.trim().toLowerCase();
+}
+
+function isTextMime(mimeType: string): boolean {
+  const base = baseMime(mimeType);
+  return base.startsWith("text/") || TEXT_MIME_ALLOWLIST.has(base);
+}
+
+function isImageMime(mimeType: string): boolean {
+  return baseMime(mimeType).startsWith("image/");
+}
+
+function isAudioOrVideoMime(mimeType: string): boolean {
+  const base = baseMime(mimeType);
+  return base.startsWith("audio/") || base.startsWith("video/");
+}
+
+/**
+ * Effective mime for `read-attachment` — same discipline the REST byte-serve
+ * route uses (`src/routes.ts`'s `GET /storage/<path>`): the stored file's
+ * EXTENSION wins over the row's `mime_type` column, since the row's mime is
+ * caller-asserted at upload time and never verified against the bytes. Falls
+ * back to the row's mime_type, then `application/octet-stream`.
+ */
+function effectiveAttachmentMime(attachment: Attachment): string {
+  const ext = sanitizeAttachmentExtension(attachment.path);
+  return ATTACHMENT_MIME_TYPES[ext] ?? attachment.mimeType ?? "application/octet-stream";
+}
+
+/** Stat the attachment's bytes, or throw the `attachment_binary_missing` refusal (D5's "row outlived bytes" case — e.g. an audio-retention eviction). */
+async function statAttachmentOrMissing(
+  attachment: Attachment,
+  provider: AttachmentBytesProvider,
+): Promise<{ size: number }> {
+  const stat = await provider.stat(attachment);
+  if (!stat) {
+    throw structuredError(`Attachment binary missing: "${attachment.id}"`, {
+      error_type: "attachment_binary_missing",
+      how_to:
+        "the attachment row exists but its bytes are gone (e.g. an audio-retention eviction after transcription) — this content can't be read",
+    });
+  }
+  return stat;
+}
+
+/**
+ * Text branch: byte-windowed read using the exact query-notes pagination
+ * contract (`content`/`content_offset`/`content_total_length`/
+ * `content_next_offset`). Does a BOUNDED positional read — never the whole
+ * file — via `alignByteWindow` (see its doc comment for the exact window
+ * the provider is asked to fetch).
+ */
+async function readTextAttachment(
+  attachment: Attachment,
+  mimeType: string,
+  params: Record<string, unknown>,
+  provider: AttachmentBytesProvider,
+): Promise<Record<string, unknown>> {
+  const range = parseAttachmentContentRange(params.content_offset, params.content_length);
+  const stat = await statAttachmentOrMissing(attachment, provider);
+  const total = stat.size;
+
+  if (range.offset >= total) {
+    return {
+      attachment_id: attachment.id,
+      mime_type: mimeType,
+      content: "",
+      content_offset: total,
+      content_total_length: total,
+      content_next_offset: null,
+    };
+  }
+
+  const rawStart = Math.max(0, range.offset - 3);
+  // +1: alignByteWindow's end-boundary check reads the byte AT the window's
+  // exclusive end — see its doc comment precondition.
+  const rawEnd = Math.min(total, range.offset + range.length + 1);
+  const raw = await provider.readRange(attachment, rawStart, rawEnd);
+  const fields = alignByteWindow(raw, rawStart, range, total);
+
+  return {
+    attachment_id: attachment.id,
+    mime_type: mimeType,
+    ...fields,
+  };
+}
+
+/**
+ * Image branch: whole-file read, gated by {@link MAX_ATTACHMENT_IMAGE_BYTES}
+ * (checked via `stat` BEFORE any bytes are read — an over-cap image never
+ * touches `readRange` at all). The base64 payload rides in `_mcpImage`, a
+ * field this tool's own `resultContent` consumes to build the real MCP image
+ * block and then strips before the text block is serialized (see the tool
+ * definition below) — no other caller should read `_mcpImage`.
+ */
+async function readImageAttachment(
+  attachment: Attachment,
+  mimeType: string,
+  provider: AttachmentBytesProvider,
+): Promise<Record<string, unknown>> {
+  const stat = await statAttachmentOrMissing(attachment, provider);
+  if (stat.size > MAX_ATTACHMENT_IMAGE_BYTES) {
+    throw structuredError(
+      `Image attachment (${stat.size} bytes) exceeds the ${MAX_ATTACHMENT_IMAGE_BYTES} byte (4 MiB) read cap`,
+      {
+        error_type: "image_too_large",
+        size: stat.size,
+        max_bytes: MAX_ATTACHMENT_IMAGE_BYTES,
+        how_to: "mint a download ticket with request-attachment-download and process the image locally",
+      },
+    );
+  }
+  const raw = await provider.readRange(attachment, 0, stat.size);
+  return {
+    attachment_id: attachment.id,
+    mime_type: mimeType,
+    size_bytes: stat.size,
+    _mcpImage: { data: Buffer.from(raw).toString("base64"), mimeType },
+  };
+}
+
+/**
+ * Audio/video branch: never bytes. Returns a transcript pointer built
+ * entirely from metadata the transcription pipeline already stamps
+ * (`attachment.metadata.transcribe_status`) plus the provider's OPTIONAL
+ * sibling-note resolution — no bytes are read or even stat'd.
+ */
+async function readAudioPointer(
+  attachment: Attachment,
+  provider: AttachmentBytesProvider,
+): Promise<Record<string, unknown>> {
+  const meta = attachment.metadata as Record<string, unknown> | undefined;
+  const transcribeStatus = typeof meta?.transcribe_status === "string" ? meta.transcribe_status : undefined;
+  if (!transcribeStatus) {
+    throw structuredError(`Audio/video attachment "${attachment.id}" has no transcript`, {
+      error_type: "audio_bytes_not_supported",
+      how_to:
+        "re-attach with transcribe: true to get a transcript, or mint a download ticket with request-attachment-download to process the bytes locally",
+    });
+  }
+  const result: Record<string, unknown> = {
+    attachment_id: attachment.id,
+    transcribe_status: transcribeStatus,
+    note_id: attachment.noteId,
+  };
+  if (provider.resolveTranscriptNote) {
+    const transcriptNote = await provider.resolveTranscriptNote(attachment);
+    if (transcriptNote) result.transcript_note = transcriptNote;
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Tool generation
 // ---------------------------------------------------------------------------
@@ -245,6 +455,58 @@ 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>;
+  };
+  /**
+   * `AttachmentBytesProvider` seam (Wave 2 model lane — D10, same "tools
+   * omitted when unwired" posture as `attachmentTickets` above). When
+   * provided, `generateMcpTools` appends `read-attachment` to the returned
+   * tool list. Omitted (a door that hasn't wired byte access yet) →
+   * `read-attachment` is ABSENT from the list entirely.
+   */
+  attachmentBytes?: {
+    provider: AttachmentBytesProvider;
+    /**
+     * OPTIONAL per-note visibility predicate — identical contract to
+     * `attachmentTickets.noteVisible` above (same tag-scope confidentiality
+     * intent; kept as a separate field since a caller could in principle
+     * wire one seam without the other, though the server layer always wires
+     * both from the same underlying check). Omitted → every attachment is
+     * visible.
+     */
+    noteVisible?: (note: Note) => boolean | Promise<boolean>;
+  };
 }
 
 /**
@@ -311,7 +573,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     });
   };
 
-  return [
+  const tools: McpToolDef[] = [
 
     // =====================================================================
     // 1. query-notes — the universal read tool
@@ -412,6 +674,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 +771,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 +912,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 +957,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 +1056,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 +1616,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 +1880,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 +1954,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 +2337,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 +2392,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 +2661,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 +3040,316 @@ 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}'`,
+          };
+        },
+      },
+    );
+  }
+
+  // =====================================================================
+  // 14. read-attachment — model-lane byte reads (Wave 2). Present ONLY
+  // when the server layer wires an AttachmentBytesProvider — see
+  // `GenerateMcpToolsOpts.attachmentBytes`'s doc comment (D10). Dispatches
+  // by mime family: text ranges come back as `content`/`content_offset`/
+  // `content_total_length`/`content_next_offset` (the exact query-notes
+  // pagination contract); images come back as a real MCP image block (see
+  // this tool's `resultContent`); audio/video never send bytes — a
+  // transcript pointer instead; PDF/other binary refuse with a
+  // download-ticket pointer. Unlike the ticket tools, bytes (or a base64
+  // encoding of them) DO pass through this tool — that's the whole point
+  // of the model lane.
+  // =====================================================================
+  const bytesSeam = opts?.attachmentBytes;
+  if (bytesSeam) {
+    tools.push({
+      name: "read-attachment",
+      requiredVerb: "read",
+      description:
+        "Read an attachment's content directly into this conversation (the model lane — bytes DO pass through this tool, unlike request-attachment-upload/download). Behavior depends on mime type: text/* (+ json/ndjson/yaml — csv/markdown are already text/*) returns a byte-windowed `content` slice using the exact query-notes content_offset/content_length/content_next_offset pagination contract (default 65536 bytes / 64 KiB, max 262144 / 256 KiB per call — loop, feeding content_next_offset back as content_offset, for more). image/* returns a real image you can see, capped at 4 MiB raw (over-cap refuses with a pointer to request-attachment-download; content_offset/content_length don't apply to images). audio/video never send bytes — you get back a transcript pointer (transcribe_status, note_id, and a transcript_note when one exists) instead of the audio itself. PDF and other binary formats aren't directly readable here — mint a download ticket with request-attachment-download and process the file with your own runtime.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          attachment_id: {
+            type: "string",
+            description: "The attachment's id (from a note's attachment rows, e.g. include_attachments: true on query-notes)",
+          },
+          content_offset: {
+            type: "number",
+            description: "Text attachments only. Byte offset to start reading from (UTF-8 bytes). Defaults to 0.",
+          },
+          content_length: {
+            type: "number",
+            description: "Text attachments only. Byte budget for this call. Defaults to 65536 (64 KiB); max 262144 (256 KiB).",
+          },
+        },
+        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 (bytesSeam.noteVisible) {
+          const owningNote = await store.getNote(attachment.noteId);
+          // Same uniform not_found posture as the ticket tools — a
+          // tag-scoped caller learns nothing about an out-of-scope note's
+          // existence via a differential error.
+          if (!owningNote || !(await bytesSeam.noteVisible(owningNote))) {
+            throw structuredError(`Attachment not found: "${attachmentId}"`, {
+              error_type: "not_found",
+              field: "attachment_id",
+            });
+          }
+        }
+
+        const mimeType = effectiveAttachmentMime(attachment);
+
+        if (isImageMime(mimeType)) {
+          if (params.content_offset !== undefined || params.content_length !== undefined) {
+            throw structuredError("content_offset/content_length don't apply to image attachments", {
+              error_type: "invalid_query",
+              field: "content_offset",
+              hint: "omit content_offset/content_length for an image read — the whole image (up to the 4 MiB cap) comes back in one call",
+            });
+          }
+          return await readImageAttachment(attachment, mimeType, bytesSeam.provider);
+        }
+        if (isTextMime(mimeType)) {
+          return await readTextAttachment(attachment, mimeType, params, bytesSeam.provider);
+        }
+        if (isAudioOrVideoMime(mimeType)) {
+          return await readAudioPointer(attachment, bytesSeam.provider);
+        }
+
+        // Other binary (PDF, zip, docx, ...) — refuse honestly rather than
+        // returning garbage or truncated bytes; extraction is a v2 concern
+        // (D5). Still stats first so a row whose bytes are ALSO gone gets
+        // the more accurate attachment_binary_missing instead.
+        const stat = await statAttachmentOrMissing(attachment, bytesSeam.provider);
+        throw structuredError(`Attachment type "${mimeType}" isn't directly readable by this tool`, {
+          error_type: "unsupported_attachment_type",
+          mime_type: mimeType,
+          size: stat.size,
+          how_to: "mint a download ticket with request-attachment-download and process the file locally",
+        });
+      },
+      resultContent: (result) => {
+        const r = result as ({ _mcpImage?: { data: string; mimeType: string } } & Record<string, unknown>) | null;
+        if (r && r._mcpImage) {
+          const { _mcpImage, ...rest } = r;
+          return [
+            { type: "text", text: JSON.stringify(rest, null, 2) },
+            { type: "image", data: _mcpImage.data, mimeType: _mcpImage.mimeType },
+          ];
+        }
+        return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+      },
+    });
+  }
+
+  return tools;
 }
 
 // ---------------------------------------------------------------------------