@staix/vault-mem 0.0.0-stage → 0.1.0

package/src/frontmatter.ts

@@ -0,0 +1,154 @@
+import { isDeepStrictEqual } from "node:util";
+import { parseYamlWithQuotedEscapes } from "./yaml-quoted.ts";
+
+interface FieldSpan { key: string; start: number; end: number }
+export interface FrontmatterDocument {
+  readonly source: string;
+  readonly body: string;
+  readonly data: Record<string, unknown>;
+  /** Original delimiters and YAML, including their original line endings. */
+  readonly frontmatter: string | null;
+}
+interface ParsedDocument extends FrontmatterDocument {
+  start: number;
+  end: number;
+  newline: string;
+  fields: FieldSpan[];
+}
+
+function mapping(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Locate a block mapping's top-level keys without mistaking quoted/flow content for keys. */
+function fieldSpans(yaml: string): FieldSpan[] {
+  const fields: FieldSpan[] = [];
+  let offset = 0, quote = "", flow = 0;
+  let blockIndent: number | null = null;
+  for (const line of yaml.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+    if (blockIndent !== null) {
+      const indent = line.match(/^[ \t]*/)![0].length;
+      if (!line.trim() || indent > blockIndent) { offset += line.length; continue; }
+      blockIndent = null;
+    }
+    if (!quote && !flow && /^[^ \t\r\n#{\[]/.test(line)) {
+      let keyQuote = "", colon = -1;
+      for (let i = 0; i < line.length; i++) {
+        const c = line[i]!;
+        if (keyQuote) {
+          if (c === "\\" && keyQuote === '"') { i++; continue; }
+          if (c === keyQuote) {
+            if (c === "'" && line[i + 1] === "'") { i++; continue; }
+            keyQuote = "";
+          }
+        } else if ((c === '"' || c === "'") && i === 0) keyQuote = c;
+        else if (c === ":" && /[ \t\r\n]/.test(line[i + 1] ?? "\n")) { colon = i; break; }
+      }
+      if (colon >= 0) {
+        const parsed: unknown = parseYamlWithQuotedEscapes(`${line.slice(0, colon)}: null`);
+        if (!mapping(parsed) || Object.keys(parsed).length !== 1) throw new Error("frontmatter: expected string mapping key");
+        const key = Object.keys(parsed)[0]!;
+        if (fields.some(field => field.key === key)) throw new Error("frontmatter: duplicate key");
+        fields.push({ key, start: offset, end: yaml.length });
+      }
+    }
+    let nodeStart = !quote && flow === 0;
+    for (let i = 0; i < line.length; i++) {
+      const c = line[i]!;
+      if (quote) {
+        if (c === "\\" && quote === '"') { i++; continue; }
+        if (c === quote) {
+          if (c === "'" && line[i + 1] === "'") { i++; continue; }
+          quote = "";
+        }
+        continue;
+      }
+      if (c === "#" && (i === 0 || /\s/.test(line[i - 1]!))) break;
+      if ((c === '"' || c === "'") && nodeStart) { quote = c; nodeStart = false; }
+      else if (nodeStart && (c === "[" || c === "{")) { flow++; nodeStart = true; }
+      else if (flow > 0 && (c === "]" || c === "}")) { flow--; nodeStart = false; }
+      else if ((c === ":" && /\s/.test(line[i + 1] ?? "\n")) || (flow > 0 && c === ",") || (nodeStart && c === "-")) nodeStart = true;
+      else if (!/\s/.test(c)) nodeStart = false;
+    }
+    if (!quote && !flow && /(?:^|:[ \t]+|-[ \t]+)[|>](?:[+-][1-9]?|[1-9][+-]?)?[ \t]*(?:#[^\r\n]*)?\r?\n?$/.test(line)) blockIndent = line.match(/^[ \t]*/)![0].length;
+    offset += line.length;
+  }
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i]!;
+    const next = fields[i + 1]?.start ?? yaml.length;
+    // Standalone comments/blank lines between fields belong to the untouched document.
+    const raw = yaml.slice(field.start, next);
+    let end = next;
+    const lines = raw.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    for (let j = lines.length - 1; j > 0; j--) {
+      if (!/^[ \t]*(?:#[^\r\n]*)?\r?\n?$/.test(lines[j]!)) break;
+      end -= lines[j]!.length;
+    }
+    field.end = end;
+  }
+  return fields;
+}
+
+/** Parse semantics with Bun's YAML parser while retaining every source byte for emission. */
+export function parseFrontmatter(source: string): FrontmatterDocument {
+  const opening = source.match(/^(?:)?---[ \t]*\r?\n/);
+  if (!opening) return { source, body: source, data: {}, frontmatter: null };
+  const start = opening[0].length;
+  const closing = /^(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/gm;
+  closing.lastIndex = start;
+  const match = closing.exec(source);
+  if (!match) throw new Error("frontmatter: missing closing delimiter");
+  const yaml = source.slice(start, match.index);
+  let value: unknown;
+  try { value = parseYamlWithQuotedEscapes(yaml); }
+  catch { throw new Error("frontmatter: invalid YAML"); }
+  if (value === null || value === undefined) value = {};
+  if (!mapping(value)) throw new Error("frontmatter: expected mapping");
+  const end = match.index + match[0].length;
+  const document: ParsedDocument = {
+    source, body: source.slice(end), data: value, frontmatter: source.slice(0, end),
+    start, end: match.index, newline: opening[0].endsWith("\r\n") ? "\r\n" : "\n", fields: fieldSpans(yaml),
+  };
+  return document;
+}
+
+function canonical(key: string, value: unknown, newline: string): string {
+  let encoded: string | undefined;
+  try { encoded = JSON.stringify(value); }
+  catch { throw new Error("frontmatter: changed values must be JSON-compatible"); }
+  if (encoded === undefined || !isDeepStrictEqual(JSON.parse(encoded), value)) throw new Error("frontmatter: changed values must be JSON-compatible");
+  return `${JSON.stringify(key)}: ${encoded}${newline}`;
+}
+
+/** Emit the entire note. Undefined deletes a key; omitted or semantically equal keys retain their bytes. */
+export function emitFrontmatter(document: FrontmatterDocument, changes: Record<string, unknown> = {}, force: ReadonlySet<string> = new Set()): string {
+  const parsed = parseFrontmatter(document.source) as ParsedDocument;
+  // `force` re-emits listed keys canonically even when semantically unchanged (escape cleanup).
+  const changed = Object.entries(changes).filter(([key, value]) => force.has(key) || !isDeepStrictEqual(parsed.data[key], value));
+  if (!changed.length) return document.source;
+  const newline = parsed.frontmatter === null ? "\n" : parsed.newline;
+  if (parsed.frontmatter === null) {
+    const yaml = changed.filter(([, value]) => value !== undefined).map(([key, value]) => canonical(key, value, newline)).join("");
+    if (!yaml) return document.source;
+    const bom = document.source.startsWith("") ? "" : "";
+    return `${bom}---${newline}${yaml}---${newline}${document.source.slice(bom.length)}`;
+  }
+  let yaml = document.source.slice(parsed.start, parsed.end);
+  const hasYamlContent = yaml.split(/\r?\n/).some(line => line.trim() && !line.trimStart().startsWith("#"));
+  if ((hasYamlContent && !parsed.fields.length) || Object.keys(parsed.data).some(key => !parsed.fields.some(field => field.key === key))) {
+    throw new Error("frontmatter: editing requires a block mapping");
+  }
+  const replacements: { start: number; end: number; value: string }[] = [];
+  let additions = "";
+  for (const [key, value] of changed) {
+    const field = parsed.fields.find(item => item.key === key);
+    const output = value === undefined ? "" : canonical(key, value, newline);
+    if (field) replacements.push({ start: field.start, end: field.end, value: output });
+    else {
+      if (Object.hasOwn(parsed.data, key)) throw new Error("frontmatter: editing requires a block mapping");
+      additions += output;
+    }
+  }
+  for (const replacement of replacements.sort((a, b) => b.start - a.start)) yaml = yaml.slice(0, replacement.start) + replacement.value + yaml.slice(replacement.end);
+  return document.source.slice(0, parsed.start) + yaml + additions + document.source.slice(parsed.end);
+}

package/src/home.ts

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { absolute, readConfig } from "./config.ts";
+export interface ResolvedHome { home: string; source: "VMEM_HOME" | "config" | "default" }
+/**
+ * Precedence: VMEM_HOME, else a `home` pointer in the default home's config, else the default
+ * home ($AGENTHUB_HOME/vmem or ~/.agenthub/vmem). VMEM_HOME bypasses the pointer entirely.
+ * Every returned path is absolute and lexically normalized (no `.`, `..` or trailing slash);
+ * symlinks are not resolved.
+ */
+export function resolveHome(env: NodeJS.ProcessEnv = process.env): ResolvedHome {
+  if (env.VMEM_HOME?.trim()) return { home: resolve(absolute(env.VMEM_HOME, "VMEM_HOME")), source: "VMEM_HOME" };
+  const fallback = join(env.AGENTHUB_HOME?.trim() ? resolve(absolute(env.AGENTHUB_HOME, "AGENTHUB_HOME")) : join(homedir(), ".agenthub"), "vmem");
+  const pointer = readConfig(fallback).home;
+  return pointer ? { home: resolve(pointer), source: "config" } : { home: fallback, source: "default" };
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+export { resolveHome } from "./home.ts";
+export { parseConfig, parseVault, readConfig, CONFIG_FILE, MAX_CONFIG_BYTES } from "./config.ts";
+export type { VaultSpec, VmemConfig } from "./config.ts";
+export { addVault, removeVault, loadRegistry, registryStatus, recoverRegistry, effectivePii, syncDirectory, LOCK_FILE } from "./registry.ts";
+export type { RecoveryReport, LockOwner } from "./registry.ts";
+export { parseFrontmatter, emitFrontmatter } from "./frontmatter.ts";
+export type { FrontmatterDocument } from "./frontmatter.ts";
+export { extractLinks, resolveLinks, normalizeTarget } from "./links.ts";
+export type { Link, LinkNote, ResolvedLink } from "./links.ts";
+export { VaultIndex, MAX_NOTE_BYTES, MAX_RESULTS, MAX_READ_BYTES } from "./vault-index.ts";
+export type { IndexedNote, SearchOptions, SearchResult } from "./vault-index.ts";
+export { applyWrite, sha256, MUTATION_LOCK, MAX_WRITE_BYTES } from "./writer.ts";
+export { validateWrite, screenContent } from "./write-validation.ts";
+export type { WriteOp, WriteRequest, WriteReceipt, WriteIssue, PlannedChange, ValidationContext, ChangeReceipt } from "./write-types.ts";
+export { appendLog, readLog, LOG_LOCK, MAX_LOG_READ_BYTES, MAX_LOG_RESULT_BYTES, LARGE_LOG_LINES } from "./vault-log.ts";
+export { formatLogEvent, LOG_TYPES, AGENT_MARKERS } from "./log-format.ts";
+export type { LogEvent, LogRequest, LogContext, LogReceipt, LogReadOptions, LogReadResult, LogBinding } from "./log-types.ts";
+export { serveMcp, validArguments, FRAME_BYTES, RESULT_BYTES } from "./mcp.ts";
+export type { McpTool, McpHandler, McpServerOptions } from "./mcp.ts";
+export { createVaultMcp, vaultTools, VMEM_TOOL_NAMES } from "./mcp-vault.ts";
+export { runSetup, defaultEntry, SETUP_TARGETS, SERVER_NAME } from "./setup.ts";
+export type { SetupTarget, SetupMode, SetupReport, SetupAction, McpEntry } from "./setup.ts";
+export { COMMANDS, completionDefinitions, completionScript } from "./commands-table.ts";
+export type { CompletionDefinition } from "./commands-table.ts";
+export { promoteFromAmem, listPromotionCandidates, draftNote, stemFor, logProjectFor } from "./promote.ts";
+export type { PromoteRequest, PromoteResult, PromoteMetadata, SeamFactory } from "./promote.ts";
+export type { AmemSeam, AmemCandidate, AmemOptions } from "./amem/seam.ts";
+
+
+export { lintVault } from "./vault-lint.ts";
+export { buildGraph, graphNeighbors, graphReport } from "./vault-graph.ts";
+export type { VaultGraph, GraphNeighborhood } from "./vault-graph.ts";
+export type { AnalysisSnapshot, LintCode, LintReport } from "./analysis-types.ts";
+export { writeAnalysisReports } from "./analysis-reports.ts";
+export type { AnalysisRequest } from "./analysis-reports.ts";
+export { promoteToOrg, screenForOrg, dropUnresolvedLinks, lintPromoted } from "./org-promote.ts";
+export type { OrgPromoteRequest, OrgPromoteResult } from "./org-promote.ts";
+export { syncVault, sameRemote } from "./sync.ts";
+export type { SyncResult } from "./sync.ts";
+
+export { normalizeSource, sourceReferences } from "./source.ts";
+export type { SourceValue, SourceReference } from "./source.ts";
+export { tidyVault, parseTidyMap, TIDY_RULES } from "./tidy.ts";
+export type { TidyRequest, TidyResult, TidyRule, TidyMap } from "./tidy.ts";

package/src/links.ts

@@ -0,0 +1,149 @@
+export interface Link {
+  target: string;
+  label: string | null;
+  heading: string | null;
+  block: string | null;
+  embed: boolean;
+  /** One-based line in the body, excluding frontmatter delimiters and YAML. */
+  line: number;
+}
+export interface LinkNote { path: string; title: string; aliases: string[]; body: string }
+export interface ResolvedLink extends Link {
+  source: string;
+  resolved: string | null;
+  reason: "missing-note" | "ambiguous-note" | "missing-heading" | "missing-block" | null;
+}
+export function normalizeTarget(value: string): string { return value.normalize("NFC").toLowerCase(); }
+/** Preserve line positions while hiding fenced code, including unclosed fences. */
+export function proseLines(body: string): string[] {
+  let fence: { char: string; size: number } | undefined;
+  return body.split(/\r?\n/).map(line => {
+    const match = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      if (match && match[1]![0] === fence.char && match[1]!.length >= fence.size && !match[2]!.trim()) fence = undefined;
+      return "";
+    }
+    if (match && !(match[1]![0] === "`" && match[2]!.includes("`"))) {
+      fence = { char: match[1]![0]!, size: match[1]!.length };
+      return "";
+    }
+    return line;
+  });
+}
+function escapedAt(text: string, offset: number): boolean {
+  let slashes = 0;
+  for (let i = offset - 1; i >= 0 && text[i] === "\\"; i--) slashes++;
+  return slashes % 2 === 1;
+}
+/** Mask matched inline code spans across lines, retaining offsets and line numbers. */
+function maskInlineCode(body: string): string {
+  const runs = [...body.matchAll(/`+/g)];
+  const next = new Map<number, number>(), closing = new Map<number, number>();
+  for (let i = runs.length - 1; i >= 0; i--) {
+    const size = runs[i]![0].length, match = next.get(size);
+    if (match !== undefined) closing.set(i, match);
+    next.set(size, i);
+  }
+  const parts: string[] = [];
+  let offset = 0;
+  for (let i = 0; i < runs.length; i++) {
+    const run = runs[i]!, start = run.index!;
+    // Backslashes escape opening delimiters, but have no escape meaning inside code.
+    if (escapedAt(body, start)) continue;
+    const endIndex = closing.get(i);
+    if (endIndex === undefined) continue; // Unmatched backticks remain literal Markdown.
+    const end = runs[endIndex]!.index! + runs[endIndex]![0].length;
+    parts.push(body.slice(offset, start), body.slice(start, end).replace(/[^\r\n]/g, " "));
+    offset = end;
+    i = endIndex;
+  }
+  parts.push(body.slice(offset));
+  return parts.join("");
+}
+export function extractLinks(body: string): Link[] {
+  const links: Link[] = [];
+  for (const [index, line] of maskInlineCode(proseLines(body).join("\n")).split("\n").entries()) {
+    for (const match of line.matchAll(/(!?)\[\[([^\]\n]+)\]\]/g)) {
+      if (escapedAt(line, match.index!)) continue;
+      const [address, ...labels] = match[2]!.split("|");
+      const hash = address!.indexOf("#");
+      const target = (hash < 0 ? address! : address!.slice(0, hash)).trim();
+      const anchor = hash < 0 ? null : address!.slice(hash + 1).trim();
+      links.push({ target, label: labels.length ? labels.join("|") : null,
+        heading: anchor && !anchor.startsWith("^") ? anchor : null,
+        block: anchor?.startsWith("^") ? anchor.slice(1) : null, embed: match[1] === "!", line: index + 1 });
+    }
+  }
+  return links;
+}
+/** Rewrite only visible wiki-link note targets; retain aliases, anchors, embeds and code verbatim. */
+export function rewriteLinkTargets(body: string, replace: (target: string) => string | undefined): string {
+  const masked = maskInlineCode(proseLines(body).join("\n")).split("\n");
+  const lines = body.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  return lines.map((raw, index) => {
+    let output = raw;
+    const matches = [...(masked[index] ?? "").matchAll(/(!?)\[\[([^\]\n]+)\]\]/g)];
+    for (const match of matches.reverse()) {
+      if (escapedAt(masked[index]!, match.index!)) continue;
+      const address = match[2]!.split("|")[0]!, hash = address.indexOf("#");
+      const target = hash < 0 ? address : address.slice(0, hash);
+      const next = replace(target.trim());
+      if (next === undefined) continue;
+      const start = match.index! + match[1]!.length + 2;
+      output = output.slice(0, start) + next + output.slice(start + target.length);
+    }
+    return output;
+  }).join("");
+}
+export function noteKey(value: string): string {
+  return normalizeTarget(value.replace(/^\.\//, "").replace(/^notes\//i, "").replace(/\.md$/i, ""));
+}
+function anchorIndex(body: string): { headings: Set<string>; blocks: Set<string> } {
+  const lines = proseLines(body), headings = new Set<string>(), blocks = new Set<string>();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!, atx = /^ {0,3}#{1,6}([ \t]+.*|)$/.exec(line);
+    if (atx) headings.add(normalizeTarget(atx[1]!.replace(/[ \t]+#+[ \t]*$/, "").trim()));
+    if (i > 0 && /^ {0,3}(?:=+|-+)\s*$/.test(line) && lines[i - 1]!.trim()) headings.add(normalizeTarget(lines[i - 1]!.trim()));
+    const block = /(?:^|\s)\^([\w-]+)\s*$/.exec(line);
+    if (block) blocks.add(normalizeTarget(block[1]!));
+  }
+  return { headings, blocks };
+}
+type Analysis = { body: string; links?: Link[]; anchors?: ReturnType<typeof anchorIndex> };
+// Per-note memo: callers that pass the same LinkNote object again (old/new validation snapshots) skip re-analysis.
+const memo = new WeakMap<LinkNote, Analysis>();
+/** Additional outgoing links share the real target anchor index but never the body code state. `sources` limits output to those source paths. */
+export function resolveLinks(notes: LinkNote[], additionalLinks?: ReadonlyMap<string, readonly Link[]>, sources?: ReadonlySet<string>): ResolvedLink[] {
+  const names = new Map<string, Set<LinkNote>>();
+  // Obsidian resolves wiki links by note path only; aliases are display metadata.
+  for (const note of notes) {
+    const key = noteKey(note.path), candidates = names.get(key) ?? new Set<LinkNote>();
+    candidates.add(note); names.set(key, candidates);
+  }
+  // Each body is read once per call; a memo entry is reused only while that body is unchanged.
+  const seen = new Map<LinkNote, Analysis>();
+  const analysis = (note: LinkNote): Analysis => {
+    let entry = seen.get(note);
+    if (entry) return entry;
+    const body = note.body;
+    entry = memo.get(note);
+    if (entry?.body !== body) memo.set(note, entry = { body });
+    seen.set(note, entry);
+    return entry;
+  };
+  const anchors = (note: LinkNote) => { const entry = analysis(note); return entry.anchors ??= anchorIndex(entry.body); };
+  const result: ResolvedLink[] = [];
+  for (const note of notes) {
+    if (sources && !sources.has(note.path)) continue;
+    const entry = analysis(note);
+    for (const link of [...(entry.links ??= extractLinks(entry.body)), ...(additionalLinks?.get(note.path) ?? [])]) {
+      const candidates = link.target ? [...(names.get(noteKey(link.target)) ?? [])] : [note];
+      const target = candidates.length === 1 ? candidates[0]! : undefined;
+      let reason: ResolvedLink["reason"] = candidates.length > 1 ? "ambiguous-note" : target ? null : "missing-note";
+      if (target && link.heading && !anchors(target).headings.has(normalizeTarget(link.heading))) reason = "missing-heading";
+      if (target && link.block && !anchors(target).blocks.has(normalizeTarget(link.block))) reason = "missing-block";
+      result.push({ ...link, source: note.path, resolved: reason ? null : target!.path, reason });
+    }
+  }
+  return result;
+}

package/src/log-commands.ts

@@ -0,0 +1,31 @@
+import { appendLog, readLog } from "./vault-log.ts";
+import type { LogEvent } from "./log-types.ts";
+export function runLogCommand(args: string[], home: string, env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
+  const command = args[0];
+  if (!["tail", "grep", "append"].includes(command ?? "")) throw new Error("log: use tail, grep or append");
+  const positional: string[] = [], flags: Record<string, string | boolean> = {};
+  const values = command === "append" ? ["--dest"] : ["--limit", "--type"];
+  for (let i = 1; i < args.length; i++) {
+    const word = args[i]!;
+    if (!word.startsWith("--")) { positional.push(word); continue; }
+    if (Object.hasOwn(flags, word) || (word !== "--json" && !values.includes(word))) throw new Error("log: unknown or repeated option");
+    if (word === "--json") flags[word] = true;
+    else {
+      const value = args[++i]; if (value === undefined || value.startsWith("--")) throw new Error("log: option value required");
+      flags[word] = value;
+    }
+  }
+  let result;
+  if (command === "append") {
+    if (positional.length !== 5) throw new Error("log append: requires vault, TYPE, project, source and note");
+    const [vault, type, project, source, note] = positional as [string, string, string, string, string];
+    const event: LogEvent = { type, project, source, note, ...(typeof flags["--dest"] === "string" ? { dest: flags["--dest"] } : {}) };
+    result = appendLog(home, { vault, event, channel: "cli" }, { env });
+  } else {
+    if (positional.length !== (command === "grep" ? 2 : 1)) throw new Error(`log ${command}: requires vault${command === "grep" ? " and pattern" : ""}`);
+    const value = flags["--limit"];
+    if (value !== undefined && (typeof value !== "string" || !/^[0-9]+$/.test(value))) throw new Error("log limit: expected integer 1..200");
+    result = readLog(home, { vault: positional[0]!, ...(value !== undefined ? { limit: Number(value) } : {}), ...(command === "grep" ? { grep: positional[1] } : {}), ...(typeof flags["--type"] === "string" ? { type: flags["--type"] } : {}) });
+  }
+  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code: result.ok ? 0 : 1 };
+}

package/src/log-filter.ts

@@ -0,0 +1,65 @@
+/** A bounded, non-backtracking grep subset: alternatives, anchors, classes and atom * + ?. */
+interface Atom { test: (char: string) => boolean; optional: boolean; repeat: boolean }
+interface Branch { atoms: Atom[]; start: boolean; end: boolean }
+export function compileLogFilter(pattern: string): (line: string) => boolean {
+  if (typeof pattern !== "string" || pattern.length > 256) throw new Error("grep pattern exceeds 256 characters");
+  const chars = [...pattern], branches: Branch[] = [];
+  let current: Branch = { atoms: [], start: false, end: false };
+  for (let i = 0; i < chars.length; i++) {
+    const char = chars[i]!;
+    if (char === "|") { branches.push(current); current = { atoms: [], start: false, end: false }; continue; }
+    if (char === "^" && current.atoms.length === 0 && !current.start && !current.end) { current.start = true; continue; }
+    if (char === "$" && (i === chars.length - 1 || chars[i + 1] === "|")) { current.end = true; continue; }
+    if (current.end || "^$()*+?{}]".includes(char)) throw new Error("unsupported grep syntax");
+    let expression: string | undefined, literal: string | undefined;
+    if (char === "\\") {
+      const escaped = chars[++i];
+      if (!escaped) throw new Error("incomplete grep escape");
+      if (/^[dDsSwW]$/.test(escaped)) expression = `\\${escaped}`;
+      else if ("\\.^$|?*+()[]{}-".includes(escaped)) literal = escaped;
+      else throw new Error("unsupported grep escape");
+    } else if (char === "[") {
+      let value = "[", closed = false;
+      while (++i < chars.length) {
+        const item = chars[i]!; value += item;
+        if (item === "\\") {
+          const escaped = chars[++i];
+          if (!escaped || (!/^[dDsSwW]$/.test(escaped) && !"\\[]^-".includes(escaped))) throw new Error("unsupported class escape");
+          value += escaped;
+        } else if (item === "]") { closed = true; break; }
+      }
+      if (!closed) throw new Error("unterminated grep class");
+      expression = value;
+    } else if (char === ".") expression = ".";
+    else literal = char;
+    const matcher = expression === undefined ? undefined : new RegExp(`^(?:${expression})$`, "u");
+    const atom: Atom = { test: matcher ? value => matcher.test(value) : value => value === literal, optional: false, repeat: false };
+    const quantifier = chars[i + 1];
+    if (quantifier && "*+?".includes(quantifier)) {
+      i++; atom.optional = quantifier !== "+"; atom.repeat = quantifier !== "?";
+    }
+    current.atoms.push(atom);
+  }
+  branches.push(current);
+  return (line: string) => {
+    const text = [...line];
+    for (const branch of branches) {
+      const atoms = branch.atoms;
+      let active = new Uint8Array(atoms.length + 1), next = new Uint8Array(atoms.length + 1);
+      for (let position = 0; position <= text.length; position++) {
+        if (!branch.start || position === 0) active[0] = 1;
+        // Epsilon transitions only move forward; a single pass computes closure.
+        for (let i = 0; i < atoms.length; i++) if (active[i] && atoms[i]!.optional) active[i + 1] = 1;
+        if (active[atoms.length] && (!branch.end || position === text.length)) return true;
+        if (position === text.length) break;
+        next.fill(0);
+        for (let i = 0; i < atoms.length; i++) if (active[i] && atoms[i]!.test(text[position]!)) {
+          next[i + 1] = 1;
+          if (atoms[i]!.repeat) next[i] = 1;
+        }
+        const previous = active; active = next; next = previous;
+      }
+    }
+    return false;
+  };
+}

package/src/log-format.ts

@@ -0,0 +1,57 @@
+import { screenContent } from "./write-validation.ts";
+import type { LogContext, LogEvent } from "./log-types.ts";
+import type { WriteIssue } from "./write-types.ts";
+
+export const LOG_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"] as const;
+export const AGENT_MARKERS = ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
+const EVENT_KEYS = new Set(["type", "project", "source", "dest", "note"]);
+const CONTEXT_KEYS = new Set(["vault", "config", "channel", "env", "now", "projectIds"]);
+function error(code: string, message: string): WriteIssue { return { code, severity: "error", message }; }
+function record(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function field(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.trim() === value &&
+    !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(value) && !value.includes("|") && !value.includes("  ") && !value.includes(" — ");
+}
+
+/** Format and screen one prospective log line. This function performs no IO. */
+export function formatLogEvent(event: LogEvent, context: LogContext): { line?: string; issues: WriteIssue[] } {
+  if (!record(event) || Object.keys(event).some(key => !EVENT_KEYS.has(key)) ||
+      !record(context) || Object.keys(context).some(key => !CONTEXT_KEYS.has(key))) {
+    return { issues: [error("L09", "invalid event or context options")] };
+  }
+  if (!field(event.type) || !LOG_TYPES.some(type => type === event.type) ||
+      !field(event.project) || (event.project !== "-" && !/^[a-z0-9][a-z0-9-]*$/.test(event.project)) ||
+      !field(event.source) || !field(event.note) || (event.dest !== undefined && !field(event.dest)) ||
+      event.source.includes(" → ") || (event.dest !== undefined && event.dest.includes(" → "))) {
+    return { issues: [error("L09", "invalid log fields, type, project or separators")] };
+  }
+  if ((context.channel !== undefined && context.channel !== "cli" && context.channel !== "mcp") ||
+      !record(context.vault) || !["personal", "org"].includes(context.vault.kind) ||
+      (context.vault.pii !== undefined && context.vault.pii !== "allow" && context.vault.pii !== "deny") ||
+      !record(context.config) || !Array.isArray(context.config.vaults) ||
+      (context.config.piiPatterns !== undefined && (!Array.isArray(context.config.piiPatterns) || context.config.piiPatterns.some(value => typeof value !== "string"))) ||
+      (context.now !== undefined && !(context.now instanceof Date)) ||
+      (context.env !== undefined && (!context.env || typeof context.env !== "object" || Array.isArray(context.env) || Object.values(context.env).some(value => value !== undefined && typeof value !== "string"))) ||
+      (context.projectIds !== undefined && !(context.projectIds instanceof Set))) {
+    return { issues: [error("L09", "invalid log context")] };
+  }
+  if (event.project !== "-" && context.projectIds !== undefined && !context.projectIds.has(event.project)) {
+    return { issues: [error("L09", "project is absent from the configured registry")] };
+  }
+  const now = context.now ?? new Date();
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime()) || now.getFullYear() < 0 || now.getFullYear() > 9999) {
+    return { issues: [error("L09", "invalid log timestamp")] };
+  }
+  const pad = (value: number, size = 2) => String(value).padStart(size, "0");
+  const timestamp = `${pad(now.getFullYear(), 4)}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+  const env = context.env ?? process.env;
+  const agent = context.channel === "mcp" || AGENT_MARKERS.some(marker => typeof env[marker] === "string" && env[marker]!.length > 0);
+  const line = `${timestamp}  ${event.type}  ${event.project}  ${event.source}${event.dest === undefined ? "" : ` → ${event.dest}`}  — ${event.note}${agent ? " (vmem:agent)" : ""}\n`;
+  const issues = screenContent(line, context.vault, context.config);
+  if (Buffer.byteLength(line, "utf8") > 1000) issues.push(error("V09", "log line exceeds 1000 UTF-8 bytes including attribution and newline"));
+  return issues.some(issue => issue.severity === "error") ? { issues } : { line, issues };
+}

package/src/log-types.ts

@@ -0,0 +1,10 @@
+import type { VaultSpec, VmemConfig } from "./config.ts";
+import type { WriteIssue } from "./write-types.ts";
+export interface LogEvent { type: string; project: string; source: string; dest?: string; note: string }
+export interface LogRequest { vault: string; event: LogEvent; channel?: "cli" | "mcp" }
+export interface LogContext { vault: VaultSpec; config: VmemConfig; channel?: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; projectIds?: ReadonlySet<string> }
+export interface LogReceipt { ok: boolean; appended: boolean | null; synced: boolean; bytesWritten: number | null; issues: WriteIssue[]; rolledBack?: boolean }
+export interface LogReadOptions { vault: string; limit?: number; grep?: string; type?: string }
+export interface LogReadResult { ok: boolean; lines: string[]; dataLines: number | null; warnings: string[]; issues: WriteIssue[] }
+
+export interface LogBinding { vault: VaultSpec; denyPaths: string[]; piiPatterns: string[]; dev: number; ino: number }