@davesheffer/hunch 1.39.3 → 1.40.1

package/dist/store/changeLedger.js

@@ -5,9 +5,9 @@
  * other record, appended atomically (con_902759b3dc). It holds the strictly ordered
  * ChangeEvent stream for that scope (seq 1, 2, 3 … with no gaps) plus the idempotency
  * table the write verb replays from. Seq is per scope, assigned by the writer in the
- * home the scope lives in; a scope has exactly ONE ledger, so there is never a second
- * sequence to reconcile. Merging two clones' ledgers for the same scope is not decided
- * here (see docs/nuryel-state-contract.md, "Not decided here").
+ * home the scope lives in; a scope has exactly ONE ledger per clone, so within a clone there
+ * is never a second sequence to reconcile. Two clones that both appended to one scope are
+ * reconciled by `mergeLedgers` (below), for the git merge driver.
  */
 import { mkdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
@@ -34,8 +34,9 @@ export const LedgerSchema = z.object({
     schema: z.literal(LEDGER_SCHEMA_VERSION),
     scope: ScopeSchema,
     head_seq: z.number().int().nonnegative(),
-    /** Events below this seq were compacted away. `events` starts at floor_seq + 1. A subscriber
-     *  whose cursor is below the floor must resynchronize (the contract's gap rule, made explicit). */
+    /** Events below this seq were compacted away, or were invalidated by a merge that renumbered
+     *  them (see `mergeLedgers`). `events` starts at floor_seq + 1. A subscriber whose cursor is
+     *  below the floor must resynchronize (the contract's gap rule, made explicit). */
     floor_seq: z.number().int().nonnegative().default(0),
     events: z.array(ChangeEventSchema),
     idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
@@ -151,9 +152,15 @@ const eventIdentity = (e) => [e.change, e.facet, e.record_id, e.record_hash, e.a
 /** Three-way merge of one scope's ledger, for the git merge driver: two clones that both
  *  appended to the same partition. The union of events is kept (identity = what changed, to
  *  which hash, when, by whom), ordered by time then ours-before-theirs, and RE-SEQUENCED from
- *  the higher floor; every subscriber's cursor is therefore invalid after a merge and the gap
- *  rule makes it resynchronize. Idempotency entries are unioned; a key both sides used for
- *  different records is a conflict the caller must surface (ours is kept). */
+ *  the higher floor. When that renumbering moves an event either side had already published,
+ *  no pre-merge cursor of EITHER side can be trusted — a cursor could otherwise sit above an
+ *  event that now holds a lower seq and never see it (issue #285). The floor is then raised
+ *  past BOTH pre-merge heads, so every such cursor satisfies subscribe's `after_seq <
+ *  floor_seq` and resynchronizes from the floor; a cursor equal to the larger head is exactly
+ *  the failing case, hence the `+ 1`. A merge that renumbers nothing keeps today's seqs (no
+ *  cursor could have seen a different numbering) and the floor stays put. Idempotency entries
+ *  are unioned; a key both sides used for different records is a conflict the caller must
+ *  surface (ours is kept). */
 export function mergeLedgers(base, ours, theirs) {
     if (scopePath(ours.scope) !== scopePath(theirs.scope))
         throw new Error("ledgers for different scopes cannot be merged");
@@ -169,9 +176,28 @@ export function mergeLedgers(base, ours, theirs) {
         add(e);
     for (const e of theirs.events)
         add(e);
-    const ranked = order.map((e, i) => ({ e, i, side: (ours.events.includes(e) ? 0 : 1) }));
+    // The tiebreak is "ours before theirs", so only an event theirs ALONE contributed sorts late:
+    // side 1 iff theirs holds it and neither ours nor base does. Deciding by object identity
+    // (`includes`) would instead put anything ours compacted away — base's object, which `add`
+    // keeps — after its same-`at` siblings and silently reorder a batch both sides already had.
+    const ourIdentities = new Set(ours.events.map(eventIdentity));
+    const baseIdentities = new Set((base?.events ?? []).map(eventIdentity));
+    const theirsOnly = (e) => {
+        const k = eventIdentity(e);
+        return !ourIdentities.has(k) && !baseIdentities.has(k);
+    };
+    const ranked = order.map((e, i) => ({ e, i, side: (theirsOnly(e) ? 1 : 0) }));
     ranked.sort((a, b) => a.e.at.localeCompare(b.e.at) || a.side - b.side || a.i - b.i);
-    const floor = Math.max(base?.floor_seq ?? 0, ours.floor_seq, theirs.floor_seq);
+    const theirSeqs = new Map(theirs.events.map((e) => [eventIdentity(e), e.seq]));
+    const ourSeqs = new Map(ours.events.map((e) => [eventIdentity(e), e.seq]));
+    let floor = Math.max(base?.floor_seq ?? 0, ours.floor_seq, theirs.floor_seq);
+    const renumbers = ranked.some(({ e }, i) => {
+        const k = eventIdentity(e);
+        const merged = floor + i + 1;
+        return (ourSeqs.get(k) ?? merged) !== merged || (theirSeqs.get(k) ?? merged) !== merged;
+    });
+    if (renumbers)
+        floor = Math.max(floor, Math.max(ours.head_seq, theirs.head_seq) + 1);
     const events = ranked.map(({ e }, i) => ({ ...e, seq: floor + i + 1 }));
     const conflicts = [];
     const idempotency = { ...(base?.idempotency ?? {}), ...theirs.idempotency, ...ours.idempotency };

package/dist/store/hunchStore.d.ts

@@ -335,6 +335,29 @@ export declare class HunchStore {
      *  present in the indexed symbol/component tables can enter the frontier, so
      *  shared external-package hubs never become context or bridge unrelated symbols. */
     private graphExpand;
+    /** The WIDE definition of "is `t` a real path?" — the gate used by the matchers
+     *  that ATTRIBUTE records to a target silently (why(), liveFindingsFor, tasksFor,
+     *  `resolveSymbols` in the MCP server). They also run for a file an agent is
+     *  about to create, where the covering component glob is the only signal there
+     *  is, so the answer must not depend on the file already being on disk. The
+     *  resolvers that NAME the file they resolved to (resolveNodeIds, structure())
+     *  deliberately use the narrower `isRepoFile` instead.
+     *
+     *  Graph data FIRST (a symbol's exact file, or an indexed component's path glob),
+     *  so a deleted-but-still-indexed path and a time-travel (`asOf`) query answer the
+     *  same as before (issue #299). The working tree is consulted only as a LAST
+     *  resort, for the case the index cannot see: a real file with zero tree-sitter
+     *  symbols and no covering component glob, which otherwise suffix-leaked an
+     *  unrelated same-basename file's records (issue #334). When the working tree is
+     *  unavailable or the file is gone, behaviour is exactly the pre-#334 behaviour.
+     *
+     *  `t` must already be repo-relative (`repoRelativeTarget`). `graph` lets a caller
+     *  that has already narrowed the graph (why()'s `canRead` visibility filter) ask
+     *  the question over exactly the records it may see, rather than all of them. */
+    isKnownPath(t: string, graph?: {
+        symbols: readonly Symbol[];
+        components: readonly Component[];
+    }): boolean;
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
      *  return only decisions/constraints whose valid-time window contained that
@@ -379,7 +402,20 @@ export declare class HunchStore {
      *  or the id itself when unindexed. */
     nodeLabel(id: string): string;
     /** Resolve a free-form target (symbol id / name / file path, component id / name)
-     *  to graph node ids — symbols win over components, exact file before suffix. */
+     *  to graph node ids — symbols win over components, exact file before suffix.
+     *  Shares why()/resolveSymbols' tiered matcher rather than one un-tiered SQL OR:
+     *  the flat query matched every tier at once, so a root `index.ts` also returned
+     *  `a/index.ts`'s symbols, and an absolute target matched nothing at all (#335).
+     *
+     *  The suffix gate here is `isRepoFile`, NOT the wider `isKnownPath`: the
+     *  exact-file tier has already run, so the only case left is a real on-disk file
+     *  with zero symbols (#334). Glob coverage alone would wrongly block a target
+     *  that no file actually carries — with a `src/**` component, `src/x.ts` living
+     *  at `packages/a/src/x.ts` stopped resolving. This resolver names the file it
+     *  resolved to in its result, so a suffix resolution is visible and only a file
+     *  that really exists may block it; why()/the pre-edit hook attribute records
+     *  silently and also run for a file about to be created, so they keep the wider
+     *  `isKnownPath`. */
     resolveNodeIds(target: string): string[];
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
@@ -590,9 +626,13 @@ export type StructureView = {
         callers: string[];
         callees: string[];
     }>;
-} | {
+}
+/** `realFile`: the target IS a regular file in the working tree, it just has no
+ *  indexed symbols — a different answer from "no such path" (#334). */
+ | {
     kind: "none";
     target: string;
+    realFile?: boolean;
 };
 export interface StaleRecord {
     kind: string;

package/dist/store/hunchStore.js

@@ -12,7 +12,7 @@
  */
 import { resolve, join, dirname, isAbsolute, relative } from "node:path";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { toPosixTarget, repoRelativeTarget, hunchPathsForDir } from "../core/paths.js";
+import { toPosixTarget, repoRelativeTarget, isRepoFile, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
@@ -1178,6 +1178,31 @@ export class HunchStore {
         }
         return hits;
     }
+    /** The WIDE definition of "is `t` a real path?" — the gate used by the matchers
+     *  that ATTRIBUTE records to a target silently (why(), liveFindingsFor, tasksFor,
+     *  `resolveSymbols` in the MCP server). They also run for a file an agent is
+     *  about to create, where the covering component glob is the only signal there
+     *  is, so the answer must not depend on the file already being on disk. The
+     *  resolvers that NAME the file they resolved to (resolveNodeIds, structure())
+     *  deliberately use the narrower `isRepoFile` instead.
+     *
+     *  Graph data FIRST (a symbol's exact file, or an indexed component's path glob),
+     *  so a deleted-but-still-indexed path and a time-travel (`asOf`) query answer the
+     *  same as before (issue #299). The working tree is consulted only as a LAST
+     *  resort, for the case the index cannot see: a real file with zero tree-sitter
+     *  symbols and no covering component glob, which otherwise suffix-leaked an
+     *  unrelated same-basename file's records (issue #334). When the working tree is
+     *  unavailable or the file is gone, behaviour is exactly the pre-#334 behaviour.
+     *
+     *  `t` must already be repo-relative (`repoRelativeTarget`). `graph` lets a caller
+     *  that has already narrowed the graph (why()'s `canRead` visibility filter) ask
+     *  the question over exactly the records it may see, rather than all of them. */
+    isKnownPath(t, graph) {
+        const symbols = graph?.symbols ?? this.recs("symbols");
+        const components = graph?.components ?? this.recs("components");
+        return isIndexedPath(t, symbols.map((s) => s.file), components.map((c) => c.paths))
+            || isRepoFile(this.paths.root, t);
+    }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
      *  return only decisions/constraints whose valid-time window contained that
@@ -1202,12 +1227,12 @@ export class HunchStore {
         // it too pulls in every OTHER file that merely shares a basename (issue
         // #299: root index.ts delivered vscode-extension/index.ts's rules and vice
         // versa). "Known to the index" is answered from already-loaded graph data
-        // (a symbol's exact file, or an indexed component's path glob — so a
-        // symbol-less real file still counts as real), never the filesystem: a
-        // deleted-but-still-indexed path must answer the same either way. Suffix
-        // matching stays reserved for a target that is not itself a real indexed
-        // path, e.g. a short/partial reference like "x/scenario.ts".
-        const indexed = isIndexedPath(target, symbols.map((s) => s.file), components.map((c) => c.paths));
+        // first (a symbol's exact file, or an indexed component's path glob — so a
+        // symbol-less indexed file still counts as real), and only then from the
+        // working tree, for a real file the index cannot see at all (issue #334).
+        // See isKnownPath. Suffix matching stays reserved for a target that is not
+        // itself a real path, e.g. a short/partial reference like "x/scenario.ts".
+        const indexed = this.isKnownPath(target, { symbols, components });
         const suffixMatch = (file) => !indexed && pathsRelated(file, target);
         const matchedSymbols = matchSymbolsTiered(target, symbols, indexed);
         const symIds = new Set(matchedSymbols.map((s) => s.id));
@@ -1335,10 +1360,23 @@ export class HunchStore {
         return c?.v ?? id;
     }
     /** Resolve a free-form target (symbol id / name / file path, component id / name)
-     *  to graph node ids — symbols win over components, exact file before suffix. */
+     *  to graph node ids — symbols win over components, exact file before suffix.
+     *  Shares why()/resolveSymbols' tiered matcher rather than one un-tiered SQL OR:
+     *  the flat query matched every tier at once, so a root `index.ts` also returned
+     *  `a/index.ts`'s symbols, and an absolute target matched nothing at all (#335).
+     *
+     *  The suffix gate here is `isRepoFile`, NOT the wider `isKnownPath`: the
+     *  exact-file tier has already run, so the only case left is a real on-disk file
+     *  with zero symbols (#334). Glob coverage alone would wrongly block a target
+     *  that no file actually carries — with a `src/**` component, `src/x.ts` living
+     *  at `packages/a/src/x.ts` stopped resolving. This resolver names the file it
+     *  resolved to in its result, so a suffix resolution is visible and only a file
+     *  that really exists may block it; why()/the pre-edit hook attribute records
+     *  silently and also run for a file about to be created, so they keep the wider
+     *  `isKnownPath`. */
     resolveNodeIds(target) {
-        const t = toPosixTarget(target);
-        const sym = this.db.prepare(`SELECT id FROM symbols WHERE id = ? OR name = ? OR file = ? OR file LIKE ? LIMIT 20`).all(t, t, t, `%/${t}`);
+        const t = repoRelativeTarget(target, this.paths.root);
+        const sym = matchSymbolsTiered(t, this.recs("symbols"), isRepoFile(this.paths.root, t)).slice(0, 20);
         if (sym.length)
             return sym.map((r) => r.id);
         const cmp = this.db.prepare(`SELECT id FROM components WHERE id = ? OR name = ? LIMIT 5`).all(t, t);
@@ -1395,10 +1433,27 @@ export class HunchStore {
                 dirs: [...dirs.entries()].map(([dir, v]) => ({ dir, ...v })).sort((a, b) => b.symbols - a.symbols),
             };
         }
-        const t = toPosixTarget(target.trim()).replace(/\/+$/, "");
+        // An absolute target (an agent's edit-payload path, verbatim) never matched the
+        // repo-relative stored file paths below and fell all the way to "none" (#335).
+        const t = repoRelativeTarget(target.trim(), this.paths.root).replace(/\/+$/, "");
         // FILE: exact path or unique suffix
         const fileRows = this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(t);
-        const fileHit = fileRows.length ? t : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
+        // Only the SUFFIX fallback is gated, and by `isRepoFile` rather than the wider
+        // `isKnownPath`: the exact-path tier above has already run, so the only case
+        // left is a real on-disk file with zero symbols, whose outline must not come
+        // from an unrelated same-basename file (#334). Glob coverage alone is not
+        // existence — with a `src/**` component, `src/x.ts` living at
+        // `packages/a/src/x.ts` would stop resolving. structure() names the file it
+        // resolved to, so a suffix resolution is visible and only a file that really
+        // exists may block it; why()/the pre-edit hook attribute records silently and
+        // also run for a file about to be created, so they keep `isKnownPath`.
+        // Directory targets are unaffected — a directory is never an `isRepoFile`
+        // (regular files only), so they keep flowing to the dir tier below.
+        const fileHit = fileRows.length
+            ? t
+            : isRepoFile(this.paths.root, t)
+                ? []
+                : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
         const file = typeof fileHit === "string" ? fileHit : fileHit.length === 1 ? fileHit[0] : null;
         if (file) {
             const syms = fileRows.length ? fileRows : this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(file);
@@ -1427,7 +1482,10 @@ export class HunchStore {
                 matches: named.map((m) => ({ ...m, callers: this.edgeNeighbors(m.id, "in", 6), callees: this.edgeNeighbors(m.id, "out", 6) })),
             };
         }
-        return { kind: "none", target: t };
+        // A real on-disk file with zero indexed symbols reaches "none" too (#334). Flag
+        // it so the renderer doesn't tell the user it isn't a known file when we just
+        // stat'd it.
+        return { kind: "none", target: t, ...(isRepoFile(this.paths.root, t) ? { realFile: true } : {}) };
     }
     /** Labelled one-hop edge neighbors of a node ("in" = who reaches it, "out" = what it reaches). */
     edgeNeighbors(id, dir, limit) {
@@ -1464,7 +1522,7 @@ export class HunchStore {
         // that merely shares a basename. Normalize once and reuse the same "is this
         // path known to the index" guard.
         const t = repoRelativeTarget(scope, this.paths.root);
-        const indexed = isIndexedPath(t, this.recs("symbols").map((s) => s.file), this.recs("components").map((c) => c.paths));
+        const indexed = this.isKnownPath(t);
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
         return this.recs("findings")
             .filter(live)
@@ -1476,9 +1534,9 @@ export class HunchStore {
      *  denied edits), newest first. Graph memory, so it spans machines and survives
      *  the local ledger's retention window. */
     tasksFor(scope, limit = 8) {
-        // Same normalization + indexed-suffix guard as liveFindingsFor/why() (issue #299).
+        // Same normalization + known-path suffix guard as liveFindingsFor/why() (issue #299).
         const t = repoRelativeTarget(scope, this.paths.root);
-        const indexed = isIndexedPath(t, this.recs("symbols").map((s) => s.file), this.recs("components").map((c) => c.paths));
+        const indexed = this.isKnownPath(t);
         return this.recs("tasks")
             .filter((r) => r.files.some((f) => pathMatchesGlob(t, f) || pathMatchesGlob(f, t) || (!indexed && pathsRelated(toPosixTarget(f), t))))
             .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))

package/dist/store/stateBinding.js

@@ -1036,7 +1036,7 @@ export function subscribeState(store, input, options = {}) {
     const access = createStateAccess(store, request.principal, options);
     const visibilityFiltered = ledger.events.some(e => e.visibility !== undefined) || access.restricted;
     const filtered = !!(facets || subjects || visibilityFiltered);
-    const resync = request.after_seq < ledger.floor_seq;
+    const resync = request.after_seq < ledger.floor_seq || request.after_seq > ledger.head_seq;
     const after = resync ? ledger.floor_seq : request.after_seq;
     const events = ledger.events.filter((e) => e.seq > after
         && (!visibilityFiltered || (visibilityAllows(e, request.principal.id) && access.canRead(findRecord(store, e.record_id)?.record) && access.referencesVisible(e)))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.39.3",
+  "version": "1.40.1",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.39.3",
+  "version": "1.40.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.39.3",
+      "version": "1.40.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {