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

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";
@@ -43,10 +43,13 @@ 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";
@@ -57,6 +60,23 @@ import {
   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;
@@ -75,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[];
 }
 
 // ---------------------------------------------------------------------------
@@ -166,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
 // ---------------------------------------------------------------------------
@@ -291,6 +488,25 @@ export interface GenerateMcpToolsOpts {
      */
     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>;
+  };
 }
 
 /**
@@ -3019,6 +3235,120 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     );
   }
 
+  // =====================================================================
+  // 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;
 }
 

package/core/src/vault-projection.ts

@@ -283,27 +283,34 @@ function sqliteToUserType(t: string): string {
  * its own context on them (bytes never ride MCP either way).
  *
  * `ticketsEnabled` reflects whether THIS door has wired an
- * `AttachmentTicketProvider` (bun: always, as of this PR; cloud: not yet
- * — its mirror is a separate PR). An unwired door omits BOTH the ticket
- * tools from `tools/list` (see `generateMcpTools`'s `attachmentTickets`
- * opt) AND the ticket-tool sentences here — the brief never dangles a
- * pointer at a tool the agent can't actually call.
+ * `AttachmentTicketProvider` (bun: always, as of the Wave 1 PR; cloud: not
+ * yet — its mirror is a separate PR). `readEnabled` reflects whether it's
+ * wired an `AttachmentBytesProvider` (bun: always, as of this PR — Wave 2).
+ * An unwired seam omits BOTH its tool(s) from `tools/list` (see
+ * `generateMcpTools`'s `attachmentTickets` / `attachmentBytes` opts) AND
+ * its sentence here — the brief never dangles a pointer at a tool the
+ * agent can't actually call.
  *
  * Kept as a single dense paragraph (not its own multi-line list) to stay
  * inside the connect-time brief's token budget — see
  * `projectionToMarkdown`'s doc comment.
  */
-export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean }): string {
+export function attachmentsInstructionBlock(opts: { ticketsEnabled: boolean; readEnabled?: boolean }): string {
   const sentences: string[] = [
-    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP).",
+    "Notes can carry file attachments (`include_attachments: true` on `query-notes` returns their rows; bytes don't ride MCP tool RESULTS unless you ask for them).",
   ];
   if (opts.ticketsEnabled) {
     sentences.push(
-      "To move bytes, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+      "To move bytes without spending your own context, call `request-attachment-upload` / `request-attachment-download` — each mints a short-lived, single-use URL (with a ready-to-run `curl_example`) your shell spends directly; no MCP session credential is needed to spend it.",
+    );
+  }
+  if (opts.readEnabled) {
+    sentences.push(
+      "To read an attachment directly into this conversation, call `read-attachment` — text comes back as a paginated `content` slice, images as a real image you can see, audio/video as a transcript pointer (never raw bytes), and PDF/other binary formats point you at a download ticket instead.",
     );
   }
   sentences.push(
-    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer`. Audio attached with `transcribe: true` is transcribed automatically.",
+    "If your runtime holds this vault's own API token, REST works too: upload = `POST {base}/storage/upload` (multipart `file`, ≤100 MB) then `POST {base}/notes/{id}/attachments` `{path, mimeType, transcribe?}`; download = `GET {base}/storage/{path}` with the same `Authorization: Bearer` (honors a `Range: bytes=a-b` header for partial reads). Audio attached with `transcribe: true` is transcribed automatically.",
   );
   return sentences.join(" ");
 }
@@ -344,7 +351,7 @@ export function projectionToMarkdown(args: {
    * that hasn't wired ticket support yet (or a test fixture) never
    * accidentally advertises tools it can't back.
    */
-  attachments?: { ticketsEnabled: boolean };
+  attachments?: { ticketsEnabled: boolean; readEnabled?: boolean };
 }): string {
   const { vaultName, description, projection, coordinates } = args;
   const stats = projection.stats;

package/package.json

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

package/src/attachment-bytes.ts

@@ -0,0 +1,68 @@
+/**
+ * Attachment bytes — bun's filesystem implementation of the model-lane
+ * (Wave 2) `AttachmentBytesProvider` seam (`core/src/attachment/bytes-provider.ts`).
+ *
+ * Stateless by design (unlike the ticket provider, there's no in-memory
+ * state to share across requests) — a fresh instance per MCP session is
+ * cheap, so `createFsAttachmentBytesProvider` is a plain factory, not a
+ * shared singleton.
+ *
+ * `readRange` uses `Bun.file(path).slice(start, end)` — a bounded,
+ * positional read (Bun resolves the slice lazily via `pread` under the
+ * hood), never the whole-file `readFileSync` this design explicitly moves
+ * away from (see `handleStorage`'s REST `Range` support in `src/routes.ts`
+ * for the sibling fix on the byte-serve side).
+ */
+
+import { existsSync, statSync } from "fs";
+import { join, normalize } from "path";
+import type { Attachment } from "../core/src/types.ts";
+import type { AttachmentBytesProvider } from "../core/src/attachment/bytes-provider.ts";
+import { assetsDir } from "./config.ts";
+import { transcriptPathFor } from "./transcript-note.ts";
+import { getVaultStore } from "./vault-store.ts";
+
+/**
+ * Resolve + confine an attachment's on-disk path under this vault's assets
+ * dir. Same guard as the ticket download spend route (`src/attachment-tickets.ts`)
+ * and the REST byte-serve route (`src/routes.ts`): normalize, then require
+ * the result to still start with the (normalized) assets root — a stored
+ * `path` can never resolve outside it, but a defense-in-depth check costs
+ * nothing. Returns `null` on a traversal attempt (treated identically to
+ * "file doesn't exist" by every caller here).
+ */
+function resolveConfinedPath(vaultName: string, attachment: Attachment): string | null {
+  const assets = assetsDir(vaultName);
+  const filePath = normalize(join(assets, attachment.path));
+  if (!filePath.startsWith(normalize(assets))) return null;
+  return filePath;
+}
+
+class FsAttachmentBytesProvider implements AttachmentBytesProvider {
+  constructor(private readonly vaultName: string) {}
+
+  async stat(attachment: Attachment): Promise<{ size: number } | null> {
+    const filePath = resolveConfinedPath(this.vaultName, attachment);
+    if (!filePath || !existsSync(filePath)) return null;
+    return { size: statSync(filePath).size };
+  }
+
+  async readRange(attachment: Attachment, start: number, end: number): Promise<Uint8Array> {
+    const filePath = resolveConfinedPath(this.vaultName, attachment);
+    if (!filePath) return new Uint8Array(0);
+    const slice = Bun.file(filePath).slice(start, end);
+    return new Uint8Array(await slice.arrayBuffer());
+  }
+
+  async resolveTranscriptNote(attachment: Attachment): Promise<{ id: string; path: string } | null> {
+    const store = getVaultStore(this.vaultName);
+    const note = await store.getNoteByPath(transcriptPathFor(attachment.path));
+    if (!note) return null;
+    return { id: note.id, path: note.path ?? transcriptPathFor(attachment.path) };
+  }
+}
+
+/** Build a fresh `AttachmentBytesProvider` scoped to one vault. Cheap — safe to call per-request. */
+export function createFsAttachmentBytesProvider(vaultName: string): AttachmentBytesProvider {
+  return new FsAttachmentBytesProvider(vaultName);
+}

package/src/attachment-tickets.test.ts

@@ -29,7 +29,15 @@ const { handleScopedMcp } = await import("./mcp-http.ts");
 const { getServerInstruction } = await import("./mcp-tools.ts");
 const { writeVaultConfig } = await import("./config.ts");
 const { getVaultStore } = await import("./vault-store.ts");
-const { getSharedAttachmentTicketProvider } = await import("./attachment-tickets.ts");
+const {
+  getSharedAttachmentTicketProvider,
+  InProcessAttachmentTicketProvider,
+  sweepExpiredAttachmentTickets,
+  startAttachmentTicketSweep,
+  stopAttachmentTicketSweep,
+} = await import("./attachment-tickets.ts");
+const { generateTicketId } = await import("../core/src/attachment/tickets.ts");
+import type { AttachmentTicket } from "../core/src/attachment/tickets.ts";
 const { attachmentsInstructionBlock } = await import("../core/src/vault-projection.ts");
 
 /** `route()` takes the pathname as a separate arg (server.ts derives it from `req.url`) — this wrapper matches that call shape everywhere below. */
@@ -347,4 +355,121 @@ describe("attachment tickets — discoverability", () => {
     expect(md).toContain("## Attachments");
     expect(md).toContain("request-attachment-upload");
   });
+
+  test("attachmentsInstructionBlock teaches read-attachment when readEnabled, and omits it when not", () => {
+    const enabled = attachmentsInstructionBlock({ ticketsEnabled: true, readEnabled: true });
+    expect(enabled).toContain("read-attachment");
+
+    const disabled = attachmentsInstructionBlock({ ticketsEnabled: true, readEnabled: false });
+    expect(disabled).not.toContain("read-attachment");
+  });
+
+  test("bun's connect-time getServerInstruction teaches read-attachment too", async () => {
+    const vaultName = freshVault("tickets-instructions-read");
+    const md = await getServerInstruction(vaultName);
+    expect(md).toContain("read-attachment");
+  });
+});
+
+describe("attachment ticket sweep (vault#612)", () => {
+  // Isolated instance — no risk of touching the one process-wide provider
+  // every OTHER test in this file (and every other test FILE, via
+  // getSharedAttachmentTicketProvider) also shares.
+  function ticketExpiringAt(id: string, expiresAt: number): AttachmentTicket {
+    return {
+      id,
+      kind: "download",
+      vaultName: "sweep-unit-test",
+      createdAt: expiresAt - 60_000,
+      expiresAt,
+      attachmentId: "att-1",
+    };
+  }
+
+  test("sweepExpired drops only expired-unspent tickets and returns the count dropped", async () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    const now = Date.now();
+    await provider.put(ticketExpiringAt("expired-1", now - 5000));
+    await provider.put(ticketExpiringAt("expired-2", now - 1));
+    await provider.put(ticketExpiringAt("fresh-1", now + 60_000));
+    expect(provider.size()).toBe(3);
+
+    const dropped = provider.sweepExpired(now);
+    expect(dropped).toBe(2);
+    expect(provider.size()).toBe(1);
+
+    // Dropped tickets are gone — take() returns null, same as "never existed".
+    expect(await provider.take("expired-1")).toBeNull();
+    expect(await provider.take("expired-2")).toBeNull();
+    // The unexpired ticket survived the sweep and is still spendable.
+    const fresh = await provider.take("fresh-1");
+    expect(fresh?.id).toBe("fresh-1");
+  });
+
+  test("a ticket expiring exactly `now` counts as expired (< comparison, not <=)", async () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    const now = Date.now();
+    await provider.put(ticketExpiringAt("boundary", now));
+    expect(provider.sweepExpired(now)).toBe(0); // expiresAt === now is NOT yet expired
+    expect(provider.sweepExpired(now + 1)).toBe(1); // one ms later, it is
+  });
+
+  test("a no-op sweep (nothing expired) drops nothing", () => {
+    const provider = new InProcessAttachmentTicketProvider();
+    expect(provider.sweepExpired(Date.now())).toBe(0);
+    expect(provider.size()).toBe(0);
+  });
+
+  test("sweepExpiredAttachmentTickets delegates to the shared provider (unique ids — safe alongside concurrent tests)", async () => {
+    const provider = getSharedAttachmentTicketProvider();
+    const now = Date.now();
+    const expiredId = generateTicketId();
+    const freshId = generateTicketId();
+    await provider.put(ticketExpiringAt(expiredId, now - 1));
+    await provider.put(ticketExpiringAt(freshId, now + 60_000));
+
+    sweepExpiredAttachmentTickets(now);
+
+    expect(await provider.take(expiredId)).toBeNull();
+    const fresh = await provider.take(freshId);
+    expect(fresh?.id).toBe(freshId);
+  });
+
+  test("sweepExpiredAttachmentTickets always returns a number (the `?? 0` fallback path never throws)", () => {
+    // By this point in the suite the shared provider already exists (other
+    // tests above created it) — this doesn't re-prove the true
+    // never-created case in isolation, but pins the return type/no-throw
+    // contract the periodic sweep timer depends on every tick.
+    expect(typeof sweepExpiredAttachmentTickets()).toBe("number");
+  });
+
+  test("start/stop the periodic sweep: idempotent start, a short-interval real timer actually drops an expired ticket, clean stop", async () => {
+    // Poll via `size()`, NOT `take(id)` — `take()` deletes unconditionally
+    // on any lookup (expired or not; see its own doc comment), so polling
+    // with it would consume the ticket itself on the FIRST poll — before
+    // the timer ever fires — and the test would pass for the wrong reason.
+    const provider = getSharedAttachmentTicketProvider() as InstanceType<typeof InProcessAttachmentTicketProvider>;
+    const now = Date.now();
+    const id = generateTicketId();
+    await provider.put(ticketExpiringAt(id, now - 1)); // already expired
+    const baseline = provider.size();
+
+    startAttachmentTicketSweep(15); // 15ms — short enough to observe within the test timeout
+    startAttachmentTicketSweep(15); // idempotent — no-op, doesn't create a second timer
+
+    // Poll briefly rather than a single fixed sleep — bounded by the test
+    // runner's own timeout.
+    let sizeDropped = false;
+    for (let i = 0; i < 20 && !sizeDropped; i++) {
+      await new Promise((r) => setTimeout(r, 15));
+      if (provider.size() < baseline) sizeDropped = true;
+    }
+    stopAttachmentTicketSweep();
+    stopAttachmentTicketSweep(); // idempotent — no-op on an already-stopped sweep
+
+    expect(sizeDropped).toBe(true);
+    // Confirm it was genuinely OUR ticket the sweep dropped, not a
+    // coincidental size change from something else.
+    expect(await provider.take(id)).toBeNull();
+  });
 });