@agfpd/iapeer-memory-core 0.1.1

package/src/migrate-auto-memory.ts

@@ -0,0 +1,289 @@
+/**
+ * Migration of a harness's built-in per-peer auto-memory into the vault's
+ * agent-memory zone (`06_Agent_Memory/<agent>/`).
+ *
+ * TS port of the reference `scripts/migrate-auto-memory.py` (behavioural
+ * parity against `tests/python/test_migrate_auto_memory.py`, 16 fixtures).
+ * Deterministic, no LLM:
+ *
+ * 1. parse each source `.md` frontmatter (flat parser — auto-memory is
+ *    simple);
+ * 2. map the harness `type` → vault `subtype` (taxonomy tokens):
+ *    user → person_profile, feedback → feedback, project → context,
+ *    reference → reference, anything else → context. A `feedback` note
+ *    that is semantically a pitfall cannot be told apart
+ *    deterministically — re-filing to `pitfall` is the agent's manual step
+ *    after migration (distill phase 5);
+ * 3. build the agent-memory frontmatter (title from filename, type/status
+ *    tokens from the taxonomy, description through the SHARED YAML-safe
+ *    serialiser, created from birthtime/mtime, author = agent);
+ * 4. per-file: backup → write target (atomic) → unlink source. Idempotent:
+ *    an existing target file is skipped, never overwritten.
+ *
+ * ADAPTER SCOPE: the ENGINE is source-agnostic — the adapter supplies the
+ * source directory (claude: `~/.claude/agent-memory/<agent>/` for launchd
+ * peers, `~/.claude/projects/<slug>/memory/` for project sessions). The
+ * codex memories source location/format is NOT fact-checked yet — wiring
+ * it up is the codex-adapter's job once verified against a live codex
+ * (никогда не выдумываем формат из памяти модели).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { TaxonomyPreset } from "./taxonomy.js";
+import { yamlSafeScalar } from "./fm-update.js";
+
+/** Source files that are backed up but never copied into the vault. */
+export const SKIP_FILES: ReadonlySet<string> = new Set(["MEMORY.md"]);
+
+/** Flat frontmatter parser — first line of each `key: value` only. */
+export function parseFlatFrontmatter(text: string): [Record<string, string>, string] {
+  const m = /^---[^\S\n]*\n([\s\S]*?\n)---[^\S\n]*(?:\n|$)/.exec(text);
+  if (!m) return [{}, text];
+  const fm: Record<string, string> = {};
+  for (const line of m[1].split("\n")) {
+    if (!line.trim() || line.startsWith("#")) continue;
+    const i = line.indexOf(":");
+    if (i === -1) continue;
+    fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return [fm, text.slice(m[0].length)];
+}
+
+/** Harness auto-memory `type` → vault subtype token (taxonomy-driven). */
+export function mapTypeToSubtype(oldType: string, taxonomy: TaxonomyPreset): string {
+  const s = taxonomy.subtypes;
+  switch (oldType.trim().toLowerCase()) {
+    case "user":
+      return s.personProfile;
+    case "feedback":
+      return s.feedback;
+    case "project":
+      return s.context;
+    case "reference":
+      return s.reference;
+    default:
+      return s.context;
+  }
+}
+
+function fileCreatedDate(p: string): string {
+  const st = fs.statSync(p);
+  const birth = st.birthtimeMs > 0 ? st.birthtimeMs : st.mtimeMs;
+  return new Date(birth).toISOString().slice(0, 10);
+}
+
+/** Agent-memory frontmatter; description through the shared YAML-safe rules. */
+export function buildNewFrontmatter(opts: {
+  title: string;
+  subtype: string;
+  description: string;
+  created: string;
+  author: string;
+  taxonomy: TaxonomyPreset;
+}): string {
+  const desc = opts.description ? yamlSafeScalar(opts.description) : "''";
+  return [
+    "---",
+    `title: ${opts.title}`,
+    `type: ${opts.taxonomy.types.agentMemory}`,
+    `subtype: ${opts.subtype}`,
+    `status: ${opts.taxonomy.statusTokens.current}`,
+    `description: ${desc}`,
+    `created: ${opts.created}`,
+    `author: ${opts.author}`,
+    "---",
+  ].join("\n") + "\n";
+}
+
+export type MigrationPlan = {
+  source: string;
+  target: string;
+  files: Array<{ name: string; oldType?: string; subtype?: string; error?: string }>;
+  skippedSystem: string[];
+  skippedAlreadyInTarget: string[];
+  subtypeCounts: Record<string, number>;
+  totalToMigrate: number;
+};
+
+/** Scan the source and build the plan WITHOUT writing anything (dry-run). */
+export function planMigration(opts: {
+  sourceDir: string;
+  agent: string;
+  vault: string;
+  taxonomy: TaxonomyPreset;
+}): MigrationPlan {
+  const targetDir = path.join(opts.vault, opts.taxonomy.folders.agentMemory, opts.agent);
+  const files: MigrationPlan["files"] = [];
+  const skippedSystem: string[] = [];
+  const skippedAlreadyInTarget: string[] = [];
+  const subtypeCounts: Record<string, number> = {};
+
+  const entries = fs
+    .readdirSync(opts.sourceDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".md"))
+    .map((e) => e.name)
+    .sort();
+
+  for (const name of entries) {
+    if (SKIP_FILES.has(name)) {
+      skippedSystem.push(name);
+      continue;
+    }
+    if (fs.existsSync(path.join(targetDir, name))) {
+      skippedAlreadyInTarget.push(name);
+      continue;
+    }
+    let text: string;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(
+        fs.readFileSync(path.join(opts.sourceDir, name)),
+      );
+    } catch {
+      files.push({ name, error: "unreadable" });
+      continue;
+    }
+    const [fm] = parseFlatFrontmatter(text);
+    const oldType = (fm.type ?? "").trim().toLowerCase();
+    const subtype = mapTypeToSubtype(oldType, opts.taxonomy);
+    subtypeCounts[subtype] = (subtypeCounts[subtype] ?? 0) + 1;
+    files.push({ name, oldType: oldType || "(none)", subtype });
+  }
+
+  return {
+    source: opts.sourceDir,
+    target: targetDir,
+    files,
+    skippedSystem,
+    skippedAlreadyInTarget,
+    subtypeCounts,
+    totalToMigrate: files.length,
+  };
+}
+
+export type MigrationResult = {
+  migrated: string[];
+  skipped: string[];
+  errors: string[];
+  backupDir: string;
+  sourceRemoved: boolean;
+};
+
+/**
+ * Apply the migration: per-file backup → convert+write target → unlink
+ * source. A failed write leaves the source intact (the backup already
+ * exists). The source dir is removed only when it ends up empty (`rmdir`,
+ * never a recursive delete).
+ */
+export function applyMigration(opts: {
+  sourceDir: string;
+  agent: string;
+  vault: string;
+  backupRoot: string;
+  taxonomy: TaxonomyPreset;
+  /** Injectable for tests. */
+  now?: Date;
+}): MigrationResult {
+  const targetDir = path.join(opts.vault, opts.taxonomy.folders.agentMemory, opts.agent);
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const now = opts.now ?? new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const backupDir = path.join(opts.backupRoot, `${opts.agent}-${stamp}`);
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  const migrated: string[] = [];
+  const skipped: string[] = [];
+  const errors: string[] = [];
+
+  const entries = fs
+    .readdirSync(opts.sourceDir, { withFileTypes: true })
+    .filter((e) => e.isFile())
+    .map((e) => e.name)
+    .sort();
+
+  for (const name of entries) {
+    const srcPath = path.join(opts.sourceDir, name);
+
+    // 1. Backup BEFORE any processing.
+    try {
+      fs.copyFileSync(srcPath, path.join(backupDir, name));
+    } catch (err) {
+      errors.push(`${name}: backup failed — ${String(err)}`);
+      continue;
+    }
+
+    // 2a. Non-md and SKIP_FILES: backup-only, removed from the source.
+    if (!name.endsWith(".md") || SKIP_FILES.has(name)) {
+      try {
+        fs.unlinkSync(srcPath);
+      } catch (err) {
+        errors.push(`${name}: unlink after backup failed — ${String(err)}`);
+      }
+      continue;
+    }
+
+    // 2b. Markdown auto-memory: convert + atomic write + unlink source.
+    const targetFile = path.join(targetDir, name);
+    if (fs.existsSync(targetFile)) {
+      skipped.push(name);
+      try {
+        fs.unlinkSync(srcPath);
+      } catch (err) {
+        errors.push(`${name}: unlink (already migrated) failed — ${String(err)}`);
+      }
+      continue;
+    }
+
+    let text: string;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(fs.readFileSync(srcPath));
+    } catch (err) {
+      errors.push(`${name}: read failed — ${String(err)}`);
+      continue;
+    }
+
+    const [fm, body] = parseFlatFrontmatter(text);
+    const newFm = buildNewFrontmatter({
+      title: name.slice(0, -3),
+      subtype: mapTypeToSubtype(fm.type ?? "", opts.taxonomy),
+      description: (fm.description ?? "").trim(),
+      created: fileCreatedDate(srcPath),
+      author: opts.agent,
+      taxonomy: opts.taxonomy,
+    });
+    const newText = body
+      ? body.startsWith("\n")
+        ? newFm + body
+        : newFm + "\n" + body
+      : newFm;
+
+    try {
+      const tmp = `${targetFile}.tmp`;
+      fs.writeFileSync(tmp, newText, "utf-8");
+      fs.renameSync(tmp, targetFile);
+    } catch (err) {
+      errors.push(`${name}: write failed — ${String(err)}`);
+      continue; // source untouched — write failed
+    }
+
+    try {
+      fs.unlinkSync(srcPath);
+      migrated.push(name);
+    } catch (err) {
+      errors.push(`${name}: written to target but source unlink failed — ${String(err)}`);
+      migrated.push(name);
+    }
+  }
+
+  let sourceRemoved = false;
+  try {
+    fs.rmdirSync(opts.sourceDir);
+    sourceRemoved = true;
+  } catch {
+    // not empty / no rights — left in place, surfaced via errors/remnants
+  }
+
+  return { migrated, skipped, errors, backupDir, sourceRemoved };
+}

package/src/parser.ts

@@ -0,0 +1,269 @@
+import matter from "gray-matter";
+import { noteTitleFromPath } from "./utils.js";
+import { linksSectionPattern, type TaxonomyPreset } from "./taxonomy.js";
+
+const WIKILINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+
+/**
+ * Strip a wikilink target down to its stored form, KEEPING the path.
+ *
+ * Obsidian allows four wikilink shapes:
+ *   [[Name]]
+ *   [[Name|alias]]
+ *   [[Folder/Subfolder/Name]]
+ *   [[Folder/Subfolder/Name|alias]]
+ *
+ * The regex above already strips the `|alias` part. We only strip a trailing
+ * `.md` and trim — the folder path is deliberately preserved so the resolver
+ * (indexer.resolveWikilinks) can do path-aware resolution: an explicit
+ * `[[03_Проекты/A/Фаза]]` must NOT collapse to the bare basename and risk
+ * resolving to a same-named note in another project.
+ */
+function stripWikilinkTarget(raw: string): string {
+  return raw.replace(/\.md$/i, "").trim();
+}
+
+/**
+ * Last path segment of a (possibly path-qualified) wikilink target. Used by
+ * the resolver for the basename-uniqueness fallback when there is no path.
+ */
+export function wikilinkBasename(target: string): string {
+  const seg = target.includes("/") ? (target.split("/").pop() ?? target) : target;
+  return seg.trim();
+}
+
+export type ParsedChunk = {
+  chunkIndex: number;
+  text: string;
+};
+
+export type ParsedWikilink = {
+  target: string;
+  contextSnippet: string;
+};
+
+export type ParsedDocument = {
+  title: string;
+  body: string;
+  text: string;
+  frontmatter: Record<string, unknown>;
+  type: string | null;
+  status: string | null;
+  tags: string[];
+  created: string | null;
+  updated: string | null;
+  wikilinks: ParsedWikilink[];
+  chunks: ParsedChunk[];
+};
+
+export function parseMarkdown(content: string, relativePath: string, chunkSize: number, chunkOverlap: number, taxonomy: TaxonomyPreset): ParsedDocument {
+  const parsed = matter(content);
+  const frontmatter = normalizeFrontmatter(parsed.data);
+  const body = parsed.content.trim();
+  const title = typeof frontmatter.title === "string" ? frontmatter.title : noteTitleFromPath(relativePath);
+
+  // Wikilinks are still extracted from the FULL body (including the "## Связи"
+  // block) so the graph stays correct. But the indexed/embedded text is the
+  // note's actual content — without the links section the wikilinks would
+  // otherwise pollute BM25 hits and steal snippet fallback.
+  const indexableBody = stripLinksSection(body, taxonomy);
+
+  return {
+    title,
+    body,
+    text: content,
+    frontmatter,
+    type: asNullableString(frontmatter.type),
+    status: asNullableString(frontmatter.status),
+    tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.filter((tag): tag is string => typeof tag === "string") : [],
+    created: asNullableString(frontmatter.created),
+    updated: asNullableString(frontmatter.updated),
+    wikilinks: extractWikilinks(body),
+    chunks: chunkText(indexableBody, chunkSize, chunkOverlap, title),
+  };
+}
+
+/**
+ * Strip the leading links-section block (taxonomy.linksSection heading)
+ * from a note body before chunking.
+ *
+ * Vault notes follow a fixed structure: body starts with the links-section heading containing
+ * a list of [[wikilinks]], then a horizontal rule "---", then the actual
+ * content. The links section is graph metadata, not semantic content — feeding
+ * it to BM25/embeddings produces false hits on every note that mentions a
+ * popular wikilink target, and the snippet fallback in search.ts pulls the
+ * first chunk which (without this strip) is always just the links block.
+ *
+ * Only strips when both conditions hold: body starts with the heading AND a
+ * "---" divider follows. Notes without that structure pass through unchanged.
+ */
+export function stripLinksSection(body: string, taxonomy: TaxonomyPreset): string {
+  // The heading pattern comes from the taxonomy preset (ADR-002): `## Links`
+  // for the EN base, `## Связи` for RU. linksSectionPattern uses (?:\s|$)
+  // instead of `\b` — JS \b is ASCII-only and useless after a cyrillic
+  // letter (the strip silently no-op'd on every RU note before this fix).
+  if (!linksSectionPattern(taxonomy).test(body)) return body;
+  const dividerMatch = body.match(/\n---\s*\n/);
+  if (!dividerMatch || dividerMatch.index === undefined) return body;
+  return body.slice(dividerMatch.index + dividerMatch[0].length).trim();
+}
+
+/**
+ * Маскирует содержимое markdown code-областей пробелами равной длины. Это
+ * подавляет `[[X]]` внутри `\`код\`` и ```fenced ...``` от попадания в граф
+ * как реальные wikilinks — раньше шаблонные placeholder'ы из инструкций
+ * Индекса/копирайтера (`\`[[X]]\``, ```\n[[Связанная заметка]]\n```) шли в
+ * `edges` как broken links, забивая `unresolved_links` фолс-orphan'ами.
+ *
+ * Замена ПРОБЕЛАМИ (не удаление) — offset'ы остального текста не сдвигаются,
+ * `contextSnippet` ниже строится из ОРИГИНАЛЬНОГО body, окно вокруг wikilink
+ * остаётся правильным.
+ *
+ * Порядок: сначала fenced (3+ backticks/tildes на отдельных строках) — они
+ * длиннее и могут содержать внутри одиночные backticks; потом многократные
+ * inline (\`\`escape\`\`) и одиночные (\`code\`). Не покрывает edge-cases
+ * CommonMark с N-backtick парами (N≥3 inline) — в наших нотах не встречаются.
+ */
+function maskCodeRegions(body: string): string {
+  let masked = body;
+  // Fenced ```...``` или ~~~...~~~ (включая многострочное содержимое).
+  masked = masked.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length));
+  // Inline ``escape`` (double backtick — для строк с backtick внутри).
+  masked = masked.replace(/``[^`\n]+``/g, (m) => " ".repeat(m.length));
+  // Inline `code` (single backtick). [^`\n] — не переносить строку, и не есть
+  // вложенные backticks (CommonMark inline code не пересекает строку без
+  // явной обёртки).
+  masked = masked.replace(/`[^`\n]+`/g, (m) => " ".repeat(m.length));
+  return masked;
+}
+
+export function extractWikilinks(body: string): ParsedWikilink[] {
+  const masked = maskCodeRegions(body);
+  const matches: ParsedWikilink[] = [];
+  for (const match of masked.matchAll(WIKILINK_RE)) {
+    const rawTarget = match[1]?.trim();
+    if (!rawTarget) continue;
+    const start = Math.max(0, (match.index ?? 0) - 50);
+    const end = Math.min(body.length, (match.index ?? 0) + match[0].length + 50);
+    matches.push({
+      // Path-preserving: [[Name]] → "Name", [[Folder/Name]] → "Folder/Name",
+      // [[Folder/Name.md]] → "Folder/Name". The resolver decides path-exact
+      // vs basename-unique — it must see the path the author actually wrote.
+      target: stripWikilinkTarget(rawTarget),
+      // contextSnippet строим из оригинального body, не masked — иначе
+      // пользователь увидит пустоту вместо реального окружения wikilink'а.
+      contextSnippet: body.slice(start, end).replace(/\s+/g, " ").trim(),
+    });
+  }
+  return matches;
+}
+
+export function chunkText(
+  body: string,
+  chunkSize: number,
+  chunkOverlap: number,
+  title?: string,
+): ParsedChunk[] {
+  const normalized = body.replace(/\r\n/g, "\n").trim();
+  // Title prefix: BM25 (FTS5) and the embedding model both index chunk_text
+  // verbatim, so a note's title was effectively invisible to search. We
+  // prepend the title to the first chunk only — that's enough for both the
+  // keyword and semantic paths to "see" the note name without bloating every
+  // chunk and skewing BM25 with repeated matches.
+  const titlePrefix = title?.trim() ? `${title.trim()}\n\n` : "";
+
+  if (!normalized) {
+    // Empty body still indexes by title alone — otherwise a freshly-created
+    // note (frontmatter only) is unsearchable until first content edit.
+    return titlePrefix
+      ? [{ chunkIndex: 0, text: titlePrefix.trim() }]
+      : [];
+  }
+
+  const paragraphs = normalized
+    .split(/\n{2,}/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  // We accumulate text-only entries here and assign sequential chunkIndex
+  // values in the final map below. Internal type kept narrow so pushChunk's
+  // signature lines up.
+  const chunks: { text: string }[] = [];
+  let current = "";
+
+  for (const paragraph of paragraphs) {
+    if (!current) {
+      current = paragraph;
+      continue;
+    }
+
+    const candidate = `${current}\n\n${paragraph}`;
+    if (candidate.length <= chunkSize) {
+      current = candidate;
+      continue;
+    }
+
+    pushChunk(chunks, current);
+    current = mergeOverlap(current, paragraph, chunkOverlap);
+
+    // Infinite-loop guard: a paragraph longer than chunkSize with no
+    // splittable whitespace can make findSplitIndex return chunkSize and the
+    // post-slice tail can stay >chunkSize indefinitely. Bail when a pass
+    // doesn't shorten `current`.
+    while (current.length > chunkSize) {
+      const before = current.length;
+      const splitIndex = findSplitIndex(current, chunkSize);
+      pushChunk(chunks, current.slice(0, splitIndex).trim());
+      current = current.slice(Math.max(0, splitIndex - chunkOverlap)).trim();
+      if (current.length >= before) {
+        // Hard cut: drop the consumed prefix outright. Better a too-large
+        // last chunk than a wedged indexer.
+        pushChunk(chunks, current.slice(0, chunkSize));
+        current = current.slice(chunkSize);
+        break;
+      }
+    }
+  }
+
+  if (current) {
+    pushChunk(chunks, current);
+  }
+
+  // Prepend the title to chunk[0] in place — keeps chunkIndex sequencing
+  // intact and preserves the per-chunk size budget for the rest.
+  if (titlePrefix && chunks.length > 0) {
+    chunks[0] = { text: `${titlePrefix}${chunks[0].text}` };
+  }
+
+  return chunks.map((chunk, index) => ({ chunkIndex: index, text: chunk.text }));
+}
+
+function pushChunk(chunks: { text: string }[], text: string): void {
+  const normalized = text.trim();
+  if (normalized) chunks.push({ text: normalized });
+}
+
+function mergeOverlap(previous: string, next: string, overlap: number): string {
+  const tail = previous.slice(Math.max(0, previous.length - overlap)).trim();
+  return [tail, next].filter(Boolean).join("\n\n").trim();
+}
+
+function findSplitIndex(input: string, target: number): number {
+  const candidates = [input.lastIndexOf("\n", target), input.lastIndexOf(" ", target)].filter((index) => index > 0);
+  return Math.max(...candidates, Math.min(target, input.length));
+}
+
+function normalizeFrontmatter(data: unknown): Record<string, unknown> {
+  return data && typeof data === "object" && !Array.isArray(data) ? { ...(data as Record<string, unknown>) } : {};
+}
+
+function asNullableString(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  // gray-matter parses YAML date scalars (e.g. `created: 2026-03-30`) into
+  // Date objects. Without this branch the meta we surface from vault_read
+  // would silently drop them as null.
+  if (value instanceof Date && !Number.isNaN(value.getTime())) {
+    return value.toISOString().slice(0, 10);
+  }
+  return null;
+}

package/src/permanent-detect.ts

@@ -0,0 +1,110 @@
+/**
+ * Permanent-change detector core — a memoryd subsystem (ADR-004).
+ *
+ * Carries over the detection SEMANTICS of the reference
+ * `mergemind-permanent-monitor.sh` (a bash poll loop; no direct unit
+ * fixtures existed — the load-bearing part, the smart hash, is ported and
+ * tested in `smart-hash.ts`):
+ *
+ * - watches the SIX permanent folders (five canonical + agent memory),
+ *   recursively; the archive is deliberately ignored (frozen notes);
+ * - compares by the sha256 of the SEMANTIC part of each file (frontmatter
+ *   minus service fields + body, `smart-hash.ts`) — NOT raw bytes, NOT
+ *   mtime. This kills both noisy-event classes: iCloud mtime-only syncs
+ *   and the hook-induced loop (service-field re-stamps are invisible);
+ * - deletions are ignored (an archive move by the Index, not a change);
+ * - events are COALESCED (ADR-004): one diff pass yields ONE event
+ *   carrying the list of changed paths, not N wake-ups.
+ *
+ * The fs-watch/debounce shell and the stdout signal line belong to the
+ * memoryd daemon stage; this module is the pure snapshot/diff core.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { hashFile } from "./smart-hash.js";
+import type { TaxonomyPreset } from "./taxonomy.js";
+
+/** rel path → smart hash. */
+export type VaultSnapshot = Map<string, string>;
+
+function* walkMdFiles(dir: string): Generator<string> {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) yield* walkMdFiles(full);
+    else if (e.isFile() && e.name.endsWith(".md")) yield full;
+  }
+}
+
+/** The six monitored folders (five canonical + agent memory). */
+export function monitoredFolders(taxonomy: TaxonomyPreset): string[] {
+  const f = taxonomy.folders;
+  return [f.knowledge, f.decisions, f.projects, f.ideas, f.lists, f.agentMemory];
+}
+
+/**
+ * Snapshot the monitored folders: rel path → smart hash. Unreadable files
+ * are skipped silently (parity with the hash helper's CLI contract).
+ */
+export function snapshotVault(vault: string, taxonomy: TaxonomyPreset): VaultSnapshot {
+  const snapshot: VaultSnapshot = new Map();
+  for (const folder of monitoredFolders(taxonomy)) {
+    for (const filePath of walkMdFiles(path.join(vault, folder))) {
+      const h = hashFile(filePath);
+      if (h) snapshot.set(path.relative(vault, filePath), h);
+    }
+  }
+  return snapshot;
+}
+
+/**
+ * Semantic diff of two snapshots: added or changed paths, sorted.
+ * Deletions are ignored by design.
+ */
+export function diffSnapshots(prev: VaultSnapshot, next: VaultSnapshot): string[] {
+  const changed: string[] = [];
+  for (const [rel, hash] of next) {
+    if (prev.get(rel) !== hash) changed.push(rel);
+  }
+  return changed.sort();
+}
+
+export type PermanentChangedEvent = {
+  kind: "PERMANENT_CHANGED";
+  /** Coalesced list of changed vault-relative paths (ADR-004). */
+  paths: string[];
+};
+
+/**
+ * One detection pass: diff the current vault state against the previous
+ * snapshot. Returns the coalesced event (or null when nothing changed)
+ * plus the snapshot to carry into the next pass.
+ */
+export function detectPermanentChanges(opts: {
+  vault: string;
+  taxonomy: TaxonomyPreset;
+  prev: VaultSnapshot;
+}): { event: PermanentChangedEvent | null; next: VaultSnapshot } {
+  const next = snapshotVault(opts.vault, opts.taxonomy);
+  const paths = diffSnapshots(opts.prev, next);
+  return {
+    event: paths.length ? { kind: "PERMANENT_CHANGED", paths } : null,
+    next,
+  };
+}
+
+/**
+ * Render the event as memoryd stdout signal lines (one per path — the
+ * notifier forwards each line verbatim; the Index batches the visible
+ * burst in one turn, and the coalescing above already bounds the burst to
+ * one pass).
+ */
+export function formatEventLines(event: PermanentChangedEvent): string[] {
+  return event.paths.map((p) => `PERMANENT_CHANGED: ${p}`);
+}