@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/store/hunchStore.d.ts

@@ -0,0 +1,624 @@
+import { type HunchPaths } from "../core/paths.js";
+import { type Component, type Constraint, type Bug, type Decision, type Symbol, type Edge, type Finding, type EntityKind, type EntityFor } from "../core/types.js";
+import { type DB } from "./db.js";
+import { type Embedder } from "./embedder.js";
+import { JsonStore } from "./jsonStore.js";
+import { type VetoTier } from "../core/strictgate.js";
+import { type DiffAnalysis } from "../extractors/diff.js";
+import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
+import { type ReviewedLandscapeSelection } from "../core/landscapeDelivery.js";
+import { type StateSlice } from "../core/stateDelivery.js";
+export interface SearchHit {
+    ref: string;
+    kind: string;
+    title: string;
+    snippet: string;
+    score: number;
+}
+export interface HybridSearchOpts {
+    embedder?: Embedder | null;
+    graphWeight?: number;
+    graphDepth?: number;
+    graphNodeCap?: number;
+    graphTokenCap?: number;
+    /** Repository whose HEAD/file history proves decision-anchor freshness. Defaults to this store's root. */
+    freshnessRoot?: string;
+}
+export interface RankedSearchOpts {
+    /** Repository whose HEAD/file history proves decision-anchor freshness. Defaults to this store's root. */
+    freshnessRoot?: string;
+}
+export type OverlayResolutionSource = "environment" | "local-config" | null;
+export interface OverlayOverride {
+    /** Repo/worktree-local target that would have won without the environment override. */
+    configuredDir: string;
+    /** Process-global target selected by HUNCH_PRIVATE_DIR. */
+    environmentDir: string;
+}
+export interface WhyResult {
+    target: string;
+    decisions: Decision[];
+    bugs: Bug[];
+    constraints: Constraint[];
+    symbols: Symbol[];
+    components: Component[];
+}
+export interface FragileNode {
+    id: string;
+    file: string;
+    name: string;
+    score: number;
+    churn_90d: number;
+    bug_count: number;
+    fan_in: number;
+    evidence: string[];
+}
+export declare class HunchStore {
+    private readonly paths;
+    readonly json: JsonStore;
+    /** Optional PRIVATE overlay (HUNCH_PRIVATE_DIR) — a second store in a repo the
+     *  user controls. Unioned into reads via recs(); never written by public paths. */
+    private readonly privateJson?;
+    /** The resolved private-overlay hunch dir (from env or .hunch/local.json), or undefined
+     *  when no overlay is configured. Surfaced so `hunch doctor` reflects the true state. */
+    readonly privateDir?: string;
+    /** How privateDir was selected. Multi-store consumers can use this instead of
+     *  inferring process-global routing from process.env. */
+    readonly overlaySource: OverlayResolutionSource;
+    /** Present only when HUNCH_PRIVATE_DIR redirects this store away from the
+     *  repo/worktree-local pointer. Precedence is compatibility-sensitive and stays
+     *  env-first; making the redirection queryable removes the silent footgun. */
+    readonly overlayOverride?: OverlayOverride;
+    /** Whether captures auto-commit the store they land in — ON by default in EVERY mode;
+     *  `--no-auto-commit` (hunch init/private/shared) persists `autoCommit: false` in
+     *  local.json to opt out. Read by the MCP write tools and `hunch sync`. */
+    readonly autoCommit: boolean;
+    /** How memory is homed: "public" (no overlay — the repo-tracked .hunch/ is the one store),
+     *  "private" (overlay holds ONLY private:true records; public records stay committed here),
+     *  or "shared" (the overlay IS the store — every capture routes there, one source of truth
+     *  across branches, worktrees, teammates, and agents). Absent `mode` in an existing
+     *  config reads as "private" — no behavior change on upgrade. */
+    readonly mode: "public" | "private" | "shared";
+    /** mode === "shared" with a configured overlay: ALL captures route to the overlay. */
+    readonly unified: boolean;
+    /** autoCommit AND a private overlay is configured: private writes auto commit+push the
+     *  overlay repo. (Public writes auto-commit the repo-tracked .hunch/ WITHOUT pushing —
+     *  see commitAndPushHunch push:false / bug_overlay_clobber.) */
+    readonly privateAutoCommit: boolean;
+    /** When true, recs() ignores the private overlay (public-only). Set transiently by
+     *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
+     *  can never render a private record — a publicly-posted output is a leak surface
+     *  equal to a committed file (dec_d7bad4ccb7). */
+    private suppressPrivate;
+    private _db;
+    /** HEAD-keyed, process-local ranking evidence. It never changes record authority or storage. */
+    private decisionFreshnessRoot;
+    private decisionFreshnessHead;
+    private readonly decisionFreshnessScopes;
+    private readonly decisionFreshnessChanges;
+    constructor(paths: HunchPaths);
+    /** Human-facing warning for the compatibility-preserving env-first resolution.
+     *  Callers decide where it is safe to emit (CLI/MCP stderr, doctor output); the
+     *  store constructor stays side-effect-free for hooks and embedded consumers. */
+    overlayResolutionWarning(teamConfigBypassed?: boolean): string | null;
+    /** Where a capture belongs: an explicit private:true always goes to the overlay
+     *  (putPrivate throws rather than silently landing public when none is configured);
+     *  otherwise the overlay in unified ("shared") mode, else the public store. ONE home
+     *  per record — the single-source-of-truth contract. */
+    captureHome(isPrivate?: boolean): "private" | "public";
+    /** Write a capture to its ONE home (see captureHome). Every capture path — MCP tools,
+     *  post-commit synthesis, inline intents, record-constraint/conform, runbooks — funnels
+     *  through here so all modes, branches, worktrees, teams, and agents agree on where
+     *  memory lives. */
+    putCapture<K extends EntityKind>(kind: K, record: EntityFor[K], isPrivate?: boolean): EntityFor[K];
+    /** Replace one capture kind in its routed home as a single bulk operation.
+     *
+     * Snapshot producers use this instead of calling putCapture once per record.
+     * That distinction is material for array-backed graph kinds: repeated puts
+     * parse, sort, and atomically rewrite the complete index for every symbol or
+     * edge, while JsonStore.replaceAll validates the full input before performing
+     * one write. Routing and cross-home collision rules remain identical to an
+     * ordinary capture, so the optimization cannot create a second source of truth.
+     */
+    replaceCaptures<K extends EntityKind>(kind: K, records: EntityFor[K][], isPrivate?: boolean): void;
+    /** Read a record by id from wherever it lives (private overlay wins on collision). */
+    getRec<K extends EntityKind>(kind: K, id: string): EntityFor[K] | undefined;
+    /** Read a record only from the configured private overlay. Callers that must
+     *  preserve privacy boundaries (for example, an explicit `--private` repair)
+     *  should use this instead of overlay-first `getRec`. */
+    getPrivateRec<K extends EntityKind>(kind: K, id: string): EntityFor[K] | undefined;
+    getStateDirect<K extends "derived" | "receipts" | "commitments">(kind: K, id: string, home: "public" | "private"): EntityFor[K] | undefined;
+    /** Update an EXISTING record in the store that holds it — an overlay record must never
+     *  fork a public copy on update (and vice versa). Falls back to captureHome routing for
+     *  a record that exists nowhere yet. */
+    putWhereItLives<K extends EntityKind>(kind: K, record: EntityFor[K]): EntityFor[K];
+    /** Delete an existing record from its actual home. The review/curation path
+     * uses this so rejecting a private draft cannot silently leave it behind or
+     * accidentally target a public record with the same id. */
+    deleteWhereItLives<K extends EntityKind>(kind: K, id: string): boolean;
+    /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
+     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash.
+     *  `autoCommit` is tri-state: true/false when the file says so, undefined when unset.
+     *  `mode` records HOW the overlay was set up ("private" split vs "shared" unified). */
+    private localConfig;
+    /** Merged read: public ∪ private overlay (private wins on id collision). Every
+     *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-
+     *  artifact writers keep using this.json.loadAll (public-only) so a private record
+     *  can never reach a committed file — see dec_d7bad4ccb7. */
+    recs<K extends EntityKind>(kind: K): EntityFor[K][];
+    /** Records for an AGENT-FACING advisory surface (escalations, orientation).
+     *
+     *  In unified ("shared") mode the overlay IS the one store — the public `.hunch/` is
+     *  only a routing shell — so reading the public home alone returns NOTHING and the
+     *  surface reports "all clear" for a store whose every record is elsewhere. That is
+     *  the worst possible answer for escalations, whose entire job is to raise the
+     *  questions only a human can settle: a real topic collision came back as an empty
+     *  list and the agent was affirmatively told there was nothing to escalate.
+     *
+     *  In "private" mode the split is a real privacy boundary, so this stays public-only:
+     *  private records must not surface on a public advisory surface. Mode-aware, not a
+     *  blanket union — the distinction is the point. */
+    advisoryRecs<K extends EntityKind>(kind: K): EntityFor[K][];
+    /** Records from exactly one storage home (no public/private union). Capture
+     * paths use this for identity/lineage checks so a private record can never
+     * inherit or disclose relationships from an identically-shaped public record. */
+    recsInHome<K extends EntityKind>(kind: K, home: "public" | "private"): EntityFor[K][];
+    /** Whether a private overlay store is configured (HUNCH_PRIVATE_DIR is set). */
+    get hasPrivate(): boolean;
+    /** Public project root protected from private-overlay commit/push operations. */
+    get publicRoot(): string;
+    /** Write a record into the PRIVATE overlay (never the public repo). Throws if no
+     *  HUNCH_PRIVATE_DIR is configured, so a "private" write can never silently land
+     *  in the public `.hunch/`. */
+    putPrivate<K extends EntityKind>(kind: K, record: EntityFor[K]): EntityFor[K];
+    get db(): DB;
+    close(): void;
+    /** Revision marker for every JSON source currently visible to this store.
+     *  SQLite/FTS is derived state; long-lived consumers compare this marker with
+     *  the marker captured only after a successful rebuild. */
+    sourceStamp(): string;
+    /** Rebuild from fresh disk reads after an out-of-process Git pull or capture.
+     *  Normal in-process writes invalidate their own kind cache; cross-process
+     *  refreshes clear both homes explicitly so schema-only changes are included. */
+    reindexFresh(): {
+        counts: Record<string, number>;
+    };
+    /** Rebuild the entire SQLite index + FTS from the JSON source of truth. */
+    reindex(): {
+        counts: Record<string, number>;
+    };
+    /** FTS5 ranked search — the RAW bm25 primitive, no priors. Callers wanting
+     *  relevance ordering (liveness/provenance/recency + topic-chain promotion)
+     *  go through hybridSearch/searchScoped, where rerankByPriors applies.
+     *  Falls back to LIKE if the query has no FTS-tokenizable terms. */
+    search(query: string, limit?: number): SearchHit[];
+    /** State-of-record ordering for nuryel.state/1 hits (superseded derived, done/cancelled
+     *  commitments, failed receipts, retired entities): indexed and findable, but ranked BELOW
+     *  the live record of the same subject. bm25 is negative (lower = better), so a history
+     *  hit's score is scaled toward 0 by STATE_HISTORY_SCORE_FACTOR and the pool is re-sorted
+     *  STABLY by score — a store with no state history returns the exact SQL order, and a
+     *  LIKE-fallback pool (all scores 0) is partitioned live-first in its existing order.
+     *  Bounded (a dimmer, not an exclusion) so the previous summary stays reachable one query
+     *  away; hybridSearch/rankedSearch additionally apply the liveness prior via priorMeta. */
+    private demoteHistoricalState;
+    /** Liveness + clock for a state hit (null for every non-state kind). */
+    private stateMeta;
+    /** The bounded "State" slice for a context brief (hunch_context / `hunch context`): the
+     *  current derived summaries, in-force commitments and latest verified receipts whose
+     *  subject or text matches `target`. Matching is AND over the target's tokens (every token
+     *  must appear, prefix-tolerant) so a file path such as src/store/x.ts never drags in a
+     *  summary that merely mentions "store"; an exact subject match always qualifies. Order is
+     *  deterministic: score (best first), then observed_at DESC, then id. Caps per kind are
+     *  STATE_SLICE_CAPS. A store with no state records returns three empty lists. */
+    stateSlice(target: string): StateSlice;
+    /** AND-shaped FTS over one state kind (every token required, prefix-tolerant); degrades to
+     *  the kind-scoped LIKE scan (OR-shaped — the caller re-checks AND) without FTS5. */
+    private stateFts;
+    /** Portable bounded fallback over titles/bodies. Each natural-language token
+     * is an OR candidate, mirroring the high-recall FTS query closely enough for
+     * runtimes whose SQLite build omits the optional FTS5 module.
+     *
+     * `_` is BOTH a LIKE single-character wildcard and the dominant character in this
+     * codebase's identifiers (dec_/con_/bug_ ids, snake_case symbols). The old code
+     * STRIPPED it, so a search for `hunch_record_decision` looked for the literal
+     * `hunchrecorddecision` and matched nothing — on precisely the runtimes with no FTS5,
+     * where this fallback is the only search there is. Escaping keeps the term literal;
+     * leaving `_` unescaped would silently over-match instead. */
+    private likeSearch;
+    /** The exact (ref, kind, title, body) docs that feed FTS — and thus embeddings.
+     *  A single source so FTS, the doc_hash, and the stored vectors never disagree. */
+    private searchDocs;
+    /** Delete embedding rows whose source doc was removed or whose text changed
+     *  (doc_hash mismatch). Model-free and cheap; run at the end of every reindex()
+     *  so vectors track the JSON truth without ever being reset. Returns the count. */
+    pruneStaleEmbeddings(): number;
+    /** Embedding coverage for a model: up-to-date vectors vs total docs (doctor). */
+    embeddingStats(model: string): {
+        embedded: number;
+        total: number;
+    };
+    /** The SINGLE gate for "can semantic search run right now": an embedder exists and
+     *  it has at least one stored vector. Used by both hybridSearch and the CLI so the
+     *  definition can't drift between them. */
+    semanticReady(embedder: Embedder | null): embedder is Embedder;
+    /** Generate/refresh embeddings for every doc missing an up-to-date vector for
+     *  this embedder's model. Batched + flushed per batch so a Ctrl-C leaves a
+     *  coherent partial index that a re-run resumes. Assumes reindex() ran first. */
+    embedAll(embedder: Embedder, opts?: {
+        batch?: number;
+        onProgress?: (done: number, total: number) => void;
+    }): Promise<{
+        embedded: number;
+        skipped: number;
+        total: number;
+    }>;
+    /** Post-fusion rerank by graph PRIORS (dec_25e277f479): relevance ordering, not
+     *  just reachability. Trust weight w = liveness × provenance × recency: liveness 0.6
+     *  for superseded/retired/rejected, provenance 1.0 / 0.85 / 0.75 for
+     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d),
+     *  and proven anchored-file staleness 0.8. Every factor is ranking-only.
+     *  Runbook trigger phrases matching the query boost ×1.5 (exact intent beats
+     *  keyword luck). Structural refs (symbols/components/edges) stay neutral.
+     *
+     *  The prior is applied as a BOUNDED POSITIONAL SHIFT, not as a multiplier on a
+     *  rank-derived score. That is deliberate and load-bearing. The old form —
+     *  `1/(60+i) × w`, sorted descending, sliced to `limit` — could not keep the
+     *  "dims, never disappears" promise it made: across a fused pool of 24 the
+     *  positional term spans only 1/60…1/83 (a 0.72 ratio) while w spans 0.48…1.0 on
+     *  this repo's own records, so the prior was WIDER than the entire pool's
+     *  positional spread and simply overrode fusion. Worse, `priorMeta` returns null
+     *  for structural refs, which left them at w = 1 — a ceiling above what any record
+     *  that is not both human_confirmed and brand-new can reach. Measured over this
+     *  repo's 152 committed decisions with the rest of the pool structural (symbols are
+     *  ~91% of the corpus): 38% of decisions were dropped from the top-12 even when
+     *  they were the #1 fused hit, and 88% from fused rank 8. Both retrieval layers
+     *  ranked the record first and the rerank alone threw it away.
+     *
+     *  A shift of at most ±MAX_PRIOR_SHIFT positions restores the intended semantics:
+     *  a stale or low-provenance record visibly dims, an exact runbook-trigger match
+     *  visibly promotes, and neither can leapfrog the whole pool. Same measurement
+     *  after: 0% evicted from fused ranks 0–8. Deterministic; ties keep fused order. */
+    private rerankByPriors;
+    /**
+     * Score only freshness that the existing graph clocks can prove: an anchored path changed after
+     * `provenance.last_verified`. One bounded Git pass fills a HEAD-keyed cache for newly encountered
+     * scopes; repeated MCP/CLI queries perform no history walk until HEAD changes.
+     */
+    private staleDecisionIds;
+    /** Fast relevance ranking for task-phrase context fallback: FTS + bounded graph priors, no model. */
+    rankedSearch(query: string, limit?: number, opts?: RankedSearchOpts): SearchHit[];
+    /** The prior-bearing metadata for a hit: liveness, provenance, effective date,
+     *  and (runbooks) trigger phrases. null = structural ref, neutral prior. */
+    private priorMeta;
+    /** Hybrid search (hunch_query / `hunch query --semantic`): FTS bm25 fused with
+     *  cosine over stored embeddings via Reciprocal Rank Fusion. Degrades to pure
+     *  sync FTS (zero added latency) when there's no embedder or no vectors yet, so
+     *  the lean install and fallback regressions are unaffected. Pass
+     *  `embedder: null` to FORCE FTS-only without auto-selecting. */
+    hybridSearch(query: string, limit?: number, opts?: HybridSearchOpts): Promise<SearchHit[]>;
+    /** Runbook-scoped retrieval (roadmap #5): the same FTS+graph(+semantic) fusion,
+     *  restricted to the `runbooks` kind — so a "what's the procedure for X" query
+     *  competes only with other runbooks, not the whole graph. Measurement showed
+     *  whole-corpus retrieval buries terse runbooks (33% recall); scoping + semantic
+     *  lifted recall@5 to 83% (dec_1239efae54 follow-up). Pass an embedder for the
+     *  semantic leg; omit for keyword+graph. */
+    searchRunbooks(query: string, limit?: number, opts?: {
+        embedder?: Embedder | null;
+    }): Promise<SearchHit[]>;
+    /** Kind-SCOPED retrieval: FTS + (optional) semantic fused, but the candidate pool is
+     *  restricted to one record kind from the START — not over-fetched from a whole-corpus
+     *  ranking (whose top-50 cap can bury a terse record before any filter). This is what
+     *  lifted runbook recall@5 from 33% → 83% in the measurement (dec_1239efae54 follow-up). */
+    searchScoped(query: string, kind: string, limit?: number, opts?: {
+        embedder?: Embedder | null;
+    }): Promise<SearchHit[]>;
+    /** FTS bm25 over a single kind (the `kind` column is UNINDEXED, so a plain `=`
+     *  constraint composes with MATCH). Empty when the query has no FTS-able terms. */
+    private scopedFts;
+    /** Brute-force exact cosine top-n over stored vectors for one model. Vectors are
+     *  pre-normalized, so cosine == dot product. Scoped to `dim = qvec.length` so a
+     *  row stored at a different dimension (model id reused at a new dim) can never
+     *  drive an out-of-bounds BLOB read; any with an unexpected byte length are
+     *  skipped defensively rather than crashing the query. */
+    private cosineRank;
+    /** Rank-based Reciprocal Rank Fusion of the FTS, semantic, and graph lists. Ranks
+     *  (not raw scores) erase the bm25-vs-cosine-vs-graph scale mismatch; a small lexical
+     *  weight keeps exact symbol/path matches from being displaced by paraphrase or
+     *  neighbor hits. An empty list contributes nothing, so 2-stream behavior is exactly
+     *  preserved when graph (or sem) is absent. */
+    private rrfFuse;
+    /** Bounded relevance traversal over the dependency graph. Lexical/semantic symbol
+     *  and component hits seed a small number of depth layers; support decays per hop
+     *  and adds across multiple useful paths. Each frontier and the returned context
+     *  obey a hard node cap, while hydration obeys a separate token cap. Only records
+     *  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;
+    /** 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
+     *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
+     *  history-inclusive view (backward-compatible default). */
+    why(target: string, opts?: {
+        asOf?: string;
+    }): WhyResult;
+    /** 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. */
+    getDependents(id: string, maxDepth?: number): Array<{
+        id: string;
+        depth: number;
+        via: string;
+    }>;
+    /** Symbols/components this id depends ON (forward walk) — used for refactor blast radius. */
+    getDependencies(id: string, maxDepth?: number): Array<{
+        id: string;
+        depth: number;
+        via: string;
+    }>;
+    /** Files whose symbols (in)directly DEPEND ON a symbol defined in `file` — the
+     *  blast radius of editing `file`, collapsed to file granularity (nearest depth
+     *  wins per file). Powers `hunch check` near-violation detection and `--blast`. */
+    blastRadiusFiles(file: string, maxDepth?: number): Array<{
+        file: string;
+        via: string;
+        depth: number;
+    }>;
+    /** Shortest undirected path between two graph nodes (symbols/components) over
+     *  call/dep/import/contains/type-relation edges — "how does A reach B?" (hunch
+     *  path / hunch_path). An iterative BFS visits each node once; the old recursive
+     *  SQL enumerated simple paths and grew exponentially on dense real repositories.
+     *  Returns the node chain in order, or null when no path exists within maxDepth. */
+    shortestPath(fromId: string, toId: string, maxDepth?: number): Array<{
+        id: string;
+        via: string;
+    }> | null;
+    /** Human label for a graph node id: "name @ file" for a symbol, the component name,
+     *  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. */
+    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,
+     *  scope-matched constraints, why) so impact and gating can never disagree. */
+    prImpact(files: string[], diff: string): ImpactReport;
+    /** Structure view (hunch_structure / hunch structure): serve the indexed shape of
+     *  the repo so an agent ORIENTS from the graph instead of running grep/glob rounds.
+     *  Resolution: no target -> repo map; a directory -> its files+symbols; a file ->
+     *  its outline; a symbol name -> exact definition site(s) with one-hop neighbors.
+     *  Deterministic, read-only, straight from the derived index. */
+    structure(target?: string): StructureView;
+    /** Labelled one-hop edge neighbors of a node ("in" = who reaches it, "out" = what it reaches). */
+    private edgeNeighbors;
+    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
+     *  By default only ACTIVE invariants are returned — a retired constraint is no
+     *  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: string, opts?: {
+        asOf?: string;
+    }): Constraint[];
+    /** LIVE findings (observations — audited, no diff yet) concerning a file/scope:
+     *  triage open / accepted-risk / scheduled; resolved and stale stay silent. The
+     *  matcher mirrors checkConstraints: an affected entry may be a concrete path or a
+     *  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: string): Finding[];
+    /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
+     *  Deterministic graph join: constraint → source_decision (the decision that
+     *  motivated the guard) → the bug whose root cause spawned it (via
+     *  lineage.spawned_constraint, else the source decision's caused_by_bug). Read-only. */
+    causalChain(constraintId: string): CausalWhy;
+    /** Assemble a CheckReport from a diff: direct invariant hits, near hits (blast
+     *  radius), and regressions (re-added retired code), with the hardened strict
+     *  gate and a causal `why` citation per direct hit. Read-only — shared by
+     *  `hunch check`, the CI guard, and hunch_merge_verdict so they never drift. */
+    buildCheckReport(files: string[], diff: string, opts: {
+        strict: boolean;
+        lastChange?: (f: string) => string;
+        publicOnly?: boolean;
+    }): CheckReport;
+    /** Sprawl/"this already exists" guard (ADVISORY, never blocks). A symbol the diff
+     *  ADDS whose name already exists in the indexed graph in a file NOT touched by the
+     *  diff is a likely re-implementation the agent's local context window couldn't see.
+     *  Read-only. Heuristic, so noise is controlled: top-level function/class/const only,
+     *  name length ≥ 4, a stopword list of generic names, deduped, and capped. */
+    redundantSymbols(added: Array<{
+        name: string;
+        kind: string;
+    }>, files: string[], opts?: {
+        movedFrom?: string[];
+        removedNames?: Set<string>;
+    }): Array<{
+        name: string;
+        kind: string;
+        existingFile: string;
+    }>;
+    /** Time-travel: the decision history for a target — every decision touching it,
+     *  newest-first, with its valid-time window and supersession links. Answers
+     *  "what did we believe, and when/why did it change?" (hunch_timeline). */
+    timeline(target: string): Decision[];
+    /** Invalidate, don't delete (Zep edge-invalidation): close `oldId`'s valid-time
+     *  window at the superseding decision's `valid_from`, mark it superseded + linked,
+     *  and write a `supersedes` edge. Returns the updated old decision, or null if it
+     *  doesn't exist. All writes are atomic via json.put (con_902759b3dc). */
+    supersede(oldId: string, by: Decision): Decision | null;
+    /** Look up a decision by id in a SPECIFIC store — the public store, or the private
+     *  overlay when `priv` is true — NOT the union. The capture guard uses this to know
+     *  whether a supersede will actually close its target: `supersede`/`supersedePrivate`
+     *  each look in only one store, so a cross-store supersede silently no-ops and would
+     *  leave two live decisions on one topic. Returns undefined if absent (or no overlay). */
+    decisionInStore(id: string, priv: boolean): Decision | undefined;
+    /** Private-overlay counterpart of `supersede`: close + link the old decision inside
+     *  the HUNCH_PRIVATE_DIR store, so a PRIVATE decision can supersede another private
+     *  one (the MCP record path is private→private). A private write never mutates the
+     *  committed public store. Returns null if no private store is configured or the old
+     *  record isn't in it. */
+    supersedePrivate(oldId: string, by: Decision): Decision | null;
+    /** Shared body for supersede / supersedePrivate against a specific store. */
+    private supersedeIn;
+    /** Regression Guard: detect a change RE-INTRODUCING something an in-force
+     *  decision deliberately removed. Matches the added symbols/deps of a diff
+     *  against the `retired` signal of decisions concerning the touched files. A hit
+     *  is `blocking` when the retiring decision is tied to an ACTIVE blocking
+     *  constraint (via source_decision) — that's the only case the strict guard
+     *  fails the commit on; everything else is an advisory warning. */
+    regressionHits(added: {
+        symbols: string[];
+        deps: string[];
+    }, files: string[]): RegressionHit[];
+    /** Veto Guard: detect a change RE-INTRODUCING an approach an in-force decision
+     *  deliberately REJECTED (`decision.rejected_tripwires`). The counterpart to
+     *  regressionHits, which only sees code that once existed — a rejected alternative
+     *  never did. Precision-first ladder (dep > symbol > pattern); the semantic tier is
+     *  advisory and lives elsewhere. A hit `blocks` only when isVetoBlocker passes (a
+     *  human-confirmed tripwire on an in-force, non-stale decision — dec_a466655539).
+     *  Read-only; shared by buildCheckReport. */
+    vetoHits(an: DiffAnalysis, files: string[], staleDecisions?: Set<string>): VetoHit[];
+    /** Resolve a veto's causal citation: the bug whose root cause spawned the decision
+     *  (decision → caused_by_bug). Distinct from causalChain, which is constraint-keyed. */
+    private vetoWhy;
+    /** Veto check for a LIVE edit (the agent pre-edit hook): no diff exists yet, so
+     *  synthesize a minimal added-only diff from the proposed new lines and run the
+     *  same vetoHits ladder. Freshness needs git lastChange (unavailable at edit time),
+     *  so the staleness gate is skipped here — the commit/CI path applies it. */
+    vetoForFileEdit(file: string, addedLines: string[]): VetoHit[];
+    /** The symbols/deps an in-force decision deliberately RETIRED from a file — the
+     *  agent-hook grounding ("don't re-add X here; dec_Y removed it"). No diff is
+     *  available at edit time, so this surfaces the risk as context, not a block. */
+    retiredForFile(file: string): RetiredNote[];
+    /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
+    bugLineage(symptomOrSymbol: string): Bug[];
+    /** Ranked fragility report (hunch fragile). fragility = weighted churn + bugs + fan-in. */
+    fragility(limit?: number): FragileNode[];
+    /** Convenience: load a single entity from JSON by id (any kind). */
+    resolve(id: string): {
+        kind: string;
+        record: unknown;
+    } | undefined;
+    /** All edges (for graph export). */
+    allEdges(): Edge[];
+    /** Drift detection (DESIGN §9 "staleness kills trust"): a decision/constraint
+     *  is STALE when a file in its scope changed AFTER it was last verified. The
+     *  caller supplies `lastChange(file) -> ISO date | ""` (git-backed). */
+    staleness(lastChange: (file: string) => string): StaleRecord[];
+    /** The Context Assembler (DESIGN §2.1/§6): the MINIMAL relevant Hunch slice for
+     *  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: string, budget?: number, opts?: {
+        asOf?: string;
+    }): AssembledContext;
+}
+/** The graph-served repo shape (hunch_structure) — orient without grep rounds. */
+export type StructureView = {
+    kind: "repo";
+    components: Array<{
+        id: string;
+        name: string;
+        responsibility: string;
+        paths: string[];
+    }>;
+    dirs: Array<{
+        dir: string;
+        files: number;
+        symbols: number;
+    }>;
+} | {
+    kind: "dir";
+    dir: string;
+    files: Array<{
+        file: string;
+        symbols: Array<{
+            name: string;
+            kind: string;
+            fan_in: number;
+        }>;
+    }>;
+} | {
+    kind: "file";
+    file: string;
+    symbols: Array<{
+        id: string;
+        name: string;
+        kind: string;
+        loc: number;
+        fan_in: number;
+        fan_out: number;
+        callers: string[];
+    }>;
+} | {
+    kind: "symbol";
+    matches: Array<{
+        id: string;
+        name: string;
+        kind: string;
+        file: string;
+        fan_in: number;
+        fan_out: number;
+        callers: string[];
+        callees: string[];
+    }>;
+} | {
+    kind: "none";
+    target: string;
+};
+export interface StaleRecord {
+    kind: string;
+    id: string;
+    last_verified: string;
+    changed_at: string;
+    files: string[];
+}
+/** A diff re-introducing something a decision deliberately removed. */
+export interface RegressionHit {
+    decision: string;
+    title: string;
+    kind: "symbol" | "dep";
+    name: string;
+    /** True only when the retiring decision is tied to an active blocking invariant. */
+    blocking: boolean;
+    reason: string;
+}
+/** A diff re-introducing an approach an in-force decision deliberately REJECTED. */
+export interface VetoHit {
+    decision: string;
+    title: string;
+    /** The rejected approach's text — the receipt headline. */
+    alternative: string;
+    /** What was chosen instead (decision.decision). */
+    chosen: string;
+    tier: VetoTier;
+    evidence: string[];
+    /** True only when the matched tripwire is human-confirmed, in-force, non-stale. */
+    blocks: boolean;
+    why?: {
+        bug?: {
+            id: string;
+            title: string;
+            root_cause: string;
+        };
+    };
+}
+/** What an in-force decision retired from a file (agent-hook grounding). */
+export interface RetiredNote {
+    decision: string;
+    title: string;
+    symbols: string[];
+    deps: string[];
+}
+export interface AssembledContext {
+    target: string;
+    constraints: Constraint[];
+    decisions: Decision[];
+    bugs: Bug[];
+    blast_radius: Array<{
+        id: string;
+        depth: number;
+        via: string;
+    }>;
+    components: Component[];
+    findings: Finding[];
+    /** Current, explicitly reviewed Engineering Landscape orientation. */
+    landscape?: ReviewedLandscapeSelection;
+    budget_tokens: number;
+}

package/dist/store/hunchStore.js

@@ -192,8 +192,10 @@ export class HunchStore {
     putCapture(kind, record, isPrivate = false) {
         const home = this.captureHome(isPrivate);
         const id = record.id;
-        const targetHasRecord = home === "private" ? !!this.privateJson?.get(kind, id) : !!this.json.get(kind, id);
-        const otherHasRecord = home === "private" ? !!this.json.get(kind, id) : !!this.privateJson?.get(kind, id);
+        const lookup = (json) => kind === "derived" || kind === "receipts" || kind === "commitments"
+            ? json?.getDirect(kind, id) : json?.get(kind, id);
+        const targetHasRecord = !!lookup(home === "private" ? this.privateJson : this.json);
+        const otherHasRecord = !!lookup(home === "private" ? this.json : this.privateJson);
         // Legacy repositories can already contain twins, so an idempotent update in
         // the selected home remains possible. A new capture must never CREATE that
         // ambiguous state: merged/private-first reads would make later writers and
@@ -244,6 +246,9 @@ export class HunchStore {
     getPrivateRec(kind, id) {
         return this.privateJson?.get(kind, id);
     }
+    getStateDirect(kind, id, home) {
+        return (home === "private" ? this.privateJson : this.json)?.getDirect(kind, id);
+    }
     /** Update an EXISTING record in the store that holds it — an overlay record must never
      *  fork a public copy on update (and vice versa). Falls back to captureHome routing for
      *  a record that exists nowhere yet. */
@@ -1987,9 +1992,12 @@ const DECISION_FRESHNESS_PATH_CACHE_CAP = 4_096;
  *  had correctly injected just below the cut line. This lifts memory records by a
  *  bounded number of positions; it never EXCLUDES a kind (a symbol-name query still
  *  returns symbols, and a constraint stays reachable), it only breaks the tie toward
- *  intent. Measured on bench/golden-retrieval.json: Recall@10 70% -> 90%, MRR
- *  0.402 -> 0.575. Set HUNCH_MEMORY_PRIOR_SHIFT=0 to disable. */
-const MEMORY_PRIOR_SHIFT = numEnv("HUNCH_MEMORY_PRIOR_SHIFT", 12);
+ *  intent. The task-report additions diluted one previously reachable decision:
+ *  on the same memory corpus, 12 positions gave Recall@10 8/11 (MRR .470);
+ *  16 restores 9/11 (.483), preserving the existing floor and exact-symbol controls.
+ *  This is bounded calibration, not immunity to arbitrary corpus growth.
+ *  Set HUNCH_MEMORY_PRIOR_SHIFT=0 to disable. */
+const MEMORY_PRIOR_SHIFT = numEnv("HUNCH_MEMORY_PRIOR_SHIFT", 16);
 const MEMORY_KINDS = new Set(["decisions", "constraints", "bugs", "runbooks", "policies", ...STATE_KINDS]);
 /** State-of-record ordering in the RAW search path: a nuryel.state/1 history hit (superseded
  *  derived, done/cancelled commitment, failed receipt, retired entity) keeps this fraction of