pi-weave 0.1.1

package/src/core/summaries.ts

@@ -0,0 +1,300 @@
+/**
+ * Deep-scan summaries (docs/scan-modes.md): LLM-written, one sidecar
+ * Markdown file per summarized source file, stored under
+ * `<repo>/.okf/repository/summaries/`. Incremental via content hash.
+ *
+ * Core never talks to an LLM — `runDeepScan` takes an injected
+ * `summarize(path, content)` function. The pi adapter wires the session
+ * model (pi-ai completeSimple); tests inject a fake.
+ */
+
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import { join } from "node:path";
+import { parseFrontMatter, quoteField, unquoteField } from "./frontmatter";
+import { listFiles } from "./git";
+import { repoKnowledgeDir } from "./paths";
+import type { NoteSource } from "./types";
+
+export const SUMMARIES_DIR = "summaries";
+export const SUMMARY_SUFFIX = ".summary.md";
+
+export const DEEP_SCAN_MAX_FILES = 300;
+export const DEEP_SCAN_MAX_FILE_BYTES = 32_768;
+export const DEEP_SCAN_CONCURRENCY = 4;
+
+/** A parsed summary sidecar. */
+export interface SummaryRecord {
+  /** Repo-relative source path this summary describes. */
+  target: string;
+  /** sha1 of the file content at summarize time. */
+  contentHash: string;
+  summary: string;
+  model: string | null;
+  at: string;
+  source: NoteSource;
+}
+
+/** One call to the (injected) language model. */
+export type SummarizeFn = (file: { path: string; content: string }) => Promise<string>;
+
+export interface DeepScanOptions {
+  summarize: SummarizeFn;
+  at?: () => Date;
+  maxFiles?: number;
+  maxFileBytes?: number;
+  concurrency?: number;
+  /** Model label recorded in sidecar front matter (provenance detail). */
+  model?: string;
+  /**
+   * Called before each candidate file is processed. `current` is 1-based
+   * (the file about to be handled), `total` is the candidate count — the
+   * adapter renders this as a live progress line.
+   */
+  onProgress?: (info: { current: number; total: number; path: string }) => void;
+  /** When aborted, stop scheduling new work and return partial results. */
+  signal?: AbortSignal;
+}
+
+export interface DeepScanFailure {
+  path: string;
+  error: string;
+}
+
+export interface DeepScanResult {
+  /** Candidate source files considered (after skip-lists and caps). */
+  considered: number;
+  written: number;
+  /** Unchanged since their summary (content hash match) — no LLM call. */
+  skippedFresh: number;
+  /** Candidates skipped because they exceed the byte cap. */
+  skippedTooBig: number;
+  failed: DeepScanFailure[];
+  /** Sidecars removed because their target is no longer tracked. */
+  pruned: number;
+}
+
+/** Deterministic sidecar file name for a repo-relative target path. */
+export function summaryFileName(target: string): string {
+  return target.split("/").join("--") + SUMMARY_SUFFIX;
+}
+
+function summariesDir(repoRoot: string): string {
+  return join(repoKnowledgeDir(repoRoot), SUMMARIES_DIR);
+}
+
+/** Absolute sidecar path for a target (name is derived, never user input). */
+export function summaryPath(repoRoot: string, target: string): string {
+  return join(summariesDir(repoRoot), summaryFileName(target));
+}
+
+/**
+ * Serialize a summary sidecar: OKF-front-matter + summary body, provenance
+ * always "generated" (AGENTS.md rule 4).
+ */
+export function serializeSummary(rec: SummaryRecord): string {
+  const lines = [
+    "---",
+    `target: ${quoteField(rec.target)}`,
+    `source: ${rec.source}`,
+    `content_hash: ${quoteField(rec.contentHash)}`,
+    `at: ${quoteField(rec.at)}`,
+  ];
+  if (rec.model !== null) lines.push(`model: ${quoteField(rec.model)}`);
+  lines.push("---", "", rec.summary.replace(/\s+$/, ""), "");
+  return lines.join("\n");
+}
+
+export function parseSummaryFile(text: string): SummaryRecord | null {
+  const parsed = parseFrontMatter(text);
+  if (!parsed) return null;
+  const target = unquoteField(parsed.fields.get("target") ?? "");
+  const contentHash = unquoteField(parsed.fields.get("content_hash") ?? "");
+  const at = unquoteField(parsed.fields.get("at") ?? "");
+  if (target.length === 0 || contentHash.length === 0 || at.length === 0) return null;
+  const rawSource = parsed.fields.get("source") ?? "";
+  return {
+    target,
+    contentHash,
+    summary: parsed.body,
+    model: parsed.fields.has("model") ? unquoteField(parsed.fields.get("model") ?? "") : null,
+    at,
+    source: rawSource === "human" || rawSource === "agent" || rawSource === "generated"
+      ? rawSource
+      : "generated",
+  };
+}
+
+/** All summaries currently on disk. Corrupt sidecars are skipped. */
+export async function readSummaries(repoRoot: string): Promise<SummaryRecord[]> {
+  let names: string[];
+  try {
+    names = await fs.readdir(summariesDir(repoRoot));
+  } catch {
+    return [];
+  }
+  const out: SummaryRecord[] = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith(SUMMARY_SUFFIX)) continue;
+    try {
+      const rec = parseSummaryFile(await fs.readFile(join(summariesDir(repoRoot), name), "utf8"));
+      if (rec) out.push(rec);
+    } catch {
+      // unreadable sidecar — skip
+    }
+  }
+  return out;
+}
+
+/** Summaries keyed by target path — the shape buildGraph/dash want. */
+export async function readSummaryMap(repoRoot: string): Promise<Map<string, SummaryRecord>> {
+  const map = new Map<string, SummaryRecord>();
+  for (const rec of await readSummaries(repoRoot)) map.set(rec.target, rec);
+  return map;
+}
+
+/* ------------------------------------------------------------------ */
+/* Deep scan                                                           */
+/* ------------------------------------------------------------------ */
+
+/** Files that never deserve a summary (lockfiles, minified, snapshots, media). */
+const SKIP_NAME = /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|composer\.lock|cargo\.lock|go\.sum|gemfile\.lock|poetry\.lock|bun\.lockb?)$/i;
+const SKIP_EXT = /\.(min\.(js|css)|map|snap|png|jpe?g|gif|webp|avif|ico|bmp|svg|woff2?|ttf|otf|eot|pdf|zip|gz|tgz|bz2|xz|7z|rar|jar|war|wasm|sqlite3?|db|bin|exe|dll|so|dylib|a|o|class|pyc|mp[34]|mov|webm|wav|flac|ogg)$/i;
+
+/** Cheap binary sniff: NUL byte in the first 8 KiB means binary. */
+function looksBinary(buf: Buffer): boolean {
+  const limit = Math.min(buf.length, 8192);
+  for (let i = 0; i < limit; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/** Never summarize our own derived artifacts (`.okf/` sidecars etc.). */
+const SKIP_OKF = /(^|\/)\.okf(\/|$)/;
+
+export function isSummarizablePath(path: string): boolean {
+  return !SKIP_OKF.test(path) && !SKIP_NAME.test(path) && !SKIP_EXT.test(path);
+}
+
+export function hashContent(content: string | Buffer): string {
+  return createHash("sha1").update(content).digest("hex");
+}
+
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>,
+  shouldStop?: () => boolean,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (next < items.length) {
+      if (shouldStop?.()) return;
+      const i = next++;
+      results[i] = await fn(items[i] as T, i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
+  return results;
+}
+
+/**
+ * Run the deep scan: summarize tracked source files into summary sidecars.
+ * Incremental (content-hash skip) and failure-tolerant per file.
+ */
+export async function runDeepScan(repoRoot: string, options: DeepScanOptions): Promise<DeepScanResult | null> {
+  const maxFiles = options.maxFiles ?? DEEP_SCAN_MAX_FILES;
+  const maxFileBytes = options.maxFileBytes ?? DEEP_SCAN_MAX_FILE_BYTES;
+  const concurrency = options.concurrency ?? DEEP_SCAN_CONCURRENCY;
+  const now = options.at ?? (() => new Date());
+  const signal = options.signal;
+  const onProgress = options.onProgress;
+  const aborted = () => signal?.aborted === true;
+
+  const listed = await listFiles(repoRoot);
+  if (listed === null) return null; // not a git repository
+
+  const candidates = listed.filter(isSummarizablePath).slice(0, maxFiles);
+  const existing = await readSummaryMap(repoRoot);
+  const existingByHash = new Map<string, SummaryRecord>(
+    [...existing.values()].map((r) => [r.target, r]),
+  );
+
+  const result: DeepScanResult = {
+    considered: candidates.length,
+    written: 0,
+    skippedFresh: 0,
+    skippedTooBig: 0,
+    failed: [],
+    pruned: 0,
+  };
+
+  await mapWithConcurrency(candidates, concurrency, async (path, index) => {
+    onProgress?.({ current: index + 1, total: candidates.length, path });
+    let buf: Buffer;
+    try {
+      buf = await fs.readFile(join(repoRoot, path));
+    } catch {
+      result.failed.push({ path, error: "unreadable" });
+      return;
+    }
+    if (buf.length > maxFileBytes || (buf.length > 0 && looksBinary(buf))) {
+      result.skippedTooBig += 1;
+      return;
+    }
+    const hash = hashContent(buf);
+    if (existingByHash.get(path)?.contentHash === hash) {
+      result.skippedFresh += 1;
+      return;
+    }
+    try {
+      const summary = (await options.summarize({ path, content: buf.toString("utf8") })).trim();
+      await writeSummary(repoRoot, {
+        target: path,
+        contentHash: hash,
+        summary,
+        model: options.model ?? null,
+        at: now().toISOString(),
+        source: "generated",
+      });
+      result.written += 1;
+    } catch (err) {
+      result.failed.push({ path, error: err instanceof Error ? err.message : String(err) });
+    }
+  }, aborted);
+
+  // Prune sidecars whose target left the tracked set.
+  const targets = new Set(listed);
+  result.pruned = await pruneSummaries(repoRoot, (rec) => targets.has(rec.target));
+  return result;
+}
+
+/** Write one summary sidecar (mkdir -p; rename for crash safety). */
+export async function writeSummary(repoRoot: string, rec: SummaryRecord): Promise<string> {
+  const dir = summariesDir(repoRoot);
+  await fs.mkdir(dir, { recursive: true });
+  const file = summaryPath(repoRoot, rec.target);
+  const tmp = `${file}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, serializeSummary(rec), "utf8");
+  await fs.rename(tmp, file);
+  return file;
+}
+
+/** Delete sidecars whose record fails `keep`. Returns number removed. */
+export async function pruneSummaries(
+  repoRoot: string,
+  keep: (rec: SummaryRecord) => boolean,
+): Promise<number> {
+  const dir = summariesDir(repoRoot);
+  let removed = 0;
+  for (const rec of await readSummaries(repoRoot)) {
+    if (keep(rec)) continue;
+    try {
+      await fs.unlink(join(dir, summaryFileName(rec.target)));
+      removed += 1;
+    } catch {
+      // already gone
+    }
+  }
+  return removed;
+}

package/src/core/types.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared types for pi-weave core.
+ *
+ * This module — and everything under src/core — must NEVER import from
+ * @earendil-works/* or any other harness-specific package. The core is the
+ * portable artifact shared by the pi adapter today and the Claude Code /
+ * opencode adapters tomorrow (see docs/design.md §21).
+ */
+
+/** Where a piece of knowledge came from. Drives trust display (design §13). */
+export type NoteSource = "human" | "agent" | "generated";
+
+export const NOTE_SOURCES: readonly NoteSource[] = ["human", "agent", "generated"];
+
+/** Metadata parsed from a vault note's front matter. */
+export interface NoteMeta {
+  title: string;
+  /** ISO-8601 timestamps. */
+  created: string;
+  updated: string;
+  tags: string[];
+  source: NoteSource;
+}
+
+/** A vault note: metadata plus its Markdown body. */
+export interface Note extends NoteMeta {
+  /** File-name slug (no extension). Stable identity of the note. */
+  slug: string;
+  body: string;
+}
+
+/** Summary of one note for list/search output. */
+export interface NoteSummary extends NoteMeta {
+  slug: string;
+  /** Size of the Markdown body in characters. */
+  bodyLength: number;
+}
+
+/** A search hit: the note plus a relevance score and a snippet. */
+export interface NoteSearchHit {
+  summary: NoteSummary;
+  score: number;
+  snippet: string;
+}
+
+/** Git state snapshot used as the staleness anchor for a repo index. */
+export interface GitState {
+  headSha: string;
+  branch: string;
+  /** Tracked-or-untracked files differing from HEAD (porcelain paths). */
+  changedFiles: string[];
+  /**
+   * sha1 of each changed path's worktree content at capture time; null for
+   * paths without file content (deletions, untracked directories). Anchors
+   * content, not just paths: re-editing an already-dirty file still moves
+   * the anchor. Indexes written before this field existed omit it — readers
+   * must tolerate its absence.
+   */
+  changedHashes: Record<string, string | null>;
+  capturedAt: string;
+}
+
+/** Repository identity (repository/identity.json). */
+export interface RepoIdentity {
+  name: string;
+  root: string;
+  remotes: string[];
+  defaultBranch: string | null;
+}
+
+/** One manifest detected in the repository (package boundary). */
+export interface RepoPackage {
+  /** Manifest path relative to the repo root, e.g. "packages/core/package.json". */
+  manifestPath: string;
+  kind: "npm" | "python" | "rust" | "go" | "ruby" | "other";
+  /** Package name when it can be read cheaply, else the directory name. */
+  name: string;
+}
+
+/** A coarse module: a meaningful directory grouping of files. */
+export interface RepoModule {
+  path: string;
+  fileCount: number;
+}
+
+/** Structural picture of the repository (repository/structure.json). */
+export interface RepoStructure {
+  capturedAt: string;
+  fileCount: number;
+  /** Language name -> file count, e.g. { TypeScript: 12 }. */
+  languages: Record<string, number>;
+  packages: RepoPackage[];
+  modules: RepoModule[];
+  /** Likely entry points, repo-relative paths. */
+  entryPoints: string[];
+  /** Top-level directory listing with direct file counts. */
+  topLevel: { name: string; fileCount: number }[];
+  /**
+   * Files under the derived <repo>/.okf/ index (repo-relative, e.g.
+   * "repository/git.json"), captured so the viewer can render `.okf` as an
+   * expandable subtree. Absent when there is no `.okf` directory.
+   */
+  okFiles?: string[];
+}
+
+/** The full repository index held under <repo>/.okf/repository/. */
+export interface RepoIndex {
+  okfVersion: 1;
+  scope: "repository";
+  generator: string;
+  /**
+   * Provenance of the whole index (AGENTS.md rule 4). Repository indexes
+   * are machine-derived, so this is always "generated" when pi-weave writes
+   * them; the reader preserves it so consumers can tell generated knowledge
+   * apart from human-authored OKF content.
+   */
+  source: NoteSource;
+  created: string;
+  updated: string;
+  identity: RepoIdentity;
+  git: GitState;
+  structure: RepoStructure;
+}
+
+export type StalenessState = "missing" | "fresh" | "stale";
+
+export interface StalenessReport {
+  state: StalenessState;
+  reasons: string[];
+}
+
+/** Status of the vault half of the workspace. */
+export interface VaultStatus {
+  root: string;
+  exists: boolean;
+  noteCount: number;
+}
+
+/** Status of the repository half of the workspace. */
+export interface RepoStatus {
+  root: string;
+  name: string;
+  indexed: boolean;
+  staleness: StalenessReport;
+  /** Deep-scan summaries on disk (docs/scan-modes.md); 0 when none indexed. */
+  summaryCount: number;
+}
+
+/** Combined knowledge-workspace view for the current directory. */
+export interface WorkspaceStatus {
+  cwd: string;
+  vault: VaultStatus;
+  /** null when cwd is not inside a git repository. */
+  repository: RepoStatus | null;
+}

package/src/core/vault.ts

@@ -0,0 +1,254 @@
+import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { parseNoteFile, serializeNote } from "./frontmatter";
+import { NOTES_DIR, OKF_MANIFEST } from "./paths";
+import { slugify, uniqueSlug } from "./slug";
+import type { Note, NoteMeta, NoteSearchHit, NoteSource, NoteSummary } from "./types";
+
+/**
+ * The vault: the "smart notepad" half of pi-weave.
+ *
+ * Plain Markdown files with front matter under <vault>/notes/. Humans can
+ * edit them in any editor; agents read/write them through this layer so the
+ * format stays consistent (design §1, §13).
+ */
+
+export interface AddNoteInput {
+  title: string;
+  body: string;
+  tags?: string[];
+  source?: NoteSource;
+  /** Injectable clock for tests. */
+  now?: Date;
+}
+
+interface VaultManifest {
+  okfVersion: 1;
+  scope: "vault";
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Create the vault layout if needed. Idempotent. */
+export async function ensureVault(root: string): Promise<void> {
+  await fs.mkdir(join(root, NOTES_DIR), { recursive: true });
+  const manifestPath = join(root, OKF_MANIFEST);
+  if (!(await exists(manifestPath))) {
+    const manifest: VaultManifest = { okfVersion: 1, scope: "vault" };
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  }
+}
+
+export async function vaultExists(root: string): Promise<boolean> {
+  return exists(join(root, OKF_MANIFEST));
+}
+
+function notePath(root: string, slug: string): string {
+  return join(root, NOTES_DIR, `${slug}.md`);
+}
+
+/**
+ * Resolve a note slug to its on-disk path, or null when the slug is unsafe.
+ * Slugs arrive from tool parameters, so they are untrusted: `../x`, nested
+ * paths, and absolute escapes must never read or write outside the flat
+ * <vault>/notes/ directory.
+ */
+export function resolveNotePath(root: string, slug: string): string | null {
+  if (slug.trim().length === 0) return null;
+  const notesDir = join(root, NOTES_DIR);
+  const candidate = join(notesDir, `${slug}.md`);
+  const rel = relative(notesDir, candidate);
+  if (rel.startsWith("..") || isAbsolute(rel) || rel.includes(sep)) return null;
+  return candidate;
+}
+
+/** Create a note. Returns the written note (with its final, unique slug). */
+export async function addNote(root: string, input: AddNoteInput): Promise<Note> {
+  await ensureVault(root);
+  const now = (input.now ?? new Date()).toISOString();
+  const base = slugify(input.title);
+  const slug = uniqueSlug(base, (candidate) => existsSync(notePath(root, candidate)));
+
+  const meta: NoteMeta = {
+    title: input.title,
+    created: now,
+    updated: now,
+    tags: input.tags ?? [],
+    source: input.source ?? "agent",
+  };
+  const text = serializeNote(meta, input.body);
+  await fs.writeFile(notePath(root, slug), text, "utf8");
+  return { slug, ...meta, body: input.body };
+}
+
+/** Read a note by slug. Returns null when missing, malformed, or an unsafe slug. */
+export async function getNote(root: string, slug: string): Promise<Note | null> {
+  const path = resolveNotePath(root, slug);
+  if (!path) return null;
+  let text: string;
+  try {
+    text = await fs.readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const { meta, body } = parseNoteFile(text);
+    return { slug, ...meta, body };
+  } catch {
+    return null;
+  }
+}
+
+/** Append Markdown to an existing note and bump `updated`. */
+export async function appendToNote(
+  root: string,
+  slug: string,
+  addition: string,
+  now: Date = new Date(),
+): Promise<Note | null> {
+  const path = resolveNotePath(root, slug);
+  if (!path) return null;
+  const note = await getNote(root, slug);
+  if (!note) return null;
+  const body = note.body.replace(/\s+$/, "") + "\n\n" + addition.trim() + "\n";
+  const meta: NoteMeta = { ...note, updated: now.toISOString() };
+  await fs.writeFile(path, serializeNote(meta, body), "utf8");
+  return { slug, ...meta, body };
+}
+
+/** The append-only tail where verbatim user scribbles live (docs/notepad.md §4). */
+export const RAW_NOTES_HEADING = "## Raw notes";
+
+/**
+ * Extract the `## Raw notes` tail (heading + everything after) verbatim, or
+ * "" when the note has no raw tail. Used by finalization so the literal
+ * record of the user's words is never rewritten.
+ */
+export function extractRawTail(body: string): string {
+  const idx = body.indexOf(RAW_NOTES_HEADING);
+  if (idx === -1) return "";
+  return body.slice(idx).trimEnd();
+}
+
+export interface FinalizeNoteInput {
+  /**
+   * The restructured body ABOVE the raw tail (front-loaded summary, sections,
+   * entities, links). The `## Raw notes` tail is preserved verbatim beneath it.
+   */
+  body: string;
+  /** Injectable clock for tests. */
+  now?: Date;
+}
+
+/**
+ * Finalize a note: replace the body above the `## Raw notes` tail with a
+ * restructured version, preserving the raw tail verbatim (append-only).
+ * Returns null when the note is missing or the slug is unsafe.
+ */
+export async function finalizeNote(
+  root: string,
+  slug: string,
+  input: FinalizeNoteInput,
+): Promise<Note | null> {
+  const path = resolveNotePath(root, slug);
+  if (!path) return null;
+  const note = await getNote(root, slug);
+  if (!note) return null;
+  const rawTail = extractRawTail(note.body);
+  const body = input.body.trim() + (rawTail ? `\n\n${rawTail}` : "");
+  const meta: NoteMeta = { ...note, updated: (input.now ?? new Date()).toISOString() };
+  await fs.writeFile(path, serializeNote(meta, body), "utf8");
+  return { slug, ...meta, body };
+}
+
+async function listNoteFiles(root: string): Promise<string[]> {
+  const dir = join(root, NOTES_DIR);
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter((name) => name.endsWith(".md")).sort();
+}
+
+/** List all notes with their metadata, newest-updated first. */
+export async function listNotes(root: string): Promise<NoteSummary[]> {
+  const files = await listNoteFiles(root);
+  const summaries: NoteSummary[] = [];
+  for (const file of files) {
+    const slug = file.slice(0, -".md".length);
+    const note = await getNote(root, slug);
+    if (!note) continue; // unreadable/malformed files are skipped, not fatal
+    const { body, ...summary } = note;
+    summaries.push({ ...summary, bodyLength: body.length });
+  }
+  return summaries.sort((a, b) => b.updated.localeCompare(a.updated));
+}
+
+export async function noteCount(root: string): Promise<number> {
+  return (await listNoteFiles(root)).length;
+}
+
+/**
+ * Substring search over title, tags, and body.
+ * Score: title match = 3, tag match = 2, body match = 1 each (capped).
+ * Case-insensitive. Deterministic ordering: score desc, then slug asc.
+ */
+export async function searchNotes(root: string, query: string): Promise<NoteSearchHit[]> {
+  const q = query.toLowerCase().trim();
+  if (q.length === 0) return [];
+
+  const hits: NoteSearchHit[] = [];
+  for (const summary of await listNotes(root)) {
+    const note = await getNote(root, summary.slug);
+    if (!note) continue;
+
+    let score = 0;
+    if (note.title.toLowerCase().includes(q)) score += 3;
+    if (note.tags.some((t) => t.toLowerCase().includes(q))) score += 2;
+
+    const bodyLower = note.body.toLowerCase();
+    let bodyMatches = 0;
+    let idx = bodyLower.indexOf(q);
+    while (idx >= 0 && bodyMatches < 5) {
+      bodyMatches++;
+      idx = bodyLower.indexOf(q, idx + q.length);
+    }
+    score += bodyMatches;
+
+    if (score === 0) continue;
+    hits.push({ summary, score, snippet: makeSnippet(note.body, q) });
+  }
+  return hits.sort((a, b) => b.score - a.score || a.summary.slug.localeCompare(b.summary.slug));
+}
+
+function makeSnippet(body: string, q: string, radius = 60): string {
+  const idx = body.toLowerCase().indexOf(q);
+  if (idx === -1) {
+    return body.trim().slice(0, radius * 2);
+  }
+  const start = Math.max(0, idx - radius);
+  const end = Math.min(body.length, idx + q.length + radius);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < body.length ? "…" : "";
+  return (prefix + body.slice(start, end) + suffix).replace(/\s+/g, " ").trim();
+}
+
+/** Re-export so adapters do not need to know about frontmatter details. */
+export { serializeNote, parseNoteFile };
+
+/** Render a note as Markdown text for agent/human consumption. */
+export function formatNote(note: Note): string {
+  const tags = note.tags.length > 0 ? `, tags: ${note.tags.join(", ")}` : "";
+  const header = `# ${note.title}\n(slug: ${note.slug}, updated ${note.updated}${tags}, source: ${note.source})`;
+  return `${header}\n\n${note.body.trim()}\n`;
+}