@flyingrobots/graft 0.4.0 → 0.6.0

package/src/metrics/logger.ts

@@ -1,7 +1,7 @@
-import * as path from "node:path";
+import { RotatingNdjsonLog } from "../adapters/rotating-ndjson-log.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { JsonCodec } from "../ports/codec.js";
-import type { DecisionEntry } from "./types.js";
+import { DecisionEntry } from "./types.js";
 
 export interface MetricsLoggerOptions {
   readonly fs: FileSystem;
@@ -9,61 +9,32 @@ export interface MetricsLoggerOptions {
   readonly maxBytes?: number;
 }
 
-const DEFAULT_MAX_BYTES = 1_048_576; // 1 MB
-
 export class MetricsLogger {
-  private readonly logPath: string;
-  private readonly fs: FileSystem;
-  private readonly codec: JsonCodec;
-  private readonly maxBytes: number;
+  private readonly writer: RotatingNdjsonLog;
 
   constructor(logPath: string, options: MetricsLoggerOptions) {
-    this.logPath = logPath;
-    this.fs = options.fs;
-    this.codec = options.codec;
-    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const writerOptions = {
+      logPath,
+      fs: options.fs,
+      codec: options.codec,
+      ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
+    };
+    this.writer = new RotatingNdjsonLog(writerOptions);
   }
 
   async log(entry: Omit<DecisionEntry, "ts">): Promise<void> {
-    const full: DecisionEntry = {
+    const full = new DecisionEntry({
       ts: new Date().toISOString(),
-      ...entry,
-    };
-
-    const line = this.codec.encode(full) + "\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");
-
-    // Keep the most recent half of lines to get well under the limit
-    let kept = lines.slice(Math.ceil(lines.length / 2));
-    let result = kept.join("\n") + "\n";
-
-    // If still over, keep halving
-    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");
+      command: entry.command,
+      path: entry.path,
+      projection: entry.projection,
+      reason: entry.reason,
+      lines: entry.lines,
+      bytes: entry.bytes,
+      estimatedBytesAvoided: entry.estimatedBytesAvoided,
+      sessionDepth: entry.sessionDepth,
+      tripwire: entry.tripwire,
+    });
+    await this.writer.append(full);
   }
 }

package/src/metrics/types.ts

@@ -1,4 +1,8 @@
-export interface DecisionEntry {
+// ---------------------------------------------------------------------------
+// DecisionEntry — runtime-backed metric event for policy decisions
+// ---------------------------------------------------------------------------
+
+export class DecisionEntry {
   readonly ts: string;
   readonly command: string;
   readonly path: string;
@@ -6,7 +10,31 @@ export interface DecisionEntry {
   readonly reason: string;
   readonly lines: number;
   readonly bytes: number;
-  readonly estimatedBytesAvoided?: number;
-  readonly sessionDepth?: string;
-  readonly tripwire?: string | null;
+  readonly estimatedBytesAvoided?: number | undefined;
+  readonly sessionDepth?: string | undefined;
+  readonly tripwire?: string | null | undefined;
+
+  constructor(fields: {
+    readonly ts: string;
+    readonly command: string;
+    readonly path: string;
+    readonly projection: string;
+    readonly reason: string;
+    readonly lines: number;
+    readonly bytes: number;
+    readonly estimatedBytesAvoided?: number | undefined;
+    readonly sessionDepth?: string | undefined;
+    readonly tripwire?: string | null | undefined;
+  }) {
+    this.ts = fields.ts;
+    this.command = fields.command;
+    this.path = fields.path;
+    this.projection = fields.projection;
+    this.reason = fields.reason;
+    this.lines = fields.lines;
+    this.bytes = fields.bytes;
+    this.estimatedBytesAvoided = fields.estimatedBytesAvoided;
+    this.sessionDepth = fields.sessionDepth;
+    this.tripwire = fields.tripwire;
+  }
 }

package/src/operations/cached-file.ts

@@ -0,0 +1,40 @@
+import { extractOutlineForFile } from "../parser/outline.js";
+import { detectStructuredFormat } from "../parser/lang.js";
+import type { SupportedStructuredFormat } from "../parser/lang.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import { hashContent } from "./observation-cache.js";
+
+/**
+ * Immutable snapshot of a file read. Built once from a single read,
+ * shared by all consumers (cache, policy, outline extraction) to eliminate
+ * TOCTOU races where the file changes between reads.
+ */
+export class CachedFile {
+  /** @internal */
+  private readonly _brand = "CachedFile" as const;
+  readonly path: string;
+  readonly rawContent: string;
+  readonly hash: string;
+  readonly lang: SupportedStructuredFormat | null;
+  readonly supportsOutline: boolean;
+  readonly outline: readonly OutlineEntry[];
+  readonly jumpTable: readonly JumpEntry[];
+  readonly actual: { readonly lines: number; readonly bytes: number };
+
+  constructor(filePath: string, rawContent: string) {
+    this.path = filePath;
+    this.rawContent = rawContent;
+    this.hash = hashContent(rawContent);
+    this.actual = {
+      lines: rawContent.split("\n").length,
+      bytes: Buffer.byteLength(rawContent),
+    };
+    this.lang = detectStructuredFormat(filePath);
+    this.supportsOutline = this.lang !== null;
+    const result = extractOutlineForFile(filePath, rawContent);
+    this.outline = result?.entries ?? [];
+    this.jumpTable = result?.jumpTable ?? [];
+    Object.freeze(this.actual);
+    Object.freeze(this);
+  }
+}

package/src/operations/diff-identity.ts

@@ -0,0 +1,127 @@
+/**
+ * Identity enrichment for structural diffs.
+ *
+ * When WARP indexed truth is available, projects canonical symbol
+ * identity (`sid:*`) onto DiffEntry objects. Level 1 address truth
+ * (name, kind, signature) is preserved — identityId is additive.
+ *
+ * Symbols without indexed identity keep identityId undefined.
+ * This module never fabricates identity from heuristics.
+ */
+
+import { DiffEntry, OutlineDiff } from "../parser/diff.js";
+import type { GraftDiffResult, FileDiff } from "./graft-diff.js";
+
+/**
+ * Identity lookup: maps symbol name to identityId for a single file.
+ */
+export type IdentityMap = ReadonlyMap<string, string>;
+
+/**
+ * Resolves canonical symbol identities for a file path.
+ * Returns an empty map when the file has no indexed symbols.
+ */
+export type IdentityResolver = (filePath: string) => Promise<IdentityMap>;
+
+/**
+ * Enrich a single DiffEntry with identity from the WARP index.
+ * Returns a new DiffEntry with identityId when found, or the
+ * original entry unchanged when no indexed identity exists.
+ */
+function enrichEntry(
+  entry: DiffEntry,
+  identities: IdentityMap,
+): DiffEntry {
+  const identityId = identities.get(entry.name);
+  const enrichedChildDiff = entry.childDiff !== undefined
+    ? enrichOutlineDiff(entry.childDiff, identities)
+    : undefined;
+
+  // No identity and no child enrichment needed — return original
+  if (identityId === undefined && enrichedChildDiff === undefined) {
+    return entry;
+  }
+
+  return new DiffEntry({
+    name: entry.name,
+    kind: entry.kind,
+    ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+    ...(entry.oldSignature !== undefined ? { oldSignature: entry.oldSignature } : {}),
+    ...(enrichedChildDiff !== undefined ? { childDiff: enrichedChildDiff } : entry.childDiff !== undefined ? { childDiff: entry.childDiff } : {}),
+    ...(identityId !== undefined ? { identityId } : {}),
+  });
+}
+
+/**
+ * Enrich all entries in an OutlineDiff with WARP identity.
+ * Returns undefined if no entries were actually enriched (saves allocation).
+ */
+function enrichOutlineDiff(
+  diff: OutlineDiff,
+  identities: IdentityMap,
+): OutlineDiff | undefined {
+  const enrichedAdded = diff.added.map((e) => enrichEntry(e, identities));
+  const enrichedRemoved = diff.removed.map((e) => enrichEntry(e, identities));
+  const enrichedChanged = diff.changed.map((e) => enrichEntry(e, identities));
+
+  const anyEnriched =
+    enrichedAdded.some((e, i) => e !== diff.added[i]) ||
+    enrichedRemoved.some((e, i) => e !== diff.removed[i]) ||
+    enrichedChanged.some((e, i) => e !== diff.changed[i]);
+
+  if (!anyEnriched) return undefined;
+
+  return new OutlineDiff({
+    added: [...enrichedAdded],
+    removed: [...enrichedRemoved],
+    changed: [...enrichedChanged],
+    continuity: [...diff.continuity],
+    unchangedCount: diff.unchangedCount,
+  });
+}
+
+/**
+ * Enrich a GraftDiffResult with canonical symbol identities.
+ *
+ * For each file in the diff, resolves symbol identities through the
+ * provided resolver and attaches them to matching DiffEntry objects.
+ * Files with no indexed symbols pass through unchanged.
+ *
+ * This function is safe to call even when the resolver has no data —
+ * it gracefully degrades to returning the original result.
+ */
+export async function enrichDiffWithIdentity(
+  result: GraftDiffResult,
+  resolve: IdentityResolver,
+): Promise<GraftDiffResult> {
+  const enrichedFiles: FileDiff[] = [];
+  let anyEnriched = false;
+
+  for (const file of result.files) {
+    const identities = await resolve(file.path);
+
+    if (identities.size === 0) {
+      enrichedFiles.push(file);
+      continue;
+    }
+
+    const enrichedDiff = enrichOutlineDiff(file.diff, identities);
+    if (enrichedDiff === undefined) {
+      enrichedFiles.push(file);
+      continue;
+    }
+
+    anyEnriched = true;
+    enrichedFiles.push({
+      ...file,
+      diff: enrichedDiff,
+    });
+  }
+
+  if (!anyEnriched) return result;
+
+  return {
+    ...result,
+    files: enrichedFiles,
+  };
+}

package/src/operations/file-outline.ts

@@ -1,13 +1,14 @@
-import { extractOutline } from "../parser/outline.js";
+import { extractOutlineForFile } from "../parser/outline.js";
 import type { OutlineEntry, JumpEntry } from "../parser/types.js";
 import type { FileSystem } from "../ports/filesystem.js";
 
 export interface FileOutlineResult {
-  [key: string]: unknown;
   path: string;
   outline: OutlineEntry[];
   jumpTable: JumpEntry[];
   partial?: boolean | undefined;
+  cacheHit?: boolean | undefined;
+  reason?: "UNSUPPORTED_LANGUAGE" | undefined;
   error?: string | undefined;
 }
 
@@ -27,7 +28,16 @@ export async function fileOutline(
     };
   }
 
-  const result = extractOutline(content);
+  const result = extractOutlineForFile(filePath, content);
+  if (result === null) {
+    return {
+      path: filePath,
+      outline: [],
+      jumpTable: [],
+      reason: "UNSUPPORTED_LANGUAGE",
+      error: "Unsupported file type: no parser-backed outline available",
+    };
+  }
 
   return {
     path: filePath,

package/src/operations/graft-diff.ts

@@ -1,5 +1,5 @@
-import * as path from "node:path";
 import type { FileSystem } from "../ports/filesystem.js";
+import type { GitClient } from "../ports/git.js";
 import { getChangedFiles, getFileAtRef } from "../git/diff.js";
 import { detectLang } from "../parser/lang.js";
 import { extractOutline } from "../parser/outline.js";
@@ -12,6 +12,14 @@ export interface FileDiff {
   diff: OutlineDiff;
 }
 
+export interface GraftDiffRefusal {
+  path: string;
+  reason: string;
+  reasonDetail: string;
+  next: readonly string[];
+  actual: { lines: number; bytes: number };
+}
+
 function buildSummary(filePath: string, status: string, diff: OutlineDiff): string {
   const parts: string[] = [];
   if (diff.added.length > 0) parts.push(`+${String(diff.added.length)} added`);
@@ -23,35 +31,60 @@ function buildSummary(filePath: string, status: string, diff: OutlineDiff): stri
 }
 
 export interface GraftDiffResult {
-  [key: string]: unknown;
   base: string;
   head: string;
   files: FileDiff[];
+  refused?: GraftDiffRefusal[] | undefined;
 }
 
 export interface GraftDiffOptions {
   cwd: string;
   fs: FileSystem;
+  git: GitClient;
+  resolveWorkingTreePath: (filePath: string) => string;
   base?: string | undefined;
   head?: string | undefined;
   path?: string | undefined;
+  refusalCheck?: ((filePath: string, actual: { lines: number; bytes: number }) => GraftDiffRefusal | null) | undefined;
 }
 
 function emptyDiff(): OutlineDiff {
   return new OutlineDiff({ added: [], removed: [], changed: [], unchangedCount: 0 });
 }
 
+function countLines(content: string): number {
+  return content.split("\n").length;
+}
+
+function measureActual(
+  baseContent: string | null,
+  headContent: string | null,
+): { lines: number; bytes: number } {
+  const byteLengths = [baseContent, headContent]
+    .filter((content): content is string => content !== null)
+    .map((content) => Buffer.byteLength(content));
+  const lineCounts = [baseContent, headContent]
+    .filter((content): content is string => content !== null)
+    .map((content) => countLines(content));
+
+  return {
+    bytes: byteLengths.length > 0 ? Math.max(...byteLengths) : 0,
+    lines: lineCounts.length > 0 ? Math.max(...lineCounts) : 0,
+  };
+}
+
 
 /**
  * Compute structural diffs between two git refs (or working tree).
  */
-export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
+export async function graftDiff(opts: GraftDiffOptions): Promise<GraftDiffResult> {
   const base = opts.base ?? "HEAD";
   const headLabel = opts.head ?? "working tree";
   const cwd = opts.cwd;
 
-  let changedFiles = getChangedFiles({
+  let changedFiles = await getChangedFiles({
     cwd,
+    git: opts.git,
     base,
     head: opts.head,
   });
@@ -62,21 +95,19 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
   }
 
   const files: FileDiff[] = [];
+  const refused: GraftDiffRefusal[] = [];
 
   for (const filePath of changedFiles) {
-    const lang = detectLang(filePath);
-
     // Get content at base (null = file absent at ref)
-    const baseContent = getFileAtRef(base, filePath, cwd);
+    const baseContent = await getFileAtRef(base, filePath, { cwd, git: opts.git });
 
     // Get content at head (null = file absent at ref/worktree)
     let headContent: string | null;
     if (opts.head !== undefined) {
-      headContent = getFileAtRef(opts.head, filePath, cwd);
+      headContent = await getFileAtRef(opts.head, filePath, { cwd, git: opts.git });
     } else {
-      const fullPath = path.join(cwd, filePath);
       try {
-        headContent = opts.fs.readFileSync(fullPath, "utf-8");
+        headContent = await opts.fs.readFile(opts.resolveWorkingTreePath(filePath), "utf-8");
       } catch {
         headContent = null;
       }
@@ -95,6 +126,15 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
       status = "modified";
     }
 
+    const actual = measureActual(baseContent, headContent);
+    const refusal = opts.refusalCheck?.(filePath, actual) ?? null;
+    if (refusal !== null) {
+      refused.push(refusal);
+      continue;
+    }
+
+    const lang = detectLang(filePath);
+
     // Compute structural diff (only for supported languages)
     if (lang === null) {
       const empty = emptyDiff();
@@ -113,5 +153,10 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
     files.push({ path: filePath, status, summary: buildSummary(filePath, status, diff), diff });
   }
 
-  return { base, head: headLabel, files };
+  return {
+    base,
+    head: headLabel,
+    files,
+    ...(refused.length > 0 ? { refused } : {}),
+  };
 }

package/src/operations/observation-cache.ts

@@ -0,0 +1,149 @@
+// ---------------------------------------------------------------------------
+// Observation cache — tracks file content seen by the agent
+// ---------------------------------------------------------------------------
+
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+
+export function hashContent(content: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < content.length; index++) {
+    hash ^= content.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export interface ObservationSnapshot {
+  readonly contentHash: string;
+  readonly outline: readonly OutlineEntry[];
+  readonly jumpTable: readonly JumpEntry[];
+  readonly actual: Readonly<{ lines: number; bytes: number }>;
+  readonly readCount: number;
+  readonly firstReadAt: string;
+  readonly lastReadAt: string;
+}
+
+export class Observation {
+  readonly contentHash: string;
+  readonly outline: readonly OutlineEntry[];
+  readonly jumpTable: readonly JumpEntry[];
+  readonly actual: Readonly<{ lines: number; bytes: number }>;
+  readonly firstReadAt: string;
+  private _readCount: number;
+  private _lastReadAt: string;
+
+  constructor(opts: {
+    contentHash: string;
+    outline: readonly OutlineEntry[];
+    jumpTable: readonly JumpEntry[];
+    actual: Readonly<{ lines: number; bytes: number }>;
+    readCount: number;
+    firstReadAt: string;
+    lastReadAt: string;
+  }) {
+    this.contentHash = opts.contentHash;
+    this.outline = opts.outline;
+    this.jumpTable = opts.jumpTable;
+    this.actual = opts.actual;
+    this._readCount = opts.readCount;
+    this.firstReadAt = opts.firstReadAt;
+    this._lastReadAt = opts.lastReadAt;
+  }
+
+  get readCount(): number {
+    return this._readCount;
+  }
+
+  get lastReadAt(): string {
+    return this._lastReadAt;
+  }
+
+  isStale(currentContentHash: string): boolean {
+    return this.contentHash !== currentContentHash;
+  }
+
+  touch(): void {
+    this._readCount++;
+    this._lastReadAt = new Date().toISOString();
+  }
+
+  snapshot(): ObservationSnapshot {
+    return {
+      contentHash: this.contentHash,
+      outline: this.outline,
+      jumpTable: this.jumpTable,
+      actual: this.actual,
+      readCount: this.readCount,
+      firstReadAt: this.firstReadAt,
+      lastReadAt: this.lastReadAt,
+    };
+  }
+
+  static fromSnapshot(snapshot: ObservationSnapshot): Observation {
+    return new Observation(snapshot);
+  }
+}
+
+export type CacheResult =
+  | { hit: true; obs: Observation }
+  | { hit: false; stale: Observation | null };
+
+export class ObservationCache {
+  private readonly entries = new Map<string, Observation>();
+
+  static fromSnapshots(
+    snapshots: Readonly<Record<string, ObservationSnapshot>> | undefined,
+  ): ObservationCache {
+    const cache = new ObservationCache();
+    if (snapshots === undefined) {
+      return cache;
+    }
+    for (const [filePath, snapshot] of Object.entries(snapshots)) {
+      cache.entries.set(filePath, Observation.fromSnapshot(snapshot));
+    }
+    return cache;
+  }
+
+  record(
+    filePath: string,
+    contentHash: string,
+    outline: readonly OutlineEntry[],
+    jumpTable: readonly JumpEntry[],
+    actual: Readonly<{ lines: number; bytes: number }>,
+  ): void {
+    const existing = this.entries.get(filePath);
+    const now = new Date().toISOString();
+    this.entries.set(filePath, new Observation({
+      contentHash,
+      outline,
+      jumpTable,
+      actual,
+      readCount: (existing?.readCount ?? 0) + 1,
+      firstReadAt: existing?.firstReadAt ?? now,
+      lastReadAt: now,
+    }));
+  }
+
+  check(filePath: string, currentContent: string): CacheResult {
+    const obs = this.entries.get(filePath);
+    if (obs === undefined) return { hit: false, stale: null };
+    if (!obs.isStale(hashContent(currentContent))) return { hit: true, obs };
+    return { hit: false, stale: obs };
+  }
+
+  get(filePath: string): Observation | undefined {
+    return this.entries.get(filePath);
+  }
+
+  snapshotEntry(filePath: string): ObservationSnapshot | null {
+    return this.entries.get(filePath)?.snapshot() ?? null;
+  }
+
+  applySnapshot(filePath: string, snapshot: ObservationSnapshot | null): void {
+    if (snapshot === null) {
+      this.entries.delete(filePath);
+      return;
+    }
+    this.entries.set(filePath, Observation.fromSnapshot(snapshot));
+  }
+}

package/src/operations/read-range.ts

@@ -3,7 +3,6 @@ import type { FileSystem } from "../ports/filesystem.js";
 const MAX_RANGE_LINES = 250;
 
 export interface ReadRangeResult {
-  [key: string]: unknown;
   path: string;
   content?: string | undefined;
   startLine?: number | undefined;