@hraness/wordcell 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
   "license": "MIT",
   "type": "module",
@@ -261,11 +261,18 @@
     "./workflows/plan-radar": {
       "types": "./src/workflows/plan-radar.ts",
       "import": "./dist/workflows/plan-radar.js"
+    },
+    "./graph-authority": {
+      "types": "./src/graph-authority.ts",
+      "import": "./dist/graph-authority.js"
+    },
+    "./graph-percolation": {
+      "types": "./src/graph-percolation.ts",
+      "import": "./dist/graph-percolation.js"
     }
   },
   "bin": {
     "wordcell": "./dist/cli.js",
-    "kb": "./dist/kb-alias.js",
     "wordcell-evaluation-builder": "./dist/evaluation-builder.js"
   },
   "main": "./dist/index.js",
@@ -285,7 +292,6 @@
     "src/url-intelligence.ts",
     "src/cli.ts",
     "src/cli-program.ts",
-    "src/kb-alias.ts",
     "src/clip/acquire.ts",
     "src/clip/archive-today.ts",
     "src/clip/args.ts",
@@ -378,14 +384,26 @@
     "src/workflows/plan-radar.ts",
     "skills/wordcell",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src/graph-authority.ts",
+    "src/graph-authority-model.ts",
+    "src/graph-cache-filesystem.ts",
+    "src/graph-facts.ts",
+    "src/graph-query.ts",
+    "src/graph-cli.ts",
+    "src/graph-percolation.ts",
+    "src/oh/authority.ts",
+    "src/oh/programs.ts",
+    "src/oh/schema.ts",
+    "src/oh/snapshot.ts",
+    "src/oh/validation.ts"
   ],
   "scripts": {
     "kb:refresh": "bunx --bun github:hraness/kb#v0.15.1 refresh --root kb",
     "kb:check:lane": "bunx --bun github:hraness/kb#v0.15.1 check --root kb --no-catalog",
     "kb:check": "bunx --bun github:hraness/kb#v0.15.1 check --root kb && bunx --bun github:hraness/kb#v0.15.1 agents check --root kb --repo .",
     "kb:catalog": "bunx --bun github:hraness/kb#v0.15.1 catalog --root kb",
-    "build": "bun -e 'await (await import(\"node:fs/promises\")).rm(\"./dist\", { recursive: true, force: true })' && bun build ./src/index.ts ./src/agent-context.ts ./src/agent-guide-audit.ts ./src/attachments.ts ./src/authoring.ts ./src/benchmark.ts ./src/clip/browser-profiles.ts ./src/capture.ts ./src/cli.ts ./src/kb-alias.ts ./src/clip/acquire.ts ./src/clip/args.ts ./src/clip/bounded-byte-buffer.ts ./src/clip/bundle-reader.ts ./src/clip/cli.ts ./src/clip/cookies.ts ./src/clip/doctor.ts ./src/clip/jobs.ts ./src/clip/network.ts ./src/clip/network-proxy.ts ./src/clip/persist.ts ./src/clip/refresh.ts ./src/clip/terminal.ts ./src/evaluation.ts ./src/evaluation-builder.ts ./src/evaluation-kb.ts ./src/git.ts ./src/graph.ts ./src/navigation.ts ./src/pdf.ts ./src/percolate.ts ./src/portfolio.ts ./src/query.ts ./src/repository-memory.ts ./src/sdk.ts ./src/search.ts ./src/search-rules.ts ./src/semantic.ts ./src/source-inbox.ts ./src/untrusted-content.ts ./src/url-intelligence.ts ./src/workflow.ts ./src/workflows/index.ts ./src/workflows/decision-context.ts ./src/workflows/explain-change.ts ./src/workflows/plan-radar.ts ./src/clip/defuddle-worker.ts --outdir ./dist --root ./src --target bun --format esm --splitting --packages external",
+    "build": "bun -e 'await (await import(\"node:fs/promises\")).rm(\"./dist\", { recursive: true, force: true })' && bun build ./src/index.ts ./src/agent-context.ts ./src/agent-guide-audit.ts ./src/attachments.ts ./src/authoring.ts ./src/benchmark.ts ./src/clip/browser-profiles.ts ./src/capture.ts ./src/cli.ts ./src/clip/acquire.ts ./src/clip/args.ts ./src/clip/bounded-byte-buffer.ts ./src/clip/bundle-reader.ts ./src/clip/cli.ts ./src/clip/cookies.ts ./src/clip/doctor.ts ./src/clip/jobs.ts ./src/clip/network.ts ./src/clip/network-proxy.ts ./src/clip/persist.ts ./src/clip/refresh.ts ./src/clip/terminal.ts ./src/evaluation.ts ./src/evaluation-builder.ts ./src/evaluation-kb.ts ./src/git.ts ./src/graph.ts ./src/graph-percolation.ts ./src/graph-authority.ts ./src/navigation.ts ./src/pdf.ts ./src/percolate.ts ./src/portfolio.ts ./src/query.ts ./src/repository-memory.ts ./src/sdk.ts ./src/search.ts ./src/search-rules.ts ./src/semantic.ts ./src/source-inbox.ts ./src/untrusted-content.ts ./src/url-intelligence.ts ./src/workflow.ts ./src/workflows/index.ts ./src/workflows/decision-context.ts ./src/workflows/explain-change.ts ./src/workflows/plan-radar.ts ./src/clip/defuddle-worker.ts --outdir ./dist --root ./src --target bun --format esm --splitting --packages external",
     "check:workflows": "bun ./scripts/check-workflow-yaml.ts",
     "check:installed-command-docs": "bun ./scripts/check-installed-command-docs.ts",
     "check:portfolio-inventory": "bun ./scripts/check-portfolio-inventory.ts",
@@ -400,7 +418,7 @@
     "check:effect": "bun run scripts/check-effect-policy.ts && bun test ./scripts/check-effect-architecture.test.ts"
   },
   "dependencies": {
-    "@hraness/oh": "github:hraness/oh#v0.2.0",
+    "@hraness/oh": "https://github.com/hraness/oh/releases/download/v0.4.3/hraness-oh-0.4.3.tgz",
     "@steipete/sweet-cookie": "0.4.3",
     "@tobilu/qmd": "git+https://github.com/hraness/qmd.git#aa993dceb3ef8cfb71d470554ca437570f5a2b3c",
     "agent-browser": "0.32.3",

package/skills/wordcell/SKILL.md

@@ -53,9 +53,9 @@ rules, then repeat command discovery. Install Wordcell only while `wordcell` rem
 missing:
 
 ```sh
-command -v kb >/dev/null 2>&1 || {
+command -v wordcell >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.20.0/hraness-wordcell-0.20.0.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.21.0/hraness-wordcell-0.21.0.tgz
 }
 wordcell --help
 ```

package/skills/wordcell/references/percolate.md

@@ -174,3 +174,7 @@ authored-catalog vault, refresh and check leave the front door untouched, while
 `wordcell catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory.
 Resolve same-note Git conflicts from the prose and evidence; do not accept one
 side's frontmatter mechanically.
+
+## Inspect positive graph proofs
+
+Use `wordcell percolate <note> --proofs --root "$KB_ROOT" --json` when you need shared-tag and shared-concept proof trees. This explicit envelope keeps existing V2 candidates under `suggestions` and separate bounded query results under `positiveSupport`. Absence and counts remain Wordcell decisions; choosing a predicate and writing a relationship remain author decisions. Inspect all truncation markers and read the cited Markdown before editing.

package/skills/wordcell/references/query.md

@@ -250,3 +250,9 @@ then leave it untouched. `wordcell catalog --root "$KB_ROOT"` renders the exhaus
 inventory on demand. A managed vault keeps the original generated-catalog
 behavior. Neither mode changes scanning, graph analysis, semantic indexing, or
 attachment validation.
+
+## Query named graph programs
+
+Use `wordcell graph query --program backlinks --note <exact-id> --root "$KB_ROOT" --json` for positive source proofs. Programs also include bounded `reachability`, predicate-specific `relation-closure`, exact `scope-route`, `shared-tags`, and `shared-concepts`. Default queries write nothing. `graph rebuild` writes only the disposable `.wordcell/oh.sqlite` cache; `graph verify` and queries with `--persisted` reject missing or stale state without repairing it. After a damaged cache, `graph rebuild --fresh` builds a replacement from Markdown.
+
+Inspect the source revision, row/proof truncation and source record digests. Reopen SDK sessions after Markdown changes. Proofs establish derivation from source records, not the truth of an authored assertion. `wordcell graph --json` keeps its existing structural report.

package/src/cli-program.ts

@@ -68,6 +68,13 @@ import {
   type RelationIssue,
   type VaultAnalysis,
 } from "./graph.js";
+import {
+  executeGraphCommand,
+  parseGraphCommand,
+  type GraphCliCommand,
+  type GraphCliDependencies,
+} from "./graph-cli.js";
+import { percolateWithGraph } from "./graph-percolation.js";
 import { initVault, type InitVaultResult } from "./init.js";
 import type {
   GitHistoryForNotesResult,
@@ -223,13 +230,16 @@ Usage:
   wordcell check [--root <directory>] [--index <path>] [--no-catalog] [--json]
   wordcell catalog [--root <directory>] [--index <path>] [--json]
   wordcell graph [--root <directory>] [--index <path>] [--json]
+  wordcell graph rebuild [--fresh] [--root <directory>] [--index <path>] [--json]
+  wordcell graph verify [--root <directory>] [--index <path>] [--json]
+  wordcell graph query --program <backlinks|reachability|scope-route|relation-closure|shared-tags|shared-concepts> [--note <id> | --scope <path>] [--predicate <predicate>] [--depth <count>] [--limit <count>] [--persisted] [--root <directory>] [--index <path>] [--json]
   wordcell backlinks <note> [--root <directory>] [--index <path>] [--json]
   wordcell links <note> [--root <directory>] [--direction <in|out|both>] [--depth <count>] [--limit <count>] [--json]
   wordcell note create <id> --title <title> [--type <type>] [--tag <tag>] [--body <markdown> | --body-file <path>] [--root <directory>] [--json]
   wordcell relation add <source> <predicate> <target> [--root <directory>] [--expected-revision <sha256:...>] [--json]
   wordcell relation remove <source> <predicate> <target> [--root <directory>] [--expected-revision <sha256:...>] [--json]
   wordcell relation list <note> [--root <directory>] [--json]
-  wordcell percolate [note] [--root <directory>] [--min-support <count>] [--limit <count>] [--json]
+  wordcell percolate [note] [--proofs] [--root <directory>] [--min-support <count>] [--limit <count>] [--json]
   wordcell list [--root <directory>] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--sort <field>] [--order <asc|desc>] [--limit <count>] [--json]
   wordcell index [--root <directory>] [--database <path>] [--force] [--json]
   wordcell search <query> [--root <directory>] [--repo <repository>] [--database <path>] [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--related <note>] [--graph-depth <1|2>] [--no-graph] [--history | --no-history | --require-history] [--limit <count>] [--candidate-limit <count>] [--min-score <score>] [--json]
@@ -252,6 +262,7 @@ Run \`wordcell clip --help\` for web capture options or \`wordcell pdf --help\`
 type VaultCommand = "refresh" | "check" | "graph" | "backlinks" | "links";
 
 type ParsedCommand =
+  | GraphCliCommand
   | { readonly kind: "help" }
   | { readonly kind: "clip"; readonly arguments: readonly string[] }
   | {
@@ -422,6 +433,7 @@ type ParsedCommand =
     }
   | {
       readonly kind: "percolate";
+      readonly proofs?: true;
       readonly root: string;
       readonly note?: string;
       readonly minSupport: number;
@@ -433,7 +445,7 @@ type ParseResult =
   | { readonly ok: true; readonly value: ParsedCommand }
   | { readonly ok: false; readonly message: string };
 
-type CliDependencies = {
+type CliDependencies = GraphCliDependencies & {
   readonly runClipCommand?: typeof runClipCommand;
   readonly readCaptureBundle?: typeof readCaptureBundle;
   readonly verifyCaptureBundle?: typeof verifyCaptureBundle;
@@ -455,6 +467,7 @@ type CliDependencies = {
   readonly addNoteRelation?: typeof addNoteRelation;
   readonly removeNoteRelation?: typeof removeNoteRelation;
   readonly percolateVault?: typeof percolateVault;
+  readonly percolateWithGraph?: typeof percolateWithGraph;
   readonly inspectAgentContextRepository?: typeof inspectAgentContextRepository;
   readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
   readonly auditAgentGuideRepository?: typeof auditAgentGuideRepository;
@@ -1678,10 +1691,16 @@ function parsePercolateCommand(arguments_: readonly string[]): ParseResult {
   let minSupport = 2;
   let limit = 25;
   let json = false;
+  let proofs = false;
   const positional: string[] = [];
   for (let cursor = 0; cursor < arguments_.length; cursor += 1) {
     const argument = arguments_[cursor];
     if (argument === undefined) continue;
+    if (argument === "--proofs") {
+      if (proofs) return { ok: false, message: "duplicate percolation proofs option" };
+      proofs = true;
+      continue;
+    }
     if (argument === "--json") {
       json = true;
       continue;
@@ -1714,10 +1733,12 @@ function parsePercolateCommand(arguments_: readonly string[]): ParseResult {
   if (positional.length > 1) {
     return { ok: false, message: "percolate accepts at most one note ID" };
   }
+  if (proofs && note === undefined) return { ok: false, message: "percolate --proofs requires one note" };
   return {
     ok: true,
     value: {
       kind: "percolate",
+      ...(proofs ? { proofs: true as const } : {}),
       root,
       ...(note === undefined ? {} : { note }),
       minSupport,
@@ -1888,6 +1909,9 @@ export function parseArguments(arguments_: readonly string[]): ParseResult {
     if (positional[0] !== undefined) directory = positional[0];
     return { ok: true, value: { kind: "init", directory, json } };
   }
+  if (command === "graph" && ["rebuild", "verify", "query"].includes(arguments_[1] ?? "")) {
+    return parseGraphCommand(arguments_.slice(1));
+  }
   if (command === "refresh" || command === "check" || command === "graph" || command === "backlinks" || command === "links") {
     return parseVaultCommand(command, arguments_.slice(1));
   }
@@ -2745,6 +2769,20 @@ async function runPercolate(
       ...(command.note === undefined ? {} : { mentionScope: command.note }),
     },
   );
+  if (command.proofs === true) {
+    if (command.note === undefined) throw new Error("percolate --proofs requires one note");
+    const result = await (dependencies.percolateWithGraph ?? percolateWithGraph)(snapshot, {
+      note: command.note, minSupport: command.minSupport, limit: command.limit,
+    });
+    const support = [result.positiveSupport.sharedTags, result.positiveSupport.sharedConcepts];
+    const partial = support.some((item) => item.truncated || item.proofsTruncated);
+    const text = `${renderPercolation(result.suggestions, command.note)}\nSnapshot: ${result.revision}\n`
+      + "Positive shared-tag and shared-concept proofs are included in --json output.\n"
+      + "Absence checks, support counts, and predicate choices remain Wordcell authoring decisions.\n"
+      + (partial ? "Partial proof evidence: a graph query reached its bounds.\n" : "");
+    output.stdout(command.json ? terminalSafeJson(result) : sanitizeTerminalText(redactSensitiveText(text)));
+    return partial ? 4 : 0;
+  }
   const result = (dependencies.percolateVault ?? percolateVault)(
     snapshot.notes,
     snapshot.analysis,
@@ -3527,6 +3565,11 @@ export async function main(
     if (command.kind === "agents") return await runAgents(command, output, dependencies);
     if (command.kind === "note-create") return await runNoteCreate(command, output, dependencies);
     if (command.kind === "relation") return await runRelation(command, output, dependencies);
+    if (command.kind === "graph-rebuild" || command.kind === "graph-verify" || command.kind === "graph-query") {
+      const result = await executeGraphCommand(command, dependencies);
+      output.stdout(command.json ? terminalSafeJson(result.value) : sanitizeTerminalText(redactSensitiveText(result.text)));
+      return result.exitCode;
+    }
     if (command.kind === "percolate") return await runPercolate(command, output, dependencies);
     if (command.kind === "list") return await runList(command, output, dependencies);
     if (command.kind === "inbox") return await runInbox(command, output, dependencies);

package/src/graph-authority-model.ts

@@ -0,0 +1,116 @@
+/** Wordcell-owned graph protocol. Vendor record and program types stay in the adapter. */
+export type GraphAtom = string | number | boolean | null;
+export type GraphFactRelation = "wordcell.note" | "wordcell.link" | "wordcell.relation"
+  | "wordcell.external-relation" | "wordcell.tag" | "wordcell.scope" | "wordcell.concept";
+
+export type GraphFact = Readonly<{ relation: GraphFactRelation; tuple: readonly GraphAtom[] }>;
+export type GraphSourceRecord = Readonly<{
+  key: string;
+  id: string;
+  path: string;
+  documentId: string | null;
+  contentSha256: string;
+  facts: readonly GraphFact[];
+}>;
+export type GraphSnapshot = Readonly<{
+  schemaVersion: 1;
+  vaultIdentity: string;
+  revision: string;
+  catalogNoteId: string;
+  sourceDigests: readonly Readonly<{ path: string; contentSha256: string }>[];
+  records: readonly GraphSourceRecord[];
+  factCount: number;
+}>;
+
+export const GRAPH_LIMITS = Object.freeze({
+  notes: 4_000,
+  facts: 100_000,
+  sourceBytes: 64 * 1024 * 1024,
+  atomBytes: 16 * 1024,
+  depth: 8,
+  rows: 1_000,
+  workUnits: 8_000_000,
+  derivedTuples: 100_000,
+  rounds: 64,
+  proofDepth: 64,
+  proofNodes: 4_096,
+  totalProofNodes: 32_768,
+  resultBytes: 8 * 1024 * 1024,
+});
+
+export type GraphQueryLimits = Readonly<{
+  rows?: number;
+  workUnits?: number;
+  derivedTuples?: number;
+  rounds?: number;
+  proofDepth?: number;
+  proofNodes?: number;
+  totalProofNodes?: number;
+  resultBytes?: number;
+}>;
+
+export type GraphProgramRequest =
+  | Readonly<{ program: "backlinks"; note: string }>
+  | Readonly<{ program: "reachability"; note: string; depth?: number }>
+  | Readonly<{ program: "scope-route"; scope: string }>
+  | Readonly<{ program: "relation-closure"; note: string; predicate: string; depth?: number }>
+  | Readonly<{ program: "shared-tags"; note: string }>
+  | Readonly<{ program: "shared-concepts"; note: string }>;
+export type GraphQueryRequest = GraphProgramRequest & Readonly<{ limits?: GraphQueryLimits }>;
+
+export type GraphProofSource = Readonly<{
+  key: string;
+  recordSha256: string;
+  noteId: string;
+  path: string;
+  contentSha256: string;
+}>;
+export type GraphProof =
+  | Readonly<{ kind: "fact"; relation: string; tuple: readonly GraphAtom[]; sources: readonly GraphProofSource[] }>
+  | Readonly<{ kind: "derived"; relation: string; tuple: readonly GraphAtom[]; ruleId: string;
+      ruleSha256: string; premises: readonly GraphProof[]; premisesTruncated: boolean }>
+  | Readonly<{ kind: "truncated"; relation: string; tuple: readonly GraphAtom[]; reason: "cycle" | "depth" | "nodes" }>;
+
+export type GraphQueryResult = Readonly<{
+  schemaVersion: 1;
+  authority: "derived";
+  vaultIdentity: string;
+  revision: string;
+  projectionSha256: string;
+  request: GraphQueryRequest;
+  columns: readonly string[];
+  rows: readonly Readonly<{ values: readonly GraphAtom[]; proofs: readonly GraphProof[];
+    proofsTruncated: boolean; supportCount: number }>[];
+  limits: Required<GraphQueryLimits>;
+  truncated: boolean;
+  proofsTruncated: boolean;
+  truncationReasons: readonly string[];
+  stats: Readonly<{ baseFacts: number; derivedFacts: number; workUnits: number;
+    rounds: number; proofNodes: number; queryMatches: number }>;
+}>;
+
+export type GraphVerification = Readonly<{
+  schemaVersion: 1;
+  status: "verified";
+  vaultIdentity: string;
+  revision: string;
+  records: number;
+  facts: number;
+}>;
+
+export interface GraphAuthority {
+  query(request: GraphQueryRequest): Promise<GraphQueryResult>;
+  /** Re-evaluate a bounded result against this authority; foreign or stale evidence is rejected. */
+  verifyResult(value: unknown): Promise<boolean>;
+  verify(): Promise<GraphVerification>;
+  close(): Promise<void>;
+}
+
+export class GraphAuthorityError extends Error {
+  readonly code: "invalid-input" | "budget" | "stale" | "unsafe-cache" | "corrupt-cache" | "closed";
+  constructor(code: GraphAuthorityError["code"], message: string) {
+    super(message);
+    this.name = "GraphAuthorityError";
+    this.code = code;
+  }
+}

package/src/graph-authority.ts

@@ -0,0 +1,219 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, mkdtemp, realpath, rename, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { createGraphSnapshot } from "./graph-facts.js";
+import { graphCacheFileSystem as fs } from "./graph-cache-filesystem.js";
+import { GraphAuthorityError, GRAPH_LIMITS } from "./graph-authority-model.js";
+import type { GraphAuthority, GraphQueryRequest, GraphQueryResult, GraphVerification } from "./graph-authority-model.js";
+import { acquireFileLease } from "./note-lock.js";
+import type { openOhGraphAdapter as OhAdapterFactory } from "./oh/authority.js";
+
+// Keep Node-compatible package discovery independent of the Bun-only graph runtime.
+const openOhGraphAdapter: typeof OhAdapterFactory = async (...args) =>
+  await (await import("./oh/authority.js")).openOhGraphAdapter(...args);
+import { validateGraphQueryRequest } from "./graph-query.js";
+import { scanVault } from "./vault.js";
+import type { VaultSnapshot } from "./vault.js";
+
+export * from "./graph-authority-model.js";
+export { createGraphSnapshot, validateGraphQueryRequest };
+export type GraphOptions = Readonly<{ index?: string }>;
+export type GraphRebuildOptions = GraphOptions & Readonly<{ fresh?: boolean }>;
+export type GraphReadOptions = GraphOptions & Readonly<{ persisted?: boolean }>;
+
+const MAX_CACHE_BYTES = 64 * 1024 * 1024;
+const ignoredCache = "# Disposable Wordcell graph state. Rebuild from Markdown.\n*\n";
+const hash = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+function errno(value: unknown, code: string): boolean {
+  return value !== null && typeof value === "object" && "code" in value && value.code === code;
+}
+async function rootPath(root: string): Promise<string> {
+  if (typeof root !== "string" || root.trim() === "" || root.includes("\0")) {
+    throw new GraphAuthorityError("invalid-input", "A graph operation requires a vault root.");
+  }
+  return await realpath(resolve(root));
+}
+async function scan(root: string, options: GraphOptions): Promise<VaultSnapshot> {
+  return await scanVault(root, { ...options, mentionScope: false,
+    maxNotes: GRAPH_LIMITS.notes, maxTotalBytes: GRAPH_LIMITS.sourceBytes,
+    maxConnectionObservations: GRAPH_LIMITS.facts });
+}
+async function directoryIdentity(path: string) {
+  const info = await fs.lstat(path, { bigint: true });
+  if (!info.isDirectory() || info.isSymbolicLink() || await realpath(path) !== path) {
+    throw new GraphAuthorityError("unsafe-cache", "Wordcell graph state requires a real directory inside the vault.");
+  }
+  return { dev: info.dev, ino: info.ino };
+}
+async function sameDirectory(path: string, expected: Awaited<ReturnType<typeof directoryIdentity>>): Promise<void> {
+  const actual = await directoryIdentity(path);
+  if (actual.dev !== expected.dev || actual.ino !== expected.ino) {
+    throw new GraphAuthorityError("unsafe-cache", "The graph cache directory changed during the operation.");
+  }
+}
+/** Read one bounded, private regular file through its observed identity. Never follow a cache symlink. */
+async function readCache(path: string, maximumBytes = MAX_CACHE_BYTES): Promise<Buffer | null> {
+  let observed;
+  try { observed = await fs.lstat(path, { bigint: true }); }
+  catch (error) { if (errno(error, "ENOENT")) return null; throw error; }
+  if (!observed.isFile() || observed.isSymbolicLink() || observed.nlink !== 1n) {
+    throw new GraphAuthorityError("unsafe-cache", "Graph cache files must be regular files with one link.");
+  }
+  if (observed.size > BigInt(maximumBytes)) throw new GraphAuthorityError("budget", "Graph cache exceeds its byte limit.");
+  const handle = await fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.nlink !== 1n || before.dev !== observed.dev || before.ino !== observed.ino) {
+      throw new GraphAuthorityError("unsafe-cache", "The graph cache changed before it could be read.");
+    }
+    if (before.size > BigInt(maximumBytes)) {
+      throw new GraphAuthorityError("budget", "Graph cache exceeds its byte limit.");
+    }
+    if (before.size !== observed.size || before.mtimeNs !== observed.mtimeNs || before.ctimeNs !== observed.ctimeNs) {
+      throw new GraphAuthorityError("stale", "The graph cache changed before it could be read.");
+    }
+    const bytes = Buffer.alloc(Number(before.size));
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+      if (bytesRead === 0) throw new GraphAuthorityError("stale", "The graph cache changed during its read.");
+      offset += bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    const current = await fs.lstat(path, { bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs
+      || current.dev !== before.dev || current.ino !== before.ino || current.nlink !== 1n) {
+      throw new GraphAuthorityError("stale", "The graph cache changed during its read.");
+    }
+    return bytes;
+  } finally { await handle.close(); }
+}
+async function requireSingleFileCache(path: string): Promise<void> {
+  for (const suffix of ["-wal", "-shm", "-journal"]) {
+    try { await fs.lstat(path + suffix); }
+    catch (error) { if (errno(error, "ENOENT")) continue; throw error; }
+    throw new GraphAuthorityError("unsafe-cache", "Graph cache has an active or foreign SQLite sidecar; close its writer before rebuilding.");
+  }
+}
+async function assertFresh(root: string, options: GraphOptions, revision: string): Promise<void> {
+  if (createGraphSnapshot(await scan(root, options)).revision !== revision) {
+    throw new GraphAuthorityError("stale", "Markdown changed during the graph operation; retry from a fresh snapshot.");
+  }
+}
+
+/** A read-only, in-memory authority sharing the caller's exact Markdown snapshot. */
+export async function openGraphAuthority(snapshot: VaultSnapshot): Promise<GraphAuthority> {
+  return await openOhGraphAdapter(createGraphSnapshot(snapshot));
+}
+
+async function withGraph<T>(rootInput: string, options: GraphReadOptions,
+  work: (authority: GraphAuthority) => Promise<T>): Promise<T> {
+  const root = await rootPath(rootInput);
+  const snapshot = createGraphSnapshot(await scan(root, options));
+  let authority: GraphAuthority;
+  if (options.persisted) {
+    const cache = join(root, ".wordcell");
+    let identity;
+    try { identity = await directoryIdentity(cache); }
+    catch (error) {
+      if (errno(error, "ENOENT")) throw new GraphAuthorityError("stale", "No graph cache exists; run wordcell graph rebuild first.");
+      throw error;
+    }
+    const path = join(cache, "oh.sqlite");
+    await requireSingleFileCache(path);
+    const bytes = await readCache(path);
+    if (bytes === null) throw new GraphAuthorityError("stale", "No graph cache exists; run wordcell graph rebuild first.");
+    await sameDirectory(cache, identity);
+    authority = await openOhGraphAdapter(snapshot, { databaseBytes: bytes });
+  } else authority = await openOhGraphAdapter(snapshot);
+  try {
+    const result = await work(authority);
+    await assertFresh(root, options, snapshot.revision);
+    return result;
+  } finally { await authority.close(); }
+}
+
+/** Verify persisted state without opening any vault file for writing. */
+export async function verifyGraph(root: string, options: GraphOptions = {}): Promise<GraphVerification> {
+  return await withGraph(root, { ...options, persisted: true }, async (authority) => await authority.verify());
+}
+
+export async function queryGraph(root: string, request: GraphQueryRequest, options: GraphReadOptions = {}): Promise<GraphQueryResult> {
+  const checked = validateGraphQueryRequest(request);
+  return await withGraph(root, options, async (authority) => await authority.query(checked));
+}
+
+/** Reconcile in a private staging database and install only after the source and old cache still match. */
+export async function rebuildGraph(rootInput: string, options: GraphRebuildOptions = {}): Promise<GraphVerification> {
+  const root = await rootPath(rootInput);
+  const rootIdentity = await directoryIdentity(root);
+  const snapshot = createGraphSnapshot(await scan(root, options));
+  const cache = join(root, ".wordcell");
+  try { await mkdir(cache, { mode: 0o700 }); }
+  catch (error) { if (!errno(error, "EEXIST")) throw error; }
+  const cacheIdentity = await directoryIdentity(cache);
+  const lease = await acquireFileLease(join(cache, ".rebuild.lock"));
+  let staging: string | undefined;
+  let stagingIdentity: Awaited<ReturnType<typeof directoryIdentity>> | undefined;
+  try {
+    await sameDirectory(root, rootIdentity);
+    await sameDirectory(cache, cacheIdentity);
+    const ignore = join(cache, ".gitignore");
+    const oldIgnore = await readCache(ignore, 4096);
+    if (oldIgnore !== null && oldIgnore.toString("utf8") !== ignoredCache) {
+      throw new GraphAuthorityError("unsafe-cache", "The graph cache has an unrecognized .gitignore; preserve it and use a separate vault root.");
+    }
+    if (oldIgnore === null) {
+      const handle = await fs.open(ignore, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { await handle.writeFile(ignoredCache); await handle.sync(); } finally { await handle.close(); }
+    }
+    const path = join(cache, "oh.sqlite");
+    await requireSingleFileCache(path);
+    const previous = await readCache(path);
+    staging = await mkdtemp(join(cache, ".build-"));
+    stagingIdentity = await directoryIdentity(staging);
+    const stagedPath = join(staging, "oh.sqlite");
+    if (previous !== null && !options.fresh) {
+      const handle = await fs.open(stagedPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      try { await handle.writeFile(previous); } finally { await handle.close(); }
+    }
+    const authority = await openOhGraphAdapter(snapshot, { databasePath: stagedPath, writable: true });
+    let result;
+    try { result = await authority.verify(); } finally { await authority.close(); }
+    const ready = await readCache(stagedPath);
+    if (ready === null) throw new GraphAuthorityError("corrupt-cache", "The graph rebuild did not produce a database.");
+    await requireSingleFileCache(stagedPath);
+    await assertFresh(root, options, snapshot.revision);
+    await lease.assertOwned();
+    await sameDirectory(root, rootIdentity);
+    await sameDirectory(cache, cacheIdentity);
+    await requireSingleFileCache(path);
+    const current = await readCache(path);
+    if ((previous === null) !== (current === null) || (previous !== null && current !== null && hash(previous) !== hash(current))) {
+      throw new GraphAuthorityError("stale", "The graph cache changed during rebuild; retry from its current state.");
+    }
+    const handle = await fs.open(stagedPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try { await handle.sync(); } finally { await handle.close(); }
+    await rename(stagedPath, path);
+    const directory = await fs.open(cache, constants.O_RDONLY);
+    try { await directory.sync(); } finally { await directory.close(); }
+    return result;
+  } finally {
+    try {
+      if (staging !== undefined && stagingIdentity !== undefined) {
+        // Never recursively remove a replacement directory after losing the original parent.
+        let stillOwned = false;
+        try {
+          await sameDirectory(root, rootIdentity);
+          await sameDirectory(cache, cacheIdentity);
+          await sameDirectory(staging, stagingIdentity);
+          stillOwned = true;
+        } catch { /* Preserve uncertain paths for the owner to inspect. */ }
+        if (stillOwned) await rm(staging, { recursive: true, force: true });
+      }
+    }
+    finally { await lease.release(); }
+  }
+}

package/src/graph-cache-filesystem.ts

@@ -0,0 +1,4 @@
+import { lstat, open } from "node:fs/promises";
+
+/** Internal filesystem boundary, kept explicit so race tests observe the real I/O sequence. */
+export const graphCacheFileSystem = { lstat, open };