trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/context/price.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a saved token was actually worth, in dollars.
+ *
+ * `savings.ts` answers "how many input tokens did graft keep out of the
+ * context"; this answers "what does an input token cost here". The two are
+ * deliberately separate: the token count is arithmetic over file sizes and is
+ * true everywhere, while the price depends on which model the session ran and
+ * how much of its context was served from cache — facts only the host's
+ * transcript knows.
+ *
+ * Nothing here guesses. There is no default rate and no env override: a model
+ * we don't have a price for yields null, and the callers then render the token
+ * count alone rather than a dollar figure we made up. A wrong number on the
+ * statusline is worse than no number.
+ */
+/** List input price for a model id, or null when we don't know it — a model
+ * released after this table was written, or a host reporting something else
+ * entirely. Null propagates all the way to "render tokens only". */
+export declare function inputUsdPerMtok(model: unknown): number | null;
+/** One turn's input-token usage, as the host's transcript reports it. */
+export interface TurnUsage {
+    model: string;
+    /** Fresh tokens, billed at the list rate. */
+    input: number;
+    /** Written to the cache this turn — a 25% premium over list. */
+    cacheCreate: number;
+    /** Served from cache — a tenth of list, and usually the bulk of a long turn. */
+    cacheRead: number;
+}
+/** What this turn's input tokens cost, in micro-dollars, or null on a model we
+ * have no price for. */
+export declare function turnInputCostMicros(usage: TurnUsage): number | null;
+/** Every input token this turn was billed for, cached or not — the denominator
+ * of the blended rate. */
+export declare function turnInputTokens(usage: TurnUsage): number;
+/**
+ * Dollars saved, at the rate the session has actually been paying.
+ *
+ * `costMicros / tokensBilled` is the blended price of one input token here —
+ * model and cache-hit ratio already folded in — so this re-blends as the
+ * session goes rather than freezing turn one's rate. Returns null when nothing
+ * has been sampled yet (turn one, or a host whose hooks name no transcript).
+ */
+export declare function dollarsSaved(savedTokens: number, costMicros: number | undefined, tokensBilled: number | undefined): number | null;
+/** `$1.23`, or `<$0.01` for a real but sub-cent saving. Never `$0.00`: a
+ * rounded-to-nothing number reads as "graft saved you nothing", which is a
+ * different claim from "graft saved you less than a cent". */
+export declare function formatDollars(usd: number): string;
+//# sourceMappingURL=price.d.ts.map

package/dist/context/price.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../../src/context/price.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH;;oEAEoE;AACpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI7D;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD;wBACwB;AACxB,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAQnE;AAED;0BAC0B;AAC1B,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAMf;AAED;;8DAE8D;AAC9D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/context/price.js

@@ -0,0 +1,83 @@
+/**
+ * What a saved token was actually worth, in dollars.
+ *
+ * `savings.ts` answers "how many input tokens did graft keep out of the
+ * context"; this answers "what does an input token cost here". The two are
+ * deliberately separate: the token count is arithmetic over file sizes and is
+ * true everywhere, while the price depends on which model the session ran and
+ * how much of its context was served from cache — facts only the host's
+ * transcript knows.
+ *
+ * Nothing here guesses. There is no default rate and no env override: a model
+ * we don't have a price for yields null, and the callers then render the token
+ * count alone rather than a dollar figure we made up. A wrong number on the
+ * statusline is worse than no number.
+ */
+/** Input $/Mtok, list price, per model family. Output tokens are irrelevant —
+ * what graft saves is context the agent would otherwise have read IN. */
+const INPUT_USD_PER_MTOK = [
+    [/^claude-(fable|mythos)-5/, 10],
+    [/^claude-opus-(5|4-[678])/, 5],
+    [/^claude-sonnet-5/, 2],
+    [/^claude-sonnet-4-6/, 3],
+    [/^claude-haiku-4-5/, 1],
+];
+/** List input price for a model id, or null when we don't know it — a model
+ * released after this table was written, or a host reporting something else
+ * entirely. Null propagates all the way to "render tokens only". */
+export function inputUsdPerMtok(model) {
+    if (typeof model !== 'string')
+        return null;
+    for (const [pattern, usd] of INPUT_USD_PER_MTOK)
+        if (pattern.test(model))
+            return usd;
+    return null;
+}
+/** Cache-write costs 1.25x list, a cache read a tenth of it. The multipliers are
+ * why a measured rate beats an assumed one: a session deep into a long
+ * conversation pays nearer $0.50/Mtok than the $5.00 its model lists at. */
+const CACHE_CREATE_MULTIPLIER = 1.25;
+const CACHE_READ_MULTIPLIER = 0.1;
+/** Micro-dollars, so a running total stays an integer and never drifts. */
+const MICROS_PER_USD = 1_000_000;
+/** What this turn's input tokens cost, in micro-dollars, or null on a model we
+ * have no price for. */
+export function turnInputCostMicros(usage) {
+    const list = inputUsdPerMtok(usage.model);
+    if (list === null)
+        return null;
+    const weighted = usage.input +
+        usage.cacheCreate * CACHE_CREATE_MULTIPLIER +
+        usage.cacheRead * CACHE_READ_MULTIPLIER;
+    return Math.round((weighted * list * MICROS_PER_USD) / 1_000_000);
+}
+/** Every input token this turn was billed for, cached or not — the denominator
+ * of the blended rate. */
+export function turnInputTokens(usage) {
+    return usage.input + usage.cacheCreate + usage.cacheRead;
+}
+/**
+ * Dollars saved, at the rate the session has actually been paying.
+ *
+ * `costMicros / tokensBilled` is the blended price of one input token here —
+ * model and cache-hit ratio already folded in — so this re-blends as the
+ * session goes rather than freezing turn one's rate. Returns null when nothing
+ * has been sampled yet (turn one, or a host whose hooks name no transcript).
+ */
+export function dollarsSaved(savedTokens, costMicros, tokensBilled) {
+    if (!costMicros || !tokensBilled || savedTokens <= 0)
+        return null;
+    const usd = (savedTokens * (costMicros / tokensBilled)) / MICROS_PER_USD;
+    // Belt and braces against a non-finite accumulator reaching a rendered
+    // surface: "$NaN" on the statusline is worse than no dollar figure at all.
+    return Number.isFinite(usd) ? usd : null;
+}
+/** `$1.23`, or `<$0.01` for a real but sub-cent saving. Never `$0.00`: a
+ * rounded-to-nothing number reads as "graft saved you nothing", which is a
+ * different claim from "graft saved you less than a cent". */
+export function formatDollars(usd) {
+    if (usd < 0.01)
+        return '<$0.01';
+    return `$${usd.toFixed(2)}`;
+}
+//# sourceMappingURL=price.js.map

package/dist/context/price.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.js","sourceRoot":"","sources":["../../src/context/price.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;yEACyE;AACzE,MAAM,kBAAkB,GAA6C;IACnE,CAAC,0BAA0B,EAAE,EAAE,CAAC;IAChC,CAAC,0BAA0B,EAAE,CAAC,CAAC;IAC/B,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACvB,CAAC,oBAAoB,EAAE,CAAC,CAAC;IACzB,CAAC,mBAAmB,EAAE,CAAC,CAAC;CACzB,CAAC;AAEF;;oEAEoE;AACpE,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,kBAAkB;QAAE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;IACrF,OAAO,IAAI,CAAC;AACd,CAAC;AAaD;;4EAE4E;AAC5E,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,2EAA2E;AAC3E,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC;wBACwB;AACxB,MAAM,UAAU,mBAAmB,CAAC,KAAgB;IAClD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,QAAQ,GACZ,KAAK,CAAC,KAAK;QACX,KAAK,CAAC,WAAW,GAAG,uBAAuB;QAC3C,KAAK,CAAC,SAAS,GAAG,qBAAqB,CAAC;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,IAAI,GAAG,cAAc,CAAC,GAAG,SAAS,CAAC,CAAC;AACpE,CAAC;AAED;0BAC0B;AAC1B,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,OAAO,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,WAAmB,EACnB,UAA8B,EAC9B,YAAgC;IAEhC,IAAI,CAAC,UAAU,IAAI,CAAC,YAAY,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,GAAG,GAAG,CAAC,WAAW,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC,GAAG,cAAc,CAAC;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED;;8DAE8D;AAC9D,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,GAAG,GAAG,IAAI;QAAE,OAAO,QAAQ,CAAC;IAChC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9B,CAAC"}

package/dist/context/savings.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared "tokens saved" estimate for every retrieval-style graft command.
+ *
+ * The model is always the same: baseline (what you'd have read otherwise, in
+ * full) − this output (what graft handed you). The baseline is measured from
+ * the `chars` the build stored on each file node, so it costs nothing and is
+ * honest about the alternative — opening the files whole. When no file in the
+ * baseline has a known size (a pre-`chars` graph), the estimate is omitted
+ * rather than faked.
+ *
+ * `graft ask` keeps its own footer (it carries an escalation nudge and feeds
+ * the session saved-token counter); everything else — skeleton, grep, callers,
+ * map — routes through {@link savingsFor} + {@link withSavings} here.
+ */
+import type { GraphV1 } from '../graph/types.js';
+export interface Savings {
+    /** How many source files the baseline covers. */
+    files: number;
+    /** Total chars of those files — the "read them whole" cost. */
+    baselineChars: number;
+}
+/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
+export declare function toTokens(chars: number): number;
+/** Baseline = whole size of the distinct `paths`, summed from file-node sizes.
+ * Returns undefined when not a single path has a known size — the caller then
+ * omits the estimate instead of claiming a bogus one. */
+export declare function savingsFor(graph: GraphV1, paths: Iterable<string>): Savings | undefined;
+/** Tell this module what an input token costs here. Null clears it, and so does
+ * anything that isn't a positive finite number — a NaN from a zero-denominator
+ * rate must render as "no dollars known", never as `$NaN` in the agent's face. */
+export declare function setInputRate(usdPerMtok: number | null): void;
+/** Appended to every retrieval footer so the agent reports the turn's running
+ * total even when SKILL.md isn't loaded — the instruction rides along in the
+ * tool output itself. Deliberately free of the `[graft] tokens saved ≈ <n>`
+ * pattern so the PostToolUse accumulator that parses these footers never
+ * mistakes the nudge (or its example) for a second number to count.
+ *
+ * Carries this call's dollar value once a rate has been measured, because the
+ * agent has no way to price a token itself — the ask it's given has to contain
+ * the number, not just request one. The example phrasing stays inside what
+ * `hasSavingsTally` (claude/tally.ts) recognises, so adding money here does not
+ * quietly zero the reported-turns metric. */
+export declare function savingsTurnNudge(savedTokens: number): string;
+/** The one-line savings estimate for a command's text output, so the agent gets
+ * the number for free — no extra tool call. `body` is the exact rendered output
+ * the agent reads (the pack). Returns "" when there's nothing honest to claim:
+ * no baseline, or the output isn't actually smaller than reading the files
+ * (tiny files, where the pointers cost more than the source). */
+export declare function savingsLine(body: string, saved: Savings | undefined): string;
+/**
+ * Sum every `[graft] tokens saved ≈ N` footer in a blob of text — the reader
+ * half of {@link savingsLine}, kept next to the writer so the two never drift.
+ * A single blob can carry several (an agent that made two graft calls in one
+ * turn); the nudge from `savingsTurnNudge` deliberately omits the pattern, so its example
+ * text is not miscounted here.
+ */
+export declare function sumSavingsFooters(text: string): number;
+/** Render `body` with the savings line on TOP.
+ *
+ * Deliberately a header, not a footer: agents routinely pipe graft through
+ * `head -N` (and hosts truncate long tool output from the end), which silently
+ * ate the number and, with it, the PostToolUse accumulator that feeds the
+ * statusline's `~N tok saved`. Every clipper keeps the head, so the number
+ * survives. Emitted once — a second copy at the bottom would be double-counted
+ * by that accumulator's `matchAll`. */
+export declare function withSavings(body: string, saved: Savings | undefined): string;
+//# sourceMappingURL=savings.d.ts.map

package/dist/context/savings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"savings.d.ts","sourceRoot":"","sources":["../../src/context/savings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAIjD,MAAM,WAAW,OAAO;IACtB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAYD;;yDAEyD;AACzD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,GAAG,SAAS,CAWvF;AAgBD;;kFAEkF;AAClF,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAK5D;AAED;;;;;;;;;;6CAU6C;AAC7C,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgB5D;AAED;;;;iEAIiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAa5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;;;;;uCAOuC;AACvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAG5E"}

package/dist/context/savings.js

@@ -0,0 +1,125 @@
+import { formatDollars } from './price.js';
+import { brand, tag } from "../brand.js";
+/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
+export function toTokens(chars) {
+    return Math.round(chars / 4);
+}
+/** path → char size, from the file nodes the build sized. Skips nodes with no
+ * `chars` (pre-upgrade graphs), so an old index just yields a smaller baseline
+ * rather than a wrong one. */
+function fileSizes(graph) {
+    const m = new Map();
+    for (const n of graph.nodes)
+        if (n.kind === 'file' && typeof n.chars === 'number')
+            m.set(n.path, n.chars);
+    return m;
+}
+/** Baseline = whole size of the distinct `paths`, summed from file-node sizes.
+ * Returns undefined when not a single path has a known size — the caller then
+ * omits the estimate instead of claiming a bogus one. */
+export function savingsFor(graph, paths) {
+    const sizes = fileSizes(graph);
+    let baselineChars = 0;
+    let files = 0;
+    for (const p of new Set(paths)) {
+        const c = sizes.get(p);
+        if (c === undefined)
+            continue;
+        baselineChars += c;
+        files++;
+    }
+    return files > 0 ? { files, baselineChars } : undefined;
+}
+/**
+ * The blended input rate this session is paying, in $/Mtok, or null when nobody
+ * has measured one.
+ *
+ * Process-level because it is a process-level fact: one CLI invocation answers
+ * one query for one session, and the alternative — threading a rate through
+ * `withSavings` and all seven of its callers — would put a billing parameter in
+ * the signature of every retrieval formatter for no gain. Set by the CLI's
+ * `noteQuery` and by the MCP dispatch, both of which already resolve the repo
+ * root; unset everywhere else, which is why every consumer treats null as
+ * "report tokens only" rather than as zero.
+ */
+let inputRateUsdPerMtok = null;
+/** Tell this module what an input token costs here. Null clears it, and so does
+ * anything that isn't a positive finite number — a NaN from a zero-denominator
+ * rate must render as "no dollars known", never as `$NaN` in the agent's face. */
+export function setInputRate(usdPerMtok) {
+    inputRateUsdPerMtok =
+        typeof usdPerMtok === 'number' && Number.isFinite(usdPerMtok) && usdPerMtok > 0
+            ? usdPerMtok
+            : null;
+}
+/** Appended to every retrieval footer so the agent reports the turn's running
+ * total even when SKILL.md isn't loaded — the instruction rides along in the
+ * tool output itself. Deliberately free of the `[graft] tokens saved ≈ <n>`
+ * pattern so the PostToolUse accumulator that parses these footers never
+ * mistakes the nudge (or its example) for a second number to count.
+ *
+ * Carries this call's dollar value once a rate has been measured, because the
+ * agent has no way to price a token itself — the ask it's given has to contain
+ * the number, not just request one. The example phrasing stays inside what
+ * `hasSavingsTally` (claude/tally.ts) recognises, so adding money here does not
+ * quietly zero the reported-turns metric. */
+export function savingsTurnNudge(savedTokens) {
+    const b = brand();
+    const sum = ` — sum each such line across your ${b} calls — e.g. `;
+    if (inputRateUsdPerMtok === null || savedTokens <= 0) {
+        return (` At the end of your reply, tell the user the total ${b} tokens saved ` +
+            `this turn${sum}"🌱 ${b} saved ~N tokens this turn".`);
+    }
+    const usd = (savedTokens * inputRateUsdPerMtok) / 1_000_000;
+    return (` This call is worth ${formatDollars(usd)} at the rate this session is ` +
+        'actually paying for input tokens. At the end of your reply, tell the user ' +
+        `the total ${brand()} tokens saved this turn and what they were worth${sum}` +
+        `"🌱 ${brand()} saved ~N tokens (~$X) this turn".`);
+}
+/** The one-line savings estimate for a command's text output, so the agent gets
+ * the number for free — no extra tool call. `body` is the exact rendered output
+ * the agent reads (the pack). Returns "" when there's nothing honest to claim:
+ * no baseline, or the output isn't actually smaller than reading the files
+ * (tiny files, where the pointers cost more than the source). */
+export function savingsLine(body, saved) {
+    if (!saved || saved.baselineChars <= 0)
+        return '';
+    const pack = toTokens(body.length);
+    const base = toTokens(saved.baselineChars);
+    if (base <= pack)
+        return '';
+    const delta = base - pack;
+    const pct = Math.round((delta / base) * 100);
+    return (`${tag()} tokens saved ≈ ${delta.toLocaleString()} (${pct}%) — this output ≈ ` +
+        `${pack.toLocaleString()} tok vs reading the ${saved.files} file(s) it covers whole ≈ ` +
+        `${base.toLocaleString()} tok (estimate).` +
+        savingsTurnNudge(delta));
+}
+/**
+ * Sum every `[graft] tokens saved ≈ N` footer in a blob of text — the reader
+ * half of {@link savingsLine}, kept next to the writer so the two never drift.
+ * A single blob can carry several (an agent that made two graft calls in one
+ * turn); the nudge from `savingsTurnNudge` deliberately omits the pattern, so its example
+ * text is not miscounted here.
+ */
+export function sumSavingsFooters(text) {
+    let total = 0;
+    // The code a query saved reading, and the digging a reused learning saved.
+    for (const m of text.matchAll(/\[(?:graft|trail)\] (?:tokens|learnings) saved ≈ ([\d,]+)/g)) {
+        total += Number(m[1].replace(/,/g, '')) || 0;
+    }
+    return total;
+}
+/** Render `body` with the savings line on TOP.
+ *
+ * Deliberately a header, not a footer: agents routinely pipe graft through
+ * `head -N` (and hosts truncate long tool output from the end), which silently
+ * ate the number and, with it, the PostToolUse accumulator that feeds the
+ * statusline's `~N tok saved`. Every clipper keeps the head, so the number
+ * survives. Emitted once — a second copy at the bottom would be double-counted
+ * by that accumulator's `matchAll`. */
+export function withSavings(body, saved) {
+    const line = savingsLine(body, saved);
+    return line ? `${line}\n\n${body}` : body;
+}
+//# sourceMappingURL=savings.js.map

package/dist/context/savings.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The Context Graph Engine.
+ *
+ * Two operations, no database:
+ *   - {@link Graft.init}  build `.context/` from a code repo.
+ *   - {@link Graft.check} report whether `.context/` is still in
+ *     sync with the code (for CI).
+ *
+ * The graph is a folder of linked markdown files committed to the repo; git is
+ * the sync. This class wires the configured LLM provider into the build/check
+ * pipelines; an API key is required for any LLM-backed operation.
+ */
+import { type EngineConfig } from "./ai/providers.js";
+import { CODE_EXTENSIONS, type BuildProgress, type BuildResult } from "./context/build.js";
+import { type CheckResult } from "./context/check.js";
+import { type GraphBuildOptions, type GraphBuildResult } from "./graph/build.js";
+import { type GraphCheckResult } from "./graph/check.js";
+import { type AskResult } from "./ask/ask.js";
+export { CODE_EXTENSIONS };
+export type { BuildResult, BuildProgress, CheckResult, GraphBuildResult, GraphCheckResult, AskResult };
+export interface InitOptions {
+    /** Code extensions to include. Default: {@link CODE_EXTENSIONS}. */
+    extensions?: string[];
+    /** Repo-relative directory prefixes to limit the concept pass (`--only-dir`). */
+    onlyDirs?: string[];
+    /** Max concept synthesis batches in flight at once. Default 4. */
+    synthConcurrency?: number;
+    /** Progress callback for long builds. */
+    onProgress?: (info: BuildProgress) => void;
+}
+export interface CheckRunOptions {
+    extensions?: string[];
+}
+export interface GraphRunOptions {
+    /** Run the Tier-2 LLM meaning pass (summary + crux). Absent → Tier-1 only. */
+    llm?: boolean;
+    /** Max files summarized in parallel during the LLM pass. */
+    concurrency?: number;
+    /** Replay unchanged files from the extraction cache (default true). */
+    reuse?: boolean;
+    /** Opt-in compiler-grade LSP edge enrichment (`graft build --lsp`). */
+    lsp?: boolean;
+    /** Repo-relative directory prefixes to limit the build to (`--only-dir`). */
+    onlyDirs?: string[];
+    onProgress?: GraphBuildOptions["onProgress"];
+}
+export declare class Graft {
+    private cfg;
+    constructor(config?: EngineConfig);
+    /** Build the `.context/` graph from the repo at `dir`. */
+    init(dir: string, opts?: InitOptions): Promise<BuildResult>;
+    /** Report whether the committed `.context/` markdown graph is in sync with the code. */
+    check(dir: string, opts?: CheckRunOptions): CheckResult;
+    /** Report whether the committed `graph.json` is in sync with the code (Tier-1 diff).
+     * Async because the breadth tier warms WASM grammars before re-extraction. */
+    checkGraph(dir: string): Promise<GraphCheckResult>;
+    /**
+     * Build `.context/graph.json` — a per-symbol code graph from tree-sitter.
+     * Tier-1 (structure) always runs; the Tier-2 meaning layer runs only when
+     * `opts.llm` is set. Either way the prior meaning layer is preserved.
+     */
+    graph(dir: string, opts?: GraphRunOptions): Promise<GraphBuildResult>;
+    /**
+     * Answer a plain-words query from the committed `graft/` graph — the active
+     * channel. Deterministic and $0: routes structural queries to the wiring
+     * edges and everything else to a lexical rank over concepts + symbols.
+     */
+    ask(dir: string, query: string, opts?: {
+        limit?: number;
+        source?: boolean;
+        full?: boolean;
+        in?: string;
+        graphRank?: boolean;
+    }): AskResult;
+    private _chatModel?;
+    /** The configured transport, or a clear error telling the user how to set a key. */
+    private chatModel;
+    private synthesizer;
+    /** Per-node crux summarizer for the code graph's Tier-2 pass. */
+    private cruxSummarizer;
+    private summarizer;
+    /** Human label for the active model, recorded in the manifest. */
+    private modelLabel;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAiB,KAAK,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAM1F,OAAO,EAAgB,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAc,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAO,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;AAEvG,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;CAC9C;AAED,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAiB;gBAEhB,MAAM,GAAE,YAAiB;IAIrC,0DAA0D;IACpD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IAarE,wFAAwF;IACxF,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,WAAW;IAI3D;kFAC8E;IAC9E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIlD;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYzE;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,SAAS;IAY7I,OAAO,CAAC,UAAU,CAAC,CAAY;IAE/B,oFAAoF;IACpF,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,WAAW;IAInB,iEAAiE;IACjE,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,UAAU;IAIlB,kEAAkE;IAClE,OAAO,CAAC,UAAU;CAKnB"}

package/dist/engine.js

@@ -0,0 +1,122 @@
+/**
+ * The Context Graph Engine.
+ *
+ * Two operations, no database:
+ *   - {@link Graft.init}  build `.context/` from a code repo.
+ *   - {@link Graft.check} report whether `.context/` is still in
+ *     sync with the code (for CI).
+ *
+ * The graph is a folder of linked markdown files committed to the repo; git is
+ * the sync. This class wires the configured LLM provider into the build/check
+ * pipelines; an API key is required for any LLM-backed operation.
+ */
+import { resolveConfig } from "./ai/providers.js";
+import { ChatSynthesizer } from "./ai/synthesize.js";
+import { ChatSummarizer } from "./ai/summarize.js";
+import { ChatCruxSummarizer } from "./ai/crux.js";
+import { createChatModel } from "./ai/llm/factory.js";
+import { buildContext, CODE_EXTENSIONS } from "./context/build.js";
+import { checkContext } from "./context/check.js";
+import { buildGraph } from "./graph/build.js";
+import { checkGraph } from "./graph/check.js";
+import { ask } from "./ask/ask.js";
+export { CODE_EXTENSIONS };
+export class Graft {
+    cfg;
+    constructor(config = {}) {
+        this.cfg = resolveConfig(config);
+    }
+    /** Build the `.context/` graph from the repo at `dir`. */
+    async init(dir, opts = {}) {
+        return buildContext(dir, {
+            contextDir: this.cfg.contextDir,
+            extensions: opts.extensions,
+            onlyDirs: opts.onlyDirs,
+            synthConcurrency: opts.synthConcurrency,
+            model: this.modelLabel(),
+            summarizer: this.summarizer(),
+            synthesizer: this.synthesizer(),
+            onProgress: opts.onProgress,
+        });
+    }
+    /** Report whether the committed `.context/` markdown graph is in sync with the code. */
+    check(dir, opts = {}) {
+        return checkContext(dir, { contextDir: this.cfg.contextDir, extensions: opts.extensions });
+    }
+    /** Report whether the committed `graph.json` is in sync with the code (Tier-1 diff).
+     * Async because the breadth tier warms WASM grammars before re-extraction. */
+    checkGraph(dir) {
+        return checkGraph(dir, { contextDir: this.cfg.contextDir });
+    }
+    /**
+     * Build `.context/graph.json` — a per-symbol code graph from tree-sitter.
+     * Tier-1 (structure) always runs; the Tier-2 meaning layer runs only when
+     * `opts.llm` is set. Either way the prior meaning layer is preserved.
+     */
+    graph(dir, opts = {}) {
+        return buildGraph(dir, {
+            contextDir: this.cfg.contextDir,
+            summarizer: opts.llm ? this.cruxSummarizer() : undefined,
+            concurrency: opts.concurrency,
+            reuse: opts.reuse,
+            lsp: opts.lsp,
+            onlyDirs: opts.onlyDirs,
+            onProgress: opts.onProgress,
+        });
+    }
+    /**
+     * Answer a plain-words query from the committed `graft/` graph — the active
+     * channel. Deterministic and $0: routes structural queries to the wiring
+     * edges and everything else to a lexical rank over concepts + symbols.
+     */
+    ask(dir, query, opts = {}) {
+        const r = ask(dir, query, {
+            contextDir: this.cfg.contextDir,
+            limit: opts.limit,
+            source: opts.source,
+            full: opts.full,
+            in: opts.in,
+            graphRank: opts.graphRank,
+        });
+        return r;
+    }
+    _chatModel;
+    /** The configured transport, or a clear error telling the user how to set a key. */
+    chatModel() {
+        if (this.cfg.chatModel)
+            return this.cfg.chatModel;
+        if (this._chatModel)
+            return this._chatModel;
+        if (!this.cfg.apiKey) {
+            throw new Error("No API key. Set GRAFT_API_KEY (and GRAFT_PROVIDER / GRAFT_BASE_URL / GRAFT_MODEL " +
+                "for your provider) to build or summarize the graph.");
+        }
+        this._chatModel = createChatModel({
+            provider: this.cfg.provider,
+            apiKey: this.cfg.apiKey,
+            model: this.cfg.model,
+            baseUrl: this.cfg.baseUrl,
+            headers: this.cfg.headers,
+        });
+        return this._chatModel;
+    }
+    synthesizer() {
+        return this.cfg.synthesizer ?? new ChatSynthesizer(this.chatModel());
+    }
+    /** Per-node crux summarizer for the code graph's Tier-2 pass. */
+    cruxSummarizer() {
+        return this.cfg.cruxSummarizer ?? new ChatCruxSummarizer(this.chatModel());
+    }
+    summarizer() {
+        return this.cfg.summarizer ?? new ChatSummarizer(this.chatModel());
+    }
+    /** Human label for the active model, recorded in the manifest. */
+    modelLabel() {
+        if (this.cfg.chatModel)
+            return this.cfg.chatModel.label;
+        if (this.cfg.synthesizer || this.cfg.summarizer || this.cfg.cruxSummarizer)
+            return "custom";
+        return `${this.cfg.provider}:${this.cfg.model}`;
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAA0C,MAAM,mBAAmB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAmB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAuB,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAwC,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,UAAU,EAAiD,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,UAAU,EAAyB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,GAAG,EAAkB,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,CAAC;AAgC3B,MAAM,OAAO,KAAK;IACR,GAAG,CAAiB;IAE5B,YAAY,SAAuB,EAAE;QACnC,IAAI,CAAC,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,OAAoB,EAAE;QAC5C,OAAO,YAAY,CAAC,GAAG,EAAE;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU;YAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE;YACxB,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;YAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,GAAW,EAAE,OAAwB,EAAE;QAC3C,OAAO,YAAY,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED;kFAC8E;IAC9E,UAAU,CAAC,GAAW;QACpB,OAAO,UAAU,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAW,EAAE,OAAwB,EAAE;QAC3C,OAAO,UAAU,CAAC,GAAG,EAAE;YACrB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU;YAC/B,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS;YACxD,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,OAA+F,EAAE;QAC/H,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE;YACxB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU;YAC/B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAEO,UAAU,CAAa;IAE/B,oFAAoF;IAC5E,SAAS;QACf,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;QAClD,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC,UAAU,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,mFAAmF;gBACjF,qDAAqD,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC;YAChC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ;YAC3B,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM;YACvB,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK;YACrB,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO;YACzB,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO;SAC1B,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAEO,WAAW;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,iEAAiE;IACzD,cAAc;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,cAAc,IAAI,IAAI,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7E,CAAC;IAEO,UAAU;QAChB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,kEAAkE;IAC1D,UAAU;QAChB,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC;QACxD,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,cAAc;YAAE,OAAO,QAAQ,CAAC;QAC5F,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IAClD,CAAC;CACF"}

package/dist/graph/bindings.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Receiver-type binding pass: a pre-order walk over a parsed file that answers,
+ * for every local variable / parameter / class field / `self`|`this` attribute,
+ * "what type is this?" — so a later member-call site (`app.include_router()`)
+ * can look up `app`'s bound type instead of resolving on the bare method name
+ * alone. Pure and dependency-only: no LLM, no network, no mutation of the AST.
+ *
+ * Only `import type` from extract.ts (never a value) — extract.ts imports
+ * `collectBindings` from here, so a value import back would be a cycle.
+ */
+import type { SyntaxNode } from "./depth-parser.js";
+import type { Language, WalkCtx } from "./extract.js";
+/** Variable/field → bare type name, keyed by scope. Scope keys mirror
+ * extract.ts's own scope stack (`scope.join(".")`, `""` at module level) so a
+ * lookup from extract.ts's walk finds exactly what was bound in the same
+ * lexical position. */
+export declare class FileBindings {
+    private map;
+    set(scopePath: string, name: string, type: string): void;
+    /** Innermost-first: for scope ["a","b"] name "x", tries `a.b|x`, `a|x`, `|x`. */
+    lookup(scope: string[], name: string): string | null;
+}
+/** Definition-node types that push a new scope segment, mirroring extract.ts's
+ * `describe()` closely enough to keep the two scope stacks in lockstep — but
+ * duplicated here (not imported) to keep bindings.ts free of a value import on
+ * extract.ts. Returns the def's scope segment (bare name, except a Go method
+ * which is receiver-qualified — `Receiver.method` — exactly like extract.ts's
+ * `idName`, so a binding recorded inside a Go method body is stored under the
+ * same scope key extract.ts's walk will look it up with), or null if `node`
+ * isn't a definition. */
+export declare function defName(node: SyntaxNode, lang: Language): string | null;
+/**
+ * The bare name a `binary_operator` (left-assign) or `function_definition`
+ * (right-assign) node defines, for R's two plain-function assignment shapes —
+ * this file's own `defName` uses it directly. extract.ts's `describeR`
+ * duplicates the same op-filtering check rather than importing this (same
+ * reasoning as the Go receiver helpers below: bindings.ts can't take a value
+ * import back on extract.ts), and additionally needs to distinguish an S3
+ * `generic.Class` method and R6/S4 class/method shapes this function doesn't
+ * know about — bindings.ts has no equivalent need since no `handleR` binding
+ * collector exists yet (R6/S4/S3 don't get a member/receiver-type table in
+ * this pass; `self`/`private` resolve directly via `ctx.enclosingClass`
+ * instead, needing no lookup). See `describeR`'s doc comment for why
+ * right-assign's AST shape needs its own branch rather than mirroring
+ * left-assign's (empirically, not assumed — `->`'s low precedence means it's
+ * absorbed into the function's own `body` field, not an outer wrapper).
+ * Null if `node` isn't one of these two shapes.
+ */
+export declare function rDefName(node: SyntaxNode): string | null;
+/** The receiver parameter's own variable name for a Go method (`func (w *Worker) …`
+ * → `w`). Null if it can't be read. */
+export declare function goReceiverVarOf(node: SyntaxNode): string | null;
+/** Resolves a call site's receiver text (from `calleeName`) to a bound type
+ * name, given the enclosing walk state. `self`/`cls`/`this`/the Go receiver
+ * var resolve directly to the enclosing class; `super` — R6's `super$` and
+ * Swift's `super.` alike — resolves to the PARENT class instead
+ * (`ctx.rSuperClass`, not `ctx.enclosingClass` — a super call must climb past
+ * the current class's own same-named override, not find it); anything else is
+ * a bindings-map lookup, normalizing `this.` to `self.` since both are stored
+ * the same way. */
+export declare function resolveRecvType(receiver: string | undefined, ctx: Pick<WalkCtx, "scope" | "enclosingClass" | "goReceiverVar" | "lang" | "bindings" | "rSuperClass">): string | undefined;
+/** Pass 1 over a parsed file: collect variable->type bindings. Pure. */
+export declare function collectBindings(root: SyntaxNode, lang: Language): FileBindings;
+//# sourceMappingURL=bindings.d.ts.map

package/dist/graph/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/graph/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEtD;;;uBAGuB;AACvB,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAA6B;IAExC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxD,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAOrD;AAID;;;;;;;yBAOyB;AACzB,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAsDvE;AAqCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAiBxD;AAED;uCACuC;AACvC,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAI/D;AAcD;;;;;;;mBAOmB;AACnB,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,eAAe,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC,GACrG,MAAM,GAAG,SAAS,CAuBpB;AAqCD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAM9E"}