@flyingrobots/graft 0.4.0 → 0.6.0

package/dist/warp/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/warp/open.ts"],"names":[],"mappings":"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"}

package/dist/warp/symbol-identity.d.ts

@@ -0,0 +1,11 @@
+import type { OutlineEntry } from "../parser/types.js";
+export type SymbolIdentityMap = ReadonlyMap<string, string>;
+export declare function buildSymbolPath(parentPath: string, name: string): string;
+export declare function assignCanonicalSymbolIdentities(input: {
+    oldEntries: readonly OutlineEntry[];
+    newEntries: readonly OutlineEntry[];
+    oldIdentityByPath: SymbolIdentityMap;
+    commitSha: string;
+    filePath: string;
+}): Map<string, string>;
+//# sourceMappingURL=symbol-identity.d.ts.map

package/dist/warp/symbol-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-identity.d.ts","sourceRoot":"","sources":["../../src/warp/symbol-identity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExE;AAmBD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAetB"}

package/dist/warp/symbol-identity.js

@@ -0,0 +1,67 @@
+import crypto from "node:crypto";
+import { diffOutlines } from "../parser/diff.js";
+export function buildSymbolPath(parentPath, name) {
+    return parentPath.length > 0 ? `${parentPath}.${name}` : name;
+}
+function mintCanonicalSymbolIdentity(commitSha, filePath, symbolPath, entry) {
+    const seed = [
+        commitSha,
+        filePath,
+        symbolPath,
+        entry.kind,
+        entry.signature ?? "",
+        String(entry.exported),
+    ].join("\n");
+    return `sid:${crypto.createHash("sha256").update(seed).digest("hex").slice(0, 16)}`;
+}
+export function assignCanonicalSymbolIdentities(input) {
+    const assigned = new Map();
+    assignLevel({
+        oldEntries: input.oldEntries,
+        newEntries: input.newEntries,
+        oldIdentityByPath: input.oldIdentityByPath,
+        commitSha: input.commitSha,
+        filePath: input.filePath,
+        oldParentPath: "",
+        newParentPath: "",
+        assigned,
+    });
+    return assigned;
+}
+function assignLevel(input) {
+    const oldByName = new Map();
+    for (const entry of input.oldEntries) {
+        oldByName.set(entry.name, entry);
+    }
+    const continuityByNewName = new Map();
+    const diff = diffOutlines(input.oldEntries, input.newEntries);
+    for (const continuity of diff.continuity) {
+        continuityByNewName.set(continuity.newName, continuity.oldName);
+    }
+    for (const newEntry of input.newEntries) {
+        const newSymbolPath = buildSymbolPath(input.newParentPath, newEntry.name);
+        const oldName = oldByName.has(newEntry.name)
+            ? newEntry.name
+            : continuityByNewName.get(newEntry.name);
+        const oldEntry = oldName !== undefined ? oldByName.get(oldName) : undefined;
+        const oldSymbolPath = oldName !== undefined
+            ? buildSymbolPath(input.oldParentPath, oldName)
+            : null;
+        const identityId = oldSymbolPath !== null
+            ? input.oldIdentityByPath.get(oldSymbolPath) ??
+                mintCanonicalSymbolIdentity(input.commitSha, input.filePath, newSymbolPath, newEntry)
+            : mintCanonicalSymbolIdentity(input.commitSha, input.filePath, newSymbolPath, newEntry);
+        input.assigned.set(newSymbolPath, identityId);
+        assignLevel({
+            oldEntries: oldEntry?.children ?? [],
+            newEntries: newEntry.children ?? [],
+            oldIdentityByPath: input.oldIdentityByPath,
+            commitSha: input.commitSha,
+            filePath: input.filePath,
+            oldParentPath: oldSymbolPath ?? "",
+            newParentPath: newSymbolPath,
+            assigned: input.assigned,
+        });
+    }
+}
+//# sourceMappingURL=symbol-identity.js.map

package/dist/warp/symbol-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-identity.js","sourceRoot":"","sources":["../../src/warp/symbol-identity.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKjD,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,IAAY;IAC9D,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC;AAED,SAAS,2BAA2B,CAClC,SAAiB,EACjB,QAAgB,EAChB,UAAkB,EAClB,KAAmB;IAEnB,MAAM,IAAI,GAAG;QACX,SAAS;QACT,QAAQ;QACR,UAAU;QACV,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,SAAS,IAAI,EAAE;QACrB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC;KACvB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,KAM/C;IACC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3C,WAAW,CAAC;QACV,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,aAAa,EAAE,EAAE;QACjB,aAAa,EAAE,EAAE;QACjB,QAAQ;KACT,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,WAAW,CAAC,KASpB;IACC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAClD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9D,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACzC,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,aAAa,GAAG,eAAe,CAAC,KAAK,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;YAC1C,CAAC,CAAC,QAAQ,CAAC,IAAI;YACf,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,MAAM,aAAa,GAAG,OAAO,KAAK,SAAS;YACzC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC;YAC/C,CAAC,CAAC,IAAI,CAAC;QAET,MAAM,UAAU,GAAG,aAAa,KAAK,IAAI;YACvC,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,aAAa,CAAC;gBAC1C,2BAA2B,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC;YACvF,CAAC,CAAC,2BAA2B,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QAE1F,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QAE9C,WAAW,CAAC;YACV,UAAU,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE;YACpC,UAAU,EAAE,QAAQ,CAAC,QAAQ,IAAI,EAAE;YACnC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,aAAa,EAAE,aAAa,IAAI,EAAE;YAClC,aAAa,EAAE,aAAa;YAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/warp/writer-id.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_WARP_WRITER_ID = "graft";
+export declare function buildWarpWriterId(kind: string, scope?: string): string;
+export declare function buildSessionWarpWriterId(sessionId: string): string;
+export declare function buildMonitorWarpWriterId(repoId: string): string;
+//# sourceMappingURL=writer-id.d.ts.map

package/dist/warp/writer-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-id.d.ts","sourceRoot":"","sources":["../../src/warp/writer-id.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAW9C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAQtE;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/warp/writer-id.js

@@ -0,0 +1,25 @@
+import * as crypto from "node:crypto";
+export const DEFAULT_WARP_WRITER_ID = "graft";
+function sanitizeSegment(input) {
+    const normalized = input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return normalized.length > 0 ? normalized : "lane";
+}
+export function buildWarpWriterId(kind, scope) {
+    const lane = sanitizeSegment(kind);
+    if (scope === undefined || scope.trim().length === 0) {
+        return `graft_${lane}`;
+    }
+    const digest = crypto.createHash("sha256").update(scope).digest("hex").slice(0, 12);
+    return `graft_${lane}_${digest}`;
+}
+export function buildSessionWarpWriterId(sessionId) {
+    return buildWarpWriterId("session", sessionId);
+}
+export function buildMonitorWarpWriterId(repoId) {
+    return buildWarpWriterId("monitor", repoId);
+}
+//# sourceMappingURL=writer-id.js.map

package/dist/warp/writer-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-id.js","sourceRoot":"","sources":["../../src/warp/writer-id.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAE9C,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,UAAU,GAAG,KAAK;SACrB,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;SAC7B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,KAAc;IAC5D,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,SAAS,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpF,OAAO,SAAS,IAAI,IAAI,MAAM,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,SAAiB;IACxD,OAAO,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,OAAO,iBAAiB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC9C,CAAC"}

package/docs/CLI.md

@@ -0,0 +1,65 @@
+# CLI
+
+The Graft command surface is a composite of published binaries and repo-local operator scripts.
+
+```mermaid
+flowchart LR
+    A[Graft CLI Surface] --> B[Lifecycle]
+    A --> C[Namespaces]
+    B --> B1[init]
+    B --> B2[serve]
+    B --> B3[daemon]
+    B --> B4[index]
+    B --> B5[migrate local-history]
+    C --> C1[read]
+    C --> C2[struct]
+    C --> C3[symbol]
+    C --> C4[diag]
+```
+
+## What it is for
+- bootstrap and setup via `graft init`
+- one-time legacy import via `graft migrate local-history`
+- local debugging and dogfooding of MCP peer commands
+- human-facing inspection of bounded state such as:
+  - `graft diag activity`
+  - `graft diag local-history-dag`
+  - `graft diag doctor`
+  - `graft diag stats`
+
+## Core namespaces
+- `read` — bounded reads and change checks
+- `struct` — structural diff / since / map
+- `symbol` — precision show / find
+- `diag` — activity, local-history-dag, doctor, explain, stats, capture
+
+## Release-facing commands
+```bash
+graft migrate local-history --json
+graft diag activity --json
+graft diag local-history-dag --json
+graft diag doctor --json
+graft symbol find 'create*' --json
+graft struct diff --json
+```
+
+## Repo-local invocation
+When working from this checkout, use one of these forms:
+
+```bash
+pnpm graft diag activity
+./bin/graft.js diag activity
+```
+
+Bare `graft ...` only works when the package is installed or linked onto your `PATH`.
+
+`graft diag activity` is the current human-facing between-commit surface. It reports bounded local `artifact_history`, not canonical provenance, and now renders a textual operator summary by default. Use `--json` when you want the structured machine-readable form.
+
+`graft diag local-history-dag` is a CLI-only debug surface over the repo-local WARP graph. It renders a bounded event-centric DAG for local history through Bijou's `dag()` component. In interactive terminals that means the Bijou DAG layout; in pipes or non-TTY contexts it degrades to Bijou's truthful pipe-mode graph listing.
+
+## Related docs
+- [README](../README.md)
+- [Setup Guide](./SETUP.md)
+- [MCP Guide](./MCP.md)
+- [Advanced Guide](./ADVANCED_GUIDE.md)
+- [Architecture](../ARCHITECTURE.md)

package/docs/MCP.md

@@ -0,0 +1,63 @@
+# MCP
+
+Graft is a high-fidelity tool provider for the Model Context Protocol (MCP).
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server as Graft Server
+    participant Policy as Policy Engine
+    participant Parser as Tree-Sitter
+    Client->>Server: call tool(safe_read, path)
+    Server->>Policy: evaluate(path, session)
+    Policy-->>Server: ALLOW (outline)
+    Server->>Parser: extract outline
+    Parser-->>Server: Outline + JumpTable
+    Server-->>Client: respond(JSON + Receipt)
+```
+
+## Startup
+
+### Repo-local stdio MCP
+```bash
+npx @flyingrobots/graft serve
+```
+
+This is the default repo-local MCP posture. The current checkout is the
+active workspace, so there is no separate daemon authorization or
+binding step.
+
+### Local Daemon
+```bash
+npx @flyingrobots/graft daemon
+```
+
+Daemon sessions start `unbound`. Once a client is connected to the
+daemon MCP surface, repository-scoped work follows this control-plane
+flow:
+
+1. `workspace_authorize` with the target `cwd`
+2. `workspace_bind` with the target `cwd`
+3. then call repository-scoped tools such as `safe_read`, `graft_since`,
+   or `code_show`
+
+## Key Tool Groups
+- **Bounded Reads**: `safe_read`, `file_outline`, `read_range`, `changed_since`
+- **Structural History**: `graft_diff`, `graft_since`, `graft_map`
+- **Precision**: `code_show`, `code_find`, `code_refs`
+- **Activity & Footing**: `activity_view`, `causal_status`, `causal_attach`, `doctor`
+- **Daemon Control Plane**: `workspace_authorizations`, `workspace_authorize`, `workspace_bind`, `workspace_status`, `workspace_rebind`, `workspace_revoke`, `daemon_status`, `daemon_repos`, `daemon_sessions`, `daemon_monitors`, `monitor_*`
+
+## Current Truth
+- MCP is the primary agent surface.
+- Responses carry versioned `_schema` metadata and `_receipt` decision data.
+- `activity_view` provides bounded local `artifact_history` anchored to Git `HEAD`.
+
+## Related docs
+- [README](../README.md)
+- [Setup Guide](./SETUP.md)
+- [CLI Guide](./CLI.md)
+- [Advanced Guide](./ADVANCED_GUIDE.md)
+- [Architecture](../ARCHITECTURE.md)
+- [Security Model](./strategy/security-model.md)
+- [Causal Provenance](./strategy/causal-provenance.md)

package/package.json

@@ -1,29 +1,49 @@
 {
   "name": "@flyingrobots/graft",
-  "version": "0.4.0",
-  "description": "Context governor for coding agents — MCP server with policy-enforced reads, structural outlines, and session tracking",
+  "version": "0.6.0",
+  "description": "Context governor and between-commit activity surface for coding agents",
   "type": "module",
   "packageManager": "pnpm@10.30.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "graft": "./bin/graft.js",
     "git-graft": "./bin/graft.js"
   },
   "files": [
     "bin/",
+    "dist/",
     "src/",
+    "ARCHITECTURE.md",
+    "CODE_OF_CONDUCT.md",
+    "docs/ADVANCED_GUIDE.md",
+    "docs/CLI.md",
     "docs/GUIDE.md",
+    "docs/MCP.md",
     "LICENSE",
     "NOTICE",
     "README.md",
     "CHANGELOG.md"
   ],
   "scripts": {
+    "graft": "node ./bin/graft.js",
     "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
-    "pack:check": "pnpm pack --dry-run"
+    "pack:check": "pnpm pack --dry-run",
+    "security:check": "tsx scripts/check-release-security.ts",
+    "release:surface-gate": "vitest run --run test/unit/release/package-library-surface.test.ts test/unit/release/three-surface-capability-posture.test.ts",
+    "release:check": "pnpm lint && pnpm typecheck && pnpm release:surface-gate && pnpm test && pnpm security:check && pnpm pack:check"
   },
   "engines": {
     "node": ">=20.11.0"
@@ -57,6 +77,8 @@
     "url": "git+https://github.com/flyingrobots/graft.git"
   },
   "dependencies": {
+    "@flyingrobots/bijou": "^4.4.1",
+    "@flyingrobots/bijou-node": "^4.4.1",
     "@git-stunts/git-warp": "^16.0.0",
     "@git-stunts/plumbing": "^2.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -74,9 +96,14 @@
     "globals": "^17.4.0",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.58.0",
+    "vite": "^8.0.5",
     "vitest": "^4.1.2"
   },
   "pnpm": {
-    "onlyBuiltDependencies": []
+    "onlyBuiltDependencies": [],
+    "overrides": {
+      "vite": "^8.0.5",
+      "hono": ">=4.12.14"
+    }
   }
 }

package/src/adapters/node-fs.ts

@@ -14,6 +14,10 @@ class NodeFileSystem implements FileSystem {
     return fsp.readFile(path);
   }
 
+  readdir(path: string): Promise<string[]> {
+    return fsp.readdir(path);
+  }
+
   writeFile(path: string, data: string, encoding: "utf-8"): Promise<void> {
     return fsp.writeFile(path, data, encoding);
   }

package/src/adapters/node-git.ts

@@ -0,0 +1,47 @@
+// ---------------------------------------------------------------------------
+// NodeGitClient — implements the GitClient port via GitPlumbing
+// ---------------------------------------------------------------------------
+
+import GitPlumbing from "@git-stunts/plumbing";
+import type { GitClient, GitRunRequest } from "../ports/git.js";
+
+class NodeGitClient implements GitClient {
+  private readonly clients = new Map<string, GitPlumbing>();
+
+  private resolveClient(cwd: string): GitPlumbing {
+    const cached = this.clients.get(cwd);
+    if (cached !== undefined) return cached;
+    const created = GitPlumbing.createDefault({ cwd });
+    this.clients.set(cwd, created);
+    return created;
+  }
+
+  async run(request: GitRunRequest) {
+    try {
+      const plumbing = this.resolveClient(request.cwd);
+      const stream = await plumbing.executeStream({ args: [...request.args] });
+      const stdout = await stream.collect({
+        asString: true,
+        ...(request.maxBufferBytes !== undefined ? { maxBytes: request.maxBufferBytes } : {}),
+      });
+      const finished = await stream.finished;
+      const error = "error" in finished && finished.error instanceof Error ? finished.error : undefined;
+      return {
+        status: finished.code,
+        stdout: typeof stdout === "string" ? stdout : new TextDecoder().decode(stdout),
+        stderr: finished.stderr,
+        ...(error !== undefined ? { error } : {}),
+      };
+    } catch (error: unknown) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      return {
+        status: 1,
+        stdout: "",
+        stderr: normalized.message,
+        error: normalized,
+      };
+    }
+  }
+}
+
+export const nodeGit: GitClient = new NodeGitClient();

package/src/adapters/node-process-runner.ts

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// NodeProcessRunner — implements the ProcessRunner port
+// ---------------------------------------------------------------------------
+
+import { spawnSync } from "node:child_process";
+import type { ProcessRunRequest, ProcessRunResult, ProcessRunner } from "../ports/process-runner.js";
+
+class NodeProcessRunner implements ProcessRunner {
+  run(request: ProcessRunRequest): ProcessRunResult {
+    const result = spawnSync(request.command, [...request.args], {
+      cwd: request.cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      ...(request.timeoutMs !== undefined ? { timeout: request.timeoutMs } : {}),
+      ...(request.maxBufferBytes !== undefined ? { maxBuffer: request.maxBufferBytes } : {}),
+    });
+
+    return {
+      status: result.status,
+      stdout: typeof result.stdout === "string" ? result.stdout : "",
+      stderr: typeof result.stderr === "string" ? result.stderr : "",
+      ...(result.error !== undefined ? { error: result.error } : {}),
+    };
+  }
+}
+
+export const nodeProcessRunner: ProcessRunner = new NodeProcessRunner();

package/src/adapters/repo-paths.ts

@@ -0,0 +1,22 @@
+import * as path from "node:path";
+
+export function createRepoPathResolver(projectRoot: string): (input: string) => string {
+  return (input: string): string => {
+    if (path.isAbsolute(input)) return input;
+    const resolved = path.resolve(projectRoot, input);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative.startsWith("..")) {
+      throw new Error(`Path traversal blocked: ${input}`);
+    }
+    return resolved;
+  };
+}
+
+export function toRepoPolicyPath(projectRoot: string, filePath: string): string {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath);
+  const relativePath = path.relative(projectRoot, absolutePath);
+  if (relativePath.length === 0 || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return absolutePath;
+  }
+  return relativePath.split(path.sep).join("/");
+}

package/src/adapters/rotating-ndjson-log.ts

@@ -0,0 +1,66 @@
+import * as path from "node:path";
+import type { JsonCodec } from "../ports/codec.js";
+import type { FileSystem } from "../ports/filesystem.js";
+
+export interface RotatingNdjsonLogOptions {
+  readonly fs: FileSystem;
+  readonly codec: JsonCodec;
+  readonly logPath: string;
+  readonly maxBytes?: number;
+}
+
+const DEFAULT_MAX_BYTES = 1_048_576;
+
+export class RotatingNdjsonLog {
+  private readonly fs: FileSystem;
+  private readonly codec: JsonCodec;
+  private readonly logPath: string;
+  private readonly maxBytes: number;
+
+  constructor(options: RotatingNdjsonLogOptions) {
+    this.fs = options.fs;
+    this.codec = options.codec;
+    this.logPath = options.logPath;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  }
+
+  async append(entry: object): Promise<void> {
+    const line = this.codec.encode(entry) + "\n";
+    const dir = path.dirname(this.logPath);
+    await this.fs.mkdir(dir, { recursive: true });
+    await this.fs.appendFile(this.logPath, line, "utf-8");
+    await this.rotateIfNeeded();
+  }
+
+  private async rotateIfNeeded(): Promise<void> {
+    let stat: { size: number };
+    try {
+      stat = await this.fs.stat(this.logPath);
+    } catch {
+      return;
+    }
+
+    if (stat.size <= this.maxBytes) {
+      return;
+    }
+
+    const content = await this.fs.readFile(this.logPath, "utf-8");
+    const lines = content.trimEnd().split("\n");
+    let kept = lines.slice(Math.ceil(lines.length / 2));
+
+    // If slicing left nothing (e.g. a single oversized entry), skip rotation —
+    // the file is already at minimum size (one entry).
+    if (kept.length === 0) {
+      return;
+    }
+
+    let result = kept.join("\n") + "\n";
+
+    while (Buffer.byteLength(result, "utf-8") > this.maxBytes && kept.length > 1) {
+      kept = kept.slice(Math.ceil(kept.length / 2));
+      result = kept.join("\n") + "\n";
+    }
+
+    await this.fs.writeFile(this.logPath, result, "utf-8");
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,107 @@
+import { startDaemonServer } from "../mcp/daemon-server.js";
+import { MCP_TOOL_NAMES } from "../contracts/capabilities.js";
+import { createGraftServer } from "../mcp/server.js";
+import { startStdioServer } from "../mcp/stdio-server.js";
+import { ObservationCache } from "../operations/observation-cache.js";
+import { RepoWorkspace } from "../operations/repo-workspace.js";
+import { StructuredBuffer } from "../operations/structured-buffer.js";
+import type { BufferRange, WarmProjectionBasis, WarmProjectionBundleResult } from "../operations/structured-buffer.js";
+import { GRAFT_VERSION } from "../version.js";
+export { createRepoLocalGraft, type CreateRepoLocalGraftOptions } from "./repo-local-graft.js";
+export { createRepoWorkspace, type CreateRepoWorkspaceOptions } from "./repo-workspace.js";
+export { callGraftTool, parseGraftToolPayload } from "./tool-bridge.js";
+
+export interface CreateStructuredBufferOptions {
+  readonly basis?: WarmProjectionBasis | undefined;
+}
+
+export interface CreateProjectionBundleOptions extends CreateStructuredBufferOptions {
+  readonly viewport?: BufferRange | undefined;
+}
+
+export function createStructuredBuffer(
+  path: string,
+  content: string,
+  options: CreateStructuredBufferOptions = {},
+): StructuredBuffer {
+  return new StructuredBuffer({ path, content, basis: options.basis });
+}
+
+export function createProjectionBundle(
+  path: string,
+  content: string,
+  options: CreateProjectionBundleOptions = {},
+): WarmProjectionBundleResult {
+  const buffer = new StructuredBuffer({ path, content, basis: options.basis });
+  try {
+    return buffer.projectionBundle({ viewport: options.viewport });
+  } finally {
+    buffer.dispose();
+  }
+}
+
+export {
+  GRAFT_VERSION,
+  MCP_TOOL_NAMES,
+  ObservationCache,
+  RepoWorkspace,
+  StructuredBuffer,
+  createGraftServer,
+  startDaemonServer,
+  startStdioServer,
+};
+
+export type {
+  AnchorAffinityResult,
+  BufferDiagnostic,
+  BufferOutlineResult,
+  BufferPoint,
+  BufferRange,
+  BufferSelection,
+  ChangedRegion,
+  DiagnosticsResult,
+  FoldRegion,
+  FoldRegionsResult,
+  InjectionRegion,
+  InjectionResult,
+  NodeLookupResult,
+  NodeSummary,
+  RenameEditPreview,
+  RenamePreviewResult,
+  SelectionStepResult,
+  SemanticSummaryKind,
+  SemanticSummaryResult,
+  StructuredBufferDiffResult,
+  SymbolOccurrence,
+  SymbolOccurrencesResult,
+  SyntaxClass,
+  SyntaxSpan,
+  SyntaxSpanResult,
+  WarmProjectionBundleResult,
+  WarmProjectionParseStatus,
+  WarmProjectionBasis,
+} from "../operations/structured-buffer.js";
+
+export type {
+  StartDaemonServerOptions,
+} from "../mcp/daemon-server.js";
+
+export type {
+  CreateGraftServerOptions,
+  GraftServer,
+  McpToolResult,
+} from "../mcp/server.js";
+
+export type {
+  McpToolName,
+} from "../contracts/capabilities.js";
+
+export type {
+  RepoWorkspaceChangedSinceResult,
+  RepoWorkspaceFileOutlineResult,
+  RepoWorkspaceReadRangeResult,
+  RepoWorkspaceRefusedResult,
+  RepoWorkspaceSafeReadCacheHitResult,
+  RepoWorkspaceSafeReadDiffResult,
+  RepoWorkspaceSafeReadResult,
+} from "../operations/repo-workspace.js";

package/src/api/repo-local-graft.ts

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+import {
+  createGraftServer,
+  type CreateGraftServerOptions,
+  type GraftServer,
+} from "../mcp/server.js";
+
+export interface CreateRepoLocalGraftOptions extends Omit<CreateGraftServerOptions, "mode" | "projectRoot" | "graftDir"> {
+  readonly cwd?: string | undefined;
+  readonly graftDir?: string | undefined;
+}
+
+export function createRepoLocalGraft(options: CreateRepoLocalGraftOptions = {}): GraftServer {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  return createGraftServer({
+    ...options,
+    mode: "repo_local",
+    projectRoot: cwd,
+    graftDir: options.graftDir ?? path.join(cwd, ".graft"),
+  });
+}