@openparachute/vault 0.7.3-rc.8 → 0.7.3

package/README.md

@@ -30,7 +30,7 @@ For remote access from Claude Desktop or mobile apps, see [Deployment](#deployme
 
 A server on port 1940 with:
 
-- **MCP** — 9 tools for AI agents (notes, tags, graph, vault info)
+- **MCP** — tools for AI agents (notes, tags, graph, vault info, attachments)
 - **REST API** — Full CRUD for notes, tags, links, full-text search
 - **Wikilink auto-linking** — `[[wikilinks]]` in note content automatically create links in the graph
 - **Obsidian import/export** — Bidirectional interop with Obsidian vaults
@@ -252,12 +252,14 @@ parachute-vault backup --schedule daily        # hourly | daily | weekly | manua
 parachute-vault backup status                  # schedule, last run, destinations, next run
 ```
 
-## MCP tools (9)
+## MCP tools (13 core, + attachments + admin)
 
 **Notes**: `query-notes` (universal read — single by ID/path, filter, search, graph neighborhood), `create-note` (single or batch), `update-note` (single or batch — content, tags, links, metadata), `delete-note`
-**Tags**: `list-tags` (with optional schema detail), `update-tag` (upsert description + schema fields), `delete-tag`
+**Tags**: `list-tags` (with optional schema detail), `update-tag` (upsert description + schema fields), `delete-tag`, `rename-tag`, `merge-tags`
 **Graph**: `find-path` (BFS between two notes)
 **Vault**: `vault-info` (get/update description + stats)
+**Admin**: `prune-schema`, `doctor` (taxonomy/metadata integrity scan), `manage-token`
+**Attachments** (2, present when the door wires an attachment-ticket provider — always true on this server): `request-attachment-upload`, `request-attachment-download` — mint a short-lived, single-use ticket a runtime's shell spends directly at `/vault/{name}/tickets/{id}`; bytes never pass through the tool call. See [`docs/HTTP_API.md`](./docs/HTTP_API.md#attachment-tickets-vault611--wave-1-bun-only).
 
 ### Vault descriptions
 

package/core/src/attachment/bytes-provider.ts

@@ -0,0 +1,65 @@
+/**
+ * `AttachmentBytesProvider` — the model-lane (Wave 2) byte-access seam.
+ * Mirrors `AttachmentTicketProvider` (`./tickets.ts`): a per-door
+ * implementation binds this to its own storage (bun: local fs, see
+ * `src/attachment-bytes.ts`; a future cloud implementation: ranged R2 GETs
+ * through the vault DO). Core stays storage-unaware — the `read-attachment`
+ * tool (`core/src/mcp.ts`) calls only through this interface, so bun and a
+ * future cloud implementation can never drift on the read contract.
+ *
+ * Deliberately narrow: stat + a bounded positional read, plus one optional
+ * hook for the audio transcript pointer. All POLICY (mime-family dispatch,
+ * size caps, range validation, tag-scope) lives in the `read-attachment`
+ * tool itself — same division as the ticket seam (`GenerateMcpToolsOpts`'s
+ * doc comment in `core/src/mcp.ts`).
+ *
+ * D10 (attachments-for-agents design): "tools omitted when unwired" — a
+ * door that hasn't wired this seam simply never passes `attachmentBytes` to
+ * `generateMcpTools`, so `read-attachment` is absent from `tools/list`
+ * entirely, not merely erroring on call.
+ */
+
+import type { Attachment } from "../types.js";
+
+/**
+ * 4 MiB raw-bytes cap on the image branch of `read-attachment` (D3): the
+ * largest honest budget under Claude's ~5 MB image API limit, with room for
+ * base64 blow-up (~5.6 MiB on the wire) and DO-transient headroom on a
+ * future cloud implementation. Enforced BEFORE a read is attempted — the
+ * tool calls `stat()` first and refuses over-cap without ever calling
+ * `readRange()`.
+ */
+export const MAX_ATTACHMENT_IMAGE_BYTES = 4 * 1024 * 1024;
+
+export interface AttachmentBytesProvider {
+  /**
+   * Byte size of the attachment's stored bytes, or `null` when the row
+   * exists but its bytes don't — e.g. an `audio_retention` eviction after a
+   * successful transcription (`src/transcription-worker.ts` unlinks the
+   * file on `until_transcribed` / `never` retention), or any other
+   * out-of-band loss. Drives the `attachment_binary_missing` refusal.
+   */
+  stat(attachment: Attachment): Promise<{ size: number } | null>;
+  /**
+   * Read the half-open byte range `[start, end)`. Bounded by construction —
+   * callers never ask for the whole file when only a window is needed (the
+   * text path); the image path DOES read start-to-end, but only after
+   * `stat()` has already confirmed the file is under
+   * {@link MAX_ATTACHMENT_IMAGE_BYTES}. `start`/`end` are always within
+   * `[0, size]` as reported by a prior `stat()` call on the same attachment
+   * — implementations don't need to re-clamp defensively, though doing so
+   * costs nothing.
+   */
+  readRange(attachment: Attachment, start: number, end: number): Promise<Uint8Array>;
+  /**
+   * OPTIONAL: resolve the sibling transcript note for a completed
+   * audio/video transcription (bun: `<attachment-path>.transcript`, see
+   * `transcriptPathFor` in `src/transcript-note.ts`). Omitted by a door
+   * whose transcript instead lives in the owning note's body (the design's
+   * cloud path, D... — no separate sibling note to point at) — the
+   * `read-attachment` audio branch falls back to `note_id` alone (the
+   * owning note) in that case, per the design's "on cloud the transcript
+   * lives in the owning note's body, so `note_id` is the pointer."
+   */
+  resolveTranscriptNote?(attachment: Attachment): Promise<{ id: string; path: string } | null>;
+}

package/core/src/content-range-constants.ts

@@ -0,0 +1,19 @@
+/**
+ * Content-range constants with ZERO runtime dependencies.
+ *
+ * Extracted from `content-range.ts` (which imports `QueryError` from
+ * `query-operators.ts` → `bun:sqlite`) so the pure-data MCP tool manifest
+ * (`mcp-manifest.ts`) can reference `MIN_CONTENT_LENGTH` in a tool
+ * `description` without dragging the sqlite driver into its import graph —
+ * the front-of-house Wave 0 workerd invariant. `content-range.ts` re-exports
+ * `MIN_CONTENT_LENGTH` from here, so every existing importer is unaffected.
+ */
+
+/**
+ * Minimum accepted `content_length`. A UTF-8 codepoint is at most 4 bytes,
+ * so any budget >= 4 is guaranteed to make progress (the codepoint at the
+ * window start always fits). Budgets 1–3 could stall forever on a 4-byte
+ * emoji (empty slice, next_offset == offset); rejecting them up front is
+ * deterministic and simpler than a runtime "no progress" error.
+ */
+export const MIN_CONTENT_LENGTH = 4;

package/core/src/content-range.test.ts

@@ -23,8 +23,13 @@ import {
   parseContentRange,
   sliceContentRange,
   applyContentRange,
+  parseAttachmentContentRange,
+  alignByteWindow,
   MIN_CONTENT_LENGTH,
+  DEFAULT_ATTACHMENT_WINDOW_BYTES,
+  MAX_ATTACHMENT_WINDOW_BYTES,
 } from "./content-range.js";
+import { QueryError } from "./query-operators.js";
 
 // ---------------------------------------------------------------------------
 // 1. parseContentRange
@@ -237,6 +242,128 @@ describe("content range — reassembly property", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// 2c. parseAttachmentContentRange + alignByteWindow (read-attachment)
+// ---------------------------------------------------------------------------
+
+describe("parseAttachmentContentRange", () => {
+  it("defaults offset=0, length=DEFAULT_ATTACHMENT_WINDOW_BYTES when both are omitted", () => {
+    expect(parseAttachmentContentRange(undefined, undefined)).toEqual({
+      offset: 0,
+      length: DEFAULT_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("offset only → length still defaults (never 'read to end' — that's the query-notes shape, not this one)", () => {
+    expect(parseAttachmentContentRange(1000, undefined)).toEqual({
+      offset: 1000,
+      length: DEFAULT_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("accepts an explicit length up to the max", () => {
+    expect(parseAttachmentContentRange(0, MAX_ATTACHMENT_WINDOW_BYTES)).toEqual({
+      offset: 0,
+      length: MAX_ATTACHMENT_WINDOW_BYTES,
+    });
+  });
+
+  it("rejects a length below MIN_CONTENT_LENGTH", () => {
+    expect(() => parseAttachmentContentRange(0, 2)).toThrow(QueryError);
+  });
+
+  it("rejects a length above MAX_ATTACHMENT_WINDOW_BYTES", () => {
+    expect(() => parseAttachmentContentRange(0, MAX_ATTACHMENT_WINDOW_BYTES + 1)).toThrow(QueryError);
+  });
+
+  it("rejects a negative offset", () => {
+    expect(() => parseAttachmentContentRange(-1, undefined)).toThrow(QueryError);
+  });
+});
+
+describe("alignByteWindow", () => {
+  /**
+   * Simulates the real caller: a BOUNDED positional read of
+   * `[max(0, offset-3), min(total, offset+length))` from `full`, THEN
+   * alignment — never handing the whole buffer to `alignByteWindow`, so a
+   * pass here proves the "never load the whole file" contract actually
+   * holds and isn't just true by accident of the test passing the full
+   * buffer.
+   */
+  function boundedRead(full: Buffer, offset: number, length: number): { raw: Uint8Array; rawStart: number } {
+    const total = full.byteLength;
+    const rawStart = Math.max(0, offset - 3);
+    // +1: alignByteWindow's end-boundary check reads the byte AT the
+    // (exclusive) window end to decide whether it's a continuation byte —
+    // that's one byte past `offset + length`, so the read must include it
+    // (see alignByteWindow's doc comment precondition).
+    const rawEnd = Math.min(total, offset + length + 1);
+    return { raw: full.subarray(rawStart, Math.max(rawStart, rawEnd)), rawStart };
+  }
+
+  it("offset past end → empty slice, complete (mirrors sliceContentRange)", () => {
+    const full = Buffer.from("abc", "utf8");
+    const { raw, rawStart } = boundedRead(full, 999, 16);
+    const r = alignByteWindow(raw, rawStart, { offset: 999, length: 16 }, full.byteLength);
+    expect(r.content).toBe("");
+    expect(r.content_offset).toBe(3);
+    expect(r.content_total_length).toBe(3);
+    expect(r.content_next_offset).toBeNull();
+  });
+
+  it("matches sliceContentRange byte-for-byte on a plain ASCII window", () => {
+    const s = "hello world";
+    const full = Buffer.from(s, "utf8");
+    const { raw, rawStart } = boundedRead(full, 0, 5);
+    const bounded = alignByteWindow(raw, rawStart, { offset: 0, length: 5 }, full.byteLength);
+    const whole = sliceContentRange(s, { offset: 0, length: 5 });
+    expect(bounded).toEqual(whole);
+  });
+
+  it("never splits a codepoint under a bounded read (matches sliceContentRange across a 4-byte emoji)", () => {
+    const s = "ab\u{1F600}cd"; // emoji occupies bytes 2..5 of 8
+    const full = Buffer.from(s, "utf8");
+    for (const [offset, length] of [
+      [0, 5], // budget cuts mid-emoji → backs off to byte 2
+      [2, 4], // exact emoji window
+      [4, 8], // offset lands mid-emoji → aligns down to byte 2
+      [6, 4], // final ASCII tail
+    ] as const) {
+      const { raw, rawStart } = boundedRead(full, offset, length);
+      const bounded = alignByteWindow(raw, rawStart, { offset, length }, full.byteLength);
+      const whole = sliceContentRange(s, { offset, length });
+      expect(bounded).toEqual(whole);
+    }
+  });
+
+  it("reassembly property: chaining content_next_offset through BOUNDED reads reproduces the full content", () => {
+    const rand = mulberry32(0xba5eba11);
+    const POOL = ["a", "Z", "9", " ", "\n", "é", "ψ", "你", "‱", "\u{1F600}", "\u{1D11E}"];
+    for (let iter = 0; iter < 40; iter++) {
+      const charCount = Math.floor(rand() * 100);
+      let content = "";
+      for (let i = 0; i < charCount; i++) content += POOL[Math.floor(rand() * POOL.length)]!;
+      const full = Buffer.from(content, "utf8");
+      const total = full.byteLength;
+      const budget = MIN_CONTENT_LENGTH + Math.floor(rand() * 13); // 4..16 bytes
+
+      let offset = 0;
+      let assembled = "";
+      for (let step = 0; step <= total + 2; step++) {
+        const { raw, rawStart } = boundedRead(full, offset, budget);
+        const slice = alignByteWindow(raw, rawStart, { offset, length: budget }, total);
+        expect(Buffer.byteLength(slice.content, "utf8")).toBeLessThanOrEqual(budget);
+        expect(slice.content_total_length).toBe(total);
+        assembled += slice.content;
+        if (slice.content_next_offset === null) break;
+        expect(slice.content_next_offset).toBeGreaterThan(offset);
+        offset = slice.content_next_offset;
+      }
+      expect(assembled).toBe(content);
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // 3. MCP face — query-notes
 // ---------------------------------------------------------------------------

package/core/src/content-range.ts

@@ -30,14 +30,11 @@
 
 import { QueryError } from "./query-operators.js";
 
-/**
- * Minimum accepted `content_length`. A UTF-8 codepoint is at most 4 bytes,
- * so any budget >= 4 is guaranteed to make progress (the codepoint at the
- * window start always fits). Budgets 1–3 could stall forever on a 4-byte
- * emoji (empty slice, next_offset == offset); rejecting them up front is
- * deterministic and simpler than a runtime "no progress" error.
- */
-export const MIN_CONTENT_LENGTH = 4;
+// `MIN_CONTENT_LENGTH` lives in the dependency-free `content-range-constants.ts`
+// so the pure-data MCP tool manifest can import it without pulling `bun:sqlite`
+// (front-of-house Wave 0). Re-exported here so existing importers are unchanged.
+export { MIN_CONTENT_LENGTH } from "./content-range-constants.js";
+import { MIN_CONTENT_LENGTH } from "./content-range-constants.js";
 
 export interface ContentRange {
   /** Byte offset (UTF-8) to start reading from. */
@@ -183,3 +180,103 @@ export function applyContentRange(
   result.content_total_length = fields.content_total_length;
   result.content_next_offset = fields.content_next_offset;
 }
+
+// ---------------------------------------------------------------------------
+// Attachment byte-window reads (`read-attachment`, Wave 2 model lane)
+// ---------------------------------------------------------------------------
+
+/** Default `read-attachment` text window when the caller omits `content_length` — small enough to never nuke a context budget. */
+export const DEFAULT_ATTACHMENT_WINDOW_BYTES = 65_536; // 64 KiB
+
+/** Hard per-call ceiling on `read-attachment`'s `content_length` — a deliberate-big-bite max, not a default. */
+export const MAX_ATTACHMENT_WINDOW_BYTES = 262_144; // 256 KiB
+
+/**
+ * Parse `read-attachment`'s `content_offset` / `content_length` pair.
+ * Unlike {@link parseContentRange} (query-notes: omitted params mean "range
+ * mode off, return everything"), a `read-attachment` call ALWAYS reads a
+ * bounded window — omitting `content_length` defaults it to
+ * {@link DEFAULT_ATTACHMENT_WINDOW_BYTES} rather than "the whole file" (an
+ * attachment can be arbitrarily large; a note can't cheaply be). Returns a
+ * fully-resolved `{offset, length}` (never the query-notes "null = off"
+ * shape). Throws `QueryError` (INVALID_QUERY) on a negative/non-integer
+ * value, a `content_length` below {@link MIN_CONTENT_LENGTH}, or one above
+ * {@link MAX_ATTACHMENT_WINDOW_BYTES}.
+ */
+export function parseAttachmentContentRange(
+  offsetRaw: unknown,
+  lengthRaw: unknown,
+): { offset: number; length: number } {
+  const offset = toNonNegativeInt(offsetRaw, "content_offset") ?? 0;
+  const length = toNonNegativeInt(lengthRaw, "content_length");
+  if (length !== undefined && length < MIN_CONTENT_LENGTH) {
+    throw new QueryError(
+      `invalid \`content_length\` value ${JSON.stringify(lengthRaw)} — must be at least ${MIN_CONTENT_LENGTH} bytes (the size of the largest UTF-8 codepoint, so every window makes progress).`,
+      "INVALID_QUERY",
+    );
+  }
+  if (length !== undefined && length > MAX_ATTACHMENT_WINDOW_BYTES) {
+    throw new QueryError(
+      `invalid \`content_length\` value ${JSON.stringify(lengthRaw)} — exceeds the ${MAX_ATTACHMENT_WINDOW_BYTES} byte (256 KiB) per-call max for read-attachment.`,
+      "INVALID_QUERY",
+    );
+  }
+  return { offset, length: length ?? DEFAULT_ATTACHMENT_WINDOW_BYTES };
+}
+
+/**
+ * Byte-level counterpart to {@link sliceContentRange} for `read-attachment`'s
+ * text path, where loading the WHOLE file into memory to slice a string
+ * (`sliceContentRange`'s approach) is exactly the thing a 500 MB attachment
+ * forbids. The caller does a BOUNDED positional read first — `raw` is
+ * whatever bytes it actually fetched, starting at file offset `rawStart`
+ * — and this function applies the identical alignment rules
+ * `sliceContentRange` applies to a full in-memory string, operating only on
+ * that window.
+ *
+ * Precondition (caller's responsibility, not re-validated here): `raw`
+ * covers at least `[max(0, range.offset - 3), min(total, range.offset +
+ * range.length) + 1)` — i.e. from 3 bytes before the requested offset
+ * through ONE byte past the requested end, clamped to `total`. The 3-byte
+ * lookback is enough to find the leading byte of any UTF-8 codepoint the
+ * requested `offset` might land inside (a codepoint is at most 4 bytes,
+ * i.e. at most 3 continuation bytes after its leading byte); the 1-byte
+ * lookahead is what the end-alignment check reads to decide whether the
+ * budget cut lands mid-codepoint (mirroring `sliceContentRange`, which
+ * checks `bytes[end]` — the byte AT the exclusive cut point).
+ */
+export function alignByteWindow(
+  raw: Uint8Array,
+  rawStart: number,
+  range: { offset: number; length: number },
+  total: number,
+): ContentRangeFields {
+  if (range.offset >= total) {
+    return {
+      content: "",
+      content_offset: total,
+      content_total_length: total,
+      content_next_offset: null,
+    };
+  }
+
+  const byteAt = (idx: number): number => raw[idx - rawStart]!;
+
+  // Align the start DOWN to the leading byte of the codepoint containing
+  // `offset` — same rule as sliceContentRange, bounded to what's in `raw`.
+  let start = range.offset;
+  while (start > rawStart && isContinuationByte(byteAt(start))) start--;
+
+  // Window end: budget capped at total, then clamped to what's actually in
+  // `raw` (defense-in-depth — a caller that under-read would otherwise
+  // index past the buffer). Aligned DOWN so the slice never ends mid-codepoint.
+  let end = Math.min(start + range.length, total, rawStart + raw.length);
+  while (end > start && end < total && isContinuationByte(byteAt(end))) end--;
+
+  return {
+    content: Buffer.from(raw.subarray(start - rawStart, end - rawStart)).toString("utf8"),
+    content_offset: start,
+    content_total_length: total,
+    content_next_offset: end >= total ? null : end,
+  };
+}

package/core/src/core.test.ts

@@ -5893,8 +5893,10 @@ describe("query-notes link expansion", async () => {
     expect(result[0].preview).toBeTruthy();
   });
 
-  it("expand_mode=summary with no metadata.summary renders empty body inline", async () => {
-    await store.createNote("unsummarized body", { path: "Plain" });
+  it("expand_mode=summary with no metadata.summary AND no lede (title-only note) renders empty body inline", async () => {
+    // Single-line content: the whole thing IS the title, so there's no
+    // paragraph after it for computeLede to fall back to.
+    await store.createNote("unsummarized title-only body", { path: "Plain" });
     await store.createNote("see [[Plain]]", { path: "Src" });
     const tools = generateMcpTools(store);
     const query = tools.find((t) => t.name === "query-notes")!;
@@ -5905,8 +5907,68 @@ describe("query-notes link expansion", async () => {
       expand_mode: "summary",
     }) as any;
     expect(result.content).toContain('mode="summary"');
-    // Summary is empty — we still get the block but with nothing between delimiters.
-    expect(result.content).not.toContain("unsummarized body");
+    // No summary, no lede — we still get the block but with nothing between delimiters.
+    expect(result.content).not.toContain("unsummarized title-only body");
+  });
+
+  it("expand_mode=summary with no metadata.summary falls back to the note's lede", async () => {
+    await store.createNote(
+      "# Long canonical statement\n\nUnforced / wu wei, in one paragraph.\n\n(Many paragraphs of detail follow...)",
+      { path: "Statements/NoSummary" },
+    );
+    await store.createNote("Overview: [[Statements/NoSummary]]", { path: "Index2" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await query.execute({
+      id: "Index2",
+      expand_links: true,
+      expand_mode: "summary",
+    }) as any;
+
+    expect(result.content).toContain('mode="summary"');
+    expect(result.content).toContain("Unforced / wu wei, in one paragraph.");
+    expect(result.content).not.toContain("Many paragraphs of detail");
+    // The heading/title itself isn't repeated as the summary.
+    expect(result.content).not.toContain("Long canonical statement");
+  });
+
+  it("expand_mode=summary: metadata.summary still wins over the lede when both are present", async () => {
+    await store.createNote(
+      "# Title\n\nThis is the lede paragraph, not the summary.",
+      { path: "Statements/Both", metadata: { summary: "The curated summary." } },
+    );
+    await store.createNote("see [[Statements/Both]]", { path: "Index3" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await query.execute({
+      id: "Index3",
+      expand_links: true,
+      expand_mode: "summary",
+    }) as any;
+
+    expect(result.content).toContain("The curated summary.");
+    expect(result.content).not.toContain("This is the lede paragraph");
+  });
+
+  it("expand_mode=summary lede fallback respects a leading frontmatter block", async () => {
+    await store.createNote(
+      "---\ntitle: X\n---\n# Real Title\n\nThe lede after frontmatter and title.",
+      { path: "Statements/Frontmatter" },
+    );
+    await store.createNote("see [[Statements/Frontmatter]]", { path: "Index4" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await query.execute({
+      id: "Index4",
+      expand_links: true,
+      expand_mode: "summary",
+    }) as any;
+
+    expect(result.content).toContain("The lede after frontmatter and title.");
+    expect(result.content).not.toContain("Real Title");
   });
 });
 

package/core/src/expand.ts

@@ -3,8 +3,9 @@
  *
  * Used by `query-notes` when `expand_links=true`. Replaces wikilink matches
  * with delimited blocks containing the linked note's content (full mode) or
- * metadata summary (summary mode). Deduplicates across the query and guards
- * against cycles via a shared `expanded` set.
+ * a summary (summary mode): `metadata.summary` when present, else the
+ * target note's lede (see `summaryText`). Deduplicates across the query and
+ * guards against cycles via a shared `expanded` set.
  */
 
 import { Database } from "bun:sqlite";
@@ -152,11 +153,18 @@ function renderSummary(note: Note): string {
   return `<expanded path="${pathAttr}" mode="summary">\n${summary}\n</expanded>`;
 }
 
+/**
+ * `metadata.summary` wins when present (no behavior change for existing
+ * callers). Absent it, falls back to the target note's lede — its opening
+ * paragraph, per `computeLede` — so a note that was never given a
+ * `metadata.summary` still yields something useful in summary-mode
+ * expansion instead of an empty block.
+ */
 function summaryText(note: Note): string {
   const meta = note.metadata as Record<string, unknown> | undefined;
   const s = meta?.summary;
   if (typeof s === "string" && s.trim()) return s.trim();
-  return "";
+  return noteOps.computeLede(note.content) ?? "";
 }
 
 function escapeAttr(s: string): string {

package/core/src/lede.test.ts

@@ -0,0 +1,96 @@
+/**
+ * `computeLede` — the first non-empty paragraph AFTER a note's title line,
+ * used by `expand_mode: "summary"` (core/src/expand.ts) as a fallback when
+ * `metadata.summary` is absent (summaries-as-content, 2026-07-17 dialogue).
+ *
+ * Shares its title-line rule (including the leading-frontmatter skip) with
+ * `computeDisplayTitle` — see `display-title.test.ts` for that function's
+ * own coverage. This file covers only the lede-specific behavior: where the
+ * paragraph starts, how it's collapsed, the length cap, and the
+ * title-only/no-content null cases.
+ */
+import { describe, it, expect } from "bun:test";
+import { computeLede, LEDE_MAX_LEN } from "./notes.js";
+
+describe("computeLede", () => {
+  it("returns the first paragraph after a heading title, blank-line separated", () => {
+    expect(
+      computeLede("# Title\n\nThis is the lede paragraph.\n\nSecond paragraph — not the lede."),
+    ).toBe("This is the lede paragraph.");
+  });
+
+  it("joins a multi-line paragraph into one collapsed line", () => {
+    expect(
+      computeLede("# Title\n\nThis lede paragraph\nspans two lines.\n\nSecond paragraph."),
+    ).toBe("This lede paragraph spans two lines.");
+  });
+
+  it("treats text immediately following the title (no blank line) as the lede", () => {
+    expect(computeLede("Grocery List\nmilk, eggs\ncheese")).toBe("milk, eggs cheese");
+  });
+
+  it("collapses internal whitespace runs to single spaces", () => {
+    expect(computeLede("Title\n\nLine one   with    extra   spaces.")).toBe(
+      "Line one with extra spaces.",
+    );
+  });
+
+  it("returns null for a title-only note (does not repeat the title)", () => {
+    expect(computeLede("Just a title")).toBeNull();
+    expect(computeLede("# Just a title")).toBeNull();
+  });
+
+  it("returns null when only blank lines follow the title", () => {
+    expect(computeLede("# Title\n\n\n   \n")).toBeNull();
+  });
+
+  it("returns null for empty, null, or undefined content", () => {
+    expect(computeLede("")).toBeNull();
+    expect(computeLede(null)).toBeNull();
+    expect(computeLede(undefined)).toBeNull();
+  });
+
+  it("returns null when content is whitespace-only (no title at all)", () => {
+    expect(computeLede("   \n\t\n   ")).toBeNull();
+  });
+
+  describe("leading frontmatter block", () => {
+    it("finds the lede after a closed frontmatter block AND its title line", () => {
+      expect(
+        computeLede("---\ntitle: X\n---\n# Real Title\n\nThe lede text."),
+      ).toBe("The lede text.");
+    });
+
+    it("finds the lede when the title immediately follows frontmatter with no blank line", () => {
+      expect(
+        computeLede("---\ntitle: X\n---\nReal Title\nlede text right after."),
+      ).toBe("lede text right after.");
+    });
+
+    it("returns null for a frontmatter-only note with no body after the title", () => {
+      expect(computeLede("---\ntitle: X\n---\nReal Title")).toBeNull();
+    });
+  });
+
+  describe("length cap", () => {
+    it("truncates to LEDE_MAX_LEN code points", () => {
+      const longParagraph = "a".repeat(1000);
+      const result = computeLede(`# Title\n\n${longParagraph}`)!;
+      expect(result.length).toBe(LEDE_MAX_LEN);
+      expect(result).toBe("a".repeat(LEDE_MAX_LEN));
+    });
+
+    it("does not truncate a lede at or under the cap", () => {
+      const exact = "a".repeat(LEDE_MAX_LEN);
+      expect(computeLede(`# Title\n\n${exact}`)).toBe(exact);
+      const short = "short lede";
+      expect(computeLede(`# Title\n\n${short}`)).toBe(short);
+    });
+
+    it("truncates by Unicode code point, not UTF-16 code unit (no split surrogate pairs)", () => {
+      const emojiParagraph = "😀".repeat(500);
+      const result = computeLede(`# Title\n\n${emojiParagraph}`)!;
+      expect(Array.from(result).length).toBe(LEDE_MAX_LEN);
+    });
+  });
+});