@flyingrobots/graft 0.6.0 → 0.7.0

package/dist/warp/stale-docs.js

@@ -0,0 +1,149 @@
+/**
+ * Stale Docs Checker — cross-references doc symbol mentions against
+ * the WARP graph to detect documentation that may be outdated.
+ *
+ * Walks markdown for backtick-quoted identifiers and code block
+ * contents. For each referenced symbol, queries the WARP graph to
+ * determine whether the symbol changed after the doc was last modified.
+ *
+ * Also detects version number drift between package.json and CHANGELOG.
+ */
+import { symbolTimeline } from "./symbol-timeline.js";
+import { observeGraph } from "./context.js";
+// ---------------------------------------------------------------------------
+// Symbol extraction
+// ---------------------------------------------------------------------------
+/** Match single-backtick content that looks like an identifier (no spaces, no dots). */
+const INLINE_CODE_RE = /`([A-Za-z_$][A-Za-z0-9_$]*)`/g;
+/**
+ * Match identifiers inside fenced code blocks.
+ * We look for function/class/const/let/var/type/interface/import declarations
+ * and bare identifiers that look like symbol names.
+ */
+const CODE_BLOCK_RE = /```[\s\S]*?```/g;
+/**
+ * Inside code blocks, match identifiers from destructured imports/exports
+ * and direct declarations.
+ */
+const CODE_BLOCK_DECL_RE = /(?:import|export|function|class|const|let|var|type|interface)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+/**
+ * Match identifiers inside braces of import/export destructuring.
+ * e.g. import { evaluatePolicy, runCheck } from '...'
+ */
+const DESTRUCTURE_RE = /(?:import|export)\s+\{([^}]+)\}/g;
+const DESTRUCTURE_IDENT_RE = /([A-Za-z_$][A-Za-z0-9_$]*)/g;
+/**
+ * Extract symbol name references from markdown content.
+ *
+ * Sources:
+ * 1. Backtick-quoted identifiers (single backtick, must be valid JS/TS identifier)
+ * 2. Declaration identifiers inside fenced code blocks
+ *
+ * Returns a deduplicated array of symbol names.
+ */
+export function extractDocSymbolReferences(markdown) {
+    const symbols = new Set();
+    // 1. Inline backtick identifiers
+    let match;
+    while ((match = INLINE_CODE_RE.exec(markdown)) !== null) {
+        if (match[1] !== undefined)
+            symbols.add(match[1]);
+    }
+    // 2. Identifiers inside fenced code blocks
+    for (const blockMatch of markdown.matchAll(CODE_BLOCK_RE)) {
+        const block = blockMatch[0];
+        // Direct declarations: function foo, class Bar, etc.
+        while ((match = CODE_BLOCK_DECL_RE.exec(block)) !== null) {
+            if (match[1] !== undefined)
+                symbols.add(match[1]);
+        }
+        // Destructured imports/exports: import { foo, bar } from ...
+        for (const destructMatch of block.matchAll(DESTRUCTURE_RE)) {
+            const inner = destructMatch[1];
+            if (inner === undefined)
+                continue;
+            let identMatch;
+            while ((identMatch = DESTRUCTURE_IDENT_RE.exec(inner)) !== null) {
+                // Skip "as" keyword in "foo as bar" patterns — keep both identifiers
+                const identifier = identMatch[1];
+                if (identifier !== undefined && identifier !== "as") {
+                    symbols.add(identifier);
+                }
+            }
+        }
+    }
+    return [...symbols];
+}
+// ---------------------------------------------------------------------------
+// Stale doc check
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the tick (lamport clock) for a given commit SHA.
+ * Returns null if the commit is not in the graph.
+ */
+async function getCommitTick(ctx, sha) {
+    const obs = await observeGraph(ctx, { match: "commit:*", expose: ["sha", "tick"] });
+    const props = await obs.getNodeProps(`commit:${sha}`);
+    return typeof props?.["tick"] === "number" ? props["tick"] : null;
+}
+/**
+ * Check a markdown document for stale symbol references.
+ *
+ * @param ctx - WARP context
+ * @param docPath - relative path of the doc (for the report)
+ * @param docCommitSha - SHA of the commit when the doc was last modified
+ * @param docContent - raw markdown content of the doc
+ */
+export async function checkStaleDocs(ctx, docPath, docCommitSha, docContent) {
+    const symbolNames = extractDocSymbolReferences(docContent);
+    const docTick = await getCommitTick(ctx, docCommitSha);
+    const staleSymbols = [];
+    const unknownSymbols = [];
+    for (const symbolName of symbolNames) {
+        const timeline = await symbolTimeline(ctx, symbolName);
+        if (timeline.versions.length === 0) {
+            unknownSymbols.push(symbolName);
+            continue;
+        }
+        // If we cannot resolve the doc commit tick, we cannot compare —
+        // treat the doc as fresh (conservative).
+        if (docTick === null)
+            continue;
+        // Check if any version has a tick after the doc's commit tick.
+        // symbolTimeline returns versions in tick order with accurate
+        // per-commit data (unlike commitsForSymbol which returns HEAD
+        // signature for all entries).
+        for (const version of timeline.versions) {
+            if (version.tick > docTick) {
+                if (version.changeKind === "changed" || version.changeKind === "removed") {
+                    staleSymbols.push({
+                        symbol: symbolName,
+                        changeKind: version.changeKind,
+                        lastChangeSha: version.sha,
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    return { docPath, staleSymbols, unknownSymbols };
+}
+// ---------------------------------------------------------------------------
+// Version drift check
+// ---------------------------------------------------------------------------
+/** Match the first semver-looking heading in a CHANGELOG. */
+const CHANGELOG_VERSION_RE = /^##\s+\[?v?(\d+\.\d+\.\d+(?:-[A-Za-z0-9.]+)?)\]?/m;
+/**
+ * Check whether the latest version in a CHANGELOG matches
+ * the version in package.json.
+ */
+export function checkVersionDrift(packageVersion, changelogContent) {
+    const match = CHANGELOG_VERSION_RE.exec(changelogContent);
+    const changelogVersion = match?.[1] ?? null;
+    return {
+        drifted: changelogVersion !== packageVersion,
+        packageVersion,
+        changelogVersion,
+    };
+}
+//# sourceMappingURL=stale-docs.js.map

package/dist/warp/stale-docs.js.map

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

package/dist/warp/structural-drift-detection.d.ts

@@ -0,0 +1,49 @@
+/** Result of checking a single drift rule. */
+export interface DriftResult {
+    readonly drifted: boolean;
+    readonly docPath: string;
+    readonly claim: string;
+    readonly expected: string;
+    readonly actual: string;
+}
+/** Options for numeric claim checking. */
+export interface NumericClaimOptions {
+    readonly docPath: string;
+    /** The text containing the numeric claim (e.g., "12 MCP tools"). */
+    readonly claim: string;
+    /** Regex with a capture group for the number. */
+    readonly pattern: RegExp;
+    /** The actual count from reality. */
+    readonly actual: number;
+}
+/**
+ * Check whether a numeric claim in a doc matches reality.
+ *
+ * Parses the claim text with the given pattern to extract the stated
+ * number, then compares against the actual count.
+ */
+export declare function checkNumericClaim(options: NumericClaimOptions): DriftResult;
+/** Result of checking a pattern prohibition. */
+export interface PatternProhibitionResult {
+    readonly drifted: boolean;
+    readonly docPath: string;
+    readonly rule: string;
+    readonly violations: readonly string[];
+}
+/** Options for pattern prohibition checking. */
+export interface PatternProhibitionOptions {
+    readonly docPath: string;
+    /** Human-readable description of the rule (e.g., "no getNodes calls in src/"). */
+    readonly rule: string;
+    /** Regex to search for in file contents. */
+    readonly pattern: RegExp;
+    /** Map of file path → content to check. */
+    readonly files: Readonly<Record<string, string>>;
+}
+/**
+ * Check whether a prohibited pattern appears in any of the given files.
+ *
+ * Returns the list of files that violate the prohibition.
+ */
+export declare function checkPatternProhibition(options: PatternProhibitionOptions): PatternProhibitionResult;
+//# sourceMappingURL=structural-drift-detection.d.ts.map

package/dist/warp/structural-drift-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-drift-detection.d.ts","sourceRoot":"","sources":["../../src/warp/structural-drift-detection.ts"],"names":[],"mappings":"AAIA,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,WAAW,CAsB3E;AAED,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAgB1B"}

package/dist/warp/structural-drift-detection.js

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// Structural Drift Detection — verify doc claims against reality
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a numeric claim in a doc matches reality.
+ *
+ * Parses the claim text with the given pattern to extract the stated
+ * number, then compares against the actual count.
+ */
+export function checkNumericClaim(options) {
+    const { docPath, claim, pattern, actual } = options;
+    const match = pattern.exec(claim);
+    if (match?.[1] === undefined) {
+        return {
+            drifted: true,
+            docPath,
+            claim,
+            expected: "no match",
+            actual: String(actual),
+        };
+    }
+    const stated = parseInt(match[1], 10);
+    return {
+        drifted: stated !== actual,
+        docPath,
+        claim,
+        expected: match[1],
+        actual: String(actual),
+    };
+}
+/**
+ * Check whether a prohibited pattern appears in any of the given files.
+ *
+ * Returns the list of files that violate the prohibition.
+ */
+export function checkPatternProhibition(options) {
+    const { docPath, rule, pattern, files } = options;
+    const violations = [];
+    for (const [filePath, content] of Object.entries(files)) {
+        if (pattern.test(content)) {
+            violations.push(filePath);
+        }
+    }
+    return {
+        drifted: violations.length > 0,
+        docPath,
+        rule,
+        violations,
+    };
+}
+//# sourceMappingURL=structural-drift-detection.js.map

package/dist/warp/structural-drift-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-drift-detection.js","sourceRoot":"","sources":["../../src/warp/structural-drift-detection.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAsB9E;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACpD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAElC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO;YACP,KAAK;YACL,QAAQ,EAAE,UAAU;YACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;SACvB,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtC,OAAO;QACL,OAAO,EAAE,MAAM,KAAK,MAAM;QAC1B,OAAO;QACP,KAAK;QACL,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;KACvB,CAAC;AACJ,CAAC;AAqBD;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAkC;IAElC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC;QAC9B,OAAO;QACP,IAAI;QACJ,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/warp/structural-queries.d.ts

@@ -0,0 +1,49 @@
+/**
+ * WARP Structural Query Helpers — commit-symbol traversals.
+ *
+ * Shared infrastructure for graft log, graft blame, and graft churn.
+ * Uses traverse for edge-following and QueryBuilder for pattern matching
+ * and batch prop reads. No getEdges() — filtering stays substrate-side.
+ */
+import type { WarpContext } from "./context.js";
+/** A symbol that was added, removed, or changed in a commit. */
+export interface SymbolChange {
+    readonly name: string;
+    readonly kind: string;
+    readonly signature?: string | undefined;
+    readonly exported: boolean;
+    readonly filePath: string;
+}
+/** All symbol changes for a single commit. */
+export interface CommitSymbols {
+    readonly sha: string;
+    readonly added: readonly SymbolChange[];
+    readonly removed: readonly SymbolChange[];
+    readonly changed: readonly SymbolChange[];
+}
+/** The kind of change a commit made to a symbol. */
+export type ChangeKind = "added" | "removed" | "changed";
+/** A single commit entry in a symbol's history. */
+export interface SymbolCommit {
+    readonly sha: string;
+    readonly changeKind: ChangeKind;
+    readonly signature?: string | undefined;
+}
+/** Full change history for a symbol across commits. */
+export interface SymbolHistory {
+    readonly symbol: string;
+    readonly filePath?: string | undefined;
+    readonly commits: readonly SymbolCommit[];
+}
+/**
+ * Given a commit SHA, return all symbols that were added, removed,
+ * or changed in that commit.
+ *
+ * Uses traverse for edge-following (substrate-side), then QueryBuilder
+ * for batch prop reads. Removals are detected by temporal diff at
+ * tick N-1 vs tick N.
+ */
+export declare function symbolsForCommit(ctx: WarpContext, commitSha: string): Promise<CommitSymbols>;
+/** @deprecated Use symbolTimeline() from ./symbol-timeline.ts instead. */
+export declare function commitsForSymbol(ctx: WarpContext, symbolName: string, filePath?: string): Promise<SymbolHistory>;
+//# sourceMappingURL=structural-queries.d.ts.map

package/dist/warp/structural-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-queries.d.ts","sourceRoot":"","sources":["../../src/warp/structural-queries.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAQhD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzD,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AA8BD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CA+DxB;AAwFD,0EAA0E;AAC1E,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAWxB"}

package/dist/warp/structural-queries.js

@@ -0,0 +1,175 @@
+/**
+ * WARP Structural Query Helpers — commit-symbol traversals.
+ *
+ * Shared infrastructure for graft log, graft blame, and graft churn.
+ * Uses traverse for edge-following and QueryBuilder for pattern matching
+ * and batch prop reads. No getEdges() — filtering stays substrate-side.
+ */
+import { observeGraph } from "./context.js";
+import { symbolTimeline } from "./symbol-timeline.js";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Lens that spans both commit and symbol nodes so the observer
+ * can see the edges between them.
+ */
+function commitSymbolLens() {
+    return {
+        match: ["commit:*", "sym:*"],
+        expose: ["sha", "name", "kind", "signature", "exported"],
+    };
+}
+function filePathFromSymId(symId) {
+    const withoutPrefix = symId.slice("sym:".length);
+    const lastColon = withoutPrefix.lastIndexOf(":");
+    if (lastColon === -1) {
+        return withoutPrefix;
+    }
+    return withoutPrefix.slice(0, lastColon);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Given a commit SHA, return all symbols that were added, removed,
+ * or changed in that commit.
+ *
+ * Uses traverse for edge-following (substrate-side), then QueryBuilder
+ * for batch prop reads. Removals are detected by temporal diff at
+ * tick N-1 vs tick N.
+ */
+export async function symbolsForCommit(ctx, commitSha) {
+    const commitId = `commit:${commitSha}`;
+    // Read the commit's tick for removal detection.
+    const commitObs = await observeGraph(ctx, { match: commitId, expose: ["tick"] });
+    const commitProps = await commitObs.getNodeProps(commitId);
+    const tick = typeof commitProps?.["tick"] === "number" ? commitProps["tick"] : null;
+    // Observer scoped to commit + symbol nodes.
+    const obs = await observeGraph(ctx, commitSymbolLens());
+    // Check if the commit node exists before traversing.
+    const commitExists = await obs.hasNode(commitId);
+    if (!commitExists) {
+        return { sha: commitSha, added: [], removed: [], changed: [] };
+    }
+    // Traverse: follow outgoing edges from this commit by label.
+    const [addedIds, changedIds] = await Promise.all([
+        obs.traverse.bfs(commitId, { dir: "out", labelFilter: "adds", maxDepth: 1 }),
+        obs.traverse.bfs(commitId, { dir: "out", labelFilter: "changes", maxDepth: 1 }),
+    ]);
+    // Batch prop read for discovered sym nodes.
+    const allSymIds = [...addedIds, ...changedIds].filter((id) => id.startsWith("sym:"));
+    const symPropsMap = new Map();
+    if (allSymIds.length > 0) {
+        const propsResult = await obs.query()
+            .match(allSymIds)
+            .select(["id", "props"])
+            .run();
+        for (const node of propsResult.nodes) {
+            if (node.id !== undefined && node.props !== undefined) {
+                symPropsMap.set(node.id, node.props);
+            }
+        }
+    }
+    function toSymbolChange(symId) {
+        const props = symPropsMap.get(symId) ?? {};
+        const name = typeof props["name"] === "string" ? props["name"] : symId;
+        const kind = typeof props["kind"] === "string" ? props["kind"] : "unknown";
+        const signature = typeof props["signature"] === "string" ? props["signature"] : undefined;
+        const exported = typeof props["exported"] === "boolean" ? props["exported"] : false;
+        const filePath = filePathFromSymId(symId);
+        return { name, kind, signature, exported, filePath };
+    }
+    const added = addedIds.filter((id) => id.startsWith("sym:")).map(toSymbolChange);
+    const changed = changedIds.filter((id) => id.startsWith("sym:")).map(toSymbolChange);
+    // Detect removals by temporal receipts across the Git commit's indexed
+    // Lamport window. Lazy indexing can write one WARP patch per file, so one
+    // Git commit may span multiple Lamport ticks.
+    let removed = [];
+    if (tick !== null) {
+        removed = await detectRemovals(ctx, await previousCommitTick(ctx, commitSha, tick), tick);
+    }
+    return { sha: commitSha, added, removed, changed };
+}
+async function previousCommitTick(ctx, commitSha, tick) {
+    const obs = await observeGraph(ctx, { match: "commit:*", expose: ["sha", "tick"] });
+    const nodeIds = await obs.getNodes();
+    let previous = 0;
+    for (const nodeId of nodeIds) {
+        const props = await obs.getNodeProps(nodeId);
+        const sha = typeof props?.["sha"] === "string"
+            ? props["sha"]
+            : nodeId.slice("commit:".length);
+        if (sha === commitSha)
+            continue;
+        const candidate = typeof props?.["tick"] === "number" ? props["tick"] : null;
+        if (candidate !== null && candidate < tick && candidate > previous) {
+            previous = candidate;
+        }
+    }
+    return previous;
+}
+/**
+ * Detect symbol removals via tick receipts.
+ *
+ * Instead of scanning all sym:* nodes at two ceilings (which assumes
+ * the full graph fits in memory), we materialize with receipts and inspect
+ * receipts in one Git commit's indexed Lamport window for NodeTombstone ops
+ * on sym nodes. O(ops in indexed file patches), not O(all sym nodes).
+ */
+async function detectRemovals(ctx, previousTick, tick) {
+    // Use latest materialization and filter receipts locally. A ceiling
+    // materialization on the shared core would leave the app cached at an old
+    // tick, corrupting later live reads in the same operation.
+    const { receipts } = await ctx.app.core().materialize({ receipts: true });
+    const scopedReceipts = receipts.filter((receipt) => receipt.lamport > previousTick && receipt.lamport <= tick);
+    if (scopedReceipts.length === 0)
+        return [];
+    // Tombstoned sym nodes = removals.
+    const removed = new Map();
+    for (const receipt of scopedReceipts) {
+        for (const op of receipt.ops) {
+            if (op.op === "NodeTombstone" && op.target.startsWith("sym:") && op.result === "applied") {
+                removed.set(op.target, receipt.lamport);
+            }
+        }
+    }
+    if (removed.size === 0)
+        return [];
+    // Read props from the pre-removal observer (nodes are gone at current tick).
+    const symLens = {
+        match: "sym:*",
+        expose: ["name", "kind", "signature", "exported"],
+    };
+    // Targeted per-node reads — bounded by removals in one commit.
+    const changes = [];
+    for (const [id, removalTick] of removed) {
+        const beforeObs = await observeGraph(ctx, symLens, {
+            source: { kind: "live", ceiling: removalTick - 1 },
+        });
+        const props = await beforeObs.getNodeProps(id);
+        if (props === null)
+            continue;
+        const name = typeof props["name"] === "string" ? props["name"] : id;
+        const kind = typeof props["kind"] === "string" ? props["kind"] : "unknown";
+        const signature = typeof props["signature"] === "string" ? props["signature"] : undefined;
+        const exported = typeof props["exported"] === "boolean" ? props["exported"] : false;
+        const filePath = filePathFromSymId(id);
+        changes.push({ name, kind, signature, exported, filePath });
+    }
+    return changes;
+}
+/** @deprecated Use symbolTimeline() from ./symbol-timeline.ts instead. */
+export async function commitsForSymbol(ctx, symbolName, filePath) {
+    const timeline = await symbolTimeline(ctx, symbolName, filePath);
+    return {
+        symbol: symbolName,
+        filePath,
+        commits: timeline.versions.map((version) => ({
+            sha: version.sha,
+            changeKind: version.changeKind,
+            signature: version.signature,
+        })),
+    };
+}
+//# sourceMappingURL=structural-queries.js.map

package/dist/warp/structural-queries.js.map

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

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

@@ -0,0 +1,34 @@
+/**
+ * WARP Symbol Timeline — ordered history of a symbol across commits.
+ *
+ * Reads WARP provenance for symbol ids and reconstructs versions from
+ * patches that touched the symbol. Callers that need removed-symbol
+ * history must pass filePath so the symbol id is explicit.
+ */
+import { type WarpContext } from "./context.js";
+/** A single version of a symbol at a specific commit. */
+export interface SymbolVersion {
+    readonly sha: string;
+    readonly tick: number;
+    readonly changeKind: "added" | "changed" | "removed";
+    readonly present: boolean;
+    readonly signature?: string | undefined;
+    readonly startLine?: number | undefined;
+    readonly endLine?: number | undefined;
+    readonly filePath: string;
+}
+/** Full ordered timeline for a symbol across commits. */
+export interface SymbolTimelineResult {
+    readonly symbol: string;
+    readonly filePath?: string | undefined;
+    readonly versions: readonly SymbolVersion[];
+}
+/**
+ * Build an ordered timeline of every version of a symbol across commits.
+ *
+ * For each commit that touched the symbol (adds, changes, removes), the
+ * returned array includes the commit SHA, tick, change kind, presence
+ * flag, signature, and line range. Entries are sorted by tick ascending.
+ */
+export declare function symbolTimeline(ctx: WarpContext, symbolName: string, filePath?: string): Promise<SymbolTimelineResult>;
+//# sourceMappingURL=symbol-timeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-timeline.d.ts","sourceRoot":"","sources":["../../src/warp/symbol-timeline.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAM9D,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AA+JD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAM/B"}