@flyingrobots/graft 0.4.0 → 0.6.0

package/dist/operations/cached-file.d.ts

@@ -0,0 +1,24 @@
+import type { SupportedStructuredFormat } from "../parser/lang.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.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 declare class CachedFile {
+    /** @internal */
+    private readonly _brand;
+    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);
+}
+//# sourceMappingURL=cached-file.d.ts.map

package/dist/operations/cached-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-file.d.ts","sourceRoot":"","sources":["../../src/operations/cached-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGlE;;;;GAIG;AACH,qBAAa,UAAU;IACrB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,SAAS,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;gBAExD,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAgBjD"}

package/dist/operations/cached-file.js

@@ -0,0 +1,37 @@
+import { extractOutlineForFile } from "../parser/outline.js";
+import { detectStructuredFormat } from "../parser/lang.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 */
+    _brand = "CachedFile";
+    path;
+    rawContent;
+    hash;
+    lang;
+    supportsOutline;
+    outline;
+    jumpTable;
+    actual;
+    constructor(filePath, rawContent) {
+        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);
+    }
+}
+//# sourceMappingURL=cached-file.js.map

package/dist/operations/cached-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-file.js","sourceRoot":"","sources":["../../src/operations/cached-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACrB,gBAAgB;IACC,MAAM,GAAG,YAAqB,CAAC;IACvC,IAAI,CAAS;IACb,UAAU,CAAS;IACnB,IAAI,CAAS;IACb,IAAI,CAAmC;IACvC,eAAe,CAAU;IACzB,OAAO,CAA0B;IACjC,SAAS,CAAuB;IAChC,MAAM,CAAqD;IAEpE,YAAY,QAAgB,EAAE,UAAkB;QAC9C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG;YACZ,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM;YACpC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;SACrC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAC1C,MAAM,MAAM,GAAG,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;CACF"}

package/dist/operations/diff-identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { GraftDiffResult } 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 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 declare function enrichDiffWithIdentity(result: GraftDiffResult, resolve: IdentityResolver): Promise<GraftDiffResult>;
+//# sourceMappingURL=diff-identity.d.ts.map

package/dist/operations/diff-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-identity.d.ts","sourceRoot":"","sources":["../../src/operations/diff-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,iBAAiB,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AA2D1E;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CA+B1B"}

package/dist/operations/diff-identity.js

@@ -0,0 +1,93 @@
+/**
+ * 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";
+/**
+ * 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, identities) {
+    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, identities) {
+    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, resolve) {
+    const enrichedFiles = [];
+    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,
+    };
+}
+//# sourceMappingURL=diff-identity.js.map

package/dist/operations/diff-identity.js.map

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

package/dist/operations/file-outline.d.ts

@@ -0,0 +1,15 @@
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import type { FileSystem } from "../ports/filesystem.js";
+export interface FileOutlineResult {
+    path: string;
+    outline: OutlineEntry[];
+    jumpTable: JumpEntry[];
+    partial?: boolean | undefined;
+    cacheHit?: boolean | undefined;
+    reason?: "UNSUPPORTED_LANGUAGE" | undefined;
+    error?: string | undefined;
+}
+export declare function fileOutline(filePath: string, opts: {
+    fs: FileSystem;
+}): Promise<FileOutlineResult>;
+//# sourceMappingURL=file-outline.d.ts.map

package/dist/operations/file-outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-outline.d.ts","sourceRoot":"","sources":["../../src/operations/file-outline.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,EAAE,EAAE,UAAU,CAAA;CAAE,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA8B5B"}

package/dist/operations/file-outline.js

@@ -0,0 +1,32 @@
+import { extractOutlineForFile } from "../parser/outline.js";
+export async function fileOutline(filePath, opts) {
+    let content;
+    try {
+        content = await opts.fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return {
+            path: filePath,
+            outline: [],
+            jumpTable: [],
+            error: "File not found",
+        };
+    }
+    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,
+        outline: result.entries,
+        jumpTable: result.jumpTable ?? [],
+        ...(result.partial === true ? { partial: true } : {}),
+    };
+}
+//# sourceMappingURL=file-outline.js.map

package/dist/operations/file-outline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-outline.js","sourceRoot":"","sources":["../../src/operations/file-outline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAc7D,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,IAAwB;IAExB,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE;YACX,SAAS,EAAE,EAAE;YACb,KAAK,EAAE,gBAAgB;SACxB,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,qBAAqB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE;YACX,SAAS,EAAE,EAAE;YACb,MAAM,EAAE,sBAAsB;YAC9B,KAAK,EAAE,2DAA2D;SACnE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;QACjC,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/dist/operations/graft-diff.d.ts

@@ -0,0 +1,43 @@
+import type { FileSystem } from "../ports/filesystem.js";
+import type { GitClient } from "../ports/git.js";
+import { OutlineDiff } from "../parser/diff.js";
+export interface FileDiff {
+    path: string;
+    status: "modified" | "added" | "deleted";
+    summary: string;
+    diff: OutlineDiff;
+}
+export interface GraftDiffRefusal {
+    path: string;
+    reason: string;
+    reasonDetail: string;
+    next: readonly string[];
+    actual: {
+        lines: number;
+        bytes: number;
+    };
+}
+export interface GraftDiffResult {
+    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;
+}
+/**
+ * Compute structural diffs between two git refs (or working tree).
+ */
+export declare function graftDiff(opts: GraftDiffOptions): Promise<GraftDiffResult>;
+//# sourceMappingURL=graft-diff.d.ts.map

package/dist/operations/graft-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graft-diff.d.ts","sourceRoot":"","sources":["../../src/operations/graft-diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,EAAgB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAYD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,UAAU,CAAC;IACf,GAAG,EAAE,SAAS,CAAC;IACf,sBAAsB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,gBAAgB,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CACtH;AA4BD;;GAEG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkFhF"}

package/dist/operations/graft-diff.js

@@ -0,0 +1,115 @@
+import { getChangedFiles, getFileAtRef } from "../git/diff.js";
+import { detectLang } from "../parser/lang.js";
+import { extractOutline } from "../parser/outline.js";
+import { diffOutlines, OutlineDiff } from "../parser/diff.js";
+function buildSummary(filePath, status, diff) {
+    const parts = [];
+    if (diff.added.length > 0)
+        parts.push(`+${String(diff.added.length)} added`);
+    if (diff.removed.length > 0)
+        parts.push(`-${String(diff.removed.length)} removed`);
+    if (diff.changed.length > 0)
+        parts.push(`~${String(diff.changed.length)} changed`);
+    if (diff.unchangedCount > 0)
+        parts.push(`=${String(diff.unchangedCount)} unchanged`);
+    const stats = parts.length > 0 ? parts.join(", ") : "no structural changes";
+    return `${filePath} | ${status} | ${stats}`;
+}
+function emptyDiff() {
+    return new OutlineDiff({ added: [], removed: [], changed: [], unchangedCount: 0 });
+}
+function countLines(content) {
+    return content.split("\n").length;
+}
+function measureActual(baseContent, headContent) {
+    const byteLengths = [baseContent, headContent]
+        .filter((content) => content !== null)
+        .map((content) => Buffer.byteLength(content));
+    const lineCounts = [baseContent, headContent]
+        .filter((content) => 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 async function graftDiff(opts) {
+    const base = opts.base ?? "HEAD";
+    const headLabel = opts.head ?? "working tree";
+    const cwd = opts.cwd;
+    let changedFiles = await getChangedFiles({
+        cwd,
+        git: opts.git,
+        base,
+        head: opts.head,
+    });
+    // Filter by path if provided
+    if (opts.path !== undefined) {
+        changedFiles = changedFiles.filter((f) => f === opts.path);
+    }
+    const files = [];
+    const refused = [];
+    for (const filePath of changedFiles) {
+        // Get content at base (null = file absent at ref)
+        const baseContent = await getFileAtRef(base, filePath, { cwd, git: opts.git });
+        // Get content at head (null = file absent at ref/worktree)
+        let headContent;
+        if (opts.head !== undefined) {
+            headContent = await getFileAtRef(opts.head, filePath, { cwd, git: opts.git });
+        }
+        else {
+            try {
+                headContent = await opts.fs.readFile(opts.resolveWorkingTreePath(filePath), "utf-8");
+            }
+            catch {
+                headContent = null;
+            }
+        }
+        // Determine status
+        let status;
+        if (baseContent === null && headContent === null) {
+            // Both absent — file listed in diff but unreadable at both refs. Skip.
+            continue;
+        }
+        else if (baseContent === null) {
+            status = "added";
+        }
+        else if (headContent === null) {
+            status = "deleted";
+        }
+        else {
+            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();
+            files.push({ path: filePath, status, summary: buildSummary(filePath, status, empty), diff: empty });
+            continue;
+        }
+        const baseOutline = baseContent !== null
+            ? extractOutline(baseContent, lang).entries
+            : [];
+        const headOutline = headContent !== null
+            ? extractOutline(headContent, lang).entries
+            : [];
+        const diff = diffOutlines(baseOutline, headOutline);
+        files.push({ path: filePath, status, summary: buildSummary(filePath, status, diff), diff });
+    }
+    return {
+        base,
+        head: headLabel,
+        files,
+        ...(refused.length > 0 ? { refused } : {}),
+    };
+}
+//# sourceMappingURL=graft-diff.js.map

package/dist/operations/graft-diff.js.map

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

package/dist/operations/observation-cache.d.ts

@@ -0,0 +1,64 @@
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+export declare function hashContent(content: string): string;
+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 declare 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;
+    private _lastReadAt;
+    constructor(opts: {
+        contentHash: string;
+        outline: readonly OutlineEntry[];
+        jumpTable: readonly JumpEntry[];
+        actual: Readonly<{
+            lines: number;
+            bytes: number;
+        }>;
+        readCount: number;
+        firstReadAt: string;
+        lastReadAt: string;
+    });
+    get readCount(): number;
+    get lastReadAt(): string;
+    isStale(currentContentHash: string): boolean;
+    touch(): void;
+    snapshot(): ObservationSnapshot;
+    static fromSnapshot(snapshot: ObservationSnapshot): Observation;
+}
+export type CacheResult = {
+    hit: true;
+    obs: Observation;
+} | {
+    hit: false;
+    stale: Observation | null;
+};
+export declare class ObservationCache {
+    private readonly entries;
+    static fromSnapshots(snapshots: Readonly<Record<string, ObservationSnapshot>> | undefined): ObservationCache;
+    record(filePath: string, contentHash: string, outline: readonly OutlineEntry[], jumpTable: readonly JumpEntry[], actual: Readonly<{
+        lines: number;
+        bytes: number;
+    }>): void;
+    check(filePath: string, currentContent: string): CacheResult;
+    get(filePath: string): Observation | undefined;
+    snapshotEntry(filePath: string): ObservationSnapshot | null;
+    applySnapshot(filePath: string, snapshot: ObservationSnapshot | null): void;
+}
+//# sourceMappingURL=observation-cache.d.ts.map

package/dist/operations/observation-cache.d.ts.map

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

package/dist/operations/observation-cache.js

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Observation cache — tracks file content seen by the agent
+// ---------------------------------------------------------------------------
+export function hashContent(content) {
+    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 class Observation {
+    contentHash;
+    outline;
+    jumpTable;
+    actual;
+    firstReadAt;
+    _readCount;
+    _lastReadAt;
+    constructor(opts) {
+        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() {
+        return this._readCount;
+    }
+    get lastReadAt() {
+        return this._lastReadAt;
+    }
+    isStale(currentContentHash) {
+        return this.contentHash !== currentContentHash;
+    }
+    touch() {
+        this._readCount++;
+        this._lastReadAt = new Date().toISOString();
+    }
+    snapshot() {
+        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) {
+        return new Observation(snapshot);
+    }
+}
+export class ObservationCache {
+    entries = new Map();
+    static fromSnapshots(snapshots) {
+        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, contentHash, outline, jumpTable, actual) {
+        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, currentContent) {
+        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) {
+        return this.entries.get(filePath);
+    }
+    snapshotEntry(filePath) {
+        return this.entries.get(filePath)?.snapshot() ?? null;
+    }
+    applySnapshot(filePath, snapshot) {
+        if (snapshot === null) {
+            this.entries.delete(filePath);
+            return;
+        }
+        this.entries.set(filePath, Observation.fromSnapshot(snapshot));
+    }
+}
+//# sourceMappingURL=observation-cache.js.map

package/dist/operations/observation-cache.js.map

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

package/dist/operations/read-range.d.ts

@@ -0,0 +1,14 @@
+import type { FileSystem } from "../ports/filesystem.js";
+export interface ReadRangeResult {
+    path: string;
+    content?: string | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+    reason?: string | undefined;
+    truncated?: boolean | undefined;
+    clipped?: boolean | undefined;
+}
+export declare function readRange(filePath: string, start: number, end: number, opts: {
+    fs: FileSystem;
+}): Promise<ReadRangeResult>;
+//# sourceMappingURL=read-range.d.ts.map

package/dist/operations/read-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-range.d.ts","sourceRoot":"","sources":["../../src/operations/read-range.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAIzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,EAAE,EAAE,UAAU,CAAA;CAAE,GACvB,OAAO,CAAC,eAAe,CAAC,CA4C1B"}