@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/core/delivery.d.ts

@@ -28,6 +28,14 @@ export interface DeliverySupplement {
     text: string;
     /** Higher values are attempted first after ranked memory. */
     priority?: number;
+    /** Stable IDENTITY of the records behind `text`, for callers that dedup
+     *  injections by hash (the pre-edit hook). Some supplements are
+     *  self-invalidating: serving them writes delivery receipts, and the next
+     *  render's wording, scores or slot order move with no record change. Set this
+     *  to what is a property of the record — never of delivery state or the clock —
+     *  and `deliveryDedupeInput` swaps it in for `text` when hashing. Omitted →
+     *  `text` is its own identity. Never shown to the agent. */
+    hash_text?: string;
 }
 export interface DeliveredSupplement {
     id: string;
@@ -106,5 +114,31 @@ export interface DeliveryOptions {
 }
 /** Validate the public receipt without trusting a caller-supplied identity. */
 export declare function assertDeliveryEnvelope(envelope: DeliveryEnvelope): void;
+/** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must
+ *  key on instead of the rendered block: a STABLE IDENTITY PROJECTION of this
+ *  envelope.
+ *
+ *  THE RULE, for every caller and every provider: nothing that depends on
+ *  delivery receipts, ranking warmth or scores, slot labels, line ORDER, or
+ *  `now` may enter the dedupe hash; a record entering, leaving, or changing
+ *  content MUST. Grounding that violates it is self-invalidating — serving the
+ *  block writes delivery receipts, the next call's ranking reads them back, the
+ *  wording moves ("today" → "delivered today"), the hash changes, and the full
+ *  block is re-sent for records the agent already has.
+ *
+ *  The projection, done line-wise over the one text the assembler produced:
+ *  - a supplement that declared `hash_text` contributes that identity (kind +
+ *    record id + the record's own content hash) instead of its rendered line —
+ *    that is where reason text, slot labels and age words live;
+ *  - every other line contributes verbatim, because it is already a property of
+ *    the records (id, statement, scope, provenance tier, validation state);
+ *  - each contiguous run of `- ` list lines is SORTED, so a pure re-ordering of
+ *    the same records is not a change while a record entering or leaving the run
+ *    still is.
+ *
+ *  Nothing is removed from what the agent SEES — this string is never emitted.
+ *  Never throws: on any surprise the caller gets `envelope.text` back, i.e. the
+ *  original hash-the-presentation behaviour (a full block, never a wrong delta). */
+export declare function deliveryDedupeInput(envelope: DeliveryEnvelope, supplements?: readonly DeliverySupplement[]): string;
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export declare function buildDeliveryEnvelope(ctx: AssembledContext, options?: DeliveryOptions): DeliveryEnvelope;

package/dist/core/delivery.js

@@ -21,6 +21,9 @@ const MIN_ADVISORY_CONFIDENCE = 0.5;
 const MIN_UNCONDITIONED_CONFIDENCE = 0.7;
 const MAX_ACTIONABLE_HYPOTHESES = 2;
 const MAX_PROFILE_HEADLINES = 8;
+/** How far a supplement's text is clipped in the rendered line. Shared so
+ *  `deliveryDedupeInput` can reconstruct that exact line to project over it. */
+const SUPPLEMENT_HEADLINE_CHARS = 700;
 const PROFILE_BASE_SCORE = {
     builder: {
         constraints: 900,
@@ -457,6 +460,62 @@ export function assertDeliveryEnvelope(envelope) {
         throw new Error("delivery envelope receipt does not match its content");
     }
 }
+/** The string a hash-based injection dedup (`injectionMode`'s `hashInput`) must
+ *  key on instead of the rendered block: a STABLE IDENTITY PROJECTION of this
+ *  envelope.
+ *
+ *  THE RULE, for every caller and every provider: nothing that depends on
+ *  delivery receipts, ranking warmth or scores, slot labels, line ORDER, or
+ *  `now` may enter the dedupe hash; a record entering, leaving, or changing
+ *  content MUST. Grounding that violates it is self-invalidating — serving the
+ *  block writes delivery receipts, the next call's ranking reads them back, the
+ *  wording moves ("today" → "delivered today"), the hash changes, and the full
+ *  block is re-sent for records the agent already has.
+ *
+ *  The projection, done line-wise over the one text the assembler produced:
+ *  - a supplement that declared `hash_text` contributes that identity (kind +
+ *    record id + the record's own content hash) instead of its rendered line —
+ *    that is where reason text, slot labels and age words live;
+ *  - every other line contributes verbatim, because it is already a property of
+ *    the records (id, statement, scope, provenance tier, validation state);
+ *  - each contiguous run of `- ` list lines is SORTED, so a pure re-ordering of
+ *    the same records is not a change while a record entering or leaving the run
+ *    still is.
+ *
+ *  Nothing is removed from what the agent SEES — this string is never emitted.
+ *  Never throws: on any surprise the caller gets `envelope.text` back, i.e. the
+ *  original hash-the-presentation behaviour (a full block, never a wrong delta). */
+export function deliveryDedupeInput(envelope, supplements = []) {
+    try {
+        const identity = new Map();
+        for (const s of supplements) {
+            if (s.hash_text === undefined)
+                continue;
+            // Key on the line exactly as the assembler rendered it, so the swap is a
+            // substitution and never a guess about the text's shape.
+            identity.set(`- supplemental/${s.kind} | ${clipHeadline(s.text, SUPPLEMENT_HEADLINE_CHARS)}`, `- supplemental/${s.kind} | identity\u0000${s.hash_text}`);
+        }
+        const projected = [];
+        let run = [];
+        const flush = () => { if (run.length) {
+            projected.push(...run.sort());
+            run = [];
+        } };
+        for (const line of envelope.text.split("\n")) {
+            if (!line.startsWith("- ")) {
+                flush();
+                projected.push(line);
+                continue;
+            }
+            run.push(identity.get(line) ?? line);
+        }
+        flush();
+        return projected.join("\n");
+    }
+    catch {
+        return envelope.text; // the projection is an optimization, never a correctness dependency
+    }
+}
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export function buildDeliveryEnvelope(ctx, options = {}) {
     const profile = options.profile ?? "builder";
@@ -742,7 +801,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         ...(options.supplements ?? []),
     ].sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.id.localeCompare(right.id));
     for (const [index, supplement] of supplementalCandidates.entries()) {
-        const content = clipHeadline(supplement.text, 700);
+        const content = clipHeadline(supplement.text, SUPPLEMENT_HEADLINE_CHARS);
         if (!content) {
             supplements.push({ id: supplement.id, kind: supplement.kind, delivered: false, reason: "empty", rank: index + 1, token_cost: 0 });
             continue;

package/dist/core/docanchors.js

@@ -1,27 +1,199 @@
 import { currentForTopic, rejectedForTopic } from "./topics.js";
 const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
+/** Expand the leading whitespace of a line to columns. A tab advances to the
+ *  NEXT 4-column tab stop (CommonMark), not a flat 4 columns: after two
+ *  spaces a tab is worth 2, so `  \t``` ` sits at column 4 like `\t``` `.
+ *  Matching-only — offsets always come from the original line. */
+function expandTabs(line) {
+    const ws = /^[ \t]*/.exec(line)[0];
+    if (!ws.includes("\t"))
+        return line;
+    let col = 0;
+    for (const c of ws)
+        col += c === "\t" ? 4 - (col % 4) : 1;
+    return " ".repeat(col) + line.slice(ws.length);
+}
+/** For every index i of `probe`, whether probe.slice(i) is a thematic break
+ *  (`---`, `* * *`, `___`: ≤3 leading spaces, then ≥3 of one char separated by
+ *  spaces only). Computed right-to-left in ONE pass so the list-marker walk
+ *  below can ask the question at each nesting level without re-scanning the
+ *  rest of the line each time — the difference between O(L) and O(L²) on a
+ *  line that is nothing but list markers (`- - - …`, an adversarial doc). */
+function thematicBreakSuffixes(probe) {
+    const L = probe.length;
+    // runFrom[i] = the break-so-far state of probe.slice(i) when it consists only
+    // of spaces and one repeated break char: its char, and how many were seen.
+    const ok = new Array(L + 1).fill(false);
+    let ch = "";
+    let count = 0;
+    let onlySpaceSoFar = true;
+    for (let i = L - 1; i >= 0; i--) {
+        const c = probe[i];
+        if (c === " " || c === "\t") {
+            // A space never breaks the run; it is allowed anywhere, including the
+            // ≤3 leading columns handled by the indent check at the call site.
+            ok[i] = ok[i + 1];
+            continue;
+        }
+        if (c === "-" || c === "*" || c === "_") {
+            if (onlySpaceSoFar) {
+                ch = c;
+                count = 1;
+                onlySpaceSoFar = false;
+            }
+            else if (c === ch)
+                count++;
+            // Two different break chars: every suffix starting at or before i now
+            // mixes them (`- - - * -` is five nested items, not a break), so stop.
+            else
+                return ok;
+        }
+        else {
+            // Any other char means no suffix starting at or before i is a break;
+            // ok is already false there, so stop.
+            return ok;
+        }
+        ok[i] = count >= 3;
+    }
+    return ok;
+}
 /** Character ranges covered by fenced code blocks (``` or ~~~), so a
  *  documentation EXAMPLE of a marker never registers as a live anchor.
  *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
  *  line of ≥N of the same char and nothing else; an unclosed fence runs to
- *  EOF; a backtick fence's info string may not itself contain a backtick. */
+ *  EOF; a backtick fence's info string may not itself contain a backtick.
+ *  The "≤3 leading spaces" is measured relative to the enclosing LIST ITEM's
+ *  content offset, so a fence indented under `1. step` (issue #331) is still a
+ *  fence and not an indented code block.
+ *
+ *  A fence hosted in a list item ends where the ITEM ends: at the first
+ *  non-blank line dedented below the item's content base. That is what the
+ *  rendered document shows — the closing ``` of a sloppily indented example
+ *  sits outside the item, so it terminates the item's fence and opens a new
+ *  top-level one — and this scanner's job is to agree with the rendering a
+ *  reader sees, not with the author's intent. In sloppy docs that differs from
+ *  a flat fence scan; the rendering is the tiebreaker.
+ *
+ *  Tabs expand to the next 4-column tab stop (not a flat 4), so `\t``` ` sits
+ *  at column 4 exactly as a renderer places it. Offsets always come from the
+ *  ORIGINAL line, never from the expanded probe.
+ *
+ *  Deliberate limits: no lazy continuations and no blockquote containers — a
+ *  `>` prefix is still read as ordinary text. With no list open the item stack
+ *  is empty, the base is 0 and behaviour is the plain CommonMark-lite one.
+ *  Expects LF-normalized text — see parseDocAnchors's normalization; a caller
+ *  that skips it re-opens the CRLF fence-detection bug. */
 function fencedRanges(text) {
+    const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
     const ranges = [];
     let open = null;
+    // Content offsets (columns) of the currently open list items, outermost first.
+    const items = [];
     let offset = 0;
+    // Whether the previous line was a paragraph-continuation line: non-blank,
+    // and not itself a container/leaf opener. Only a bullet or a `1.`/`1)` with
+    // non-empty content may interrupt such a paragraph (CommonMark), so prose
+    // like "see item\n2. the second point" stays one paragraph.
+    let inParagraph = false;
     for (const line of text.split("\n")) {
-        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
-        if (m) {
-            const ch = m[1][0];
-            if (!open) {
-                if (!(ch === "`" && m[2].includes("`")))
-                    open = { ch, len: m[1].length, start: offset };
-            }
-            else if (ch === open.ch && m[1].length >= open.len && m[2].trim() === "") {
-                ranges.push([open.start, offset + line.length]);
+        // Matching-only copy: tabs advance to the next 4-column tab stop.
+        const probe = expandTabs(line);
+        const indent = probe.length - probe.replace(/^ +/, "").length;
+        const blank = probe.trim() === "";
+        if (open) {
+            if (!blank && indent < open.base) {
+                // The list item holding the fence ended, which ends the fence too.
+                ranges.push([open.start, offset - 1]);
                 open = null;
             }
+            else {
+                const m = FENCE.exec(probe.slice(Math.min(open.base, indent)));
+                if (m && m[1][0] === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                    ranges.push([open.start, offset + line.length]);
+                    open = null;
+                }
+                offset += line.length + 1;
+                continue; // the item stack is frozen while a fence is open
+            }
+        }
+        if (blank) {
+            offset += line.length + 1;
+            inParagraph = false;
+            continue; // a blank line neither opens nor closes an item here
+        }
+        // A dedent that closes an item also closes the paragraph inside it, so the
+        // line is a fresh block start: `1. one\n2. two` is two sibling items, not
+        // item one's paragraph being "interrupted" by a `2.`.
+        let popped = false;
+        while (items.length && items.at(-1) > indent) {
+            items.pop();
+            popped = true;
+        }
+        const isBreak = thematicBreakSuffixes(probe);
+        // Walk the line with an INDEX, peeling one list marker per step. Each step
+        // is O(marker) and the cheap checks are O(1), so a line costs O(length)
+        // however many markers it carries.
+        let base = items.at(-1) ?? 0;
+        let opened = false;
+        let thematic = false;
+        for (;;) {
+            // Leading spaces of this nesting level: ≤3, else it is indented content
+            // (and `    ---` is paragraph text or code, never a thematic break).
+            let i = base;
+            while (i < probe.length && probe[i] === " " && i - base < 4)
+                i++;
+            const lead = i - base;
+            if (lead > 3)
+                break;
+            if (isBreak[i]) {
+                thematic = true;
+                break;
+            } // thematic break, not a list marker
+            const c = probe[i];
+            let markerLen = 0;
+            if (c === "-" || c === "*" || c === "+")
+                markerLen = 1;
+            else if (c !== undefined && c >= "0" && c <= "9") {
+                let d = i;
+                while (d < probe.length && probe[d] >= "0" && probe[d] <= "9" && d - i < 9)
+                    d++;
+                if (probe[d] === "." || probe[d] === ")")
+                    markerLen = d - i + 1;
+            }
+            if (!markerLen)
+                break;
+            // Spaces between the marker and the item's content.
+            let s = i + markerLen;
+            while (s < probe.length && probe[s] === " ")
+                s++;
+            const gap = s - (i + markerLen);
+            const emptyItem = s >= probe.length;
+            if (!emptyItem && gap === 0)
+                break; // `-foo` / `1.foo` is not a marker
+            if (!opened && !popped && inParagraph && items.length === 0) {
+                // Interrupting a paragraph: only a bullet, or `1.`/`1)`, and never with
+                // empty content. `2. the second point` mid-prose stays paragraph text.
+                const ordinal = markerLen > 1 ? probe.slice(i, i + markerLen - 1) : "";
+                if (emptyItem || (ordinal !== "" && ordinal !== "1"))
+                    break;
+            }
+            // ≥5 spaces after the marker starts an indented code block, so the
+            // item's content begins one column after the marker instead.
+            const w = gap >= 1 && gap <= 4 ? gap : 1;
+            base = base + lead + markerLen + w;
+            items.push(base);
+            opened = true;
+            continue; // `- 1. x` nests, and "- ```js" opens a fence on the marker line
+        }
+        const m = FENCE.exec(probe.slice(base));
+        if (m) {
+            const ch = m[1][0];
+            if (!(ch === "`" && m[2].includes("`")))
+                open = { ch, len: m[1].length, start: offset, base };
         }
+        // A fence line or a thematic break ends the paragraph it follows; ordinary
+        // text (including an item's own content) continues or starts one.
+        inParagraph = !m && !thematic;
         offset += line.length + 1;
     }
     if (open)
@@ -31,7 +203,11 @@ function fencedRanges(text) {
 /** Character ranges covered by inline code spans (`…`), same rationale as
  *  fencedRanges: prose quoting a marker in backticks is showing an example.
  *  CommonMark-lite: an opener run pairs with the next run of the SAME length
- *  on the same line; unpaired runs never open a span. */
+ *  on the same line; unpaired runs never open a span.
+ *  Expects LF-normalized text — see parseDocAnchors's normalization.
+ *  `split("\n")` does not split a bare CR, so on CR-only input the whole
+ *  document reads as one line and stray backticks on different lines
+ *  falsely pair. */
 function inlineSpanRanges(text) {
     const ranges = [];
     let offset = 0;
@@ -55,6 +231,14 @@ function inlineSpanRanges(text) {
  *  fenced code blocks or inline code spans are examples, not declarations,
  *  and are skipped. */
 export function parseDocAnchors(text) {
+    // fencedRanges is CRLF-sensitive (its fence-line regex's `.` excludes \r, so
+    // "```\r" never matched at all on a CRLF checkout); inlineSpanRanges is
+    // lone-CR-sensitive (split("\n") doesn't split a bare CR — see its
+    // docblock). Either way an example marker inside a fence/span registered as
+    // a live, pinned anchor. Normalizing both CRLF and lone CR once here keeps
+    // fencedRanges/inlineSpanRanges/MARKER offsets consistent with each other
+    // and with the line numbers reported below.
+    text = text.replace(/\r\n?/g, "\n");
     const out = [];
     const skip = [...fencedRanges(text), ...inlineSpanRanges(text)];
     MARKER.lastIndex = 0;

package/dist/core/format.js

@@ -16,8 +16,13 @@ export function formatSearchHit(hit, record) {
 /** Render a StructureView as a compact orientation brief (hunch_structure). */
 export function formatStructure(v) {
     const NL = "\n";
-    if (v.kind === "none")
+    if (v.kind === "none") {
+        // A real working-tree file with zero indexed symbols is a different answer from
+        // an unknown path — never tell the user a file we just stat'd doesn't exist.
+        if (v.realFile)
+            return `"${v.target}" is a real file, but the index holds no symbols for it — nothing to outline. Run hunch index if the repo changed, or hunch_why for its recorded decisions and invariants.`;
         return `Nothing indexed matches "${v.target}" — not a known file, directory, or symbol. Run hunch index if the repo changed, or hunch_query for fuzzy search.`;
+    }
     if (v.kind === "repo") {
         const out = [`# Repo structure (from the graph — no grep needed)`];
         if (v.components.length) {

package/dist/core/glob.d.ts

@@ -7,3 +7,28 @@ export declare function pathMatchesGlob(path: string, glob: string): boolean;
 /** Do two concrete repo paths identify the same path at different prefix depth?
  * Segment-anchored: `x/scenario.ts` relates to `scenario.ts`, never `io.ts`. */
 export declare function pathsRelated(left: string, right: string): boolean;
+/** True when `target` is a path Hunch's index already knows about: an indexed
+ *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
+ *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
+ *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
+ *  known file. Derived entirely from already-loaded graph data — never the
+ *  filesystem — so the answer doesn't depend on untracked working-tree state
+ *  (a deleted-but-still-indexed path stays "real"; issue #299). It is therefore
+ *  only HALF the "is this a real path" question: a real file with no symbols and
+ *  no covering component is invisible here, so callers OR in `isRepoFile` as a
+ *  last resort (issue #334) — `HunchStore.isKnownPath` is that composition. */
+export declare function isIndexedPath(target: string, symbolFiles: Iterable<string>, componentPaths: Iterable<readonly string[]>): boolean;
+/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+ *  (only when `target` is NOT a path already known to be real) segment-anchored
+ *  suffix. A real file with zero symbols must return [] rather than fall through
+ *  to the suffix tier, which would leak an unrelated same-basename file's records
+ *  (issues #299/#334). Callers decide what counts as "real": one that ATTRIBUTES
+ *  records silently (why(), the pre-edit hook) passes `HunchStore.isKnownPath`, the
+ *  wider graph-or-working-tree answer that also covers a file about to be created;
+ *  one that NAMES the file it resolved to (resolveNodeIds, structure()) passes the
+ *  narrower `isRepoFile`, since glob coverage alone is not existence. */
+export declare function matchSymbolsTiered<S extends {
+    id: string;
+    file: string;
+    name: string;
+}>(target: string, symbols: readonly S[], indexed: boolean): S[];

package/dist/core/glob.js

@@ -66,4 +66,47 @@ export function pathsRelated(left, right) {
     const b = norm(right);
     return a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
 }
+/** True when `target` is a path Hunch's index already knows about: an indexed
+ *  symbol's exact file, or a path an indexed component's `paths` glob(s) cover.
+ *  The latter catches a symbol-less-but-indexed file (README.md, package.json,
+ *  Dockerfile, ...) that has zero tree-sitter symbols but is still a real,
+ *  known file. Derived entirely from already-loaded graph data — never the
+ *  filesystem — so the answer doesn't depend on untracked working-tree state
+ *  (a deleted-but-still-indexed path stays "real"; issue #299). It is therefore
+ *  only HALF the "is this a real path" question: a real file with no symbols and
+ *  no covering component is invisible here, so callers OR in `isRepoFile` as a
+ *  last resort (issue #334) — `HunchStore.isKnownPath` is that composition. */
+export function isIndexedPath(target, symbolFiles, componentPaths) {
+    for (const f of symbolFiles)
+        if (f === target)
+            return true;
+    for (const globs of componentPaths)
+        for (const g of globs)
+            if (pathMatchesGlob(target, g))
+                return true;
+    return false;
+}
+/** Resolve symbols matching `target`, tiered: exact id > exact name > exact file >
+ *  (only when `target` is NOT a path already known to be real) segment-anchored
+ *  suffix. A real file with zero symbols must return [] rather than fall through
+ *  to the suffix tier, which would leak an unrelated same-basename file's records
+ *  (issues #299/#334). Callers decide what counts as "real": one that ATTRIBUTES
+ *  records silently (why(), the pre-edit hook) passes `HunchStore.isKnownPath`, the
+ *  wider graph-or-working-tree answer that also covers a file about to be created;
+ *  one that NAMES the file it resolved to (resolveNodeIds, structure()) passes the
+ *  narrower `isRepoFile`, since glob coverage alone is not existence. */
+export function matchSymbolsTiered(target, symbols, indexed) {
+    const byId = symbols.find((s) => s.id === target);
+    if (byId)
+        return [byId];
+    const byName = symbols.filter((s) => s.name === target);
+    if (byName.length)
+        return byName;
+    const exact = symbols.filter((s) => s.file === target);
+    if (exact.length)
+        return exact;
+    if (indexed)
+        return [];
+    return symbols.filter((s) => pathsRelated(s.file, target));
+}
 //# sourceMappingURL=glob.js.map

package/dist/core/hookcache.d.ts

@@ -1,7 +1,14 @@
 /** Decide whether this injection should be the FULL grounding block or a delta
  *  one-liner. Records the content hash as a side effect (so the next identical
- *  call dedups). Never throws. */
-export declare function injectionMode(sessionId: string | undefined, key: string, content: string): "full" | "delta";
+ *  call dedups). Never throws.
+ *
+ *  `hashInput` lets a caller dedup on a STABLE PROJECTION of the block instead
+ *  of its presentation: some grounding is self-invalidating —
+ *  serving it writes delivery receipts, and the next call's wording moves
+ *  ("today" → "delivered today") with no record change, so hashing the rendered
+ *  text re-sends the full block forever. Callers pass the identity of the
+ *  underlying records; omitting it hashes `content`, the original contract. */
+export declare function injectionMode(sessionId: string | undefined, key: string, content: string, hashInput?: string): "full" | "delta";
 /** Forget everything injected into a session. Compaction summarizes injected
  *  grounding out of the agent's context while the dedup map still says
  *  "delivered" — so on PreCompact / SessionStart[source=compact] the map must

package/dist/core/hookcache.js

@@ -23,8 +23,15 @@ const MAX_KEYS = 300;
 const SWEEP_AGE_MS = 48 * 3600 * 1000;
 /** Decide whether this injection should be the FULL grounding block or a delta
  *  one-liner. Records the content hash as a side effect (so the next identical
- *  call dedups). Never throws. */
-export function injectionMode(sessionId, key, content) {
+ *  call dedups). Never throws.
+ *
+ *  `hashInput` lets a caller dedup on a STABLE PROJECTION of the block instead
+ *  of its presentation: some grounding is self-invalidating —
+ *  serving it writes delivery receipts, and the next call's wording moves
+ *  ("today" → "delivered today") with no record change, so hashing the rendered
+ *  text re-sends the full block forever. Callers pass the identity of the
+ *  underlying records; omitting it hashes `content`, the original contract. */
+export function injectionMode(sessionId, key, content, hashInput = content) {
     try {
         if (!sessionId || process.env.HUNCH_HOOK_DEDUP === "0")
             return "full";
@@ -32,7 +39,7 @@ export function injectionMode(sessionId, key, content) {
         mkdirSync(dir, { recursive: true });
         sweep(dir);
         const file = join(dir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
-        const hash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        const hash = createHash("sha256").update(hashInput).digest("hex").slice(0, 16);
         let map;
         try {
             const raw = JSON.parse(readFileSync(file, "utf8"));

package/dist/core/paths.d.ts

@@ -1,10 +1,53 @@
 export declare const HUNCH_DIR = ".hunch";
-/** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
- *  every path with forward slashes (git emits "/" on all OSes), so any user- or
- *  agent-supplied target must be normalized before comparison — otherwise a
- *  Windows caller passing `src\auth\session.ts` never matches the stored
- *  `src/auth/session.ts`. Safe on symbol names too: they contain no backslashes. */
+/** Canonicalize a free-form path/target to forward-slash form (Hunch stores every
+ *  path with "/" — git emits it on all OSes — so any user- or agent-supplied
+ *  target must be normalized before comparison, otherwise a Windows caller passing
+ *  `src\auth\session.ts` never matches the stored `src/auth/session.ts`). Safe on
+ *  symbol names too: they contain no backslashes. This does NOT make a path
+ *  repo-relative — an absolute path passes through with its separators flipped,
+ *  unchanged otherwise; use `repoRelativeTarget` for that. */
 export declare function toPosixTarget(target: string): string;
+/** realpath a path even if it doesn't exist yet (e.g. a new file an agent is about
+ *  to Write, or a glob whose concrete segments aren't literal): resolve the longest
+ *  existing ancestor, then re-append the missing tail. Idempotent on an
+ *  already-resolved path. */
+export declare function realpathNorm(p: string): string;
+/** Rewrite an ABSOLUTE target to repo-relative POSIX form when it falls inside
+ *  `root`. Hunch's stored paths (symbols, constraint scopes, ...) are always
+ *  repo-relative, so a caller that hands over an absolute edit-payload path
+ *  matched nothing (issue #296: hunch_check_constraints / hunch_blast_radius
+ *  returned empty for an absolute target that plainly had a matching rule). A
+ *  relative target, a glob, or an absolute path outside `root` passes through
+ *  unchanged (toPosixTarget'd) — there is nothing safe to rewrite it to.
+ *
+ *  BOTH ends are realpath-normalized before the relative-path computation: on
+ *  macOS `process.cwd()` (hence `findRoot`) resolves /var → /private/var, but a
+ *  hook event's `file_path` arrives UN-resolved, so a naive `relative()` yields a
+ *  bogus "../" path under a symlinked root (/var, /tmp, symlinked $HOME) and the
+ *  caller treats the file as outside the repo, silently dropping all context
+ *  (dec_e0a36efbf5). */
+export declare function repoRelativeTarget(target: string, root: string): string;
+/** True when `target` (already repo-relative POSIX form) names a regular FILE
+ *  that really exists inside `root`. The LAST-RESORT half of the "is this a real
+ *  path" question: `isIndexedPath` answers it from graph data alone, but a real
+ *  working-tree file with zero tree-sitter symbols and no covering component
+ *  glob is invisible to it, so it fell through to the suffix tier and leaked an
+ *  unrelated same-basename file's records (issue #334). Callers consult the
+ *  index FIRST and only fall back here, so a deleted-but-still-indexed path and
+ *  a time-travel (`asOf`) query keep answering exactly as before.
+ *
+ *  Deliberately narrow: an absolute path (or a Windows drive letter) and any
+ *  target escaping `root` via ".." are rejected rather than resolved — the
+ *  caller has already run `repoRelativeTarget`, so anything still absolute is
+ *  outside the repo. A DIRECTORY is false: directory targets must keep flowing
+ *  to `structure()`'s dir tier. Any fs error (missing, EACCES, ...) → false.
+ *
+ *  Containment is checked twice: lexically, then again on the REALPATHS. `statSync`
+ *  follows symlinks, so an in-repo `link -> /outside` would otherwise make
+ *  `isRepoFile(root, "link/secret.ts")` true and turn this into a one-bit existence
+ *  oracle for paths outside the repo. A symlinked file pointing at another file
+ *  INSIDE the repo stays true. */
+export declare function isRepoFile(root: string, target: string): boolean;
 export interface HunchPaths {
     /** Repo root (where .hunch/ lives). */
     root: string;