@flyingrobots/graft 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-04-05
+
+### Added
+
+- **WARP Level 1 — structural memory substrate**: git-warp-backed
+  graph stores structural facts per commit. Directory tree, file,
+  symbol, and commit nodes with containment edges and provenance
+  links (touches, adds, changes, removes).
+- **`graft_since`**: structural changes since a git ref — symbols
+  added, removed, and changed per file with summary lines. Instant.
+- **`graft_map`**: structural map of a directory — all files and
+  their symbols in one call via tree-sitter.
+- **`graft index` CLI**: manual WARP indexing trigger.
+- **WARP indexer**: walks git history, parses files with tree-sitter,
+  emits WARP patches. Handles nested symbols, file deletion,
+  signature changes, unsupported language degradation.
+- **Observer factory**: 8 canonical lens patterns for focused graph
+  projections (file symbols, all symbols, directory files, etc.).
+- **11 WARP invariants**: observer-only-access, materialization-
+  deterministic, delta-only-storage, address-not-identity, and more.
+- **`@git-stunts/git-warp` v16** + `@git-stunts/plumbing` deps.
+
+## [0.3.5] - 2026-04-05
+
+### Fixed
+
+- **CI**: use `npx npm@latest` for OIDC trusted publishing — avoids
+  self-upgrade breakage on Node 22's bundled npm.
+
+## [0.3.4] - 2026-04-05
+
+### Fixed
+
+- **CI**: upgrade npm CLI to >=11.5.1 for OIDC trusted publishing.
+
+## [0.3.3] - 2026-04-05
+
+### Fixed
+
+- **CI**: use `npm publish` instead of `pnpm publish` for OIDC
+  provenance.
+
+## [0.3.2] - 2026-04-05
+
+### Added
+
+- **`graft init`**: zero-friction project onboarding. Scaffolds
+  `.graftignore`, adds `.graft/` to `.gitignore`, generates
+  `CLAUDE.md` snippet instructing agents to prefer graft tools,
+  and prints Claude Code hook config. Idempotent.
+- **CI**: release workflow attaches npm tarball + SHA256SUMS to
+  GitHub releases as downloadable assets.
+- **CI**: npm publish via OIDC provenance (no secret needed).
+
+### Changed
+
+- **CLI bootstrap**: `bin/graft.js` resolves tsx from the package's
+  own `node_modules`, so `graft init` works from any directory.
+- **Docs**: regenerated README, GUIDE, BEARING, and VISION signposts.
+- **package.json**: added `publishConfig`, `homepage`, `bugs`,
+  `packageManager`, upgraded keywords for MCP/agent discovery.
+
+### Fixed
+
+- **CI**: removed pnpm version override that conflicted with
+  `packageManager` field.
+
 ## [0.3.1] - 2026-04-05
 
 ### Changed

package/README.md

@@ -10,7 +10,7 @@ tools (outlines, diffs, symbol history) are useful to anyone.
 
 ## Why
 
-Empirical analysis of 1,091 real coding sessions (Blacklight) found
+Empirical analysis of 1,091 real coding sessions ([Blacklight](https://github.com/flyingrobots/blacklight)) found
 that **Read accounts for 96.2 GB of context burden** — 6.6x all
 other tools combined. 58% of reads are full-file. The fattest 2.4%
 of reads produce 24% of raw bytes. Dynamic read caps + session
@@ -36,6 +36,16 @@ docker run -i --rm -v "$PWD:/workspace" flyingrobots/graft
 
 ## Quick start
 
+```bash
+npx @flyingrobots/graft init
+```
+
+Scaffolds `.graftignore`, adds `.graft/` to `.gitignore`, generates
+a `CLAUDE.md` snippet telling agents to prefer graft tools, and
+prints Claude Code hook config.
+
+Then add graft to your MCP config:
+
 ```json
 {
   "mcpServers": {
@@ -96,6 +106,47 @@ is structured JSON.
 | `doctor` | Runtime health check |
 | `stats` | Decision metrics summary |
 
+## Claude Code hooks
+
+Two hooks work alongside the MCP server to govern native `Read`
+calls — a safety net for when agents bypass graft's tools:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add to `.claude/settings.json` in your project root.
+**PreToolUse** blocks banned files before the read.
+**PostToolUse** shows the agent what `safe_read` would have saved.
+
+See the **[Setup Guide](docs/GUIDE.md)** for full details on hooks,
+per-editor MCP config, `.graftignore`, and troubleshooting.
+
 ## Reason codes
 
 Every refusal or policy decision includes a machine-readable reason

package/bin/graft.js

@@ -1,11 +1,42 @@
-#!/usr/bin/env -S node --import tsx
+#!/usr/bin/env node
 
-// Graft MCP server — stdio transport
-// Usage: npx @flyingrobots/graft
+// Graft — context governor for coding agents
+// Bootstrap: re-exec with tsx loader resolved from the package's own deps.
 
-import { createGraftServer } from "../src/mcp/server.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 
-const graft = createGraftServer();
-const transport = new StdioServerTransport();
-await graft.getMcpServer().connect(transport);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// If already running under tsx, proceed directly
+if (process.env.__GRAFT_TSX_LOADED === "1") {
+  const command = process.argv[2];
+  if (command === "init") {
+    const { runInit } = await import("../src/cli/init.js");
+    runInit();
+  } else if (command === "index") {
+    const { runIndex } = await import("../src/cli/index-cmd.js");
+    await runIndex();
+  } else {
+    const { createGraftServer } = await import("../src/mcp/server.js");
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const graft = createGraftServer();
+    const transport = new StdioServerTransport();
+    await graft.getMcpServer().connect(transport);
+  }
+} else {
+  // Re-exec with tsx loader from our own node_modules
+  const tsxPath = require.resolve("tsx/esm");
+  const script = join(__dirname, "graft.js");
+  try {
+    execFileSync(process.execPath, ["--import", tsxPath, script, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: { ...process.env, __GRAFT_TSX_LOADED: "1" },
+    });
+  } catch (err) {
+    process.exit(err?.status ?? 1);
+  }
+}

package/docs/GUIDE.md

@@ -12,6 +12,20 @@ Or run without installing:
 npx @flyingrobots/graft
 ```
 
+## Quick setup
+
+```bash
+npx @flyingrobots/graft init
+```
+
+Scaffolds your project for graft in one command:
+- Creates `.graftignore` (template with examples)
+- Adds `.graft/` to `.gitignore`
+- Generates a `CLAUDE.md` snippet instructing agents to prefer graft tools
+- Prints Claude Code hook config for manual setup
+
+Idempotent — safe to run again without duplicating entries.
+
 ## MCP Configuration
 
 Graft runs as an MCP server over stdio. Add it to your editor or

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@flyingrobots/graft",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Context governor for coding agents — MCP server with policy-enforced reads, structural outlines, and session tracking",
   "type": "module",
+  "packageManager": "pnpm@10.30.0",
   "bin": {
     "graft": "./bin/graft.js",
     "git-graft": "./bin/graft.js"
@@ -16,6 +17,14 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "pnpm pack --dry-run"
+  },
   "engines": {
     "node": ">=20.11.0"
   },
@@ -48,6 +57,8 @@
     "url": "git+https://github.com/flyingrobots/graft.git"
   },
   "dependencies": {
+    "@git-stunts/git-warp": "^16.0.0",
+    "@git-stunts/plumbing": "^2.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "picomatch": "^4.0.4",
     "tree-sitter-wasms": "0.1.13",
@@ -65,12 +76,7 @@
     "typescript-eslint": "^8.58.0",
     "vitest": "^4.1.2"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "pack:check": "pnpm pack --dry-run"
+  "pnpm": {
+    "onlyBuiltDependencies": []
   }
-}
+}

package/src/cli/index-cmd.ts

@@ -0,0 +1,22 @@
+import { openWarp } from "../warp/open.js";
+import { indexCommits } from "../warp/indexer.js";
+
+export async function runIndex(): Promise<void> {
+  const cwd = process.cwd();
+  const from: string | undefined = process.argv[3];
+
+  console.log(`\nIndexing structural history in ${cwd}\n`);
+
+  try {
+    const warp = await openWarp({ cwd });
+    const result = await indexCommits(warp, { cwd, ...(from !== undefined ? { from } : {}) });
+
+    console.log(`  commits indexed: ${String(result.commitsIndexed)}`);
+    console.log(`  patches written: ${String(result.patchesWritten)}`);
+    console.log("\nDone.\n");
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${msg}`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/init.ts

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const GRAFTIGNORE_TEMPLATE = `# Graft ignore patterns — files matching these are refused by safe_read.
+# Syntax: same as .gitignore (glob matching via picomatch).
+
+# Examples:
+# *.generated.ts
+# vendor/**
+# data/**/*.json
+`;
+
+const AGENT_SNIPPET = `## File reads
+
+This project uses [graft](https://github.com/flyingrobots/graft) as
+a context governor. Prefer graft's MCP tools over native file reads:
+
+- Use \`safe_read\` instead of \`Read\` for file contents
+- Use \`file_outline\` to see structure before reading
+- Use \`read_range\` with jump table entries for targeted reads
+- Use \`graft_diff\` instead of \`git diff\` for structural changes
+- Use \`explain\` if you get an unfamiliar reason code
+- Call \`set_budget\` at session start if context is tight
+
+These tools enforce read policy, cache observations, and track
+session metrics. Native reads bypass all of that.
+`;
+
+const GITIGNORE_ENTRY = "\n# Graft runtime data\n.graft/\n";
+
+const HOOKS_CONFIG = `
+Add to .claude/settings.json for Claude Code hook integration:
+
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;
+
+function writeIfMissing(filePath: string, content: string, label: string): void {
+  if (fs.existsSync(filePath)) {
+    console.log(`  exists  ${label}`);
+  } else {
+    fs.writeFileSync(filePath, content);
+    console.log(`  create  ${label}`);
+  }
+}
+
+function appendIfMissing(filePath: string, marker: string, content: string, label: string): void {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, "utf-8");
+    if (existing.includes(marker)) {
+      console.log(`  exists  ${label} (already has graft entry)`);
+      return;
+    }
+    fs.appendFileSync(filePath, content);
+    console.log(`  append  ${label}`);
+  } else {
+    fs.writeFileSync(filePath, content.trimStart());
+    console.log(`  create  ${label}`);
+  }
+}
+
+export function runInit(): void {
+  const cwd = process.cwd();
+  console.log(`\nInitializing graft in ${cwd}\n`);
+
+  // 1. .graftignore
+  writeIfMissing(path.join(cwd, ".graftignore"), GRAFTIGNORE_TEMPLATE, ".graftignore");
+
+  // 2. .gitignore — append .graft/
+  appendIfMissing(path.join(cwd, ".gitignore"), ".graft/", GITIGNORE_ENTRY, ".gitignore");
+
+  // 3. CLAUDE.md — append agent instructions snippet
+  appendIfMissing(path.join(cwd, "CLAUDE.md"), "safe_read", "\n" + AGENT_SNIPPET, "CLAUDE.md");
+
+  // 4. Print hooks config for manual setup
+  console.log(HOOKS_CONFIG);
+
+  console.log("Done. Add graft to your MCP config:\n");
+  console.log(`  {
+    "mcpServers": {
+      "graft": {
+        "command": "npx",
+        "args": ["-y", "@flyingrobots/graft"]
+      }
+    }
+  }
+`);
+}

package/src/mcp/context.ts

@@ -9,6 +9,7 @@ import type { SessionTracker } from "../session/tracker.js";
 import type { McpToolResult } from "./receipt.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { JsonCodec } from "../ports/codec.js";
+import type WarpApp from "@git-stunts/git-warp";
 
 import type { z } from "zod";
 
@@ -32,6 +33,7 @@ export interface ToolContext {
   readonly codec: JsonCodec;
   respond(tool: string, data: Record<string, unknown>): McpToolResult;
   resolvePath(relative: string): string;
+  getWarp(): Promise<WarpApp>;
 }
 
 /**

package/src/mcp/server.ts

@@ -13,6 +13,8 @@ import { nodeFs } from "../adapters/node-fs.js";
 import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
 import { evaluatePolicy } from "../policy/evaluate.js";
 import { RefusedResult } from "../policy/types.js";
+import type WarpApp from "@git-stunts/git-warp";
+import { openWarp } from "../warp/open.js";
 
 // Tool definitions — each file exports a ToolDefinition object
 import { safeReadTool } from "./tools/safe-read.js";
@@ -26,6 +28,8 @@ import { doctorTool } from "./tools/doctor.js";
 import { statsTool } from "./tools/stats.js";
 import { explainTool } from "./tools/explain.js";
 import { setBudgetTool } from "./tools/budget.js";
+import { sinceTool } from "./tools/since.js";
+import { mapTool } from "./tools/map.js";
 
 export type { McpToolResult, ToolHandler, ToolContext };
 
@@ -43,6 +47,8 @@ const TOOL_REGISTRY: readonly ToolDefinition[] = [
   statsTool,
   explainTool,
   setBudgetTool,
+  sinceTool,
+  mapTool,
 ];
 
 export interface GraftServer {
@@ -78,7 +84,19 @@ export function createGraftServer(): GraftServer {
     return result;
   }
 
-  const ctx: ToolContext = { projectRoot, graftDir, session, cache, metrics, respond, resolvePath: createPathResolver(projectRoot), fs: nodeFs, codec };
+  // Lazy WARP initialization — only loaded when a WARP-backed tool needs it.
+  // Single pending promise prevents duplicate instances from concurrent calls.
+  // On rejection, clear cache so subsequent calls can retry.
+  let warpPromise: Promise<WarpApp> | null = null;
+  function getWarp(): Promise<WarpApp> {
+    warpPromise ??= openWarp({ cwd: projectRoot }).catch((err: unknown) => {
+      warpPromise = null;
+      throw err;
+    });
+    return warpPromise;
+  }
+
+  const ctx: ToolContext = { projectRoot, graftDir, session, cache, metrics, respond, resolvePath: createPathResolver(projectRoot), fs: nodeFs, codec, getWarp };
 
   function wrapWithPolicyCheck(toolName: string, inner: ToolHandler): ToolHandler {
     return (args: Record<string, unknown>) => {

package/src/mcp/tools/map.ts

@@ -0,0 +1,82 @@
+import * as path from "node:path";
+import { z } from "zod";
+import { extractOutline } from "../../parser/outline.js";
+import { detectLang } from "../../parser/lang.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { execFileSync } from "node:child_process";
+
+interface FileEntry {
+  path: string;
+  lang: string;
+  symbols: { name: string; kind: string; signature?: string | undefined; exported: boolean; startLine?: number | undefined; endLine?: number | undefined }[];
+}
+
+/**
+ * List files in a directory (git ls-files for tracked files).
+ */
+function listFiles(dirPath: string, cwd: string): string[] {
+  try {
+    const args = dirPath.length > 0
+      ? ["ls-files", "--", dirPath]
+      : ["ls-files"];
+    return execFileSync("git", args, { cwd, encoding: "utf-8" })
+      .trim().split("\n").filter((l) => l.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+export const mapTool: ToolDefinition = {
+  name: "graft_map",
+  description:
+    "Structural map of a directory — all files and their symbols " +
+    "(function signatures, class shapes, exports) in one call. " +
+    "Uses tree-sitter to parse the working tree directly.",
+  schema: {
+    path: z.string().optional(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const dirPath = (args["path"] as string | undefined) ?? "";
+
+      const filePaths = listFiles(dirPath, ctx.projectRoot);
+      const files: FileEntry[] = [];
+
+      for (const filePath of filePaths) {
+        const lang = detectLang(filePath);
+        if (lang === null) continue;
+
+        let content: string;
+        try {
+          content = ctx.fs.readFileSync(path.join(ctx.projectRoot, filePath), "utf-8");
+        } catch {
+          continue;
+        }
+
+        const result = extractOutline(content, lang);
+        const symbols: FileEntry["symbols"] = result.entries.map((entry) => {
+          const jump = result.jumpTable?.find((j) => j.symbol === entry.name);
+          return {
+            name: entry.name,
+            kind: entry.kind,
+            signature: entry.signature,
+            exported: entry.exported,
+            startLine: jump?.start,
+            endLine: jump?.end,
+          };
+        });
+
+        files.push({ path: filePath, lang, symbols });
+      }
+
+      files.sort((a, b) => a.path.localeCompare(b.path));
+      const totalSymbols = files.reduce((n, f) => n + f.symbols.length, 0);
+
+      return ctx.respond("graft_map", {
+        directory: dirPath.length > 0 ? dirPath : ".",
+        files,
+        summary: `${String(files.length)} files, ${String(totalSymbols)} symbols`,
+      });
+    };
+  },
+};

package/src/mcp/tools/since.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { graftDiff } from "../../operations/graft-diff.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const sinceTool: ToolDefinition = {
+  name: "graft_since",
+  description:
+    "Structural changes since a git ref. Shows symbols added, removed, " +
+    "and changed per file — not line hunks. Includes per-file summary " +
+    "lines for quick triage. Defaults to HEAD as the comparison target.",
+  schema: {
+    base: z.string(),
+    head: z.string().optional(),
+  },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => {
+      const base = args["base"] as string;
+      const head = (args["head"] as string | undefined) ?? "HEAD";
+
+      const result = graftDiff({
+        cwd: ctx.projectRoot,
+        fs: ctx.fs,
+        base,
+        head,
+      });
+
+      // Aggregate symbol-level changes across all files
+      let totalAdded = 0;
+      let totalRemoved = 0;
+      let totalChanged = 0;
+
+      for (const file of result.files) {
+        totalAdded += file.diff.added.length;
+        totalRemoved += file.diff.removed.length;
+        totalChanged += file.diff.changed.length;
+      }
+
+      return ctx.respond("graft_since", {
+        ...result,
+        summary: `+${String(totalAdded)} added, -${String(totalRemoved)} removed, ~${String(totalChanged)} changed across ${String(result.files.length)} files`,
+      });
+    };
+  },
+};

package/src/warp/indexer.ts

@@ -0,0 +1,398 @@
+/**
+ * WARP Indexer — walks git history and writes structural delta
+ * patches into the WARP graph.
+ *
+ * Observer Law: this module WRITES facts. It never reads them back.
+ * Reading is done exclusively through observers (see observers.ts).
+ */
+
+import type WarpApp from "@git-stunts/git-warp";
+import { execFileSync } from "node:child_process";
+import { extractOutline } from "../parser/outline.js";
+import { diffOutlines } from "../parser/diff.js";
+import { detectLang } from "../parser/lang.js";
+import { getFileAtRef } from "../git/diff.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import type { DiffEntry } from "../parser/diff.js";
+
+export interface IndexOptions {
+  readonly cwd: string;
+  readonly from?: string;
+  readonly to?: string;
+}
+
+export interface IndexResult {
+  readonly commitsIndexed: number;
+  readonly patchesWritten: number;
+  readonly commitTicks: ReadonlyMap<string, number>;
+}
+
+// Patch builder shape — matches PatchBuilderV2's fluent API.
+interface PatchOps {
+  addNode(id: string): PatchOps;
+  removeNode(id: string): PatchOps;
+  setProperty(id: string, key: string, value: unknown): PatchOps;
+  addEdge(from: string, to: string, label: string): PatchOps;
+  removeEdge(from: string, to: string, label: string): PatchOps;
+}
+
+function listCommits(cwd: string, from?: string, to?: string): string[] {
+  const range = from !== undefined ? `${from}..${to ?? "HEAD"}` : to ?? "HEAD";
+  const args = ["log", "--reverse", "--format=%H", range];
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8" })
+      .trim().split("\n").filter((l) => l.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function getCommitChanges(sha: string, cwd: string): { status: string; path: string }[] {
+  // --root handles the initial commit (no parent to diff against)
+  const args = ["diff-tree", "--root", "--no-commit-id", "-r", "--name-status", sha];
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8" })
+      .trim().split("\n").filter((l) => l.length > 0).map((line) => {
+        const parts = line.split("\t");
+        return { status: parts[0] ?? "", path: parts[1] ?? "" };
+      });
+  } catch {
+    return [];
+  }
+}
+
+function getCommitMeta(sha: string, cwd: string): { message: string; author: string; email: string; timestamp: string } {
+  try {
+    const output = execFileSync("git", ["log", "-1", "--format=%s%n%aN%n%aE%n%aI", sha], { cwd, encoding: "utf-8" });
+    const lines = output.trim().split("\n");
+    return { message: lines[0] ?? "", author: lines[1] ?? "", email: lines[2] ?? "", timestamp: lines[3] ?? "" };
+  } catch {
+    return { message: "", author: "", email: "", timestamp: "" };
+  }
+}
+
+/**
+ * Check if a commit has a parent (is not the root commit).
+ */
+function hasParent(sha: string, cwd: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--verify", `${sha}~1`], { cwd, encoding: "utf-8" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function dirNodeId(dirPath: string): string {
+  return `dir:${dirPath}`;
+}
+
+function fileNodeId(filePath: string): string {
+  return `file:${filePath}`;
+}
+
+function symNodeId(filePath: string, name: string): string {
+  return `sym:${filePath}:${name}`;
+}
+
+/**
+ * Build a lookup from symbol name → line range from the jump table.
+ */
+function buildJumpLookup(jumpTable: readonly JumpEntry[]): Map<string, { start: number; end: number }> {
+  const lookup = new Map<string, { start: number; end: number }>();
+  for (const entry of jumpTable) {
+    lookup.set(entry.symbol, { start: entry.start, end: entry.end });
+  }
+  return lookup;
+}
+
+/**
+ * Emit directory nodes + edges for all path components of a file.
+ */
+function emitDirectoryChain(patch: PatchOps, filePath: string): void {
+  const parts = filePath.split("/");
+  if (parts.length <= 1) return;
+
+  let current = "";
+  for (let i = 0; i < parts.length - 1; i++) {
+    const parent = current;
+    const part = parts[i] ?? "";
+    current = current.length > 0 ? `${current}/${part}` : part;
+    const dirId = dirNodeId(current);
+    patch.addNode(dirId);
+    patch.setProperty(dirId, "path", current);
+
+    if (parent.length > 0) {
+      patch.addEdge(dirNodeId(parent), dirId, "contains");
+    }
+  }
+
+  patch.addEdge(dirNodeId(current), fileNodeId(filePath), "contains");
+}
+
+/**
+ * Emit symbol nodes + edges for all entries in a file outline.
+ */
+function emitSymbols(
+  patch: PatchOps,
+  filePath: string,
+  entries: readonly OutlineEntry[],
+  jumpLookup: Map<string, { start: number; end: number }>,
+  parentSymId?: string,
+): void {
+  for (const entry of entries) {
+    const symId = symNodeId(filePath, entry.name);
+    patch.addNode(symId);
+    patch.setProperty(symId, "name", entry.name);
+    patch.setProperty(symId, "kind", entry.kind);
+    patch.setProperty(symId, "exported", entry.exported);
+    if (entry.signature !== undefined) {
+      patch.setProperty(symId, "signature", entry.signature);
+    }
+    const jump = jumpLookup.get(entry.name);
+    if (jump !== undefined) {
+      patch.setProperty(symId, "startLine", jump.start);
+      patch.setProperty(symId, "endLine", jump.end);
+    }
+    patch.addEdge(fileNodeId(filePath), symId, "contains");
+    if (parentSymId !== undefined) {
+      patch.addEdge(parentSymId, symId, "child_of");
+    }
+    if (entry.children !== undefined && entry.children.length > 0) {
+      emitSymbols(patch, filePath, entry.children, jumpLookup, symId);
+    }
+  }
+}
+
+/**
+ * Tombstone (remove) symbol nodes recursively including children.
+ */
+function removeSymbols(
+  patch: PatchOps,
+  filePath: string,
+  entries: readonly OutlineEntry[],
+): void {
+  for (const entry of entries) {
+    // Recurse into children FIRST (bottom-up removal)
+    if (entry.children !== undefined && entry.children.length > 0) {
+      removeSymbols(patch, filePath, entry.children);
+    }
+    const symId = symNodeId(filePath, entry.name);
+    patch.removeEdge(fileNodeId(filePath), symId, "contains");
+    patch.removeNode(symId);
+  }
+}
+
+/**
+ * Remove symbols from DiffEntry (removed symbols in a diff).
+ * Also recursively handles childDiff if present.
+ */
+function removeDiffSymbols(
+  patch: PatchOps,
+  filePath: string,
+  fileId: string,
+  entries: readonly DiffEntry[],
+): void {
+  for (const entry of entries) {
+    // Recurse into childDiff if present (remove grandchildren first)
+    if (entry.childDiff !== undefined) {
+      removeDiffSymbols(patch, filePath, fileId, [...entry.childDiff.removed]);
+      removeDiffSymbols(patch, filePath, fileId, [...entry.childDiff.added]);
+      removeDiffSymbols(patch, filePath, fileId, [...entry.childDiff.changed]);
+    }
+    const symId = symNodeId(filePath, entry.name);
+    patch.removeEdge(fileId, symId, "contains");
+    patch.removeNode(symId);
+  }
+}
+
+/**
+ * Apply child diffs for changed symbols (methods added/removed/changed
+ * inside a class that kept its name).
+ */
+function applyChildDiffs(
+  patch: PatchOps,
+  filePath: string,
+  fileId: string,
+  commitId: string,
+  changed: readonly DiffEntry[],
+  jumpLookup: Map<string, { start: number; end: number }>,
+): void {
+  for (const entry of changed) {
+    if (entry.childDiff === undefined) continue;
+    const parentSymId = symNodeId(filePath, entry.name);
+
+    for (const added of entry.childDiff.added) {
+      const symId = symNodeId(filePath, added.name);
+      patch.addNode(symId);
+      patch.setProperty(symId, "name", added.name);
+      patch.setProperty(symId, "kind", added.kind);
+      patch.setProperty(symId, "exported", false);
+      if (added.signature !== undefined) {
+        patch.setProperty(symId, "signature", added.signature);
+      }
+      const jump = jumpLookup.get(added.name);
+      if (jump !== undefined) {
+        patch.setProperty(symId, "startLine", jump.start);
+        patch.setProperty(symId, "endLine", jump.end);
+      }
+      patch.addEdge(fileId, symId, "contains");
+      patch.addEdge(parentSymId, symId, "child_of");
+      patch.addEdge(commitId, symId, "adds");
+    }
+
+    for (const removed of entry.childDiff.removed) {
+      const symId = symNodeId(filePath, removed.name);
+      patch.addEdge(commitId, symId, "removes");
+      patch.removeEdge(fileId, symId, "contains");
+      patch.removeNode(symId);
+    }
+
+    // Recurse into changed children that have their own childDiffs
+    applyChildDiffs(patch, filePath, fileId, commitId, [...entry.childDiff.changed], jumpLookup);
+
+    for (const child of entry.childDiff.changed) {
+      const symId = symNodeId(filePath, child.name);
+      patch.setProperty(symId, "kind", child.kind);
+      if (child.signature !== undefined) {
+        patch.setProperty(symId, "signature", child.signature);
+      }
+      patch.addEdge(commitId, symId, "changes");
+    }
+  }
+}
+
+/**
+ * Index a range of commits into the WARP graph.
+ */
+export async function indexCommits(
+  warp: WarpApp,
+  options: IndexOptions,
+): Promise<IndexResult> {
+  const { cwd } = options;
+  const commits = listCommits(cwd, options.from, options.to);
+
+  let patchesWritten = 0;
+  const commitTicks = new Map<string, number>();
+
+  for (const sha of commits) {
+    const changes = getCommitChanges(sha, cwd);
+
+    // Only materialize when removals are possible (D or M status).
+    // Materialization is expensive — O(n) replay of all prior patches.
+    // Add-only commits (A status) and no-change commits don't need it.
+    const hasRemovals = changes.some((c) => c.status === "D" || c.status === "M");
+    if (hasRemovals) {
+      await warp.core().materialize();
+    }
+
+    const meta = getCommitMeta(sha, cwd);
+    const parentExists = hasParent(sha, cwd);
+    const parentRef = `${sha}~1`;
+
+    await warp.patch((p) => {
+      const patch = p as unknown as PatchOps;
+
+      const commitId = `commit:${sha}`;
+      patch.addNode(commitId);
+      patch.setProperty(commitId, "sha", sha);
+      patch.setProperty(commitId, "message", meta.message);
+      patch.setProperty(commitId, "author", meta.author);
+      patch.setProperty(commitId, "email", meta.email);
+      patch.setProperty(commitId, "timestamp", meta.timestamp);
+
+      for (const change of changes) {
+        const filePath = change.path;
+        const fileId = fileNodeId(filePath);
+        const lang = detectLang(filePath);
+
+        if (change.status === "D") {
+          if (lang !== null && parentExists) {
+            const oldContent = getFileAtRef(parentRef, filePath, cwd);
+            if (oldContent !== null) {
+              const oldOutline = extractOutline(oldContent, lang).entries;
+              removeSymbols(patch, filePath, oldOutline);
+            }
+          }
+          patch.removeNode(fileId);
+          continue;
+        }
+
+        // Added or modified — ensure file + directory nodes exist
+        patch.addNode(fileId);
+        patch.setProperty(fileId, "path", filePath);
+        patch.setProperty(fileId, "lang", lang ?? "unknown");
+        patch.addEdge(commitId, fileId, "touches");
+        emitDirectoryChain(patch, filePath);
+
+        if (lang === null) continue;
+
+        const newContent = getFileAtRef(sha, filePath, cwd);
+        if (newContent === null) continue;
+        const newResult = extractOutline(newContent, lang);
+        const newOutline = newResult.entries;
+        const jumpLookup = buildJumpLookup(newResult.jumpTable ?? []);
+
+        if (change.status === "A" || !parentExists) {
+          // New file or root commit — emit all symbols
+          emitSymbols(patch, filePath, newOutline, jumpLookup);
+        } else {
+          // Modified file — structural diff
+          const oldContent = getFileAtRef(parentRef, filePath, cwd);
+          if (oldContent === null) {
+            emitSymbols(patch, filePath, newOutline, jumpLookup);
+            continue;
+          }
+
+          const oldOutline = extractOutline(oldContent, lang).entries;
+          const diff = diffOutlines(oldOutline, newOutline);
+
+          // Remove deleted symbols
+          for (const removed of diff.removed) {
+            const symId = symNodeId(filePath, removed.name);
+            patch.addEdge(commitId, symId, "removes");
+            removeDiffSymbols(patch, filePath, fileId, [removed]);
+          }
+
+          // Add new symbols (preserve actual exported status)
+          for (const added of diff.added) {
+            const symId = symNodeId(filePath, added.name);
+            patch.addNode(symId);
+            patch.setProperty(symId, "name", added.name);
+            patch.setProperty(symId, "kind", added.kind);
+            // DiffEntry doesn't carry exported — default false for safety.
+            // Full exported status comes from emitSymbols on initial add.
+            patch.setProperty(symId, "exported", false);
+            if (added.signature !== undefined) {
+              patch.setProperty(symId, "signature", added.signature);
+            }
+            const jump = jumpLookup.get(added.name);
+            if (jump !== undefined) {
+              patch.setProperty(symId, "startLine", jump.start);
+              patch.setProperty(symId, "endLine", jump.end);
+            }
+            patch.addEdge(fileId, symId, "contains");
+            patch.addEdge(commitId, symId, "adds");
+          }
+
+          // Update changed symbols
+          for (const changed of diff.changed) {
+            const symId = symNodeId(filePath, changed.name);
+            patch.setProperty(symId, "kind", changed.kind);
+            if (changed.signature !== undefined) {
+              patch.setProperty(symId, "signature", changed.signature);
+            }
+            patch.addEdge(commitId, symId, "changes");
+          }
+
+          // Apply nested child diffs (methods in classes)
+          applyChildDiffs(patch, filePath, fileId, commitId, [...diff.changed], jumpLookup);
+        }
+      }
+    });
+    patchesWritten++;
+    commitTicks.set(sha, patchesWritten);
+  }
+
+  return { commitsIndexed: commits.length, patchesWritten, commitTicks };
+}

package/src/warp/observers.ts

@@ -0,0 +1,105 @@
+/**
+ * WARP Observer Factory — canonical observer lenses for graft queries.
+ *
+ * Observer Law: this module READS through observers. It never
+ * walks the graph directly, maintains shadow state, or implements
+ * traversal algorithms.
+ *
+ * Each function returns an observer with a focused lens. The lens
+ * determines the aperture — what the observer can see.
+ */
+
+import type WarpApp from "@git-stunts/git-warp";
+import type { Observer } from "@git-stunts/git-warp";
+
+/** Lens config for creating focused observers. */
+export interface Lens {
+  match: string;
+  expose?: string[];
+  redact?: string[];
+}
+
+/**
+ * Observe all symbols in a specific file.
+ * Aperture: sym:<path>:*
+ */
+export function fileSymbolsLens(filePath: string): Lens {
+  return {
+    match: `sym:${filePath}:*`,
+    expose: ["name", "kind", "signature", "exported", "startLine", "endLine"],
+  };
+}
+
+/**
+ * Observe all symbols in the project.
+ * Aperture: sym:*
+ */
+export function allSymbolsLens(): Lens {
+  return {
+    match: "sym:*",
+    expose: ["name", "kind", "signature", "exported"],
+  };
+}
+
+/**
+ * Observe all files in the project.
+ * Aperture: file:*
+ */
+export function allFilesLens(): Lens {
+  return {
+    match: "file:*",
+    expose: ["path", "lang"],
+  };
+}
+
+/**
+ * Observe a single symbol by name across all files.
+ * Aperture: sym:*:<name>
+ */
+export function symbolByNameLens(symbolName: string): Lens {
+  return {
+    match: `sym:*:${symbolName}`,
+    expose: ["name", "kind", "signature", "exported", "startLine", "endLine"],
+  };
+}
+
+/**
+ * Observe a directory subtree.
+ * Aperture: dir:<path>*
+ */
+export function directoryLens(dirPath: string): Lens {
+  return {
+    match: `dir:${dirPath}*`,
+    expose: ["path"],
+  };
+}
+
+/**
+ * Observe all files under a directory.
+ * Aperture: file:<path>/*
+ */
+export function directoryFilesLens(dirPath: string): Lens {
+  return {
+    match: `file:${dirPath}/*`,
+    expose: ["path", "lang"],
+  };
+}
+
+/**
+ * Observe commit metadata.
+ * Aperture: commit:*
+ */
+export function commitsLens(): Lens {
+  return {
+    match: "commit:*",
+    expose: ["sha", "message", "timestamp", "author", "email"],
+  };
+}
+
+/**
+ * Create an observer on the current frontier with a given lens.
+ * Observers are static snapshots — create a new one after writes.
+ */
+export function observe(warp: WarpApp, lens: Lens): Promise<Observer> {
+  return warp.observer(lens);
+}

package/src/warp/open.ts

@@ -0,0 +1,30 @@
+/**
+ * WARP graph initialization — opens the graft-ast graph backed by
+ * the repo's own .git directory.
+ *
+ * Single entry point. Returns a WarpApp instance ready for patch
+ * writes and observer reads.
+ */
+
+import WarpApp, { GitGraphAdapter } from "@git-stunts/git-warp";
+import GitPlumbing from "@git-stunts/plumbing";
+
+const GRAPH_NAME = "graft-ast";
+const WRITER_ID = "graft";
+
+export interface OpenWarpOptions {
+  readonly cwd: string;
+}
+
+export async function openWarp(options: OpenWarpOptions): Promise<WarpApp> {
+  // createDefault() wires the ShellRunnerFactory (required port)
+  const plumbing = GitPlumbing.createDefault({ cwd: options.cwd });
+  const persistence = new GitGraphAdapter({ plumbing });
+
+  return WarpApp.open({
+    persistence,
+    graphName: GRAPH_NAME,
+    writerId: WRITER_ID,
+    onDeleteWithData: "cascade",
+  });
+}

package/src/warp/plumbing.d.ts

@@ -0,0 +1,11 @@
+declare module "@git-stunts/plumbing" {
+  import type { GitPlumbing as GitPlumbingInterface } from "@git-stunts/git-warp";
+
+  export default class GitPlumbing implements GitPlumbingInterface {
+    readonly emptyTree: string;
+    constructor(options: { runner: unknown; cwd?: string });
+    static createDefault(options?: { cwd?: string; env?: string }): GitPlumbing;
+    execute(options: { args: string[]; input?: string | Uint8Array }): Promise<string>;
+    executeStream(options: { args: string[] }): Promise<AsyncIterable<Uint8Array> & { collect(opts?: { asString?: boolean }): Promise<Uint8Array | string> }>;
+  }
+}