@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/store/hunchStore.js

@@ -1341,8 +1341,8 @@ export class HunchStore {
      *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) never matched
-        // the repo-relative stored file paths below (issue #299).
+        // An agent's verbatim edit-payload path is absolute; stored paths are
+        // repo-relative, so rewrite before any matching (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         // A record id (every delivered brief line ends in `hunch_why("dec_…")`) resolves
         // to that record directly (issue #474). With `asOf`, a record not in force then
@@ -1350,8 +1350,10 @@ export class HunchStore {
         const lookup = WHY_RECORD_ID.test(target) ? this.whyRecord(target, opts.canRead, opts.asOf) : undefined;
         if (lookup?.record)
             return { target, decisions: [], bugs: [], constraints: [], symbols: [], components: [], byId: lookup };
-        // A miss is reported only for a generated-shape id; anything else resolves as before.
-        const byId = lookup && WHY_GENERATED_ID.test(target) ? lookup : undefined;
+        // A miss is reported for a generated-shape id, or for any id on file that was not
+        // in force at `asOf` (issue #493); anything else resolves as before.
+        const byId = lookup && (WHY_GENERATED_ID.test(target) || (opts.asOf && this.whyRecord(target, opts.canRead).record))
+            ? lookup : undefined;
         const decisions = this.recs("decisions").filter(opts.canRead ?? (() => true));
         const bugs = this.recs("bugs").filter(opts.canRead ?? (() => true));
         const constraints = this.recs("constraints").filter(opts.canRead ?? (() => true));
@@ -1362,11 +1364,11 @@ export class HunchStore {
         // so an unanchored suffix pulled unrelated files' records into why()/the
         // pre-edit grounding block (issue #32). Segment-anchored matching only.
         //
-        // A target that IS a path Hunch's index already knows about (README.md,
-        // vscode-extension/index.ts, ...) names exactly one file — suffix-matching
-        // 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 target that is a path the index already knows (README.md,
+        // `vscode-extension/index.ts`) names exactly ONE file. Suffix-matching it too
+        // would pull in every other file sharing its basename (issue #299: root
+        // `index.ts` received `vscode-extension/index.ts`'s rules and vice versa). "Known
+        // to the index" is answered from already-loaded graph data, looked up
         // 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).
@@ -1446,7 +1448,8 @@ export class HunchStore {
     }
     /** Transitive blast radius: every symbol/component that (in)directly depends on
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
-     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
+     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains,
+     *  plus `references` — the only edge YAML/Helm/Kustomize emit (issue #486). */
     getDependents(id, maxDepth = 6) {
         return this.db.prepare(
         /* sql */ `
@@ -1455,7 +1458,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT up.node AS id, MIN(up.depth) AS depth,
              COALESCE(s.name || ' @ ' || s.file, c.name, up.node) AS via
@@ -1497,7 +1500,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT s.file AS file, s.name AS via, MIN(up.depth) AS depth
       FROM up JOIN symbols s ON s.id = up.node
@@ -1693,9 +1696,8 @@ export class HunchStore {
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
      *  that instant (time-travel: "what must I not have broken as of commit X?"). */
     checkConstraints(scope, opts = {}) {
-        // Constraint scopes are always repo-relative; an absolute target (an
-        // agent's edit-payload path, verbatim) matched nothing even when a
-        // blocking rule plainly applied (issue #296).
+        // Scopes are repo-relative; an absolute target matched nothing even when a
+        // blocking rule applied (issue #296).
         scope = repoRelativeTarget(scope, this.paths.root);
         const all = this.recs("constraints");
         const asOf = opts.asOf;
@@ -1710,11 +1712,8 @@ export class HunchStore {
      *  glob, and the queried scope may be either too. Advisory only — findings never
      *  enter any block path. Sorted worst-first, then id for stable output. */
     liveFindingsFor(scope) {
-        // Same absolute-target and same-basename-leak gaps as why() (issue #299): an
-        // un-rewritten absolute scope never matched the repo-relative `affected_files`
-        // below, and an un-guarded suffix fallback could pull in an unrelated file
-        // that merely shares a basename. Normalize once and reuse the same "is this
-        // path known to the index" guard.
+        // Same absolute-target and same-basename-leak gaps as why() (issue #299):
+        // normalize once and reuse the known-path guard.
         const t = repoRelativeTarget(scope, this.paths.root);
         const indexed = this.isKnownPath(t);
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
@@ -2337,9 +2336,7 @@ export class HunchStore {
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
     assembleContext(target, budget = 1500, opts = {}) {
-        // An absolute target (an agent's edit-payload path, verbatim) must be
-        // repo-relative BEFORE it reaches why()/liveFindingsFor() below, or an
-        // absolute path never matches the repo-relative stored data (issue #299).
+        // Normalize before it reaches why()/liveFindingsFor() below (issue #299).
         target = repoRelativeTarget(target, this.paths.root);
         const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);

package/dist/store/jsonStore.d.ts

@@ -126,12 +126,22 @@ export declare class JsonStore {
      *  overlay. Returns the number of files removed. Invalidates the memoized load. */
     dropAll(kind: EntityKind): number;
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
-     *  A record that still fails validation after migration is kept untouched (never
-     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
-     *  bumps the manifest afterward. */
+     *  A record that still fails validation after migration (or whose migration
+     *  throws) is kept in its ORIGINAL shape (never deleted, never half-migrated) and
+     *  counted as `skipped`, so migration can't lose data. The caller stamps the
+     *  manifest at the returned `version`: SCHEMA_VERSION only when nothing was
+     *  skipped, else the FROM version, so a manual fix plus a rerun re-applies the
+     *  (idempotent) migrations to the skipped records instead of skipping them.
+     *  A bad record of a kind NO pending migration touches can't be fixed by a
+     *  rerun, so it is counted as `invalid` instead and doesn't hold the version. */
     persistMigration(): {
         migrated: number;
         skipped: number;
+        invalid: number;
+        version: number;
     };
+    /** Migrate + validate one raw record for persistMigration; a throwing migration
+     *  step counts as a failure, so the record stays in its original shape. */
+    private tryMigrate;
 }
 export {};

package/dist/store/jsonStore.js

@@ -8,7 +8,7 @@ import { randomBytes } from "node:crypto";
 import { hostname } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
-import { BASELINE_VERSION, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
+import { BASELINE_VERSION, hasPendingMigration, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
 import { writeFileAtomic } from "../core/io.js";
 import { readStoreArtifact } from "../core/storeArtifact.js";
 import { createdAfterLock, heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
@@ -942,19 +942,29 @@ export class JsonStore {
         return names.length;
     }
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
-     *  A record that still fails validation after migration is kept untouched (never
-     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
-     *  bumps the manifest afterward. */
+     *  A record that still fails validation after migration (or whose migration
+     *  throws) is kept in its ORIGINAL shape (never deleted, never half-migrated) and
+     *  counted as `skipped`, so migration can't lose data. The caller stamps the
+     *  manifest at the returned `version`: SCHEMA_VERSION only when nothing was
+     *  skipped, else the FROM version, so a manual fix plus a rerun re-applies the
+     *  (idempotent) migrations to the skipped records instead of skipping them.
+     *  A bad record of a kind NO pending migration touches can't be fixed by a
+     *  rerun, so it is counted as `invalid` instead and doesn't hold the version. */
     persistMigration() {
         let migrated = 0;
         let skipped = 0;
+        let invalid = 0;
         this.cache.clear(); // every record is rewritten; drop all memoized loads
         const version = this.schemaVersion(); // read once; we're migrating FROM this
         for (const kind of ENTITY_KINDS) {
             const directory = this.safeKindDirectory(kind, false);
             if (!directory)
                 continue;
-            const schema = SCHEMAS[kind];
+            const pending = hasPendingMigration(kind, version);
+            const fail = () => { if (pending)
+                skipped++;
+            else
+                invalid++; };
             const single = SINGLE_FILE[kind];
             if (single) {
                 const f = join(directory.lexical, single);
@@ -966,23 +976,23 @@ export class JsonStore {
                     arr = JSON.parse(text);
                 }
                 catch {
-                    skipped++;
+                    fail();
                     continue;
                 }
                 if (!Array.isArray(arr)) {
-                    skipped++;
+                    fail();
                     continue;
                 }
                 const kept = [];
                 for (const raw of arr) {
-                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    const r = this.tryMigrate(kind, raw, version);
                     if (r.success) {
                         kept.push(r.data);
                         migrated++;
                     }
                     else {
                         kept.push(raw); // preserve unmigratable records rather than drop them
-                        skipped++;
+                        fail();
                     }
                 }
                 this.writeContainedFile(directory, f, encode(kept), this.maxBytes(kind));
@@ -995,24 +1005,38 @@ export class JsonStore {
                         const text = this.readContainedFile(directory, p, this.maxBytes(kind));
                         if (text === null)
                             continue;
+                        // A 0-byte merge-driver tombstone holds no record (issue #37) — the
+                        // loader's rule; counting it would pin the manifest version forever.
+                        if (text.trim() === "")
+                            continue;
                         raw = JSON.parse(text);
                     }
                     catch {
-                        skipped++;
+                        fail();
                         continue;
                     }
-                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    const r = this.tryMigrate(kind, raw, version);
                     if (r.success) {
                         this.writeContainedFile(directory, p, encode(r.data), this.maxBytes(kind));
                         migrated++;
                     }
                     else {
-                        skipped++; // leave the file as-is
+                        fail(); // leave the file as-is
                     }
                 }
             }
         }
-        return { migrated, skipped };
+        return { migrated, skipped, invalid, version: skipped ? version : SCHEMA_VERSION };
+    }
+    /** Migrate + validate one raw record for persistMigration; a throwing migration
+     *  step counts as a failure, so the record stays in its original shape. */
+    tryMigrate(kind, raw, version) {
+        try {
+            return SCHEMAS[kind].safeParse(this.migrate(kind, raw, version));
+        }
+        catch {
+            return { success: false };
+        }
     }
 }
 //# sourceMappingURL=jsonStore.js.map

package/dist/store/stateBinding.js

@@ -795,15 +795,21 @@ function writeStateAuthorized(store, input, opts, access) {
         // land its `superseded` event in THIS ledger, invisible to that partition's subscribers.
         if (!inScope(supersededRecord))
             throw new StateRefusal("conflict", `supersedes ${request.supersedes} is on record in ${scopePath(recordScope(supersededRecord, repo))}, not ${scopePath(request.scope)}: a write supersedes only a record in its own partition`, { incumbent_id: String(supersededRecord.id), reason: "supersede target in another partition" });
+        const matches = typeof request.expected_version === 'number'
+            ? latestSeqFor(ledger, String(supersededRecord.id)) === request.expected_version
+            : request.expected_version === stateHash(supersededRecord);
         if (stateHash(supersededVisibility ?? null) !== stateHash(nextVisibility ?? null)) {
             if (supersededVisibility ? supersededVisibility.owner !== request.principal.id : request.principal.kind !== 'human')
                 deny();
-            const matches = typeof request.expected_version === 'number'
-                ? latestSeqFor(readLedger(hunchDir, request.scope), String(supersededRecord.id)) === request.expected_version
-                : request.expected_version === stateHash(supersededRecord);
-            if (!matches)
+            if (request.expected_version === null)
                 throw new StateRefusal('malformed', 'changing visibility during supersession requires the predecessor expected_version');
         }
+        // A supersession's expected_version names the predecessor (#510): a stale one is a conflict.
+        if (request.expected_version !== null && !matches)
+            throw new StateRefusal("conflict", `expected_version does not match the superseded ${supersededRecord.id}`, { incumbent_id: String(supersededRecord.id), reason: "expected_version mismatch" });
+    }
+    else if (request.supersedes && request.expected_version !== null) {
+        throw new StateRefusal("conflict", `expected_version names ${request.supersedes}, which is not on record`, { incumbent_id: request.supersedes, reason: "expected_version without incumbent" });
     }
     if (!incumbent && !supersededRecord && nextVisibility?.owner !== undefined && nextVisibility.owner !== request.principal.id)
         deny();
@@ -873,6 +879,13 @@ function writeStateAuthorized(store, input, opts, access) {
         if (!ok)
             throw new StateRefusal("conflict", `expected_version does not match the incumbent ${id}`, { incumbent_id: id, reason: "expected_version mismatch" });
     }
+    // Compare-and-swap with no incumbent (#510): a writer naming a version believes a record exists,
+    // so a fresh create under it is a stale read, never silently accepted. Numeric 0 is the ledger's
+    // "never seen" and asserts absence; a supersession's expected_version names its predecessor.
+    if (!existing && request.expected_version !== null && !request.supersedes
+        && !(typeof request.expected_version === "number" && latestSeqFor(ledger, id) === request.expected_version)) {
+        throw new StateRefusal("conflict", `expected_version ${JSON.stringify(request.expected_version)} names a version, but ${id} has none on record: pass null to create it (0 asserts the id was never written)`, { incumbent_id: id, reason: "expected_version without incumbent" });
+    }
     if (replayLink) {
         const recordHash = stateHash(replayLink);
         appendChanges(hunchDir, request.scope, missingEventFor(ledger, facet, replayLink, request.principal.id), { key: request.idempotency_key, entry: { record_id: replayLink.id, record_hash: recordHash, payload_hash: hash, facet } }, now, opts.ledgerCache?.ledger);

package/dist/synthesis/provider.d.ts

@@ -111,8 +111,9 @@ export interface SynthProvider {
 }
 /** Every selectable synthesis mode. `auto` is a preference value rather than a
  * provider: it resolves the invocation's origin without choosing by availability.
- * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
- * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+ * "openai-compat" is the opt-in local or self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio and so on). It is not a subscription, but it can be selected
+ * explicitly like one. */
 export declare const SYNTH_PROVIDER_NAMES: readonly ["claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export declare const SYNTH_PREFERENCES: readonly ["auto", "claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export type SynthProviderName = (typeof SYNTH_PROVIDER_NAMES)[number];
@@ -172,8 +173,11 @@ export declare function safeModel(v: string | undefined, fallback: undefined): s
  * the explicit skip flag preserves that neutral-cwd isolation without loading a
  * target repo's agent rules or MCP configuration. */
 export declare function codexExecArgs(model?: string): string[];
+/** Sanitize HUNCH_SYNTH_TIMEOUT_MS: a finite number > 0, else `fallback`. */
 export declare function safeTimeout(v: string | undefined, fallback: number): number;
+/** Sanitize HUNCH_SYNTH_MAX_TOKENS: a finite number > 0, else `fallback`. */
 export declare function safeMaxTokens(v: string | undefined, fallback: number): number;
+/** True only when the user explicitly opted in to public (possibly metered) hosts. */
 export declare function meteredHostsAllowed(env?: NodeJS.ProcessEnv): boolean;
 export declare class OpenAICompatProvider extends PromptSynthProvider {
     readonly name = "openai-compat";
@@ -182,9 +186,10 @@ export declare class OpenAICompatProvider extends PromptSynthProvider {
 }
 /** Best-effort: does the configured openai-compat endpoint look like Ollama with
  *  an UNSET num_ctx? Returns
- *  an advisory warning string when so, or null when the endpoint isn't reachable,
- *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
- *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  a warning string when the model does not pin num_ctx, or null when the
+ *  endpoint is unreachable, does not look like Ollama's /api/show response shape,
+ *  or already has num_ctx set. Diagnostics only: it never throws and never blocks.
+ *  Deliberately does NOT try to
  *  report the model's effective context length: modern Ollama defaults may come
  *  from server configuration or VRAM tiers, and model_info keys are not a stable
  *  parse target. We therefore report only the observed fact — whether num_ctx is
@@ -203,19 +208,12 @@ export declare class DeterministicProvider implements SynthProvider {
  *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
  *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
 export declare function extractCodexText(out: string): string;
-/** Test-only: clears the availability memoization cache so a test that toggles
- *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
- *  cached by an earlier call in the same process. Never call from production code. */
+/** Test-only: empty the availability cache so a test that changes env vars
+ *  mid-process is not served a stale cached result. */
 export declare function __resetAvailabilityCacheForTests(): void;
-/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
- *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
- *  server can implement), but Ollama is the most common self-hosted target and
- *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
- *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
- *  command (index.ts) normalizes it the same way before validating/persisting a
- *  local preference — the two paths must agree, or a user who sets one and reads
- *  the other back gets a confusing "unknown provider" message for a name that
- *  actually works. */
+/** The provider is not Ollama-specific, but Ollama is the name users try first, so
+ *  "ollama" is an alias for "openai-compat". The env var and `hunch provider <name>`
+ *  both normalize through here so the two paths agree. */
 export declare function normalizeProviderName(v: string | undefined): string | undefined;
 /** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
  * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
@@ -258,10 +256,10 @@ export declare class EnsembleProvider implements SynthProvider {
 export declare function selectEnsemble(opts?: ProviderSelectionOptions & {
     samples?: number;
 }): Promise<EnsembleProvider | null>;
-/** Pick a provider to run the Critic pass — the same resolved provider normal
- *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
- *  honoring the same env/local-preference/auto policy. Returns null when that
- *  resolves to the deterministic fallback — verification then no-ops and the
+/** Pick the provider for the Critic pass: the same resolved provider normal
+ *  synthesis would use (a subscription CLI or the opt-in openai-compat endpoint),
+ *  under the same env / local-preference / auto policy. Returns null when that
+ *  resolves to the deterministic fallback, in which case verification does nothing. The
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
 export declare function selectVerifier(opts?: ProviderSelectionOptions): Promise<SynthProvider | null>;
 /** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the