#pragma once #include "infra/emit.h" // rw::emitTo / emitRaw / formatTo — THE emitter and its siblings #include "gitcmd.h" // rw::gitCmd — every git child starts with --no-optional-locks -c core.fsmonitor=false #include "langfacts.h" #include // %.*s (precision, pointer) collapses to one view // quality.h — --quality-baseline / --quality-delta: the deterministic oracle for a code-quality CONVERGENCE // LOOP. Snapshot the current per-symbol cognitive complexity, the duplicate-clone groups, and the dead-symbol // set to a `.ripwire_quality_baseline` sidecar; then `--quality-delta` reports ONLY what got WORSE vs that // baseline — the "delta, not absolute" discipline that lets a refine loop target *the regression it // introduced* instead of chasing absolute numbers (the defense against Goodhart / metric-gaming). Exits 2 if // any NEW regression (worse complexity over the bar, new duplication, newly-dead), like --arch. // // Why a baseline file (not a git diff): it is deterministic, git-independent, and matches the existing // `--arch --baseline` pattern. A convergence loop baselines ONCE at the start, then re-runs --quality-delta // after each edit — each step is one cheap warm call. Determinism: every record is an FNV-1a-64 hash (of the // canonical id, or of a clone group's sorted member ids); the file is sorted; output is byte-stable. // // Honesty: this measures STRUCTURE (complexity / duplication / reachability), not data flow — it cedes // use-after-move / taint / type errors to the compiler. Thresholds are heuristics; the loop applies judgment. #include "model.h" #include "ingest.h" // ingest() — the HEAD-tree snapshot re-ingests the archived commit (computeHeadSnapshot) #include "graph.h" #include "valuerefindex.h" // reference-as-value round: a function a table/field/argument holds is not dead (dead kind) #include "clones.h" #include "cloneidiom.h" // idiom-class demotion — the closed 3-idiom shape classifier that turns an idiom-COLLISION clone group into a minor row instead of a gating one #include "lintrules.h" // findQualityConstructs — the built-in error-masking rule table (GitClear +47% kind) + the placeholder shapes #include "similarargs.h" // the similar-argument-list scanner (the params kind's report-only similar= facet) #include "defectshape.h" // the defect-shape kind's four scanners (format-arity, utf8-cut, dedup-first, vacuous-assert) #include "arch.h" // fnv1a64 #include "pathguard.h" // CWE-59/367: rw::pathguard::openNoFollowTruncate — writeBaseline truncates, so its open must refuse a link atomically #include "gitmine.h" // shSingleQuote + gitFileCommitCountsInDayWindow — short-horizon-churn window mining #include "diffhunks.h" // DiffHunk + gitDiffHunksVsHead + diffHunksMemoized — THE zero-context hunk primitive (extracted from this header 2026-09-27; situ.h's change-set narrowing is its second consumer) #include "docparse.h" // docparse::detail::readWholeFile — THE canonical whole-file byte read (commentcoherence.h names it that); reused rather than re-rolled, see forEachSymbolBody #include "filter.h" // B10.1a: isTestPath — the general test-dir convention behind isTestScriptPath #include "memguard.h" // #387: loadRefTree reads the hard line between a commit's ingest and its graph #include "infra/Diagnostics.h" // DISCLOSE — the degrade path when git archive/ingest fails (no-op under NDEBUG; a gate-visible degrade line needs its own fprintf) #include "infra/namesplit.h" // afterLast — a path's last component (isConftestFile, pythonModuleTail), not a third hand-rolled basename #include "infra/jsonesc.h" // L2 — rw::jsonesc::escapeMcp for staleAcksJsonArray's kind= field (the same posture serialize.h's jsonStr uses) #include "infra/platform.h" // RW_LIFETIMEBOUND — the DefectSiteKey projection lambdas; owned here, not transitively #include "sourceidentity.h" // rw::kRipwireSourceIdentity — the producer identity the qsnap/qbody keys and blob header carry #include "btree.hpp" // gtl btree_map — sorted like std::map, cache-friendly nodes (house rule: never std::map) #include "infra/dynamic_map.hpp" // S+tree scratch maps — bounded, no per-operation allocation in hot seen-set paths #include "infra/os.h" // rw::os — mkdir/lstat/chmod/getuid for the per-user cache-dir ladder (cacheDirLadder); open/flock/close for // F-04, the ack ledger's cross-process write lock (SidecarWriteLock); getpid for the HEAD-snapshot temp-dir suffix #include // EWOULDBLOCK — the LOCK_NB retry predicate #include // ::nanosleep — the lock's bounded 10 ms poll #include #include // OwnBuildBlobTails — one tagged tail per root-keyed family #include // the A5 process-once cache-sweep guard #include // std::isxdigit/std::isdigit — B10.2d churn-blame porcelain parsing #include // A5: the 30-day cache-blob age cutoff (evictOldCacheFamily) #include #include #include // std::memcpy / std::memcmp — POD (de)serialization of the qsnap blob #include #include #include // std::numeric_limits::max() — "no count cap" sentinel (evictOldCacheFamily) #include // Phase-M: serialize concurrent ingest() (prefetch worker vs request thread) #include // L2 — computeStaleAcks' per-kind dispatch: nullopt = "not stale" #include #include #include // std::is_trivially_copyable_v — the qsnap POD put/get static_assert #include #include // mergeBuiltinsWithConfig — a non-owning view over either built-in list #include namespace rw { namespace quality { inline const char* kBaselineFile = ".ripwire_quality_baseline"; constexpr std::uint32_t kMinCloneTokens = 18; // matches the --clones default (so both verbs see the same clones) constexpr std::uint32_t kCcxBar = 15; // P8 (L7): situ.h spells this as kTestGateCcxBarMirror (test-gate root ccx_bar=) — the static_assert below the constants keeps them equal // SonarSource cognitive-complexity bar — a regression must end up OVER this // Q1 — bars for the MEASURED agent-code failure modes: agent code runs 2.3× // verbose, erodes structure in 77% of trajectories, drifts contracts. Each per-symbol kind mirrors ccx's // "grew AND now over a bar" discipline (`now > was && now > BAR`) — a bar so a benign +1 line / +1 nest of an // already-small function is not spam, and the reported set is genuinely-worse-AND-now-large. HEURISTICS (like // kCcxBar): defensible defaults, the loop applies judgment; report numbers, never gate a normal run. constexpr std::uint32_t kLocBar = 60; // "large function" LOC bar (below Sonar's 75 default) — a verbosity regression must END UP over it (SIZE is the master variable, §1d) constexpr std::uint32_t kNestBar = 4; // max-nesting-depth bar — deep nesting (>3-4) is the structural-erosion signal; a regression must end up over it constexpr std::uint32_t kParamBar = 5; // param-count bar — a REGRESSION (grew AND now high), NOT the debunked absolute 7±2 rule (§1d kill-list); the growth is the signal, the bar just suppresses tiny-fn noise // §D#4 / §E-17 — three GitClear-2026-backed kinds. Each fires ONLY on a regression vs baseline (the // quality-delta contract), never on pre-existing debt. See the per-kind comments in computeSnapshot/computeDelta. constexpr std::uint32_t kShortHorizonDays = 14; // "new code rewritten within two weeks" window (+15% in AI code) — from git COMMIT TIMESTAMPS vs HEAD's epoch, not wall-clock (det-gate safe) constexpr std::uint32_t kShortHorizonMinCommits = 2; // only flag a symbol whose FILE already had ≥2 commits in the window (a genuine rewrite churn, not a first touch) constexpr std::uint32_t kReusedHelperMinFanin = 3; // "cross-file reuse declining": a NEW clone of a helper whose fan-in ≥ this is a reuse-connectivity regression (GitClear) // Signal-to-noise round (2026-07-13, quality-delta noise rules) — MATERIALITY TIERS. A numeric // regression whose DELTA (now − was) is below the kind's tier is reported sev="minor" and does not gate exit 2 // by itself: a +1-ccx edit to an already-over-the-bar function is a regression by the letter but noise that // drowns the material findings a refine loop should chase. 0 = the kind has no minor tier (any delta is major). // Presence kinds (duplication / dead-code / api-surface / error-masking / churn / reuse-decline) and nesting // (every +1 nest is structural erosion) stay major. HEURISTICS like the bars: defensible, documented, judged. constexpr std::uint32_t kMinorCcxDelta = 3; // complexity: delta < 3 → minor constexpr std::uint32_t kMinorLocDelta = 10; // verbosity: delta < 10 LOC → minor constexpr std::uint32_t kMinorParamDelta = 2; // params: +1 param → minor; +2 or more → major // Q-DIAL-3 (2026-09-10) — GROWTH IS A SIGNAL, and the bar alone was not one. `now > was && now > BAR` says // nothing about how much this change added: audit lane Q1 measured the median growth of a GATING complexity // row at 6% and of a gating verbosity row at 6% (§2d) — +3% on a function that was 1,068 lines before the // change gated, while 6 → 55 LOC (9x) and ccx 5 → 13 (+160%) were invisible because neither ends up over the // bar. Two thresholds fix both halves, and they apply to complexity and verbosity ONLY (params is the // highest-precision kind in the table at 77% and nesting has no measured false positive — neither is moved // on a hunch): constexpr std::uint32_t kMaterialGrowthPct = 25; // over the bar: gate on a bar CROSSING, or on growth >= this. Otherwise the row is real, reported, and sev="minor" — chronic debt the change did not create. constexpr std::uint32_t kSubBarGrowthPct = 100; // UNDER the bar: a DOUBLING is worth a minor row rather than silence (synthetics S4b/S8) — never gating, because nothing is over the bar yet. // …with a floor so a 3 → 6 line helper is not a finding. Two thirds of the kind's own bar, so the floor moves // with the bar it belongs to and there is no third number to keep in sync: ccx 10, loc 40. inline constexpr std::uint32_t subBarGrowthFloor( std::uint32_t bar ) noexcept { return ( bar * 2 ) / 3; } // QD-MONSTER-GROWTH (2026-11-12) — the 25 % tier bends the average and misses the monsters: on a function far // over the bar, a real tangle is a small PERCENTAGE forever (`buildGraph` ccx 1950 → 1968 was +0.9 %, minor). // So complexity growth of kMonsterGrowthCcx or more on a function that was already kMonsterMul × its bar is // major at any percentage, and the row says monster="1". Measured on 47 first-parent merges 09-05..11-11 // (reports/qd-ge-card-verify-1112.md § E3): Δccx ≥ 3 was the designed trigger — 34 events on 38 % of merges, // precision 0.37, half of them flat branching (an `else if` option arm, a legend append). Δccx ≥ 10 left 10 // events on 17 % of merges, 6 of 7 sampled ones tangle (0.86); the false one is `parseArgs` +12 (two flat // `else if( --flag= )` arms). Complexity ONLY: verbosity never triggers it (owner 11-05 — a long flat function // is fine), and a flat run of statements adds 0 ccx, so it cannot. Nesting needs no clause: every nesting row // is already major (no minor tier), monster or not. constexpr std::uint32_t kMonsterMul = 5; // "monster" = was ≥ kMonsterMul × the bar (ccx 75 at kCcxBar 15) constexpr std::uint32_t kMonsterGrowthCcx = 10; // …and grew by ≥ this in one change: major, whatever the percentage // The clause itself, one body for the live decision and the ack re-score. `monsterGrowth` 0 = the kind has none. inline constexpr bool isMonsterGrowth( std::uint32_t was, std::uint32_t now, std::uint32_t bar, std::uint32_t monsterGrowth ) noexcept { return monsterGrowth != 0 && was >= kMonsterMul * bar && now >= was + monsterGrowth; } // QD-ENTRY-CEILING (GE design E2, owner decision C4 2026-11-12) — THE NEW-FUNCTION CEILING. A new symbol never gated, whatever its // size, and that is how a 1,000-line function starts. A NEW complexity or verbosity row whose `now` reaches this multiple of its // kind's bar gates: ccx 60 or 240 code lines at 4. The step plan is 4, then 3, then 2, each step only while sampled precision holds // 0.8 and a typical lane diff prints at most one such row (GE design § 1.5). Report-only, never gating: a MOVED body (origin="moved") // and a TEST DRIVER (isTestPath — owner C4: every function under test/ is report-only). A knob, in the knob census. // MOVES (2026-11-13): the clone-sketch Jaccard at which a NEW body and a vacated baseline body (each the other's unique best) are one // moved body. Picked from the 30-PR replay (last 30 merges to 0b8f0bf8d): the three real moves scored 0.851 (extractHtmlFlat, #572), // 0.922 and 0.976; the best non-move scored 0.310; the gate's 4-of-245-statement rename scores 0.804. 0.70 sits in that gap, ~5 // standard errors of the 128-component estimate from either side. // Kept as an exact percentage: the decision runs on the integer sketch-match count (moveSketchAtThreshold), never on a float. constexpr std::uint32_t kMoveSketchMinJaccardPct = 70; // cloneSketchJaccard's estimate J = (256 m - K) / (255 K) for m matching components of K, so J >= pct/100 is the exact integer test // 100 (256 m - K) >= pct 255 K: the 0.70 threshold is m >= 90 of 128. inline constexpr bool moveSketchAtThreshold( std::uint32_t matches ) noexcept { const std::uint64_t k = kSketchHashes; return 100 * ( 256 * std::uint64_t( matches ) ) >= std::uint64_t( kMoveSketchMinJaccardPct ) * 255 * k + 100 * k; } static_assert( !moveSketchAtThreshold( 89 ) && moveSketchAtThreshold( 90 ), "0.70 of a 128-component sketch is 90 matches" ); constexpr std::uint32_t kNewSymbolCeilingMul = 4; inline constexpr std::uint32_t newSymbolCeiling( std::uint32_t bar ) noexcept { return bar * kNewSymbolCeilingMul; } // ─── ACK PROVENANCE / RE-SCORE — the per-symbol numeric kinds' materiality, as ONE declarative table ───── // // kind → the three constants perSymbolKind already compares (was,now) against. Pulled out as a table // (CONTRIBUTING.md §3 "declarative constexpr tables over scattered switch/if") so the LIVE decision // (perSymbolKind, below) and the RE-SCORE decision (an ack row's stored `was=`/`now=`, read back off the // ledger by rescoreAckRecord — see AckRecord::provenance) are the SAME lookup, not two hand-kept copies // that can drift. The two facet-driven kinds (duplication / new-clone-of-reused-helper: decided by the // recognized clone idiom, not a bar) and the two presence kinds (dead-code / api-surface tier A: always // major, no materiality question) are deliberately absent — findRowByKind over this table returns nullptr. struct MaterialityBar { std::string_view kind; std::uint32_t bar; std::uint32_t minorDelta; bool growthTiered; std::uint32_t monsterGrowth; // QD-MONSTER-GROWTH: growth that is major on a function ≥ kMonsterMul × bar (0 = none) }; inline constexpr MaterialityBar kMaterialityBars[] = { { "complexity", kCcxBar, kMinorCcxDelta, true, kMonsterGrowthCcx }, { "verbosity", kLocBar, kMinorLocDelta, true, 0 }, { "nesting", kNestBar, 0, false, 0 }, { "params", kParamBar, kMinorParamDelta, false, 0 }, }; // computeDelta calls perSymbolKind with these rows by index; the order is the contract. static_assert( kMaterialityBars[0].kind == "complexity" && kMaterialityBars[1].kind == "verbosity" && kMaterialityBars[2].kind == "nesting" && kMaterialityBars[3].kind == "params", "computeDelta's perSymbolKind calls index kMaterialityBars by kind order" ); inline constexpr std::string_view kMonsterFacet = "1"; // a complexity row's facet, emitted as monster="1" (kFacetAttrs) // The linear scan behind every "kind → its declarative table row" lookup in this file — rescoreNumericMajor's // own lookup below and facetAttrName (kFacetAttrs, further down) are both this shape over a different small // constexpr table, so this is the one body instead of two. `Row` need only expose a `.kind` field comparable // to a string_view; the table is small (at most a handful of kinds) so a linear scan over a sorted-by-nothing // array beats any container overhead. No `materialityBarFor` wrapper around it: rescoreNumericMajor is its // only caller, and a one-line forwarding wrapper that short is itself clone-bait — measured turning this one // in: it duplication-matched three unrelated one-line forwarders elsewhere in the tree the moment it existed // as its own named symbol, for no reader benefit over calling findRowByKind at the one call site directly. template inline const Row* findRowByKind( const Row* begin, const Row* end, std::string_view kind ) noexcept { const Row* const hit = std::find_if( begin, end, [ kind ]( const Row& r ) { return r.kind == kind; } ); return hit != end ? hit : nullptr; } // The growth-vs-bar formula itself, factored out of perSymbolKind so it has exactly one body: the caller // already knows `now > was` and `now > bar` (perSymbolKind's own guards), and already has `growthPct` in // hand (it needs it for the sub-bar branch too), so this takes both rather than recomputing either. inline bool numericRegressionIsMajor( std::uint32_t was, std::uint32_t now, const MaterialityBar& mb, std::uint32_t bar, std::uint32_t minorDelta, std::uint64_t growthPct ) noexcept { const bool crossed = was <= bar; return !mb.growthTiered ? ( minorDelta == 0 || now - was >= minorDelta ) : ( crossed || growthPct >= kMaterialGrowthPct || isMonsterGrowth( was, now, bar, mb.monsterGrowth ) ); } // RE-SCORE, mechanical: given a (kind, was, now) triple alone — no re-ingest, no git history — recompute // whether this would be a MAJOR (gating-eligible) or minor finding under the kind's bar/minorDelta today. // nullopt means "cannot answer from these three values": either `kind` is not one of the four numeric bar // kinds (duplication/new-clone-of-reused-helper decide via `facet` — see AckRecord's doc comment — and // dead-code/api-surface tier A have no materiality question at all), or now<=was, which is not a regression // under any threshold. This is the whole payoff of storing was=/now= on the ack row: the knob sweep this // exists for calls it with a DIFFERENT bar/minorDelta than kMaterialityBars carries today. inline std::optional rescoreNumericMajor( std::string_view kind, std::uint32_t was, std::uint32_t now, std::optional barOverride = std::nullopt, std::optional minorDeltaOverride = std::nullopt ) noexcept { const MaterialityBar* mb = findRowByKind( std::begin( kMaterialityBars ), std::end( kMaterialityBars ), kind ); if( mb == nullptr || now <= was ) { return std::nullopt; } const std::uint32_t bar = barOverride.value_or( mb->bar ); const std::uint32_t minorDelta = minorDeltaOverride.value_or( mb->minorDelta ); if( now <= bar ) { return false; // under the bar — never MAJOR (may still be a reported sev="minor" row; not this predicate's question) } const std::uint64_t growthPct = ( std::uint64_t( now - was ) * 100 ) / std::max( was, 1u ); return numericRegressionIsMajor( was, now, *mb, bar, minorDelta, growthPct ); } // Signal-to-noise round — the per-finding ACK RATCHET sidecar (`--quality-ack[=REASON]`): each line records one // deliberately-accepted finding; --quality-delta suppresses it (honestly, via acked="N") until the finding // WORSENS past the acked magnitude, at which point it reappears. Committable, like the baseline sidecar. inline const char* kAcksFile = ".ripwire_quality_acks"; // D1 fix (HIGH): both sidecars above are FILE NAME constants, not paths — every read/write/remove // site must resolve them against the ANALYZED ROOT, never the process CWD. The CLI is invoked // `ripwire --quality-ack` and may run from ANY cwd (a wrapper script, an orchestrator batching // several roots from one launch dir, a Makefile target) — a bare relative filename then reads/writes/ // deletes CWD's sidecar instead of ``'s. Observed live: --quality-ack on root B run from cwd A // rewrote A's committed `.ripwire_quality_acks`; the stale-baseline self-heal (main.cpp) could have // DELETED A's baseline the same way. The MCP server already root-qualified for exactly this reason // (mcpverbs.h's SIDECAR LOCATION note); this is the one shared home so the CLI and MCP paths can never // re-diverge again. Mirrors notes::notesPath's root + "/" + name discipline (notes.h). inline std::string rootQualifiedSidecar( const std::string& root, const char* name ) { std::string p = root; if( !p.empty() && p.back() != '/' ) { p += '/'; } return p + name; } inline std::string baselinePath( const std::string& root ) { return rootQualifiedSidecar( root, kBaselineFile ); } inline std::string acksPath( const std::string& root ) { return rootQualifiedSidecar( root, kAcksFile ); } // P2.2 (agent-friction round, 2026-08-29) — the FIRST general-purpose `.ripwire_config` sidecar. No // config-file parser existed anywhere in this codebase before this (checked: no other `.ripwire_config` // reader, no `RIPWIRE_CONFIG` constant). Smallest thing consistent with the two house sidecar // conventions already in the tree — `.ripwire_notes` (committed, degrade-don't-throw, absent=inert) and // `.ripwire_quality_acks` (root-qualified via rootQualifiedSidecar, never the process CWD): a committed, // human-editable key=value text file at the repo root. TWO recognized keys today (readRegisterMacrosConfig // below); an unrecognized key is skipped rather than refused, so the file can grow new keys later without // a binary that predates them choking on it — notes.h's own forward-compat rule, restated here for a new // file rather than invented twice. inline const char* kConfigFile = ".ripwire_config"; inline std::string configPath( std::string_view root ) { return rootQualifiedSidecar( std::string( root ), kConfigFile ); } template using ScratchMap = stree::dyn::dynamic_map; // uint64 keys on Apple cache lines; use only when a hard capacity bound is obvious // Every caller sizes `seen` at ing.symbols.size() and inserts at most one key per symbol it iterates (traced 2026-09-19: // the per-symbol, api, mask and churn passes of quality.h), so the container can never reject a new key. inline bool insertScratchSeen( ScratchMap& seen, std::uint64_t key ) { const auto [ it, inserted ] = seen.insert( { key, 1 } ); ASSUME( it != seen.end(), "a scratch map is sized at the symbol count and takes at most one key per symbol" ); return inserted; } // S2: the BASELINE-ONLY canonical id — `relForHash(path,root)::scope::name`. Byte-identical to the graph's // g.canonId EXCEPT the path segment is made root-relative, so a COMMITTED .ripwire_quality_baseline is // portable across root spellings (`ripwire .` vs `ripwire /abs/repo` produce the SAME baseline key + hash). // The graph's g.canonId — and thus the emitted `id=` attribute and resolution — is left completely UNCHANGED; // this key exists only where a baseline hash is taken (computeSnapshot / computeDelta). `root` is the ingest // root as invoked (cfg.rootPath). Deterministic: a pure string function of (path, root, scope, name). // §B1.3: the rule itself now lives ONCE, in resolve.h beside canonicalId — serialize.h's field-note target // is the same identity and used to derive it independently, which is how the two would have drifted. inline std::string baselineCanonId( const IngestResult& ing, NodeId i, std::string_view root ) { return canonicalIdRelTo( ing, ing.symbols[i], root ); } // The defect-shape kind's per-site record. `anchor` is the definition the site sits in (its qualityKey) or, for // top-level code, defectFileAnchor( path ). `site` is fnv1a64 of the facet name and the site's NORMALIZED text, // with the facet in its low two bits; two values are reserved: 0 is the FILE-PRESENCE record (the file was // scanned at all — the origin oracle of a file anchor), 1 is "the file did not read" (its sites are unknown, so // no current site in that file may be judged new against it). struct DefectSiteKey { std::uint64_t anchor = 0; std::uint64_t site = 0; friend bool operator==( const DefectSiteKey&, const DefectSiteKey& ) = default; friend auto operator<=>( const DefectSiteKey&, const DefectSiteKey& ) = default; }; inline constexpr std::uint64_t kDefectFilePresent = 0; inline constexpr std::uint64_t kDefectFileUnreadable = 1; // A deterministic snapshot of the structural-quality state. Each per-symbol metric map is keyed by // hash(baselineCanonId) and stores the MAX over the overload set sharing that id (see computeSnapshot) — so a // low-metric overload written last can never manufacture a phantom regression on the next delta (the trap that // bit quality-delta once; mirrored identically on the delta side). struct Snapshot { gtl::btree_map ccxBySym; // hash(canonId) → MAX ccx (btree = sorted iteration for the byte-stable sidecar) gtl::btree_map locBySym; // Q1 verbosity — hash(canonId) → MAX CODE lines (Q-DIAL-3: blank and comment-only lines are not debt; see codeLinesInBody). ALSO the r26 ORIGIN oracle, which reads MEMBERSHIP only, so the value change does not touch it. gtl::btree_map nestBySym; // Q1 erosion — hash(canonId) → MAX control-nesting depth gtl::btree_map paramsBySym; // Q1 erosion — hash(canonId) → MAX parameter count gtl::btree_map defsBySym; // hash(canonId) → COUNT of definitions sharing the id (an overload set's CARDINALITY, deliberately NOT a MAX — see computeSnapshot) gtl::btree_map maskBySym; // §D#4 error-masking — hash(canonId) → COUNT of error-masking constructs in the symbol (SUM over overloads, see computeSnapshot) gtl::btree_map maskReportBySym; // the REPORT-ONLY part of maskBySym's count: widened handler shapes that do not gate in the symbol's language (kHandlerShapeGates); absent = 0 gtl::btree_map failureDefaultBySym; // the failure-default part of maskBySym's count (handlershape.h): a row whose count of it grew carries facet="failure-default"; absent = 0 gtl::btree_map placeholderBySym; // the placeholder kind — hash(canonId) → COUNT of stub / TODO constructs in the symbol (SUM over overloads, like maskBySym) gtl::btree_map bodyHashBySym; // §D#4 short-horizon-churn — pathQualifiedKey(path,scope,name) → fnv1a64 of the RAW body bytes (change detection; literal-only edits move NO metric, so metrics can't detect them). Path-qualified since v6: a bare canonId key folded every scope-less same-named symbol ACROSS FILES into one join identity (the W1-S2 cross-file churn misattribution) gtl::btree_map moveCidBySym; // QD-ENTRY-CEILING MOVED-BODY — qualityKey → moveCidOf (the scrubbed hash of the callable's BODY), recorded only for a function or method over the ccx or the line bar: the baseline half of "this new function is a body the same diff removed elsewhere" (origin="moved"). A sidecar or blob without it recognizes no move gtl::btree_map bodyCidBySym; // QD-RENAME-IDENTITY — qualityKey → moveCidOf of EVERY function or method (the MAX over overloads, read only where defsBySym is 1): the baseline half of "this new key is a vacated key's body under a new name or file" (ContentMoves). A sidecar or blob without it matches no rename gtl::btree_map moveSketchBySym; // QD-ENTRY-CEILING MOVES — qualityKey → the clone matcher's minhash sketch (cloneSketchOfStream, 128 B) of the same body moveCidBySym identifies, so a body moved WITH a small edit is still recognized (MovedBodies). A sidecar or blob without it recognizes exact moves only std::vector cloneGroups; // sorted hash(sorted member canonIds) std::vector dead; // sorted hash(canonId) of dead-candidate symbols std::vector publicApi; // Q1 contract drift — sorted hash(canonId) of PUBLIC/exported symbols (see isPublicApi) std::vector defectSites; // the defect-shape kind — sorted (anchor, site) records, one per offending site (a multiset), plus each scanned file's presence record // QD-GIT-RENAME-HEAL — NEVER SERIALIZED: the git-recorded earlier paths (newest first) of each current file the rename record // re-filed this baseline across (healIdentity). Read only by the clone-group hold, which re-spells a moved member at its old path. gtl::btree_map> renamedFrom; std::vector renamedKeys; // sorted: the current keys the rename record re-filed (dead-code rows on them read origin="moved") }; // ─── THE TWELVE KINDS AS A SET (qd-memory-degrade) ───────────────────────────────────────────────────────── // --quality-kinds=K[,K] runs a subset of the kinds (the replay a degraded --quality-delta=A..B hands back), and the // degraded range form runs the subset its changed files can decide. Each kind stays a separately reported, separately // skippable unit: the mask decides which passes run and which rows are kept, never how a row is computed — a kind that // runs computes its rows with the same code and the same bars as in a full answer. Alphabetical, the order every list // of them (kinds_skipped=, the refusal, the help) is spelled in. inline constexpr std::string_view kQualityKindNames[] = { "api-surface", "complexity", "dead-code", "defect-shape", "duplication", "error-masking", "nesting", "new-clone-of-reused-helper", "params", "placeholder", "short-horizon-churn", "verbosity", }; using KindMask = std::uint16_t; inline constexpr KindMask kAllKinds = KindMask( ( 1u << std::size( kQualityKindNames ) ) - 1u ); static_assert( std::size( kQualityKindNames ) == 12 && std::size( kQualityKindNames ) <= 16, "one bit per kind" ); // the kind's bit, or 0 for a name that is not one of the twelve inline constexpr KindMask kindBit( std::string_view kind ) noexcept { const auto* const at = std::find( std::begin( kQualityKindNames ), std::end( kQualityKindNames ), kind ); return at == std::end( kQualityKindNames ) ? KindMask( 0 ) : KindMask( 1u << ( at - std::begin( kQualityKindNames ) ) ); } // the kinds that need EVERY file of the target tree (dead-code: the whole graph's evidence; the two clone kinds: every // body) — what a changed-files answer cannot run inline constexpr KindMask kWholeTreeKinds = KindMask( kindBit( "dead-code" ) | kindBit( "duplication" ) | kindBit( "new-clone-of-reused-helper" ) ); inline constexpr bool kindSelected( KindMask mask, std::string_view kind ) noexcept { return ( mask & kindBit( kind ) ) != 0; } // the kinds of `mask`, alphabetical, joined by `sep` inline std::string kindList( KindMask mask, std::string_view sep ) { std::string out; for( std::size_t k = 0; k < std::size( kQualityKindNames ); ++k ) { if( ( mask & ( 1u << k ) ) != 0 ) { out.append( out.empty() ? std::string_view{} : sep ).append( kQualityKindNames[ k ] ); } } return out; } // What a snapshot or a delta is computed FOR (qd-memory-degrade): the kinds to run, and — when the index holds only some // of the tree's files (a changed-files answer) — the tree's C-family macro names to scan its C++ files against // (defectSitesOf). The default is every kind over a whole tree: the computation these functions always did. struct KindScope { KindMask kinds = kAllKinds; const std::vector* macroOverride = nullptr; }; // --quality-kinds' value parsed: the mask, or 0 with `bad` naming the first token that is not a kind (an empty token too) inline KindMask parseKindList( std::string_view spec, std::string& bad ) { KindMask mask = 0; while( true ) { const std::size_t comma = spec.find( ',' ); const std::string_view token = spec.substr( 0, comma ); const KindMask bit = kindBit( token ); if( bit == 0 ) { bad.assign( token ); return 0; } mask |= bit; if( comma == std::string_view::npos ) { return mask; } spec.remove_prefix( comma + 1 ); } } // Q1 api-surface — the PUBLIC/exported contract surface. DEFINITION (deterministic, documented): // a symbol is PUBLIC iff it is DECLARED IN A HEADER file (`.h/.hpp/.hh/.hxx`) — the C/C++/ObjC export surface // by convention, exactly the convention `isDeadCandidate` already uses ("header-exported by convention"). // Markdown sections and non-header (translation-unit-local) definitions are NOT public. This is a SET signal: // contract drift = a public canonId present now but absent in the baseline (new exported surface), so it needs // no MAX aggregation — set membership is overload-collision-proof (multiple overloads collapse to one canonId). inline bool isPublicApi( const IngestResult& ing, NodeId i ) noexcept { const Symbol& s = ing.symbols[i]; if( s.kind == SymKind::Section || s.kind == SymKind::ModuleScope ) { return false; // markdown heading / a file's module scope — neither is a code contract } const std::string& p = ing.files[ s.fileId ]; const auto ends = [ & ]( std::string_view e ) { return p.size() >= e.size() && p.compare( p.size() - e.size(), e.size(), e ) == 0; }; return ends( ".h" ) || ends( ".hpp" ) || ends( ".hh" ) || ends( ".hxx" ); } // Signal-to-noise round — TEST-FIXTURE paths are exempt from the dead-code and short-horizon-churn kinds: // symbols in adversarial/golden fixture trees are dead (nothing calls a fixture) and churny (fixtures get // regenerated) BY DESIGN, and on this repo's own dogfood runs they drowned the real findings. DEFINITION // (deterministic, path-component based): a component named `fixture`/`fixtures` anywhere, or a component // ending in `fix` whose immediately-preceding component is `test`/`tests` (the `test/anchorfix/` convention). // The parent-dir requirement keeps real code dirs like `prefix/`, `bugfix/`, `hotfix/` in scope. Fixtures stay // visible to every OTHER kind (a fixture with exploding complexity is still worth a look). inline bool isFixturePath( std::string_view p ) noexcept { std::string_view prev; std::size_t start = 0; while( start <= p.size() ) { const std::size_t slash = p.find( '/', start ); const std::string_view c = p.substr( start, ( slash == std::string_view::npos ? p.size() : slash ) - start ); if( c == "fixture" || c == "fixtures" ) { return true; } if( c.size() > 3 && c.substr( c.size() - 3 ) == "fix" && ( prev == "test" || prev == "tests" ) ) { return true; } if( !c.empty() && c != "." && c != ".." ) { prev = c; // "." / ".." spellings never count as the test parent } if( slash == std::string_view::npos ) { break; } start = slash + 1; } return false; } // B10.1a (signal-to-noise round 2) — TEST-SCRIPT exemption: a shell test-RUNNER script (test/*.sh — the // general isTestPath test-dir convention from filter.h, so test/, tests/, spec/, etc. are ALL covered, not // just a literal "test/" — combined with a shell-script extension) gets the SAME fixture-class treatment as // isFixturePath for the dead-code and duplication kinds. Mechanism (the concrete false-positive this fixes): // a shell helper function invoked via `$(...)`/direct call is a normal bash call, but sibling test scripts in // this repo repeat near-identical setup/ok/no boilerplate BY CONVENTION (see e.g. // test/cochangeboostcheck.sh's inertPair/rankOf, which quality-delta on this repo's own diffs false-flagged // as both dead-code — nothing in the INDEXED tree calls a script's own helper except that same script — and // cross-script duplication). Shell scripts stay visible to every OTHER kind (a test script with exploding // complexity is still worth a look) — only dead-code and duplication treat them as fixture-class. inline bool isTestScriptPath( std::string_view p ) noexcept { if( !isTestPath( p ) ) { return false; } return endsWithLowerAscii( p, ".sh" ) || endsWithLowerAscii( p, ".bash" ) || endsWithLowerAscii( p, ".zsh" ); } // ---- P2.2 (agent-friction round, 2026-08-29): self-registering test/benchmark macros ------------------- // EVIDENCE (an orchestrated multi-agent authorship wave, agent-friction round 2026-08-29): a doctest/Catch2 // TEST_CASE (or a GoogleTest TEST/TEST_F/TEST_P, or a Google Benchmark BENCHMARK) registers itself via a // STATIC INITIALIZER at file scope — a mechanism the name-based call graph cannot see. Nothing in the // indexed tree ever "calls" the test body, so isDeadCandidate's zero-in-edges evidence flagged every one // of them, and --quality-delta reported the whole file as a pile of `dead-code origin="new-symbol"` rows // the moment an agent added a test — the single most repeated --quality-delta false positive across three // separate task gates in that wave. // // TWO DIFFERENT SHAPES, ONE DETECTABLE SIGNATURE. doctest/Catch2's block-forming macros // (kTestBlockMacroNames, ingest_names.h — LB-E) cannot be expanded by tree-sitter and are captured by hand // (testMacroBlockPartsOf) as a "testmacroblock" symbol named by its TITLE string — the macro name itself is // gone from s.name. GoogleTest's TEST/TEST_F/TEST_P and Google Benchmark's BENCHMARK family take // IDENTIFIER (not string) arguments, so tree-sitter-cpp's ordinary function_definition grammar accepts the // whole `MACRO( Args ) { … }` shape outright with no custom capture at all — verified empirically // (test/registermacrocheck.sh): the resulting symbol's NAME is literally the macro token itself ("TEST", // "BENCHMARK", …), never the caller's intended test/benchmark name. Both shapes, though extracted by // different ingest code paths, agree on ONE byte fact: `sigStartByte` is `ts_node_start_byte` of the // definition node either way (ingest.cpp), unconditionally — so the symbol's OWN signature text, read // from that byte, begins with the macro's identifier (`TEST_CASE( "title" )`, `TEST( Suite, Case )`, // `BENCHMARK( Name )`, …) immediately (optional whitespace) followed by '('. That single textual fact is // checked here, at REPORT time — no ingest change, no kParserVer bump, no new persisted field — and it is // exactly as extensible as a text scan can be: a repo's own block-forming macro that happens to take // identifier args gets the same free pass a GoogleTest TEST() gets, the moment its name is registered // (built in below, or via .ripwire_config's register_macros=, readRegisterMacrosConfig below). // // PRECISION OVER RECALL (the LB-E discipline, deliberately kept, same as isFixturePath/isTestScriptPath // above): matching is a WHOLE-TOKEN compare against a short, named list — never a "looks test-ish" guess, // and never testScope (L8's in-file test-scope bit is BROADER than this: for Rust/Python/TS/JS/C# it also // fires on a naming/attribute CONVENTION with no macro at all, and folding that in here would be exactly // the general "looks like a test, skip it" heuristic the plan calls out as the failure mode NOT to build). // The floor this leaves, stated rather than hidden: a hand-written function whose own text happens to // start with one of these exact tokens followed by '(' — realistically only a function or macro invocation // LITERALLY spelled `TEST(`/`BENCHMARK(`/etc. — is exempted too. That is a MISS (an undetected real // dead-code candidate), never a false accusation, the same failure direction the two predicates above // already accept. inline constexpr std::array kBuiltinRegisterMacros = { "TEST_CASE", "TEST_CASE_FIXTURE", "TEST_CASE_METHOD", "SCENARIO", "TEST_SUITE", // doctest + Catch2 (shared macro names) "TEST", "TEST_F", "TEST_P", // GoogleTest "BENCHMARK", "BENCHMARK_F", "BENCHMARK_TEMPLATE", "BENCHMARK_CAPTURE", // Google Benchmark }; // A macro-name token: a valid C-family identifier ([A-Za-z_][A-Za-z0-9_]*). Degrade-skip anything else // (a malformed .ripwire_config line mints NOTHING rather than a token that could accidentally prefix-match // real code) — the same "never throws, never guesses" posture notes.h documents for its own sidecar. inline bool isValidMacroToken( std::string_view token ) noexcept { if( token.empty() || ( !std::isalpha( static_cast( token[0] ) ) && token[0] != '_' ) ) { return false; } for( char c : token ) { if( !std::isalnum( static_cast( c ) ) && c != '_' ) { return false; } } return true; } // F-13 (audit 2026-09-02) — readRegisterMacrosConfig's two return lists: the valid names, and every KEY // token seen that was not "register_macros". The second list used to be thrown away at the point of // discovery (a bare `continue`), which is how a typo like `register_macrs = …` silently restored the false // positives the real key exists to remove — nothing on stderr, no header attribute, an inert config that // LOOKED live. Kept as two vectors rather than one struct-per-line list: every consumer wants "the name // set" untouched (registeredMacroNames, the hot matching path) and only the CLI verb layer wants the // second list, once per invocation, for disclosure. struct RegisterMacrosConfig { std::vector names; // valid register_macros=NAME tokens, sorted + deduped std::vector vendoredPaths; // Q-DIAL-5: vendored_paths=PATH[, PATH...] tokens, sorted + deduped std::vector unrecognizedKeys; // distinct key seen that is neither of the two above, sorted + deduped }; // NAME NOTE: this type and its reader are spelled for the FIRST key they carried, and they keep those names // on purpose — test/qschemetripcheck.sh's manifest keys the determinism guard on the function NAME // `readRegisterMacrosConfig`, so renaming it for tidiness would silently retire a guard. It is the // .ripwire_config reader; it reads two keys. // `.ripwire_config`'s TWO recognized keys: `register_macros = NAME[, NAME...]` and, since 2026-09-10, // `vendored_paths = PATH[, PATH...]` (Q-DIAL-5 — code this repo carries but did not write). Grammar: one directive per // line, '#' full-line comments, blank lines ignored; a line with no '=' at all carries no key/value shape // this file defines anything for, so it is left alone rather than guessed at (same "never throws, never // guesses" posture as the malformed-token skip below). A line that DOES have that shape but whose key is // not "register_macros" is a candidate directive with the wrong name — recorded in unrecognizedKeys rather // than silently skipped (F-13) — and a malformed/non-identifier value token is dropped rather than // accepted. Absent/unreadable/empty file yields two empty lists — INERTNESS CONTRACT: no config file // changes nothing about this run's set of exempted names (kBuiltinRegisterMacros still applies), and an // unrecognized key is disclosed, never a refusal — a typo in an otherwise-inert config must not fail a run. // One directive's VALUE list: comma-separated tokens, each trimmed, each admitted by its key's own rule. // Hoisted out of the line loop so that loop stays readable (and under its bars) now that the file carries two // keys. A PATH is root-relative with no '..' segment and no leading '/'; anything else is a value this file's // grammar defines nothing for and is dropped rather than guessed at, the same posture the macro-token check // takes. Never throws, never warns: a malformed VALUE is inert, and only a malformed KEY is disclosed. inline void appendConfigValueTokens( std::string_view rest, bool isVendor, RegisterMacrosConfig& out ) { std::size_t start = 0; while( start <= rest.size() ) { const std::size_t comma = rest.find( ',', start ); std::string_view tok( rest.data() + start, ( comma == std::string_view::npos ? rest.size() : comma ) - start ); while( !tok.empty() && ( tok.back() == ' ' || tok.back() == '\t' ) ) { tok.remove_suffix( 1 ); } while( !tok.empty() && ( tok.front() == ' ' || tok.front() == '\t' ) ) { tok.remove_prefix( 1 ); } if( isVendor ) { if( !tok.empty() && tok.front() != '/' && tok.find( ".." ) == std::string_view::npos ) { out.vendoredPaths.emplace_back( tok ); } } else if( isValidMacroToken( tok ) ) { out.names.emplace_back( tok ); } if( comma == std::string_view::npos ) { break; } start = comma + 1; } } inline RegisterMacrosConfig readRegisterMacrosConfig( std::string_view root ) { RegisterMacrosConfig out; // readRegularFile: a FIFO at the name hung every --quality-delta, and a directory there aborted on Linux (docparse.h). const std::string text = docparse::detail::readRegularFile( ".ripwire_config", configPath( root ) ).value_or( std::string() ); if( text.empty() ) { return out; // absent/unreadable/empty — inert, never a refusal } std::size_t pos = 0; while( pos <= text.size() ) { const std::size_t nl = text.find( '\n', pos ); std::string_view line( text.data() + pos, ( nl == std::string::npos ? text.size() : nl ) - pos ); pos = ( nl == std::string::npos ) ? text.size() + 1 : nl + 1; while( !line.empty() && ( line.back() == '\r' || line.back() == ' ' || line.back() == '\t' ) ) { line.remove_suffix( 1 ); } while( !line.empty() && ( line.front() == ' ' || line.front() == '\t' ) ) { line.remove_prefix( 1 ); } if( line.empty() || line.front() == '#' ) { continue; } const std::size_t eq = line.find( '=' ); if( eq == std::string_view::npos ) { continue; // no '=' at all — not this file's directive grammar, nothing to warn about } std::string_view key = line.substr( 0, eq ); while( !key.empty() && ( key.back() == ' ' || key.back() == '\t' ) ) { key.remove_suffix( 1 ); } constexpr std::string_view kKey = "register_macros"; constexpr std::string_view kVendorKey = "vendored_paths"; // Q-DIAL-5 const bool isVendor = key == kVendorKey; if( key != kKey && !isVendor ) { out.unrecognizedKeys.emplace_back( key ); // F-13: disclosed, not skipped continue; } appendConfigValueTokens( line.substr( eq + 1 ), isVendor, out ); } std::sort( out.names.begin(), out.names.end() ); out.names.erase( std::unique( out.names.begin(), out.names.end() ), out.names.end() ); std::sort( out.vendoredPaths.begin(), out.vendoredPaths.end() ); out.vendoredPaths.erase( std::unique( out.vendoredPaths.begin(), out.vendoredPaths.end() ), out.vendoredPaths.end() ); std::sort( out.unrecognizedKeys.begin(), out.unrecognizedKeys.end() ); out.unrecognizedKeys.erase( std::unique( out.unrecognizedKeys.begin(), out.unrecognizedKeys.end() ), out.unrecognizedKeys.end() ); return out; } // The combined, sorted, deduped registered-macro name list for ONE run: the built-ins above plus whatever // .ripwire_config's register_macros= adds. Sorted so nothing downstream needs its own re-sort. // The ONE shape both .ripwire_config consumers need: this tool's built-in list, plus whatever the repo's own // config adds, sorted and deduped so nothing downstream re-sorts. Factored the moment the second consumer // existed — `--quality-delta` reported vendoredPathPrefixes as a 114-token clone of this function the first // time it was written out longhand, which is the kind's whole job. inline std::vector mergeBuiltinsWithConfig( std::span builtins, std::vector fromConfig ) { std::vector out; out.reserve( builtins.size() + fromConfig.size() ); for( std::string_view b : builtins ) { out.emplace_back( b ); } for( std::string& extra : fromConfig ) { out.push_back( std::move( extra ) ); } std::sort( out.begin(), out.end() ); out.erase( std::unique( out.begin(), out.end() ), out.end() ); return out; } inline std::vector registeredMacroNames( std::string_view root ) { return mergeBuiltinsWithConfig( kBuiltinRegisterMacros, readRegisterMacrosConfig( root ).names ); } // Q-DIAL-5 (2026-09-10) — VENDORED PATHS: code this repo CARRIES but did not WRITE. No such notion existed // anywhere in this file, and the clone kinds paid for it: one commit (08416403, the timsort landing) produced // 9 duplication rows, 8 of 8 dead-code:new-symbol acks and 37 api-surface acks against an upstream body whose // shape is not this repo's to fix. The ledger says so in its own words, 11 times. // // Built-in conventions plus whatever `.ripwire_config`'s vendored_paths= adds. The built-ins are the four // directory names the ecosystem agrees on; a vendored file that lives somewhere else (this repo's own // src/infra/timsort.hpp) is exactly what the config key is for, because no convention can guess it. // HONEST SCOPE, measured while writing the gate for this: the CRAWLER already drops third_party/, vendor/ // and node_modules/, so those three names are here for completeness rather than effect — `external/` is the // only built-in the indexer actually reaches, and everything else vendored is reached through the config key. inline constexpr std::array kBuiltinVendoredPrefixes = { "third_party/", "vendor/", "node_modules/", "external/" }; inline std::vector vendoredPathPrefixes( std::string_view root ) { return mergeBuiltinsWithConfig( kBuiltinVendoredPrefixes, readRegisterMacrosConfig( root ).vendoredPaths ); } // `rel` is ROOT-RELATIVE (the relForHash spelling every sidecar key uses). A prefix ending in '/' names a // DIRECTORY and matches everything under it; one that does not is a whole path and must match exactly, so // `vendored_paths = src/infra/timsort.hpp` cannot silently swallow src/infra/timsort_extra.hpp. inline bool isVendoredPath( std::string_view rel, const std::vector& prefixes ) noexcept { for( const std::string& p : prefixes ) { if( p.empty() ) { continue; } if( p.back() == '/' ) { if( rel.size() >= p.size() && rel.compare( 0, p.size(), p ) == 0 ) { return true; } } else if( rel == p ) { return true; } } return false; } // A registered macro's own call syntax, read starting at the CALLEE's own signature start byte (`region` // begins at sigStartByte — either forEachSymbolBody's per-symbol slice below, or a caller's own substr): // a leading identifier exactly matching one of `names`, then optional whitespace, then '('. Linear scan // over `names` — the list is short (a dozen built-ins plus whatever a repo adds), so a sorted-binary-search // would spend more on the comparator than the scan it replaces. inline bool startsWithRegisteredMacro( std::string_view region, const std::vector& names ) noexcept { std::size_t end = 0; while( end < region.size() && ( std::isalnum( static_cast( region[end] ) ) || region[end] == '_' ) ) { ++end; } if( end == 0 ) { return false; } const std::string_view token = region.substr( 0, end ); bool matched = false; for( const std::string& name : names ) { if( token == name ) { matched = true; break; } } if( !matched ) { return false; } std::size_t p = end; while( p < region.size() && std::isspace( static_cast( region[p] ) ) ) { ++p; } return p < region.size() && region[p] == '('; } // W1-S2 (2026-08-11) — TOP-LEVEL INVOCATION IS A USE: the fnv1a64 name-hash set of every callee invoked from // FILE SCOPE (fromSymbol == kNoNode). buildGraph deliberately drops file-scope references from the call-graph // CSR (no caller symbol → no edge — correct for PageRank and the ranked map), which starves the dead kind: a // bash function whose ONLY call site is a top-level script statement has zero in-edges and was false-flagged // dead (confirmed on hooks/ripwire-nudge.sh's helpers, while the fn→fn-called control was correctly silent — // the same hole applies to any script language's module-level statements). The dead kind therefore consults // these file-scope call sites as its second evidence source. The ref filter mirrors buildGraph's call-edge // admission EXACTLY (Call|Macro roles; no inherit/doc-link/compose — a README backtick-mention must never // mark a symbol live) with only the fromSymbol test inverted. NAME-level matching, not per-target resolution // — the same heuristic level as the resolver's bare-name spray, and a collision errs in the safe direction // (false-live, never false-dead). Sorted + deduped for binary_search; deterministic (reference order is). // // ISSUE #60 — "FILE SCOPE" IS NOW A SYMBOL, AND THIS SET MUST STILL SEE IT. ingest_model.h // mintModuleScopeOwners gives a top-level call an owner, so `fromSymbol == kNoNode` alone stopped selecting // anything on a code corpus and this evidence source silently went EMPTY. What that costs is not // hypothetical: a file-scope call the resolver DECLINES (tier 3 — several same-named defs, none in the // caller's file or directory) mints no in-edge either, so its callee had no evidence left at all and // --quality-delta gated dead-code on an untouched, genuinely-called function (measured: +154 dead keys on // vue-core, +98 on django, +64 here). The mint only ever ADDS a caller, so this predicate widens to match: // a reference owned BY a module-scope owner is exactly the file-scope reference it used to be. kNoNode is // kept beside it — a non-call reference outside every definition still has no owner (emitReferences takes // findOwnedDef for those roles), and a corpus the mint never ran over must read the same as before. inline std::vector topLevelCalleeNameHashes( const IngestResult& ing ) { const auto atFileScope = [ & ]( const Reference& r ) noexcept { return r.fromSymbol == kNoNode || ( r.fromSymbol < ing.symbols.size() && ing.symbols[ r.fromSymbol ].kind == SymKind::ModuleScope ); }; std::vector hashes; for( const Reference& r : ing.references ) { if( !atFileScope( r ) || r.isInherit || r.isDocLink || r.isCompose || ( r.role != RefRole::Call && r.role != RefRole::Macro ) ) { continue; } hashes.push_back( fnv1a64( r.calleeName ) ); } std::sort( hashes.begin(), hashes.end() ); hashes.erase( std::unique( hashes.begin(), hashes.end() ), hashes.end() ); return hashes; } // Q-DIAL-2 (2026-09-10) — THE SYMBOLS A LANGUAGE INVOKES, for which "zero in-edges in a name-based call // graph" is evidence of nothing at all. This is what the dead kind's blanket header exclusion was a PROXY // for, stated directly, and it is measurable in both directions: all ten dead-code rows the verb produced // across 40 replayed commits were exactly these shapes (audit Q1 §2e W1), and the header rule that hid them // also hid 96.8% of this repo's own source from the kind (Q1 §3, synthetic S6 — the sole caller of a header // function deleted, silently missed). // // Each clause names a call site the parser cannot see as a named CALL: // * a TYPE (class/struct/interface) is never invoked at all — its in-edge count is not a liveness signal; // * `main` is invoked by the runtime; // * `operator...` is invoked by the OPERATOR'S SYNTAX (`a + b`, `p[i]`, `new T`, `f( x )` on a functor); // * a leading `~` is a C++ destructor — the language runs it at scope exit; // * name == the innermost scope segment is a CONSTRUCTOR in every language that spells one that way // (C++, Java, C#, PHP-in-part), built by object creation rather than by a call to that name; // * a Python-style dunder (`__enter__`, `__repr__`, `__init__`) is invoked by a protocol, never by name; // * a METHOD named init/deinit/constructor is Swift's / JavaScript's spelling of the same constructor // protocol. Scoped to Method deliberately: a free function called `init` is an ordinary function, and // excluding it would be the header rule's over-reach in a smaller costume. // A Rust Drop::drop is not a name rule here: it needs its impl block, so rustDropImplMethodIds (below) exempts it. // FLOOR, stated: this is a NAME-level rule, exactly like the resolver's own bare-name matching, and it errs // toward false-LIVE (a symbol wrongly considered invoked is silently not reported) rather than false-dead, // which is the direction a deletion candidate must err in. inline bool languageInvokedSymbol( const Symbol& s ) noexcept { if( s.kind == SymKind::Class || isStructOrNamedType( s.kind ) || s.kind == SymKind::Interface ) { return true; // a type is declared, never called } if( s.name == "main" ) { return true; // the runtime's entry point } if( s.name.rfind( "operator", 0 ) == 0 ) { return true; // invoked by the operator's own syntax } if( !s.name.empty() && s.name.front() == '~' ) { return true; // C++ destructor } if( s.name.size() > 4 && s.name.rfind( "__", 0 ) == 0 && s.name.compare( s.name.size() - 2, 2, "__" ) == 0 ) { return true; // Python dunder — invoked by a protocol } if( s.kind == SymKind::Method && ( s.name == "init" || s.name == "deinit" || s.name == "constructor" ) ) { return true; // Swift init/deinit, JavaScript constructor } if( !s.scope.empty() ) { const std::size_t sep = s.scope.rfind( "::" ); const std::string_view tail = sep == std::string::npos ? std::string_view( s.scope ) : std::string_view( s.scope ).substr( sep + 2 ); if( !tail.empty() && tail == s.name ) { return true; // constructor: the member that shares its type's name } } return false; } // Python test-framework hook names, ONE table per framework (CONTRIBUTING: one place per feature family). Two consumers read // them: pythonFrameworkInvokedSymbol below (the --quality-delta dead set) and pythonRunnerRoot (--dead-code / --safe-delete). // kXunitHooks pytest's xunit-style fixtures, collected from a test module with no call in the tree // kUnittestHooks unittest/Django TestCase methods the runner calls around a test (class scope) // kUnittestModuleHooks unittest's module-level entry points inline constexpr std::array kXunitHooks = { "setup_module", "teardown_module", "setup_function", "teardown_function", "setup_class", "teardown_class", "setup_method", "teardown_method" }; inline constexpr std::array kUnittestHooks = { "setUp", "tearDown", "setUpClass", "tearDownClass", "setUpTestData", "runTest", "asyncSetUp", "asyncTearDown" }; inline constexpr std::array kUnittestModuleHooks = { "setUpModule", "tearDownModule", "load_tests" }; // Python test-framework entry points (#228). unittest and Django's TestCase call the kUnittestHooks names around tests, the // kUnittestModuleHooks names around a module, and run every test* method as a test. Pytest runs test_* too, and calls the // kXunitHooks names (setup_method, teardown_module, ...) of a test module. No call in the indexed tree names them, so zero // in-edges says nothing. Name-level, like the dunder rule in languageInvokedSymbol: errs toward live. The test* and xunit // clauses also need a test module (isTestPath, or Django's tests.py), so a helper named testSomething or setup_method in // application code still reads as dead. Not covered, still reported: pytest's conftest hooks (pytest_configure ...). // @pytest.fixture functions need no clause here: a decorated def is handed to its decorator as a value (ingest_valuerefs.h // emitDecorators), so --quality-delta never reports one, and --dead-code lists none (pythonDecoratedDef, decorated-excluded=). inline bool pythonFrameworkInvokedSymbol( const Symbol& s, std::string_view p ) noexcept { if( !langFacts( s.lang ).frameworkEntryHooks || ( s.kind != SymKind::Method && s.kind != SymKind::Function ) ) { return false; } const std::string_view n = s.name; if( std::ranges::contains( kUnittestHooks, n ) || std::ranges::contains( kUnittestModuleHooks, n ) ) { return true; } if( n.substr( 0, 4 ) != "test" && !std::ranges::contains( kXunitHooks, n ) ) { return false; } const std::size_t sl = p.rfind( '/' ); const std::string_view fn = sl == std::string_view::npos ? p : p.substr( sl + 1 ); return isTestPath( p ) || fn == "tests.py"; } // QD-TEST-DEAD (P5 pilot 2026-11-10): Go and Rust tests are called by their language's test runner, never by name from the tree, // so zero in-edges says nothing about them — every new Go or Rust test printed a dead-code row (Python's runner hooks are // pythonFrameworkInvokedSymbol above; JS/TS tests are anonymous callbacks; C++ test macros are register macros). Rules: // Go `go test` runs a top-level func named Test, Benchmark, Example or Fuzz, bare or followed by a character that is not a // lowercase letter (TestMain, Test_x, ExampleT_M; `Testify` is no test), in a `_test.go` file. Name-level like the Python // rule: a helper in a _test.go file and a TestX in production code stay candidates. // Rust a def the ingest marked testScope: a `#[test]`-family fn, or a `#[cfg(test)]` module and everything inside it (the // in-file half of filter.h isTestSymbol). FLOOR, stated: a never-called helper inside a test module is not reported — // the bit does not say which item carries the attribute, and the rule errs toward live, as a deletion candidate must. inline bool goTestEntryName( std::string_view n ) noexcept { for( std::string_view prefix : { std::string_view( "Test" ), std::string_view( "Benchmark" ), std::string_view( "Example" ), std::string_view( "Fuzz" ) } ) { if( n.starts_with( prefix ) && ( n.size() == prefix.size() || !( n[ prefix.size() ] >= 'a' && n[ prefix.size() ] <= 'z' ) ) ) { return true; } } return false; } inline bool testRunnerInvokedSymbol( const Symbol& s, std::string_view p ) noexcept { switch( langFacts( s.lang ).testRunnerEntry ) { case TestRunnerEntry::GoTestName: return s.kind == SymKind::Function && p.ends_with( "_test.go" ) && goTestEntryName( s.name ); case TestRunnerEntry::RustTestAttr: return s.testScope != 0; case TestRunnerEntry::None: return false; } return false; } // The structural half of isDeadCandidate: a symbol with a body of its own that no indexed edge, file-scope statement or Python // self/cls dispatch reaches. Whether something the graph cannot see calls it is the other half (isDeadCandidate, below). inline bool uncalledBody( const IngestResult& ing, const Graph& g, NodeId i, const std::vector& topLevelCallees, const std::vector& pythonDispatchIds ) noexcept { const Symbol& s = ing.symbols[i]; if( s.kind == SymKind::Section || s.kind == SymKind::ModuleScope ) { return false; // markdown heading / a file's module scope (no body of its own) } if( s.sigEndByte >= s.endByte ) { return false; // no body (decl / prototype) } const auto* ro = g.inEdges.rowOffsets(); if( ro[i + 1] - ro[i] != 0 ) { return false; // has at least one caller } if( std::binary_search( topLevelCallees.begin(), topLevelCallees.end(), fnv1a64( s.name ) ) ) { return false; // W1-S2: invoked from file scope (a top-level script statement) — a use the CSR drops } // a Python self/cls call can dispatch to this override through an indexed base return !std::binary_search( pythonDispatchIds.begin(), pythonDispatchIds.end(), i ); } // A "dead deletion-candidate": has a body, no caller in the indexed tree, not invoked from file scope, not // invoked by the LANGUAGE itself (languageInvokedSymbol, above), not a test fixture, not produced by a // registered self-registering macro. A SIMPLE, // internally-consistent heuristic — the delta only needs baseline↔current consistency, not parity with the // fuller --dead-code verb. `topLevelCallees` is the sorted set topLevelCalleeNameHashes builds and // `registeredMacroIds` the sorted set registeredMacroSymbolIds builds (below, past forEachSymbolBody), and `dropImplIds` the // sorted set rustDropImplMethodIds builds. Every call site builds all three ONCE outside its symbol loop. `exemptedByRegisterMacro`, // when non-null, is set true iff this symbol satisfied every OTHER test here and was excluded SOLELY by the macro check, or is a // Rust test that the test-runner rule exempts first and registersItself also holds — the signal a caller needs to disclose an // honest "N excluded" count instead of just applying the rule silently (P2.2's honesty requirement). inline bool isDeadCandidate( const IngestResult& ing, const Graph& g, NodeId i, const std::vector& topLevelCallees, const std::vector& registeredMacroIds, const std::vector& pythonDispatchIds, const std::vector& dropImplIds, bool* exemptedByRegisterMacro = nullptr ) noexcept { if( exemptedByRegisterMacro ) { *exemptedByRegisterMacro = false; } if( !uncalledBody( ing, g, i, topLevelCallees, pythonDispatchIds ) ) { return false; } const Symbol& s = ing.symbols[i]; // Q-DIAL-2: the LANGUAGE calls it (languageInvokedSymbol replaced a blanket header exclusion); issue #494: Drop::drop, run by // the compiler at scope exit (rustDropImplMethodIds) if( languageInvokedSymbol( s ) || std::binary_search( dropImplIds.begin(), dropImplIds.end(), i ) ) { return false; } const std::string_view p = rootRelPath( ing, s.fileId ); // #228: a directory above the root never decides this // #228 unittest/Django/pytest, QD-TEST-DEAD `go test` / the Rust harness: the test runner calls this const bool runnerCalls = pythonFrameworkInvokedSymbol( s, p ) || testRunnerInvokedSymbol( s, p ); // fixtures are dead by design (noise rules); B10.1a: shell test-runner helpers — $(...) calls invisible to the parser if( !runnerCalls && ( isFixturePath( p ) || isTestScriptPath( p ) ) ) { return false; } // P2.2: self-registers via a static initializer the call graph cannot see. A Rust #[test] fn is exempt by the runner rule // first (QD-TEST-DEAD's testScope bit) and is ALSO registered (#499's registersItself), so it is counted either way. const bool registered = std::binary_search( registeredMacroIds.begin(), registeredMacroIds.end(), i ); if( !runnerCalls && !registered ) { return true; } if( exemptedByRegisterMacro ) { *exemptedByRegisterMacro = registered; } return false; } // The dead-code kind's one exemption beyond isDeadCandidate: a call the builtin-method name gate DECLINED could have // meant this definition (graph.h BuiltinMethodGate, Graph::gateDeclinedTarget), so it is not provably uncalled — which // is what it was before the gate, when that call bound to it by name. Both dead-set readers (the snapshot and the // delta) apply it after isDeadCandidate, so a symbol it exempts is exactly one that would otherwise be dead, and the // delta counts those as declined-call-excluded=. inline bool declinedCallMayReach( const Graph& g, NodeId i ) noexcept { return i < g.gateDeclinedTarget.size() && g.gateDeclinedTarget[ i ] != 0; } // ONE clone group of the CURRENT tree, reduced to the two facts an ack row can be healed from: the // member-set hash that IS the ack identity for both clone kinds, and the idiom verdict that decides their // severity. computeDelta already computes both for every group it scans (exactIdioms/type3Idioms), so // exporting them costs a copy rather than a second clone pass — see its cloneIdiomsOut parameter, and // backfillCloneAckProvenance, the one consumer. struct CloneIdiomFact { std::uint64_t hash = 0; std::string idiom; // cloneIdiomName( vd.idiom ) — the same string Regression::facet carries }; // hash a clone group by its SORTED member canonical ids — so "this set of functions is duplicated" is the // group's stable identity (adding a 3rd copy changes the set ⇒ a new group ⇒ reported as new duplication). // S2: member ids are the root-RELATIVE baselineCanonId so a committed clone baseline is root-spelling-portable // (member set identity is unchanged; only the path prefix inside each id is normalized). Deterministic. inline std::uint64_t cloneMemberSetHash( std::vector ids ) { std::sort( ids.begin(), ids.end() ); std::string joined; for( const std::string& x : ids ) { joined += x; joined.push_back( '\n' ); } return fnv1a64( joined ); } inline std::uint64_t cloneGroupHash( const CloneGroup& cg, const IngestResult& ing, std::string_view root ) { std::vector ids; for( NodeId m : cg.members ) { if( m < ing.symbols.size() ) { ids.push_back( baselineCanonId( ing, m, root ) ); } } return cloneMemberSetHash( std::move( ids ) ); } // The ONE body-hash identity rule: fnv1a64( path \0 scope \0 name ), path root-relative (relForHash). // PATH-QUALIFIED ALWAYS, including when scope is empty. canonicalId() DEGRADES to the bare name when a // symbol has no scope (resolve.h) — fine for display, catastrophic as a comparison key: every scope-less // `ok()` in a tree folds to ONE identity. --merge-scout hit it first (laneA adds a.sh::ok, laneB adds // b.sh::ok -> conflicts="1"), then --quality-delta's short-horizon-churn (W1-S2 repro, 2026-08-11: a NEW // shell fn rows() in one test script flagged churn against the same-named rows() in a file the change never // touched — gates 2+3 judged a cross-file FOLD, not a symbol). mergescout::buildTreeIndex and lanes.h claims // key byte-for-byte the same way — one key space, pinned by test/scoutkeycheck.sh, never a third scheme. inline std::uint64_t pathQualifiedKey( std::string_view relPath, std::string_view scope, std::string_view name ) { std::string idText; idText.reserve( relPath.size() + scope.size() + name.size() + 2 ); idText.append( relPath ).push_back( '\0' ); idText.append( scope ).push_back( '\0' ); idText.append( name ); return fnv1a64( idText ); } // THE SAME KEY, taken from a Symbol — and the ONE place a language's keying rule lives. Elixir indexes a // callable as `name/N` (parser version 95): run/1 and run/2 are two ENTITIES, so canonicalId keeps the arity, // but they are one piece of SOURCE under this key — exactly as C++ overloads of `f` already share one — so // an arity edit is a params movement on one identity (--edit-check: contract-change, params_was/params_now; // --quality-delta: a params row), never a dead old symbol beside a brand-new one, which is what the // arity-carrying key reported (PR #81 review item 4, test/elixirnamearitycheck.sh arm C). Every language // but Elixir keys by the name as indexed. Every call site keys through this overload: a raw // (path, scope, name) call beside it would be a second rule that has to be ARGUED equal to this one. // kQSnapCacheScheme v11 is this fold — a v10 blob's Elixir keys hash a different byte string. inline std::uint64_t pathQualifiedKey( std::string_view relPath, const Symbol& s ) { return pathQualifiedKey( relPath, s.scope, s.lang == Lang::Elixir ? elixirBaseName( s.name ) : std::string_view( s.name ) ); } // §D#4 error-masking and placeholder — attribute each hit (findQualityConstructs) to its ENCLOSING symbol by // byte-span containment, then COUNT hits per baseline canonId. A symbol contains a hit iff the hit's start byte // lies in the symbol's full def span [sigStartByte, endByte) in the same file. Overloads sharing a canonId SUM // (the count is a magnitude, not a max — two overloads each masking once = 2 masks under that id, and the delta // then fires when the total grows). Deterministic: findQualityConstructs is deterministic and the fold is a // pure sum. // // Attribution is O(hits · symbols-per-file) via a per-file symbol index; a hit inside no def (file-scope) is // dropped (no owning symbol → nothing to attribute a regression to — for a file-level TODO comment that is a // stated floor of the placeholder kind). Byte-span containment mirrors how ingest attributes References to // their enclosing definition, so the same-file, same-span discipline is consistent. struct ConstructCounts { gtl::btree_map mask; // every error-masking hit (→ Snapshot::maskBySym) gtl::btree_map maskReport; // the REPORT-ONLY subset of `mask` (→ maskReportBySym): widened shapes whose (shape, language) is not in kHandlerShapeGates gtl::btree_map placeholder; // stub / TODO hits (→ Snapshot::placeholderBySym) gtl::btree_map failureDefault; // the failure-default subset of `mask` (→ failureDefaultBySym): it names the row's facet }; // The innermost def whose span holds `startByte` in file `fileId`, or kNoNode. Smallest enclosing def wins // (a nested lambda/method inside a method), so a count lands on the innermost owning symbol. inline NodeId enclosingDefOf( const IngestResult& ing, const SymbolsByFile& byFile, std::uint32_t fileId, std::uint32_t startByte ) { if( fileId >= byFile.size() ) { return kNoNode; } NodeId owner = kNoNode; std::uint32_t bestLen = UINT32_MAX; for( NodeId i : byFile[ fileId ] ) { const Symbol& s = ing.symbols[i]; if( startByte >= s.sigStartByte && startByte < s.endByte && s.endByte - s.sigStartByte < bestLen ) { bestLen = s.endByte - s.sigStartByte; owner = i; } } ENSURES( owner == kNoNode || owner < ing.symbols.size(), "an owner is a def id taken from byFile, which indexes ing.symbols" ); return owner; } // One error-masking hit, counted under its owner's key: in the total, in the report-only part when it does not gate in // the owner's language, and in the failure-default part when it is that facet. inline void tallyMaskHit( ConstructCounts& counts, std::uint64_t key, std::string_view id, Lang lang ) { ++counts.mask[ key ]; if( !errorMaskHitGates( id, lang ) ) { ++counts.maskReport[ key ]; } if( id == kShapeFailureDefault ) { ++counts.failureDefault[ key ]; } } inline ConstructCounts constructCountsBySym( const IngestResult& ing, std::string_view root ) { ConstructCounts counts; const QualityConstructHits hits = findQualityConstructs( ing ); if( hits.mask.empty() && hits.placeholder.empty() ) { return counts; } // per-file symbol id list (only real-body defs can enclose a masking block). `symbols[i].id == i`, so // the shared bucket-and-sort's `s.id` is the same value the hand-written loop pushed as `i`. const SymbolsByFile byFile = symbolsByFileInIdOrder( ing, []( const Symbol& s ) { return s.endByte > s.sigStartByte; } ); // RIPWIRE_TEST_FAILURE_DEFAULT_SITES=1: list each failure-default hit an owning symbol holds on stderr, the whole-tree // sweep the facet's precision read is drawn from. Test-only; no output and no cost on any normal run. const bool listSites = std::getenv( "RIPWIRE_TEST_FAILURE_DEFAULT_SITES" ) != nullptr; // pathQualifiedKey, via the SAME rule maskBySym is stored under (see qualityKey). These counts are compared // against that map key-for-key, so a scheme that differs by one byte silently reports every construct as new. const auto keyOf = [ & ]( NodeId owner ) { return pathQualifiedKey( relForHash( ing.files[ing.symbols[owner].fileId], root ), ing.symbols[owner] ); }; for( const ErrorMaskHit& h : hits.mask ) { const NodeId owner = enclosingDefOf( ing, byFile, h.fileId, h.startByte ); if( owner == kNoNode ) { continue; } tallyMaskHit( counts, keyOf( owner ), h.id, ing.symbols[owner].lang ); if( listSites && h.id == kShapeFailureDefault ) { rw::emitTo( stderr, "ripwire: failure-default-site {}:{}\n", ing.files[h.fileId], h.line ); } } for( const ErrorMaskHit& h : hits.placeholder ) { const NodeId owner = enclosingDefOf( ing, byFile, h.fileId, h.startByte ); if( owner != kNoNode ) { ++counts.placeholder[ keyOf( owner ) ]; } } ENSURES( counts.maskReport.size() <= counts.mask.size() && counts.failureDefault.size() <= counts.maskReport.size(), "every report-only hit was also counted in the total, and every failure-default hit is report-only, under the same key" ); return counts; } // QD-IDENTITY-ONCE — the whole-tree passes that are PURE functions of one ingest, computed at most once per // `--quality-delta` call however many consumers read them. Under the IDENTITY BASIS (computeHeadBasis) the HEAD // snapshot is taken from the very ingest computeDelta then judges, so the clone passes (findClones + // findClonesType3, two thirds of the verb on envoy) and the construct re-parse used to run twice on one input, // and a third time for the --show-stale snapshot. Each accessor computes on first use and hands back the same // value after, which is byte-identical BY CONSTRUCTION: the passes are deterministic and read nothing but `ing` // (and `root`, for the construct keys). One instance serves ONE ingest; binding a second one is a plumbing bug. // A caller with nothing to share passes nullptr and each consumer computes its own, exactly as before. class TreePasses { public: const std::vector& exactClones( const IngestResult& ing ) { bind( ing ); if( !exact_ ) { exact_ = findClones( ing, int( kMinCloneTokens ) ); } return *exact_; } const std::vector& type3Clones( const IngestResult& ing ) { bind( ing ); if( !type3_ ) { type3_ = findClonesType3( ing, int( kMinCloneTokens ) ); } return *type3_; } // The keys are root-relative, so a second root is a second value: recomputed, never served from the first. const ConstructCounts& constructCounts( const IngestResult& ing, std::string_view root ) { bind( ing ); if( !constructs_ || constructsRoot_ != root ) { constructs_ = constructCountsBySym( ing, root ); constructsRoot_ = std::string( root ); } return *constructs_; } private: void bind( const IngestResult& ing ) { ASSUME( ing_ == nullptr || ing_ == &ing, "TreePasses: one instance serves one ingest" ); ing_ = &ing; } const IngestResult* ing_ = nullptr; std::optional> exact_; std::optional> type3_; std::optional constructs_; std::string constructsRoot_; }; // THE quality key, for a symbol in the CURRENT tree — the one rule computeSnapshot and computeDelta must // agree on, living ONCE so they cannot drift (the §B1.3 discipline baselineCanonId above follows for the // display id). // // WHY THIS IS NOT `fnv1a64( baselineCanonId(...) )` ANY MORE (2026-08-25, the scope-less fold round). It was, // for all seven canonId-keyed kinds — ccx/loc/nest/params/mask/dead/api — and that inherited canonicalId's // bare-name degrade wholesale: a scope-less symbol's key was `fnv1a64(name)`, PATH-INDEPENDENT, so every // scope-less `helper()` in the tree was one identity and perSymbolKind's max() reported whichever file's was // largest. That is not a cosmetic id problem, it SILENTLY HIDES REGRESSIONS: a function going ccx 1 -> 18 // under a same-named ccx-23 neighbour moves no max at all and is reported as nothing (test/qualitykeycheck.sh // arm (A) is exactly that fixture). Measured on this repo: 6,418 scope-less rows collapsing into 3,845 // identities — 2,573 identities lost. // // WHY THE FIX IS HERE AND NOT IN canonicalId. Path-qualifying canonicalId itself was measured and REJECTED: // the default map omits id= whenever it would equal the bare name, so qualifying it grows an attribute on all // 6,418 rows — +293,886 bytes, +26.4%, a straight G4 breach — and canonicalId is the resolver's identity, the // selector grammar, the MCP handle source, the notes key and merge-scout's key across 67 call sites. It would // also SPLIT 21 CORRECT folds in src/ alone: the `extern "C" tree_sitter_X` grammar entry points are declared // in BOTH ingest.cpp and main.cpp and are ONE C function, which the bare-name fold correctly unifies. // canonicalId answers "which ENTITY is this?" and must keep answering it; the quality key has to answer // "which piece of SOURCE is this?", and those are different questions. The bug was that quality borrowed the // entity key to ask a source question. // // So this is pathQualifiedKey — NOT A THIRD SCHEME, the SAME key d593de3 gave short-horizon-churn for this // exact reason ("pathQualifiedKey is THE one key space"), now extended to the other seven kinds. The two // CLONE kinds keep their member-set hash and are deliberately untouched; that floor is recorded in EVALS. inline std::uint64_t qualityKey( const IngestResult& ing, NodeId i, std::string_view root ) { const Symbol& s = ing.symbols[i]; return pathQualifiedKey( relForHash( ing.files[ s.fileId ], root ), s ); // the Symbol overload: the one keying rule per language } // ─── the defect-shape kind (the twelfth) ───────────────────────────────────────────────────────────────── // The anchor of top-level code: a key no definition can carry (no symbol has an empty name). inline std::uint64_t defectFileAnchor( std::string_view relPath ) { return pathQualifiedKey( relPath, "", "" ); } inline defectshape::Facet defectFacetOf( std::uint64_t site ) noexcept { return static_cast( site & 3u ); } // A site's identity: the facet and its normalized text. Never one of the two reserved file records (0, 1). inline std::uint64_t defectSiteValue( defectshape::Facet f, std::string_view text ) { std::string id( defectshape::facetName( f ) ); id.push_back( '\0' ); id.append( text ); std::uint64_t h = fnv1a64( id ) & ~std::uint64_t( 3 ); if( h == 0 ) { h = 4; } const std::uint64_t v = h | static_cast( f ); const bool keepsFacet = ( v & 3u ) == static_cast( f ); ENSURES( v != kDefectFilePresent && v != kDefectFileUnreadable && keepsFacet, "a site value is never a reserved file record and carries its facet" ); return v; } // A defect-shape ROW's identity — the ack key: the anchor, the facet AND the identities of the anchor's sites of // that facet (each a defectSiteValue: facet + normalized offending text), so an ack covers exactly the defects it // named (checklist 16). A format-arity ack and a utf8-cut ack on one definition are two acks; and an ack of // defect A does not cover a different defect B swapped into the same definition, nor a second site added beside // A — any change to the anchor's site set of that facet re-reports. `siteVals` is that set, ascending, copies // included (a multiset). fnv1a64 over the bytes: no wrapping multiply of our own (-fsanitize=integer). // Ledgers: the line format is unchanged; an ack written by an earlier build of this lane (key = anchor + facet) // matches no row, so its row re-reports and the ack is listed stale (finding-gone). No released build wrote one. inline std::uint64_t defectRowKey( std::uint64_t anchor, defectshape::Facet f, const std::vector& siteVals ) { std::string id( defectshape::facetName( f ) ); id.push_back( '\0' ); const auto put = [ &id ]( std::uint64_t v ) { for( int b = 0; b < 8; ++b ) { id.push_back( static_cast( ( v >> ( 8 * b ) ) & 0xFFu ) ); } }; put( anchor ); for( std::uint64_t v : siteVals ) { put( v ); } return fnv1a64( id ); } // The anchor's real sites of facet `f` in a key-sorted record list (records of one anchor are contiguous and // their site values ascending), for defectRowKey. template inline std::vector defectSiteValsOf( const Range& sorted, std::uint64_t anchor, defectshape::Facet f, KeyOf keyOf ) { std::vector vals; for( const auto& rec : sorted ) { const DefectSiteKey& k = keyOf( rec ); if( k.anchor == anchor && k.site != kDefectFilePresent && k.site != kDefectFileUnreadable && defectFacetOf( k.site ) == f ) { vals.push_back( k.site ); } } return vals; } // One current-side site with what the delta needs to print it: the anchoring definition (kNoNode for a file // anchor), its file and 1-based line. struct DefectSiteAt { DefectSiteKey key; NodeId owner = kNoNode; std::uint32_t fileId = 0; std::uint32_t line = 0; }; // §D#4 short-horizon-churn — a per-identity hash of the symbols' RAW body bytes, for CHANGE detection that // metrics miss. `hot(){ return 2; }` → `hot(){ return 3; }` moves NO metric (same ccx/loc/nest/params), and // clones.h normalization erases the literal (`$N`), so neither can tell the body changed — only a raw-byte // hash can. We read each file ONCE (per-file, like findClones), hash each def's [sigStartByte,endByte) body, // and fold overloads sharing an identity by hashing their SORTED per-symbol hashes (order-independent, // stable). Deterministic: pure function of file bytes + spans. A file that won't read contributes nothing // (degrade). Keys are pathQualifiedKey (above) on EVERY side — baseline, window-ref and working tree are // only ever compared to each other, and a one-sided qualification makes every symbol read as rewritten // (the trap the 1722-line comment used to pin). The churn loop in computeDelta derives its per-node lookup // key through the same helper, so the join's surfaces cannot drift independently. // THE per-file body-bytes walk, owned once. Every symbol with a real body, visited with a view of its // [sigStartByte, endByte) span, reading each FILE exactly once (the findClones shape) and degrading // identically on a file that will not read or a span that does not fit: it contributes nothing, silently, // because a truncated read is not evidence of anything. // // Extracted when --quality-delta flagged this lane against itself. The R1 content-id index needed the same // walk and copied it, and the reuse-decline kind reported a 495-token clone of a helper that already had // three call sites — which is precisely the finding that kind exists to catch, on the run that was adding // it. Two copies of "read each file once and hand me each body" is two places for the degrade rules to // drift, and those rules are the honesty contract here, not an implementation detail. // visit( NodeId, const Symbol&, body ), or visit( NodeId, const Symbol&, body, fileBytes ) for a rule that reads text OUTSIDE // the slice (#499's Rust test attribute stacks above the item): the walk passes the whole file only to a four-argument visitor. template inline void forEachSymbolBody( const IngestResult& ing, Fn&& visit ) { // per-file def ids with a real body (see constructCountsBySym above on `symbols[i].id == i`). const SymbolsByFile byFile = symbolsByFileInIdOrder( ing, []( const Symbol& s ) { return s.endByte > s.sigStartByte; } ); for( std::uint32_t f = 0; f < ing.files.size(); ++f ) { if( byFile[f].empty() ) { continue; } const std::string bytes = docparse::detail::readWholeFile( ing.files[f] ).value_or( std::string() ); if( bytes.empty() ) { continue; // unreadable or empty — contributes nothing, silently: a partial read is evidence of nothing } for( NodeId i : byFile[f] ) { const Symbol& s = ing.symbols[i]; if( s.endByte > bytes.size() || s.sigStartByte >= s.endByte ) { continue; } const std::string_view body( bytes.data() + s.sigStartByte, s.endByte - s.sigStartByte ); if constexpr( std::is_invocable_v ) { visit( i, s, body, std::string_view( bytes ) ); } else { visit( i, s, body ); } } } } // Direct Python class members get an owner: the enclosing class. A def nested inside a method gets a host: the // nearest enclosing method, whose self/cls it reads as a free variable. Module-level functions have neither. struct PythonScopes { std::vector owner; std::vector host; }; // Records one definition's enclosing scope: a class makes it a direct member; a method, or a closure in one, makes // the nearest method its host. inline void pythonRecordParent( PythonScopes& scopes, const IngestResult& ing, NodeId id, NodeId parent ) noexcept { if( ing.symbols[parent].kind != SymKind::Class ) { scopes.host[id] = scopes.owner[parent] != kNoNode ? parent : scopes.host[parent]; } else if( ing.symbols[id].kind != SymKind::Class ) { scopes.owner[id] = parent; } } inline PythonScopes pythonMethodOwners( const IngestResult& ing ) { const bool hasClasses = std::any_of( ing.symbols.begin(), ing.symbols.end(), []( const Symbol& s ) { return s.lang == Lang::Python && s.kind == SymKind::Class; } ); if( !hasClasses ) { return {}; } PythonScopes scopes; scopes.owner.assign( ing.symbols.size(), kNoNode ); scopes.host.assign( ing.symbols.size(), kNoNode ); SymbolsByFile byFile = symbolsByFileInIdOrder( ing, []( const Symbol& s ) { return s.lang == Lang::Python && ( s.kind == SymKind::Class || s.kind == SymKind::Function || s.kind == SymKind::Method ); } ); std::vector parents; for( auto& ids : byFile ) { std::sort( ids.begin(), ids.end(), [ & ]( NodeId a, NodeId b ) { const Symbol& x = ing.symbols[a]; const Symbol& y = ing.symbols[b]; if( x.sigStartByte != y.sigStartByte ) { return x.sigStartByte < y.sigStartByte; } if( x.endByte != y.endByte ) { return x.endByte > y.endByte; } return a < b; } ); parents.clear(); for( NodeId id : ids ) { const Symbol& s = ing.symbols[id]; while( !parents.empty() && ( ing.symbols[parents.back()].sigStartByte >= s.sigStartByte || ing.symbols[parents.back()].endByte < s.endByte ) ) { parents.pop_back(); } if( !parents.empty() ) { pythonRecordParent( scopes, ing, id, parents.back() ); } parents.push_back( id ); } } return scopes; } // The conventional receiver of each Python def and the receiver names it binds as parameters. Parameters are // VarDecl bindings in source order (emitBindings). kind: 1 self, 2 cls, 3 a first parameter that is neither, 0 none; // the first parameter decides it, so a later parameter named cls cannot replace it. bound: bit 1 self, bit 2 cls, // wherever the name sits in the list. struct PythonReceivers { std::vector kind; std::vector bound; }; inline PythonReceivers pythonReceiverParameters( const IngestResult& ing ) { PythonReceivers receivers; receivers.kind.assign( ing.symbols.size(), 0 ); receivers.bound.assign( ing.symbols.size(), 0 ); for( const Binding& b : ing.bindings ) { if( b.fromSymbol >= receivers.kind.size() || !langFacts( ing.symbols[b.fromSymbol].lang ).closureReceiverDispatch || b.kind != LocalBindKind::VarDecl || b.spanStart != 0 || b.spanEnd != 0 ) { continue; } const std::uint8_t name = b.var == "self" ? 1 : b.var == "cls" ? 2 : 0; receivers.bound[ b.fromSymbol ] |= name; if( receivers.kind[ b.fromSymbol ] == 0 ) { receivers.kind[ b.fromSymbol ] = name != 0 ? name : 3; } } return receivers; } // The method whose receiver a self./cls. call reads, or kNoNode. A method reads its own receiver. A closure nested // in a method reads the enclosing method's, unless the closure binds that receiver name itself. The method's receiver // must be the conventional one: self for ThisObj, cls for the NamedVar cls. inline NodeId pythonReceiverScope( const PythonScopes& scopes, const PythonReceivers& receivers, const Reference& r ) noexcept { const std::uint8_t want = r.recv == RecvKind::ThisObj ? 1 : 2; NodeId scope = kNoNode; if( scopes.owner[ r.fromSymbol ] != kNoNode ) { scope = r.fromSymbol; } else if( scopes.host[ r.fromSymbol ] != kNoNode && ( receivers.bound[ r.fromSymbol ] & want ) == 0 ) { scope = scopes.host[ r.fromSymbol ]; } return scope != kNoNode && receivers.kind[ scope ] == want ? scope : kNoNode; } // Deduplicate receiver-call evidence before walking inheritance; repeated call sites have the same possible targets. // Views borrow the ingested reference names for this one snapshot computation. inline std::vector> pythonDispatchRequests( const IngestResult& ing, const PythonScopes& scopes, const PythonReceivers& receivers ) { std::vector> requests; for( const Reference& r : ing.references ) { const bool selfOrCls = r.recv == RecvKind::ThisObj || ( r.recv == RecvKind::NamedVar && r.recvVar == "cls" ); if( !langFacts( r.lang ).closureReceiverDispatch || r.role != RefRole::Call || r.fromSymbol >= scopes.owner.size() || !r.qualifier.empty() || !selfOrCls ) { continue; } const NodeId scope = pythonReceiverScope( scopes, receivers, r ); if( scope != kNoNode ) { requests.emplace_back( scopes.owner[ scope ], r.calleeName ); } } std::sort( requests.begin(), requests.end(), []( const auto& a, const auto& b ) { return a.first != b.first ? a.first < b.first : rw::sortutil::svLess( a.second, b.second ); } ); requests.erase( std::unique( requests.begin(), requests.end() ), requests.end() ); return requests; } // Include the class itself and follow implementors DOWNWARD only. A walk up then down would admit // sibling classes the receiver cannot be. The graph already filters inheritance by language/root. inline std::vector pythonDispatchClasses( const Graph& g, NodeId base ) { std::vector classes{ base }; for( const ImplementorRow& row : implementorClosure( g.implementors, base ) ) // cycles and diamonds visit a class once { classes.push_back( row.id ); } return classes; } // Python self/cls dispatch can reach a subclass override even when the call graph pins the base // definition. Keep possible targets out of the deletion-candidate set; do not invent call edges. // Evidence is bounded to an enclosing class, a receiver parameter, and the indexed inheritance graph. // This is conservative liveness, not a model of Python's MRO, descriptors, or monkey-patching. inline std::vector pythonDispatchedMethodIds( const IngestResult& ing, const Graph& g ) { const PythonScopes scopes = pythonMethodOwners( ing ); if( scopes.owner.empty() ) { return {}; } const std::vector& owner = scopes.owner; HashMap> methods; methods.reserve( 32 ); for( NodeId i = 0; i < owner.size(); ++i ) { if( owner[i] != kNoNode && ing.symbols[i].sigEndByte < ing.symbols[i].endByte ) { methods[ owner[i] ].push_back( i ); } } const PythonReceivers receivers = pythonReceiverParameters( ing ); std::vector result; for( const auto& [ base, name ] : pythonDispatchRequests( ing, scopes, receivers ) ) { for( NodeId id : pythonDispatchClasses( g, base ) ) { const auto it = methods.find( id ); if( it == methods.end() ) { continue; } for( NodeId method : it->second ) { if( ing.symbols[method].name == name ) { result.push_back( method ); } } } } std::sort( result.begin(), result.end() ); result.erase( std::unique( result.begin(), result.end() ), result.end() ); return result; } // Q-DIAL-3 (2026-09-10) — THE VERBOSITY KIND'S METRIC: CODE lines, not physical lines. // // `Symbol::loc` is the def's physical line span, and the verbosity kind judged it directly. That makes blank // lines and comments debt: audit lane Q1 added 60 PURE BLANK lines inside an 18-LOC body and got // `verbosity was="18" now="78"`, gating, exit 2 — and the same for 60 pure COMMENT lines, in a repo whose own // CONTRIBUTING.md requires the reasoning to be written down. It is not hypothetical either: landed commit // 7d5dd201 ("comment(caps): update three stale cap justifications") added 7 comment lines and 1 code line and // produced two verbosity regression rows. Measured composition of what the kind judges, over 60 rows: // 72.8% code, 23.3% comment, 3.9% blank. // // A LINE HEURISTIC, NOT A LEXER, and the floor is stated rather than implied: a line counts as code unless it // is blank or its first non-space characters open a comment. So a trailing comment after code counts as code // (correct), a comment marker inside a string literal makes that line read as a comment (wrong, and rare), and // a multi-line raw string full of blank lines reads as blank (wrong, and rarer). The alternative is a second // tokenization pass per symbol on every --quality-delta, for a metric whose whole job is to say "this body is // big". Both sides of every comparison run the identical rule, which is the property the delta actually needs. // // Markers by language family, from the symbol's own `lang`: `//` plus `/* … */` for the C family and its // descendants, `#` for the shell/Python/Ruby/Elixir/config family (in the C family `#` opens a PREPROCESSOR // directive, which is code — that is why this is per-language and not one union set), `--` for Lua. Markdown // and JSON have no comment syntax, so every non-blank line there is content. // Slice 6c: hashComment moved to langFacts(l) in langfacts.h inline std::uint32_t codeLinesInBody( std::string_view body, Lang lang ) noexcept { const bool hash = langFacts( lang ).hashComment; const bool cLike = !hash && lang != Lang::Markdown && lang != Lang::Json && lang != Lang::Lua; const bool lua = lang == Lang::Lua; std::uint32_t code = 0; bool inBlock = false; std::size_t at = 0; while( at <= body.size() ) { const std::size_t nl = body.find( '\n', at ); std::string_view line = body.substr( at, ( nl == std::string_view::npos ? body.size() : nl ) - at ); at = ( nl == std::string_view::npos ) ? body.size() + 1 : nl + 1; while( !line.empty() && ( line.front() == ' ' || line.front() == '\t' || line.front() == '\r' ) ) { line.remove_prefix( 1 ); } while( !line.empty() && ( line.back() == ' ' || line.back() == '\t' || line.back() == '\r' ) ) { line.remove_suffix( 1 ); } if( inBlock ) { const std::size_t close = line.find( "*/" ); if( close == std::string_view::npos ) { continue; // still inside the block comment } inBlock = false; line.remove_prefix( close + 2 ); while( !line.empty() && ( line.front() == ' ' || line.front() == '\t' ) ) { line.remove_prefix( 1 ); } } if( line.empty() ) { continue; // blank } if( cLike && line.rfind( "//", 0 ) == 0 ) { continue; } if( hash && line.front() == '#' ) { continue; } if( lua && line.rfind( "--", 0 ) == 0 ) { continue; } if( cLike && line.rfind( "/*", 0 ) == 0 ) { inBlock = line.find( "*/", 2 ) == std::string_view::npos; if( !inBlock ) { const std::size_t close = line.find( "*/", 2 ); std::string_view rest = line.substr( close + 2 ); while( !rest.empty() && ( rest.front() == ' ' || rest.front() == '\t' ) ) { rest.remove_prefix( 1 ); } if( rest.empty() ) { continue; // `/* … */` alone on the line } } else { continue; } } ++code; } return code; } // The per-NODE code-line count for THIS tree, read off each symbol's own body bytes in ONE pass over the // files (forEachSymbolBody). A symbol with no readable body — a declaration, a prototype, an unreadable file — // keeps its physical `loc`: that span IS its signature, there is nothing to discount, and a silent 0 there // would read as "this symbol shrank to nothing" on the next delta. inline std::uint64_t scrubbedBodyHash( std::string_view body, std::string_view name ); // R1 IDENTITY, defined below // MOVED-BODY (QD-ENTRY-CEILING card 2, 2026-11-12) — THE MOVE IDENTITY of one callable: scrubbedBodyHash (whitespace and the // symbol's own name scrubbed, nothing semantic) over the BODY after its signature, so the same body under another name, in another // file, re-indented into a namespace or class, or with a reworded signature is one identity, and a body with one changed statement // is another. `def` is the [sigStartByte, endByte) view forEachSymbolBody hands out. 0 = no identity (not a callable). // The BODY of a [sigStartByte, endByte) definition view: everything after its signature (the whole view when no signature span is known). inline std::string_view bodyAfterSignature( const Symbol& s, std::string_view def ) noexcept { const std::size_t bodyAt = ( s.sigEndByte > s.sigStartByte && s.sigEndByte - s.sigStartByte < def.size() ) ? s.sigEndByte - s.sigStartByte : 0; return def.substr( bodyAt ); } inline std::uint64_t moveCidOf( const Symbol& s, std::string_view def ) { if( s.kind != SymKind::Function && s.kind != SymKind::Method ) { return 0; } const std::uint64_t cid = scrubbedBodyHash( bodyAfterSignature( s, def ), s.name ); return cid != 0 ? cid : 1; } // MOVES (2026-11-13) — the same body as the clone matcher sees it: its normalized token stream's minhash sketch (clones.h). inline CloneSketch moveSketchOf( const Symbol& s, std::string_view def ) { const std::string body( bodyAfterSignature( s, def ) ); return cloneSketchOfStream( normalizeTokens( body, 0, std::uint32_t( body.size() ), usesHashLineComments( s.lang ) ) ); } // The move identities of one tree: moveCidOf per node (0 = none) and, for the same nodes, the sketch (sparse, ascending node order). struct MoveIdentities { std::vector cid; std::vector> sketch; std::vector body; // QD-RENAME-IDENTITY: moveCidOf of EVERY callable, under the bars too (0 = not a callable) }; // `moveOut` (MOVED-BODY): when given, also each callable's moveCidOf and its sketch — only for a body over the ccx or the line bar, the only // bodies a new-function row (and so a move) can be about; 0 elsewhere. Same pass, so the corpus is read once. QD-RENAME-IDENTITY: and // moveCidOf of every callable in `body`, the identity a rename or move keeps (ContentMoves). inline std::vector codeLocByNode( const IngestResult& ing, MoveIdentities* moveOut = nullptr ) { std::vector out( ing.symbols.size(), 0 ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { out[i] = ing.symbols[i].loc; } if( moveOut != nullptr ) { moveOut->cid.assign( ing.symbols.size(), 0 ); moveOut->body.assign( ing.symbols.size(), 0 ); } forEachSymbolBody( ing, [ & ]( NodeId i, const Symbol& s, std::string_view body ) { if( s.kind == SymKind::Section || s.kind == SymKind::ModuleScope ) { return; // a markdown SECTION is prose: there is no code/comment line to separate, and counting // its non-blank lines as "code" makes an in-place doc rewrite that swaps 5 blank lines // for 5 sentences read as +5 verbosity. Measured on the ref-pair replay before this // clause: 03ec6f14 (a docs correction) went from a clean report to three minor rows. // Sections keep the physical span they always had — the churn kind exempts them for the // same reason ("doc sections churn by design"). } out[i] = codeLinesInBody( body, s.lang ); if( moveOut == nullptr ) { return; } moveOut->body[i] = moveCidOf( s, body ); if( moveOut->body[i] == 0 ) { return; } if( s.ccx > kCcxBar || out[i] > kLocBar ) { moveOut->cid[i] = moveOut->body[i]; moveOut->sketch.emplace_back( i, moveSketchOf( s, body ) ); } } ); return out; } // MOVED-BODY (QD-ENTRY-CEILING card 2) — WHICH NEW CALLABLE IS A BODY THIS DIFF MOVED. A body moved to another file or name gets a // new canonical id, so the origin axis read it as new code: the 11-04 replay's one moved row at the 4x ceiling (dispatchMainBody) // would gate as a "new 1,000-line function" on the commit that only relocated it. A current callable is a move when its move // identity (moveCidOf) equals the identity of a VACATED baseline body (MOVES below), and no other current // callable carries that identity (a body that is both kept and copied, or copied twice, is a copy: refuse, floors not guesses). // A rewrite is not a move: one changed statement changes the identity. Only bodies over the ccx or the line bar are recorded. // MOVES (2026-11-13, owner "fix moves in-lane first"): the exact identity missed the 30-PR replay's one false ceiling row, // extractHtmlFlat (#572) — the old extractHtml body under a new name with a 4-line edit, the old name kept as a 3-line wrapper. Two // changes: (1) a baseline body is VACATED when its key no longer carries a body over a bar (gone, or shrunk under the bars: the // wrapper case), not only when the key is gone; (2) a NEW callable (its key absent from the baseline) whose exact identity matches // nothing is still a move when it and one vacated body are each other's best clone-sketch match (cloneSketchJaccard, the Type-3 // matcher's own minhash) at kMoveSketchMinJaccardPct or more, with no tie on either side. A copy is still not a move (the original keeps // its body, so nothing is vacated), and two candidates for one vacated body refuse (the mutual-best test). struct MovedBodies { std::vector removed; // sorted move identities of VACATED baseline bodies std::vector current; // sorted move identities of every current body over a bar (a multiset: the uniqueness test) std::vector nearMoved; // sorted: new callables matched to a vacated body by sketch (mutual best, at the threshold) const std::vector& cidOf; MovedBodies( const Snapshot& base, const std::vector& keyOf, const MoveIdentities& now ) : cidOf( now.cid ) { std::vector held; // keys that still carry a body over a bar for( NodeId i = 0; i < keyOf.size() && i < now.cid.size(); ++i ) { if( keyOf[i] != 0 && now.cid[i] != 0 ) { held.push_back( keyOf[i] ); } } std::sort( held.begin(), held.end() ); for( std::uint64_t c : now.cid ) { if( c != 0 ) { current.push_back( c ); } } std::sort( current.begin(), current.end() ); // A vacated body some current body carries UNCHANGED is claimed by that exact match: its sketch is no near-move source, so a // lightly edited copy beside the unchanged move is never a second "moved" body of the same source (#646 CR). std::vector vacated; for( const auto& [ key, cid ] : base.moveCidBySym ) { if( !std::binary_search( held.begin(), held.end(), key ) ) { removed.push_back( cid ); const auto sk = base.moveSketchBySym.find( key ); if( sk != base.moveSketchBySym.end() && !std::binary_search( current.begin(), current.end(), cid ) ) { vacated.push_back( &sk->second ); } } } std::sort( removed.begin(), removed.end() ); matchNearMoves( base, keyOf, now, vacated ); } bool isMoved( NodeId i ) const { if( i >= cidOf.size() || cidOf[i] == 0 ) { return false; } if( std::binary_search( removed.begin(), removed.end(), cidOf[i] ) ) { const auto [ lo, hi ] = std::equal_range( current.begin(), current.end(), cidOf[i] ); return hi - lo == 1; } return std::binary_search( nearMoved.begin(), nearMoved.end(), i ); } private: // The best index by sketch-match count, or -1 when the best is shared (a tie refuses: floors, not guesses). Integer counts: // two equal counts are a tie exactly, never a float-equality accident. static std::ptrdiff_t uniqueBest( std::span scores ) { std::ptrdiff_t best = -1; bool tie = false; for( std::size_t k = 0; k < scores.size(); ++k ) { if( best < 0 || scores[k] > scores[ std::size_t( best ) ] ) { best = std::ptrdiff_t( k ); tie = false; } else if( scores[k] == scores[ std::size_t( best ) ] ) { tie = true; } } return tie ? -1 : best; } // The new callables a sketch match may claim: their key is absent from the baseline and their exact identity moved nothing. std::vector nearMoveCandidates( const Snapshot& base, const std::vector& keyOf, const MoveIdentities& now ) const { std::vector cands; // indexes into now.sketch for( std::size_t c = 0; c < now.sketch.size(); ++c ) { const NodeId i = now.sketch[c].first; if( i < keyOf.size() && keyOf[i] != 0 && base.locBySym.find( keyOf[i] ) == base.locBySym.end() && !std::binary_search( removed.begin(), removed.end(), now.cid[i] ) ) { cands.push_back( c ); } } return cands; } void matchNearMoves( const Snapshot& base, const std::vector& keyOf, const MoveIdentities& now, const std::vector& vacated ) { const std::vector cands = nearMoveCandidates( base, keyOf, now ); const std::size_t nv = vacated.size(); std::vector sim( cands.size() * nv ); // row = candidate, column = vacated body: matching sketch components for( std::size_t a = 0; a < cands.size(); ++a ) { for( std::size_t v = 0; v < nv; ++v ) { sim[ a * nv + v ] = cloneSketchMatches( now.sketch[ cands[a] ].second.data(), vacated[v]->data() ); } } std::vector col( cands.size() ); for( std::size_t a = 0; a < cands.size() && nv != 0; ++a ) { const std::span row( sim.data() + a * nv, nv ); const std::ptrdiff_t v = uniqueBest( row ); if( v < 0 || !moveSketchAtThreshold( row[ std::size_t( v ) ] ) ) { continue; } for( std::size_t b = 0; b < cands.size(); ++b ) { col[b] = sim[ b * nv + std::size_t( v ) ]; } if( uniqueBest( col ) == std::ptrdiff_t( a ) ) { nearMoved.push_back( now.sketch[ cands[a] ].first ); } } std::sort( nearMoved.begin(), nearMoved.end() ); } }; // EXTENT-CTOR (QD-ENTRY-CEILING card 1, 2026-11-12) — A CLASS IS NOT ITS CONSTRUCTOR'S BODY. A C++ class symbol is scoped by its // own name, so `class TextPool` and its constructor `TextPool::TextPool` share one canonical id, and every per-symbol kind keeps // the MAX over an id: the constructor's verbosity row read the CLASS's extent (TextPool::TextPool 129 lines, a 4-line // LayeredSearch::LayeredSearch 149, NameScan::NameScan 1,011 in the 11-04 replay). Where a callable (function or method) shares // the id, the non-callable symbols under it measure 0 code lines, so the row measures the callable's own body. A class with no // constructor keeps its id and its extent, as before; --metrics reads Symbol::loc and does not move. `keyOf[i]` is the // symbol's qualityKey, 0 for a symbol with no canonical id. Applied on both sides of the delta (computeSnapshot and computeDelta). inline void measureCallableNotItsContainer( const IngestResult& ing, const std::vector& keyOf, std::vector& codeLoc ) { const auto isCallable = []( SymKind k ) noexcept { return k == SymKind::Function || k == SymKind::Method; }; std::vector callableKeys; for( NodeId i = 0; i < ing.symbols.size() && i < keyOf.size(); ++i ) { if( keyOf[i] != 0 && isCallable( ing.symbols[i].kind ) ) { callableKeys.push_back( keyOf[i] ); } } std::sort( callableKeys.begin(), callableKeys.end() ); for( NodeId i = 0; i < ing.symbols.size() && i < keyOf.size() && i < codeLoc.size(); ++i ) { if( keyOf[i] != 0 && !isCallable( ing.symbols[i].kind ) && std::binary_search( callableKeys.begin(), callableKeys.end(), keyOf[i] ) ) { codeLoc[i] = 0; } } } // Q-DIAL-4 (2026-09-10) — DOES THE LAST DECLARED PARAMETER CARRY A DEFAULT? // // 113 of the 132 `api-surface` acks in this repo's own committed ledger (85.6%) say the same sentence: "one // trailing DEFAULTED parameter, every existing caller compiles unchanged". A kind whose acks are 86% one // shape is describing that shape, so the shape is read off the signature and reported sev="minor" instead of // being acked one row at a time. It is still a row — the contract DID change, and a defaulted parameter is // how most contract rot starts. // // A BRACE-DEPTH SCAN, NOT A PARSER, and the floor is stated: the signature's first '(' opens the parameter // list, its matching ')' closes it, the last comma at depth 0 starts the final parameter, and an '=' in that // final parameter is a default. Depth counts ( ) [ ] { } and, for C++ templates, < > — which is where the // heuristic can be fooled (`a < b` inside a default expression, an `operator<`), and where being fooled costs // exactly one severity tier on one row. Languages that spell defaults the same way (Python, TypeScript, PHP, // Ruby, C#, Swift) are covered by the same scan for free; a language that does not spell them at all simply // never matches. inline bool trailingParamHasDefault( std::string_view signature ) noexcept { const std::size_t open = signature.find( '(' ); if( open == std::string_view::npos ) { return false; } int depth = 0; int angle = 0; std::size_t lastComma = std::string_view::npos; std::size_t close = std::string_view::npos; for( std::size_t i = open; i < signature.size(); ++i ) { const char c = signature[i]; if( c == '(' || c == '[' || c == '{' ) { ++depth; } else if( c == ')' || c == ']' || c == '}' ) { --depth; if( depth == 0 ) { close = i; break; } } else if( c == '<' ) { ++angle; } else if( c == '>' && angle > 0 ) { --angle; } else if( c == ',' && depth == 1 && angle == 0 ) { lastComma = i; } } if( close == std::string_view::npos || close <= open + 1 ) { return false; // unclosed, or an empty parameter list } const std::size_t from = ( lastComma == std::string_view::npos ) ? open + 1 : lastComma + 1; const std::string_view last = signature.substr( from, close - from ); for( std::size_t i = 0; i < last.size(); ++i ) { if( last[i] != '=' ) { continue; } const bool cmp = ( i + 1 < last.size() && last[ i + 1 ] == '=' ) || ( i > 0 && ( last[ i - 1 ] == '=' || last[ i - 1 ] == '!' || last[ i - 1 ] == '<' || last[ i - 1 ] == '>' ) ); if( !cmp ) { return true; } } return false; } // The per-NODE answer for THIS tree, read off each symbol's own signature bytes in the same one-pass shape // codeLocByNode uses. forEachSymbolBody hands back [sigStartByte, endByte), and the signature is its prefix. inline std::vector trailingDefaultByNode( const IngestResult& ing ) { std::vector out( ing.symbols.size(), 0 ); forEachSymbolBody( ing, [ & ]( NodeId i, const Symbol& s, std::string_view body ) { const std::size_t sigLen = s.sigEndByte > s.sigStartByte ? std::size_t( s.sigEndByte - s.sigStartByte ) : 0; if( sigLen == 0 || sigLen > body.size() ) { return; } out[i] = trailingParamHasDefault( body.substr( 0, sigLen ) ) ? 1 : 0; } ); return out; } // ---- Rust test-harness registration (issue #493) --------------------------------------------------------------- // `#[test]` and `#[tokio::test]` (optionally with an argument list) register a function with the test harness, // which calls it by name without any call in the tree. They are attributes, not macro calls, so the signature- // text check above never sees them: the attribute stacks ABOVE the item, outside [sigStartByte, endByte). // isRustTestAttribute answers whether the text between "#[" and "]" is one of the two spellings. inline bool isRustTestAttribute( std::string_view attr ) noexcept { if( attr == "test" ) { return true; } constexpr std::string_view tokio = "tokio::test"; if( attr.substr( 0, tokio.size() ) == tokio ) { return attr.size() == tokio.size() || attr[ tokio.size() ] == '('; } return false; } // rustCodeOfAttributeLine returns an attribute line without a trailing `//` comment. Rust reads that comment as // whitespace, so `#[test] // case` is still `#[test]`. A `//` inside a double-quoted string is attribute text: // `#[tokio::test(flavor = "http://x")]` keeps its argument whether or not a comment follows it. inline std::string_view rustCodeOfAttributeLine( std::string_view line ) noexcept { bool inString = false; for( std::size_t i = 0; i < line.size(); ++i ) { const char c = line[ i ]; if( inString ) { if( c == '\\' ) { ++i; } else if( c == '"' ) { inString = false; } } else if( c == '"' ) { inString = true; } else if( c == '/' && i + 1 < line.size() && line[ i + 1 ] == '/' ) { line = line.substr( 0, i ); break; } } while( !line.empty() && std::isspace( static_cast( line.back() ) ) ) { line.remove_suffix( 1 ); } return line; } // rustAttributeClose returns the index of the `]` that closes the attribute whose text starts at `from` (just past its `#[`), // or npos when the line ends first. Brackets nest, and a double-quoted string is opaque: the `]` in // `#[doc = "a ]"]` and the `#[` in `#[doc = "#[test]"]` are text (CodeRabbit on #668). inline std::size_t rustAttributeClose( std::string_view line, std::size_t from ) noexcept { std::size_t depth = 1; bool inString = false; for( std::size_t i = from; i < line.size(); ++i ) { const char c = line[ i ]; if( inString ) { i += c == '\\' ? 1 : 0; inString = c != '"'; } else if( c == '"' ) { inString = true; } else if( c == '[' || c == ']' ) { depth = c == '[' ? depth + 1 : depth - 1; if( depth == 0 ) { return i; } } } return std::string_view::npos; } // How one line above an item reads, once its leading whitespace and trailing `//` comment are gone. enum class RustAttributeLine : std::uint8_t { Code, // anything but a run of whole `#[...]` attributes: the attribute block above the item ends here Test, // a run of attributes, one of them a test attribute Other, // a run of attributes, none of them a test attribute: keep reading upward }; // Splits the line into its top-level `#[...]` attributes and tests EACH one, so `#[tokio::test(flavor = "x")] #[allow(unused)]` // is a test line though its last attribute is not (CodeRabbit on #668). inline RustAttributeLine classifyRustAttributeLine( std::string_view line ) noexcept { bool test = false; for( std::size_t i = 0; i < line.size(); ) { if( std::isspace( static_cast( line[ i ] ) ) ) { ++i; continue; } const std::size_t close = line.substr( i, 2 ) == "#[" ? rustAttributeClose( line, i + 2 ) : std::string_view::npos; if( close == std::string_view::npos ) { return RustAttributeLine::Code; } test = test || isRustTestAttribute( line.substr( i + 2, close - i - 2 ) ); i = close + 1; } return test ? RustAttributeLine::Test : RustAttributeLine::Other; } // rustTestAttributed reads backwards from the item's signature start over blank lines, `//` comments and other // attribute lines (`#[inline]`, `#[allow(...)]`), and answers true when one of them is a test attribute. Whole-token // compare: `#[testing]` and a `#[test]` inside a comment do not count. An attribute line is a run of whole `#[...]` // attributes once its leading whitespace is gone: a `#[test]` written after code on the same line (`const A: u32 = 1; #[test]`) // is not read as an attribute of the item below it, so it ends the scan like any other code (issue #499 review). // FLOOR, stated: a multi-line attribute, or a block comment between attribute and item, ends the scan and the item // stays a dead-code candidate. That is a miss in the reporting direction, never a false exemption. inline bool rustTestAttributed( std::string_view file, std::size_t sigStart ) noexcept { std::size_t end = std::min( sigStart, file.size() ); // everything before `end` is still unread for( ;; ) { while( end > 0 && std::isspace( static_cast( file[ end - 1 ] ) ) ) { --end; } if( end == 0 ) { return false; } const std::size_t nl = file.rfind( '\n', end - 1 ); const std::size_t from = nl == std::string_view::npos ? 0 : nl + 1; std::string_view line = file.substr( from, end - from ); while( !line.empty() && std::isspace( static_cast( line.front() ) ) ) { line.remove_prefix( 1 ); } if( line.substr( 0, 2 ) == "//" ) { end = from; // a comment or doc line: keep reading upward continue; } line = rustCodeOfAttributeLine( line ); if( line.empty() ) { end = from; continue; } const RustAttributeLine kind = classifyRustAttributeLine( line ); if( kind != RustAttributeLine::Other ) { return kind == RustAttributeLine::Test; // a test attribute, or code that ends the attribute block } end = from; // another attribute on the way up: keep reading } } // The exemption a definition gets for registering itself with a runner the call graph cannot see: its own signature // begins with a registered macro call (the list above), or, for Rust only, a test attribute stacks above it. Both // --dead-code and --quality-delta read this one predicate, so the two verbs cannot disagree about one symbol. inline bool registersItself( const Symbol& s, std::string_view file, std::string_view sigRegion, const std::vector& names ) noexcept { if( startsWithRegisteredMacro( sigRegion, names ) ) { return true; } return langFacts( s.lang ).attributeRegistersTests && rustTestAttributed( file, s.sigStartByte ); } // issue #499 — whether the --quality-delta legend owes its Rust sentence (verbs_quality.h kQdRustTestLegend): some def sits in a // Rust in-file test scope (`#[test] fn`, `#[cfg(test)] mod`; model.h testScope) of a language whose test attribute registers it. // Read with register-macro-excluded= > 0, that is the run whose excluded set holds the harness's functions. No exemption reads it. inline bool anyRustTestScopeDef( const IngestResult& ing ) noexcept { return std::any_of( ing.symbols.begin(), ing.symbols.end(), []( const Symbol& s ) { return s.testScope != 0 && langFacts( s.lang ).attributeRegistersTests; } ); } // P2.2 — every symbol in THIS tree whose own signature text is a registered-macro call (built ONCE per // computeSnapshot/computeDelta run, exactly like topLevelCallees above), reading each file's bytes once via // forEachSymbolBody — whose per-symbol `body` view already starts at sigStartByte, which is precisely where // startsWithRegisteredMacro needs to look (see the P2.2 comment block above isFixturePath's neighbours). // Sorted for isDeadCandidate's binary_search. Short-circuits to empty when `names` is empty (never true for // the built-in call sites — kBuiltinRegisterMacros is never empty — but keeps the function honest for any // future caller that passes an empty override). // `rule` MacroCallOnly reads the macro-call half alone: inertRegisterMacroNames asks whether a configured NAME matched, and a // Rust #[test] fn matches no name (CodeRabbit on #668: with it counted, a typo'd name looked live in any tree with a Rust test). enum class RegisterRule : std::uint8_t { AnyRegistration, // registersItself: a registered macro call, or a Rust test attribute MacroCallOnly, // startsWithRegisteredMacro: the signature is a call of one of `names` }; inline std::vector registeredMacroSymbolIds( const IngestResult& ing, const std::vector& names, RegisterRule rule = RegisterRule::AnyRegistration ) { std::vector ids; if( names.empty() ) { return ids; } forEachSymbolBody( ing, [ & ]( NodeId i, const Symbol& s, std::string_view body, std::string_view file ) { if( rule == RegisterRule::MacroCallOnly ? startsWithRegisteredMacro( body, names ) : registersItself( s, file, body, names ) ) { ids.push_back( i ); } } ); std::sort( ids.begin(), ids.end() ); return ids; } // issue #494 (maintainer review): Rust Drop::drop, the method the compiler runs when a value leaves scope, which no call names. // A method named drop (or r#drop) is exempt when its span lies inside an ImplBlock record (model.h) of the same file whose trait // (var, the final path segment, so `impl std::ops::Drop` counts) is Drop, and no fn or method of that file encloses it inside that // block. The trait decides; the implementor's name is never the test. Stays reported: // * a free fn named drop: its kind is Function, or a `mod` fn (the grammar captures it as a Method) outside any Drop block; // * an inherent or other-trait method at file level: an inherent impl leaves no ImplBlock record, and another trait's block is not Drop; // * an inherent or other-trait method nested in a Drop body: that body's own Drop::drop encloses it, so the enclosing test holds it; // * the method of a mock trait named Drop (#[automock]): its ImplBlock names no implementor, so it never counts. // FLOOR, stated: the enclosing test reads only the symbols the extractor captures, and it looks for fn and method bodies. A method // inside the impl header (a block in a const generic argument) is in no body, so this rule exempts it; no test covers that shape. // FLOOR, stated: a user-defined trait whose final segment is Drop is read the same way, so its implementations are exempt too. // Built once per run, like registeredMacroSymbolIds, and read by isDeadCandidate. inline std::vector rustDropImplMethodIds( const IngestResult& ing ) { std::vector dropBlocks; for( const Binding& b : ing.bindings ) { if( b.kind == LocalBindKind::ImplBlock && b.var == "Drop" && !b.typeName.empty() ) { dropBlocks.push_back( &b ); } } std::vector ids; if( dropBlocks.empty() ) { return ids; } for( NodeId i = 0; i < ing.symbols.size(); ++i ) { const Symbol& s = ing.symbols[i]; if( s.kind != SymKind::Method || ( s.name != "drop" && s.name != "r#drop" ) || !langFacts( s.lang ).dropRunsAtScopeExit ) { continue; } for( const Binding* block : dropBlocks ) { if( block->fileId != s.fileId || s.sigStartByte < block->spanStart || s.sigStartByte >= block->spanEnd ) { continue; } bool nested = false; // a fn or method of this file, inside the block, whose body holds the method for( NodeId x = 0; x < ing.symbols.size() && !nested; ++x ) { const Symbol& o = ing.symbols[x]; nested = x != i && o.fileId == s.fileId && ( o.kind == SymKind::Function || o.kind == SymKind::Method ) && o.sigStartByte >= block->spanStart && o.endByte <= block->spanEnd && o.sigStartByte < s.sigStartByte && s.sigStartByte < o.endByte; } if( !nested ) { ids.push_back( i ); break; } } } return ids; } // F-13 (audit 2026-09-02) — which of `configNames` (the .ripwire_config-supplied names ONLY; never pass the // built-ins here, they are the tool's own defaults, not a repo's claim) matched NO indexed symbol at all. // Such a name is either a typo or names a macro this corpus does not use — inert either way, and inert // SILENTLY was the actual defect: the exemption looked live in .ripwire_config but excluded nothing, which // is worse than not having the line, because it reads as "handled". Reuses registeredMacroSymbolIds itself // (one full-corpus scan per name) rather than re-deriving the match rule, so "matched" here means exactly // what it means for the exemption that actually runs — a repo's config is at most a handful of names, so // the O(names) rescan costs nothing next to the ingest this verb already paid for. inline std::vector inertRegisterMacroNames( const IngestResult& ing, const std::vector& configNames ) { std::vector inert; for( const std::string& name : configNames ) { if( registeredMacroSymbolIds( ing, { name }, RegisterRule::MacroCallOnly ).empty() ) { inert.push_back( name ); } } return inert; } // F-13 — the two disclosure lists a CLI verb needs, computed once. Pure (no I/O): the caller owns the // stderr wording and the root attribute, same split every other verb in this file keeps (quality.h // computes, verbs_quality.h prints) — kept here rather than duplicated at each of the two call sites // (--dead-code and --quality-delta both exempt via registeredMacroNames/registeredMacroSymbolIds). struct RegisterMacroConfigDiagnostics { std::vector unrecognizedKeys; // distinct unrecognized .ripwire_config keys std::vector inertNames; // register_macros= names that matched no indexed symbol std::size_t total() const noexcept { return unrecognizedKeys.size() + inertNames.size(); } }; inline RegisterMacroConfigDiagnostics diagnoseRegisterMacroConfig( const IngestResult& ing, std::string_view root ) { const RegisterMacrosConfig cfg = readRegisterMacrosConfig( root ); RegisterMacroConfigDiagnostics diag; diag.unrecognizedKeys = cfg.unrecognizedKeys; diag.inertNames = inertRegisterMacroNames( ing, cfg.names ); return diag; } inline gtl::btree_map bodyHashesBySym( const IngestResult& ing, std::string_view root ) { gtl::btree_map> perId; // pathQualifiedKey → its symbols' raw-body hashes forEachSymbolBody( ing, [ & ]( NodeId, const Symbol& s, std::string_view body ) { const std::uint64_t key = pathQualifiedKey( relForHash( ing.files[ s.fileId ], root ), s ); perId[ key ].push_back( fnv1a64( body ) ); } ); gtl::btree_map out; for( auto& [ key, hs ] : perId ) { std::sort( hs.begin(), hs.end() ); // order-independent overload fold std::string joined; for( std::uint64_t h : hs ) { char b[ 17 ]; rw::formatTo( b, sizeof( b ), "{:016x}", static_cast( h ) ); joined += b; } out[ key ] = fnv1a64( joined ); } return out; } // ─── R1 IDENTITY: the SCRUBBED content hash ──────────────────────────────────────────────────────────── // // WHY A SECOND BODY HASH EXISTS AT ALL. bodyHashesBySym above hashes RAW bytes, because its job is CHANGE // DETECTION — it must notice `return 2` becoming `return 3`, so it may not normalize anything. This hash has // the opposite job: IDENTITY across a move. A symbol that was relocated is the same finding; a symbol that // was rewritten is not. The two cannot share one function, and merging them would break whichever caller // lost the argument. // // WHAT IS SCRUBBED, AND WHY EACH — each decided by a replay over this repo's own rename history, run // before any of this was written rather than justified after it: // * WHITESPACE. Every run of spaces/tabs collapses to one space; leading/trailing per-line whitespace and // blank lines are dropped entirely. This is the load-bearing one. A move that wraps a body in a // namespace or class RE-INDENTS it, and re-indentation is the single most common companion of a real // move. Measured on this repo's own 0eacce7 (ten pure header moves, 59 symbols): raw-byte body-hash // equality survives 100% of the byte-identical move and only 37.3% once the moved body is re-indented // by four spaces. A content identity that dies on indentation is not a content identity. // * THE SYMBOL'S OWN NAME, replaced by a fixed sentinel byte, so a rename of the symbol ITSELF keeps the // identity the brief asks it to keep. HONESTY, measured: this one is nearly inert — the same probe put // raw-hash survival at 96.6% under a symbol rename, because a body mentions its own name once or twice // at most. It costs one substitution and it is what the brief specifies, so it is here; it is NOT // claimed as a win, and the report records it as inert rather than dressing it up. // * `// ripwire-ack:` COMMENT LINES. An in-source ack comment must not change the hash of the very symbol // it annotates, or writing the ack would immediately destroy the identity the ack was written against // (a self-invalidating fixed point). The in-source ack surface itself is NOT part of this round — this // is only the hash-side precondition that makes it landable later without a second scrub revision. // // WHAT IS DELIBERATELY *NOT* SCRUBBED: anything semantic. No comment stripping beyond the ack line, no // literal normalization, no token normalization (clones.h owns that, for a different question). The moment // this hash starts erasing meaning it starts calling a REWRITE the same finding, which is precisely the // blank check the ack contract forbids — see test/identitycheck.sh claim (C). // // Deterministic: a pure function of (body bytes, name). No map, no state, no locale. inline constexpr std::string_view kInSourceAckMarker = "ripwire-ack:"; inline std::string scrubbedBody( std::string_view body, std::string_view name ) { std::string out; out.reserve( body.size() ); std::size_t lineStart = 0; while( lineStart <= body.size() ) { const std::size_t nl = body.find( '\n', lineStart ); const std::string_view line = body.substr( lineStart, ( nl == std::string_view::npos ? body.size() : nl ) - lineStart ); // collapse: drop leading/trailing blanks, squeeze interior runs to one space std::string squeezed; squeezed.reserve( line.size() ); bool pendingSpace = false; for( char c : line ) { if( c == ' ' || c == '\t' || c == '\r' ) { pendingSpace = !squeezed.empty(); // never emit a LEADING space continue; } if( pendingSpace ) { squeezed.push_back( ' ' ); pendingSpace = false; } squeezed.push_back( c ); } if( !squeezed.empty() && squeezed.find( kInSourceAckMarker ) == std::string::npos ) { out += squeezed; out.push_back( '\n' ); // one canonical separator; blank lines contribute nothing } if( nl == std::string_view::npos ) { break; } lineStart = nl + 1; } // the symbol's own name → a fixed sentinel. Whole-token only: replacing a bare substring would rewrite // `computeX` while scrubbing `compute` and make two unrelated symbols collide. if( !name.empty() ) { const auto wordByte = []( char c ) { return ( c >= 'a' && c <= 'z' ) || ( c >= 'A' && c <= 'Z' ) || ( c >= '0' && c <= '9' ) || c == '_'; }; std::string swapped; swapped.reserve( out.size() ); std::size_t at = 0; while( at < out.size() ) { const std::size_t hit = out.find( name, at ); if( hit == std::string::npos ) { swapped.append( out, at, std::string::npos ); break; } const bool whole = ( ( hit == 0 ) || !wordByte( out[ hit - 1 ] ) ) && ( ( hit + name.size() >= out.size() ) || !wordByte( out[ hit + name.size() ] ) ); swapped.append( out, at, hit - at ); swapped.push_back( whole ? '\x01' : out[ hit ] ); at = hit + ( whole ? name.size() : 1 ); } out.swap( swapped ); } return out; } inline std::uint64_t scrubbedBodyHash( std::string_view body, std::string_view name ) { return fnv1a64( scrubbedBody( body, name ) ); } // The corpus-wide content-id index: every symbol's scrubbed body hash, reachable from EITHER key space a // finding can carry, plus the multiplicity that decides whether a content match is allowed to resolve. // // TWO KEY SPACES, ONE INDEX — and this is the point of the round. A Regression's `key` is a canonId hash for // eight kinds and a pathQualifiedKey for short-horizon-churn (see Regression::key). Building a THIRD keying // for content would fork the key space the d593de3 churn-keying fix spent a whole round unifying, so the // index is instead keyed by BOTH of the existing spaces at once: each symbol inserts its cid under its // canonId hash AND under its pathQualifiedKey. The two are different hash spaces over different strings, so a // lookup by either finds the same cid and no consumer needs to know which space it holds. // // `symbolsPerCid` counts SYMBOLS, not keys (each symbol contributes one, regardless of being indexed twice), // because it answers exactly one question: is this scrubbed body unique in the tree? A cid shared by two // symbols is a genuine clone pair, and letting one ack rescue a finding on either of them would suppress a // finding nobody accepted. Ambiguity refuses to resolve — floors, not guesses. struct ContentIdIndex { gtl::btree_map cidByKey; // canonId hash OR pathQualifiedKey → scrubbed body hash gtl::btree_map keyByCid; // scrubbed body hash → the canonId hash of its ONE symbol (only meaningful when unique) gtl::btree_map symbolsPerCid; // scrubbed body hash → how many symbols carry it (>1 ⇒ refuses to resolve) bool isUnique( std::uint64_t cid ) const { const auto it = symbolsPerCid.find( cid ); return it != symbolsPerCid.end() && it->second == 1; } }; // One pass over the corpus, same per-file read shape as bodyHashesBySym (and the same degrade: a file that // will not read contributes nothing). Deliberately NOT folded into bodyHashesBySym: that function runs on // EVERY --quality-delta for the churn kind, while this one is paid for only when the ledger can actually use // it (see the callers, which skip it entirely for a cid-less ledger). inline ContentIdIndex contentIdsBySym( const IngestResult& ing, const Graph& g, std::string_view root ) { ContentIdIndex out; forEachSymbolBody( ing, [ & ]( NodeId i, const Symbol& s, std::string_view body ) { const std::string rel{ relForHash( ing.files[ s.fileId ], root ) }; const std::uint64_t cid = scrubbedBodyHash( body, s.name ); const bool hasCanon = ( i < g.canonId.size() && !g.canonId[i].empty() ); out.symbolsPerCid[ cid ] += 1; // per SYMBOL — the uniqueness question const std::uint64_t pqKey = pathQualifiedKey( rel, s ); if( hasCanon ) { // The canonId-space key is still INDEXED (an ack written by a pre-2026-08-25 // binary is spelled that way, and the "is this ack's target alive?" test must // recognize it), but it is no longer what a rescue RESOLVES TO: every quality key // space is pathQualifiedKey now, so handing back a canonId hash would re-file the // ack into a space nothing reads. out.cidByKey[ fnv1a64( canonicalId( rel, s.scope, s.name ) ) ] = cid; } out.cidByKey[ pqKey ] = cid; out.keyByCid[ cid ] = pqKey; // only read when symbolsPerCid[cid] == 1 } ); return out; } // ─── git-baseline helpers (the auto-vs-HEAD machinery behind --quality-delta / the quality_delta MCP verb) ─── // // These four helpers used to live in main.cpp's anonymous namespace. They are relocated here — the one home // that owns baselines — so BOTH the CLI (--quality-baseline / --quality-delta) and the MCP `quality_delta` / // `quality_baseline` verbs call the SAME code (no duplication of the git-archive / stale-vs-HEAD logic). main.cpp // re-exports them with `using` aliases so its existing call sites are byte-unchanged. // S4: shared per-user cache-directory ladder: $TMPDIR/ripwire → $XDG_CACHE_HOME/ripwire → // /tmp/ripwire-, always mode 0700. Keeping our artifacts one level below TMPDIR is a performance // boundary as well as a security one: cache hygiene must never enumerate an unbounded shared TMPDIR full of // unrelated agent-session files. Returns the dir with NO trailing slash. Deterministic per (user, env). // // #326 (structural follow-up): the value RETURNED here is what EVERY consumer in the tree builds cache paths // from — resolveCacheBlobPath (the choke point nearly every blob path routes through), evictOldCacheFamily/ // sweepStaleCacheBlobsOnce, slicediff.h/editpreview.h's temp parse roots, crossref.h's blob-batch listing, // ingest_docpass.h's doc-bridge cache, and main.cpp's remote-clone cache all take this string and either hand // it straight to os:: calls (already correctly rebased internally, no bug there) or to something OUTSIDE the // os:: layer — std::filesystem, a bare std::fopen — that is not. `--doctor`'s cache-dir check used to be the // one LOCAL fix (rebasing only its own copy of this string before use); rebasing HERE instead makes every one // of those consumers correct by construction, with none of them needing to know this ever mattered. os:: // mkdir/lstat/chmod below still verify the PRE-rebase spelling (harmless either way — rebased_path is a no-op // on an already-native path, since NativePath's own dispatch only fires on a leading "/tmp" or "/dev/null"), // so the verification logic is unchanged; only the RETURN value is now the spelling every downstream reader // needs. Identity on POSIX (rebased_path is `return path;` there), and identity on Windows for the two // TMPDIR/XDG_CACHE_HOME tiers too UNLESS the value they hold is itself "/tmp"-shaped (a plausible real case: // Git Bash sets TMPDIR=/tmp) — rebasing unconditionally, regardless of which tier produced the string, is // what makes that case correct too, rather than special-casing only the hardcoded third tier. // // #334, THE WINDOWS LAST RUNG, RULED AND KEPT: the third tier's "/tmp" rebases to GetTempPathW, whose documented order // is TMP, TEMP, USERPROFILE, then the Windows directory. So with TMPDIR, TEMP and TMP all unset the cache lands in the // profile root (%USERPROFILE%\ripwire-), not %LOCALAPPDATA%. That is kept: it is what every Win32 program calls // "temp" in that environment, it is per-user, --doctor's cache-dir row discloses it, and a Windows-only // %LOCALAPPDATA%\ripwire rung would break this ladder's one-shape-everywhere rule for an environment Windows itself // never produces (it sets TEMP and TMP per user). README's Windows section says where the cache goes. inline std::string cacheDirLadder() { std::string d; const char* tmpDir = std::getenv( "TMPDIR" ); if( tmpDir && *tmpDir ) { d = tmpDir; while( d.size() > 1 && d.back() == '/' ) { d.pop_back(); } d += "/ripwire"; } else if( const char* xdgCache = std::getenv( "XDG_CACHE_HOME" ); xdgCache && *xdgCache ) { d = std::string( xdgCache ) + "/ripwire"; } else { d = "/tmp/ripwire-" + std::to_string( static_cast( os::getuid() ) ); } const int mkdirRc = os::mkdir( d.c_str(), 0700 ); os::stat_t st {}; if( mkdirRc == 0 || ( os::lstat( d.c_str(), &st ) == 0 && S_ISDIR( st.st_mode ) && st.st_uid == os::getuid() ) ) { // Win32 chmod propagates inheritable ACLs through the whole cache tree, even when unchanged. // lstat already verifies a protected owner-only DACL; repair only a missing/private-mode mismatch. const bool alreadyOwnerOnly = ( st.st_mode & 0777 ) == 0700; if( ( alreadyOwnerOnly || os::chmod( d.c_str(), 0700 ) == 0 ) && os::lstat( d.c_str(), &st ) == 0 && S_ISDIR( st.st_mode ) && st.st_uid == os::getuid() && ( st.st_mode & 0777 ) == 0700 ) { return os::rebased_path( d.c_str() ); } } // unsafe/unusable candidate: make cache I/O fail closed. Rebased too, for the same reason — Windows' // rebaseDevNull spelling ("|unusable|...", a byte no Win32 filename may hold) is what actually makes it // unopenable there; the raw "/dev/null/..." spelling is only fail-closed by accident (drive-relative, // usually absent) the way the bug this file exists for relied on. return os::rebased_path( "/dev/null/ripwire-cache-unavailable" ); } // popen a shell command and return its trimmed stdout ("" on any failure — never crashes). THE one copy of // the popen-trim shape is rw::popenTrimmed in gitmine.h (the lower header; moved 2026-09-04 when resolveSinceScope // needed it too) — the git one-liners below, crossref.h, binstale.h and the doctor probes (doctorPopenTrim) all // still spell quality::popenTrimmed, which this using-declaration resolves. Not a wrapper: one definition. using rw::popenTrimmed; // isBareCommitSha (THE object-name gate) and gitResolveCommitSha (THE commit resolver) live in gitmine.h too — // moved down 2026-09-10 when resolveSinceScope needed them, so --since hands git a resolved sha instead of the // caller's string. gitIsAncestor / materializeCommitTree below and crossref.h still spell them quality::…, // which these using-declarations resolve. One definition each. using rw::isBareCommitSha; using rw::gitResolveCommitSha; // Run one short git query against `root` and return its whitespace-trimmed output (expected single-line), or // "" on any failure. The shared shape behind gitHeadSha / gitWindowRefSha — `tail` is everything after // `git -C ` INCLUDING redirects (so a caller can pipe, e.g. "rev-list HEAD 2>/dev/null | tail -1"). inline std::string gitOneLine( const std::string& root, const std::string& tail ) { return popenTrimmed( gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " " + tail ); } // ─── R1 IDENTITY: the GIT-RECORDED RENAME MAP ────────────────────────────────────────────────────────── // // computeDelta's own origin-axis comment states the rule this obeys: "There is no rename detection here and // adding one would make the classification non-deterministic (a similarity heuristic), which the determinism // law forbids." That objection is exactly right about a similarity heuristic WE compute, and exactly why // this reads a rename git ALREADY RECORDED instead of inferring one. The distinction is the whole design: // * The detection options are PINNED IN THE COMMAND — `-c diff.renames=true -M50%` — never inherited from // the user's config. A repo with `diff.renames=false`, or a different `diff.renameLimit`, must not make // a --quality-delta report different from the same tree elsewhere; that is the same reason the crawl // refuses `core.excludesFile`. // * The window is a FIXED COMMIT COUNT from HEAD, not a date. `git log -n K` from a fixed HEAD is a pure // function of the history; "since 30 days ago" is a function of the wall clock, which the determinism // law forbids everywhere else in this file too (see the churn window's HEAD-committer-epoch basis). // * Truncation is DISCLOSED, never silent: both hitting the commit window and hitting the pair cap are // reported on the root, so "your ack did not follow that rename" is answerable rather than mysterious. constexpr std::uint32_t kRenameWindowCommits = 400; // commits back from HEAD scanned for recorded renames constexpr std::size_t kRenameMaxPairs = 4000; // hard cap on recorded pairs (disclosed when hit) constexpr std::size_t kRenameMaxChain = 8; // a→b→c… chain depth followed from one current path (disclosed) struct RenameMap { // new-relative-path → the path it had immediately before that rename. Chains are followed by // ancestorsOf, not flattened here, so an ack recorded at ANY intermediate spelling still resolves. gtl::btree_map previousOf; std::uint32_t commitsScanned = 0; std::size_t pairsRecorded = 0; bool truncatedPairs = false; // kRenameMaxPairs hit — some renames are NOT in this map bool truncatedWindow = false; // history is deeper than kRenameWindowCommits — older renames unseen bool available = false; // git answered at all (a non-git root leaves this false) bool refusedPartial = false; // hwh-fix4 (N1): a partial clone, so the map was not asked for (no commit scanned) // Every path this one is known to have had, oldest-last, capped at kRenameMaxChain. Empty when the path // was never renamed — the overwhelmingly common case, and the one that must cost nothing. std::vector ancestorsOf( const std::string& rel ) const { std::vector out; std::string cur = rel; while( out.size() < kRenameMaxChain ) { const auto it = previousOf.find( cur ); if( it == previousOf.end() ) { break; } cur = it->second; if( std::find( out.begin(), out.end(), cur ) != out.end() ) { break; // a rename cycle (A→B then B→A across two commits) — stop rather than loop } out.push_back( cur ); } return out; } }; // Fold one `--name-status` listing's rename rows into `rm` (new path → its previous path), first writer wins, capped at kRenameMaxPairs. inline void absorbRenameRows( RenameMap& rm, const std::string& raw ) { std::size_t at = 0; while( at <= raw.size() ) { const std::size_t nl = raw.find( '\n', at ); const std::string line = raw.substr( at, ( nl == std::string::npos ? raw.size() : nl ) - at ); at = ( nl == std::string::npos ) ? raw.size() + 1 : nl + 1; if( line.empty() || line[0] != 'R' ) { continue; // only rename rows; the R-score suffix (R100/R089) is part of the status token } const std::size_t t1 = line.find( '\t' ); if( t1 == std::string::npos ) { continue; } const std::size_t t2 = line.find( '\t', t1 + 1 ); if( t2 == std::string::npos ) { continue; } const std::string oldPath = line.substr( t1 + 1, t2 - t1 - 1 ); const std::string newPath = line.substr( t2 + 1 ); if( oldPath.empty() || newPath.empty() || oldPath == newPath ) { continue; } if( rm.previousOf.size() >= kRenameMaxPairs ) { rm.truncatedPairs = true; return; } // FIRST writer wins: the log is walked newest-first, so the first row for a path is its most // recent rename, and ancestorsOf walks backwards from there one link at a time. rm.previousOf.emplace( newPath, oldPath ); rm.pairsRecorded = rm.previousOf.size(); } } // The UNCOMMITTED half: staged and unstaged renames against HEAD. `pinned` = the git prefix with quotepath/renames pinned and -C root. inline void absorbUncommittedRenames( RenameMap& rm, const std::string& pinned ) { // BOTH uncommitted queries are needed, and this is not belt-and-braces. Measured while building // test/identitycheck.sh arm (2): after a plain `git mv`, `git diff -M50% --name-status HEAD` reports // `A src/core/lib.h` + `D src/lib.h` — no rename row at all — while `git diff --cached` over the // IDENTICAL state reports `R100 src/lib.h src/core/lib.h`. Rename detection did not fail; the // index-vs-HEAD diff is simply the one that sees the pair. Querying only the worktree form would have // silently dropped the most common rename an agent ever makes — and the gate would still have passed, // because the content route rescues that same ack by a different mechanism. That near-miss is why the // gate asserts the ROUTE (acked_by_rename) and not merely the outcome. absorbRenameRows( rm, popenTrimmed( pinned + "diff --no-ext-diff --no-textconv --ignore-submodules=dirty -M50% --diff-filter=R --name-status --cached 2>/dev/null" ) ); absorbRenameRows( rm, popenTrimmed( pinned + "diff --no-ext-diff --no-textconv --ignore-submodules=dirty -M50% --diff-filter=R --name-status HEAD 2>/dev/null" ) ); } // Both halves of "what has been renamed since the ack was written": the UNCOMMITTED half (a `git mv` staged // in the working tree — the moment an agent is most likely to run --quality-delta) and the COMMITTED half // (the durable case, `git log -M50%` over the window). Read in that order so a path renamed twice — once in // history and again in the working tree — chains correctly through both. // // A pure function of (HEAD, index, working tree) for a fixed window. `--name-status -z` is NOT used: the // tab-separated porcelain here is stable, and quotepath=false is already pinned by gitOneLine's shape, so a // path with a space or a UTF-8 byte arrives intact. A path containing a literal TAB would mis-split; that is // recorded as a known floor rather than papered over, and it cannot corrupt anything — the worst case is a // pair that does not resolve, i.e. today's behavior. // `span` empty (the working-tree form) = the uncommitted `git mv` PLUS the last kRenameWindowCommits // commits. `span` set (the ref-pair form, "A..B") = exactly that range and nothing else, read against the // REAL repo — the two trees a ref-pair delta compares are materialized into temp dirs outside the repo, so // asking THEM about renames would answer "not a git repo" and silently lose every rename in the wave being // measured. The span is the honest scope there: the comparison IS that range. inline RenameMap gitRenameMap( const std::string& root, const std::string& span = {} ) { RenameMap rm; // One probe that answers BOTH questions — is this a git repo with a resolvable HEAD, and how deep is its // history (which decides whether the fixed window truncated). A non-git root answers "" and this returns // an empty, unavailable map: degrade, never guess. const std::string depth = gitOneLine( root, "rev-list --count HEAD 2>/dev/null" ); if( depth.empty() ) { return rm; } rm.available = true; const unsigned long long tot = std::strtoull( depth.c_str(), nullptr, 10 ); rm.commitsScanned = std::uint32_t( tot < kRenameWindowCommits ? tot : kRenameWindowCommits ); rm.truncatedWindow = tot > kRenameWindowCommits; if( gitIsPartialClone( root ) ) { // F1: rename detection (-M50%) reads blobs, and on a partial clone git scans the whole promisor pack before it fails (gitmine.h // gitIsPartialClone). So the map is not asked for: no commit was scanned (rename_window_commits="0") and the window is said to be // truncated, which is the existing way to say "older renames unseen". Git's recorded renames are not consulted; content routes remain. rm.commitsScanned = 0; rm.truncatedWindow = true; rm.refusedPartial = true; return rm; } const std::string pinned = gitCmd( " -c core.quotepath=false -c diff.renames=true -C " ) + shSingleQuote( root ) + " "; if( span.empty() ) { // Uncommitted first (a staged `git mv` is the single moment an agent is most likely to run this), // then history — in that order so a path renamed in history AND again in the working tree chains // through both. absorbUncommittedRenames( rm, pinned ); absorbRenameRows( rm, popenTrimmed( pinned + "log --no-ext-diff --no-textconv -M50% --diff-filter=R --name-status --format= -n " + std::to_string( kRenameWindowCommits ) + " 2>/dev/null" ) ); } else { rm.truncatedWindow = false; // the range IS the scope; nothing outside it was in question rm.commitsScanned = 0; absorbRenameRows( rm, popenTrimmed( pinned + "log --no-ext-diff --no-textconv -M50% --diff-filter=R --name-status --format= " + shSingleQuote( span ) + " 2>/dev/null" ) ); } return rm; } // QD-GIT-RENAME-HEAL — the no-ledger read (healIdentity with no ack ledger, working-tree form): only the staged and unstaged // renames, no commit scanned (rename_window_commits="0"). The baseline that form compares against is HEAD's (a pinned sidecar // is used only when pinned at HEAD), so a rename already in history cannot separate the two sides; the window is the ledger's, // whose rows may be older than any commit. No depth probe (it walks the whole history); on a partial clone the read is not // made and nothing is claimed unread (an unavailable map, as before this read existed). inline RenameMap gitUncommittedRenameMap( const std::string& root ) { RenameMap rm; if( gitOneLine( root, "rev-parse --verify --quiet HEAD 2>/dev/null" ).empty() || gitIsPartialClone( root ) ) { return rm; } rm.available = true; absorbUncommittedRenames( rm, gitCmd( " -c core.quotepath=false -c diff.renames=true -C " ) + shSingleQuote( root ) + " " ); return rm; } // The current HEAD commit sha (full, trimmed), or "" if `root` is not a git repo with a resolvable HEAD. // Used to STAMP a --quality-baseline sidecar and to detect a STALE one: a baseline pinned at a different HEAD // (an abandoned/parallel session, or from before a commit) no longer describes this tree, so trusting it makes // --quality-delta report a wall of false regressions. inline std::string gitHeadSha( const std::string& root ) { return gitOneLine( root, "rev-parse --verify --quiet HEAD 2>/dev/null" ); } // HEAD's committer date in ISO short form (YYYY-MM-DD) — the deterministic clock the L3 field-notes writer // stamps a note with (git's committer date, %cs), NOT the wall clock. A note's line is then a PURE function of // (the commit it was added under, target, text): byte-stable across machines and re-runs, the same det-gate // discipline the churn window follows (system now() is never consulted). Reuses gitOneLine (the shared // git-C+popen+trim shape). Empty on no-git / no-HEAD OR any output that is not exactly YYYY-MM-DD (10 chars, // dashes at 4 and 7) — the caller degrades to a fixed epoch date. Read-only: `git log` never mutates the repo. inline std::string gitCommitterDateIso( const std::string& root ) { std::string out = gitOneLine( root, "log --no-ext-diff --no-textconv -1 --format=%cs HEAD 2>/dev/null" ); // not const: a const local cannot be moved out on return if( out.size() != 10 || out[4] != '-' || out[7] != '-' ) { return {}; } return out; } // The commit-graph REACHABILITY check: is `ancestor` reachable from `descendant` (an ancestor of it, or the // same commit) in `root`'s history? Uses the standard `git merge-base --is-ancestor` primitive (exit 0 = yes; // 1 = no; anything else, including an unresolvable sha = degrade to false — never TRUST an unresolvable ref). // Empty inputs degrade to false. Deterministic for fixed repo state. // // R3 (owner ruling, 2026-07-29): this used to ALSO back the stale-baseline carve-out — a // `.ripwire_quality_baseline` pinned at a REACHABLE ancestor of HEAD was honored as a deliberate floor (B10.1b). // That carve-out is REVOKED (a parallel session's ancestor-pinned sidecar produced 31 phantom regressions on // the CLI while the MCP arm honestly reported zero); `selectBaseline` now decides staleness by STRICT sha // equality and never calls this. The remaining caller is `binstale.h`'s "is the built binary older than the // sources?" check, which is a genuine reachability question — do not delete this. inline bool gitIsAncestor( const std::string& root, const std::string& ancestor, const std::string& descendant ) { if( ancestor.empty() || descendant.empty() ) { return false; } // SINK GUARD (r27): both operands reach `std::system` as argv entries. merge-base has no file-writing // option today, which is the ONLY reason the sidecar-sourced `ancestor` was merely low severity rather // than the P0.1 data-loss bug — the shape is identical. Refuse anything that is not a bare object name. if( !isBareCommitSha( ancestor ) || !isBareCommitSha( descendant ) ) { DISCLOSE( "quality: refusing a non-sha revision token on the merge-base path" ); return false; // degrade: "not reachable" → the caller self-heals the pin } const std::string cmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " merge-base --is-ancestor " + shSingleQuote( ancestor ) + " " + shSingleQuote( descendant ) + " >/dev/null 2>&1"; return os::system( cmd.c_str() ) == 0; } // Signal-to-noise round — the CHURN-WINDOW reference commit: the newest commit STRICTLY OLDER than the // short-horizon window (HEAD's committer epoch − `days`), or — for a repo younger than the window, where every // commit is in-window — the OLDEST commit reachable from HEAD. Comparing a symbol's body at this ref vs the // baseline (HEAD) proves the symbol was ALREADY rewritten inside the window by COMMITS, which is the churn // evidence the current uncommitted edit alone can never supply. Deterministic: a pure function of repo state // (HEAD epoch anchors the window — wall-clock is never consulted). "" on any failure (degrade: churn silent). inline std::string gitWindowRefSha( const std::string& root, std::uint32_t days ) { const std::string epochStr = gitOneLine( root, "log --no-ext-diff --no-textconv -1 --format=%ct HEAD 2>/dev/null" ); if( epochStr.empty() ) { return {}; } const std::int64_t headEpoch = std::strtoll( epochStr.c_str(), nullptr, 10 ); if( headEpoch <= 0 ) { return {}; } // newest commit at-or-before the window floor (rev-list --min-age filters on committer time ≤ the bound; // cutoff−1 keeps a commit landing exactly ON the floor inside the window, matching gitmine's inclusive floor). const std::int64_t cutoff = headEpoch - std::int64_t( days ) * 86400; std::string preWindow = gitOneLine( root, "rev-list --max-count=1 --min-age=" + std::to_string( cutoff - 1 ) + " HEAD 2>/dev/null" ); // not const: moved out on return if( !preWindow.empty() ) { return preWindow; } return gitOneLine( root, "rev-list HEAD 2>/dev/null | tail -1" ); // repo younger than the window → its first commit } // Does `root` sit in a git repo that HAS at least one commit? A WINDOWLESS probe (no --since), so it is true // whenever history exists. This tells "git unavailable / not-a-repo / no-history" apart from "git fine, history // exists, but a --since window matched zero commits". popen failure degrades to false. inline bool gitRepoHasHistory( const std::string& root ) { const std::string cmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " rev-parse --verify --quiet HEAD 2>/dev/null"; std::FILE* pipe = os::popen( cmd.c_str(), "r" ); if( !pipe ) { return false; } char buf[ 128 ]; bool gotHead = false; while( std::fgets( buf, sizeof( buf ), pipe ) ) { if( buf[0] != '\n' && buf[0] != '\0' ) { gotHead = true; } } const int rc = os::pclose( pipe ); return rc == 0 && gotHead; } // ─── SHALLOW-HISTORY HONESTY (0.6.6 command sweep) ────────────────────────────────────────────────────── // A `--depth=N` clone (actions/checkout's default) holds only the newest N commits. Every history verb then // answers from that stub, and the sweep found them saying things that are false about the REPOSITORY: // "a root commit" for a commit whose parent was simply not fetched, "git unavailable" for a git repo with a // short history, `window="all-history"` over one commit, bf="1" from one squashed commit. The at= stamp's // `+shallow` suffix was the only disclosure. These three are the ONE probe and the ONE sentence every such // verb now shares (gitstamp::isShallow and the shallow="1" root attribute read the same probe). // // Not memoized: the MCP server is long-lived, and a `git fetch --unshallow` mid-session must be seen. inline bool gitIsShallow( const std::string& root ) { return gitOneLine( root, "rev-parse --is-shallow-repository 2>/dev/null" ) == "true"; } // Is `sha` a shallow BOUNDARY — a commit whose object records a parent the clone never fetched? The raw // commit object still carries its `parent` lines when the parent is missing (the shallow file grafts them // away from rev-parse/rev-list, not from the object), so this tells a boundary from a TRUE root commit in // a shallow clone whose depth happens to reach the root. `sha` must be a resolved commit name (the caller's // gitResolveCommitSha output); anything else answers false. inline bool gitIsShallowBoundary( const std::string& root, const std::string& sha ) { if( !isBareCommitSha( sha ) || !gitIsShallow( root ) ) { return false; } return !gitOneLine( root, "cat-file commit " + sha + " 2>/dev/null | sed -n '/^parent /{p;q;}'" ).empty(); } // The one way to say how to get the missing history, so no two verbs name it differently. // (Worded so no string literal here OPENS with a git command: githardencheck (L) reads such a literal as an // executed git invocation spelled outside rw::gitCmd(); this one is advice to a reader, never run.) inline constexpr std::string_view kShallowDeepenHint = "deepen it with git fetch --deepen=N, or git fetch --unshallow"; // A4-P1 — the HEAD-snapshot ingest cache. The HEAD tree is IMMUTABLE for a given HEAD sha, so its cold ingest // (~12.5 s on the 1498-file corpus) is perfectly cacheable: we hand the archived-tree ingest an incremental // content-hash cache file (the SAME format ingest()/loadCache()/saveCache() use for the auto-cache), so a // second --quality-delta on an unchanged HEAD is a pure warm hit. // // NEVER-STALE by construction, on two independent guards: // 1) FILENAME key = (realpath(repo-root), HEAD sha, the excludes list, a format tag). A different HEAD, a // different repo, or a different --exclude set → a different file → the wrong tree can never be loaded. // 2) ingest()'s own cache header (magic + kCacheVersion + parserVer, checksum trailer) and its PER-FILE // content-hash gate. Even if guard 1 were bypassed, loadCache rejects a format/parserVer mismatch outright // and every file whose content hash differs is re-parsed — so a stale or foreign blob self-heals to a // correct cold parse, never wrong facts. (Verified in ingest.cpp: kParserVer bumps invalidate the header; // contentHash64(bytes) — content-, not path-keyed — gates each file.) // // PORTABLE across the per-run tmp root: the HEAD tree is materialized under a pid-suffixed tmpRoot that differs // every run, but saveCache stores each key ROOT-RELATIVE (relForHash) and loadCache re-absolutizes it against // the CURRENT tmpRoot (ingest.cpp T5), and the freshness gate is a CONTENT hash — so run 1's cache built under // /…/ripwire-qhead- warm-hits run 2 under /…/ripwire-qhead- for the same HEAD. The cache file lives // under cacheDirLadder() directly (NOT inside tmpRoot), so it survives the tmpRoot RAII teardown. // // Bump when the HEAD-snapshot cache SCHEME changes (independent of ingest's own kParserVer, which the blob // header already self-validates). Folded into the filename key so an old-scheme file is simply never named. constexpr std::uint32_t kHeadSnapCacheScheme = 1; // ─── THE ROOT KEY — one canonical spelling, for every cache family ──────────────────────────────────── // // The 16-hex field every cache blob's filename carries, identifying the ROOT the blob belongs to: // `ripwire--{lean,rich}-cp.bin` (main.cpp::defaultCachePath), // `ripwire-mcp--cp.cache` (mcpindex.h::mcpCachePath) and `ripwire----.bin` // (shaKeyedCachePath below: qheadsnap, qsnap, qbody, qhist, qms, qchurn, stier). It is what makes // "which root does this blob belong to?" answerable from the NAME alone — see cacheBlobRootKey and the // byte-budget pin in evictBySizeBudget, which is only ever as wide as the set of blobs that spell the // key the SAME way. // // AND TWO SPELLINGS SHIPPED. Both builders hashed realpath(root) with FNV-1a, but with DIFFERENT offset // bases: `defaultCachePath` (and `mcpCachePath`) seeded 1469598103934665603 — seventeen digits, a // TRUNCATED FNV-1a-64 basis — while this function seeded arch.h's `fnv1a64`, i.e. the real // 14695981039346656037. Same material, two keys, on every root, always. Measured on llvm-project: // lean/rich carried 4280d3ca01d82374 while qchurn carried 6b73c58ba5897c7a; reproduced on a four-file // fixture as `ripwire-844a155665d606eb-{lean,rich}.bin` beside `ripwire-qchurn-526f2ad625b9f069--….bin`. // The consequence is exactly the gap P1-1 stated: the pin covered lean+rich and left every git-metadata // family evictable by the very root that had just written it. // // WHY THE SURVIVING BASIS IS THE TRUNCATED ONE, AND WHY IT MUST NOT BE "FIXED". A key change orphans // every blob spelled the old way. Adopting `fnv1a64`'s basis would have renamed the MAIN PARSE CACHE — // 1.76 GB of it on llvm-project alone (rich 1.19 GB + lean 0.57 GB), a full cold re-parse for every root // on the machine. Adopting defaultCachePath's renames only the git-metadata families, which are // kilobytes and rebuild from one `git log` walk. The constant is an IDENTITY, not a digest: FNV-1a's // avalanche comes from the prime multiply, and any odd seed gives the same distribution over these // inputs, so nothing is weaker — only the naming compatibility differs, and it differs by three orders // of magnitude. Changing `kCacheRootKeySeed` to the textbook basis would silently throw away every warm // parse cache in existence; test/evictioncheck.sh (k) is what makes such a change visible, but it will // go GREEN on a uniform wrong seed, so this paragraph is the guard. // // NORMALIZED, so the key follows the TREE and not its spelling: `realpath` collapses symlinks, `.`/`..`, // `//` and a trailing '/'. When realpath fails — the path does not exist, so there is nothing to cache // under it anyway — the same folding is done LEXICALLY (resolve.h's `lexicalNormalize`, the house's // segment-stack folder) so that at least the trailing-slash and `.`/`..` cases still agree; an unsound // `..` escape yields "" there and degrades to the verbatim spelling, still correct, at worst one extra // cold miss. Gate: test/evictioncheck.sh (k) one root ⇒ one key across every family, (l) a trailing // slash and a symlinked spelling add no new key. // // NO SCHEME BUMP, AND THE REASON IS THE HOUSE RULE ITSELF, NOT AN OMISSION. `kQChurnCacheScheme`, // `kQSnapCacheScheme` and `kHeadSnapCacheScheme` exist so that a blob whose CONTENT MEANING changed // becomes a clean miss rather than a wrong answer served from cache (see kQChurnCacheScheme's own comment: // scheme 2 was a merge-blind stream). Nothing about any blob's content changes here — only the root FIELD // of its NAME. Every pre-existing blob is therefore already never NAMED again, which is precisely the // effect a bump buys, reached by the key rather than by a version. Bumping on top would assert a content // change that did not happen, and would additionally invalidate the blobs that are about to be re-minted // under the unified key anyway. The old-spelling blobs are ordinary orphans: the "ripwire-" family sweep // still matches them by prefix, so the 30-day age pass deletes them on schedule — verified by seeding one // backdated `ripwire-qchurn--…bin` and watching a later run remove it. That pass is silent for // every blob it takes (it has no disclosure line at all — see evictBySizeBudget's note on why only the // byte-budget pass speaks), so an orphan is treated exactly as any other aged-out blob, with no special // case in either direction. inline constexpr std::uint64_t kCacheRootKeySeed = rw::hashutil::kFnv1aLegacySeed64; inline std::string cacheRootKeyHex( const std::string& root ) { char* rp = os::realpath( root.c_str(), nullptr ); std::string absRoot; if( rp != nullptr ) { absRoot = rp; std::free( rp ); } else { absRoot = lexicalNormalize( root ); if( absRoot.empty() ) { absRoot = root; // a `..` that escapes above its own base — unsound to fold, hash it verbatim } } std::uint64_t h = kCacheRootKeySeed; for( const char c : absRoot ) { h = rw::hashutil::fnv1aAbsorb( h, c ); } char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( h ) ); return std::string( hex ); } // ─── P0.2 — the EXTRACTION-IDENTITY key (r27) ────────────────────────────────────────────────────────── // // THE BUG THIS CLOSES (it already fired, in production, silently). Every sha-keyed quality cache blob — // qheadsnap (the HEAD ingest), qsnap (the computed HEAD Snapshot), qbody (the window-ref body hashes) — // holds facts that are FUNCTIONS OF TREE-SITTER EXTRACTION: canonIds, ccx/loc/nest/params, raw-body hashes, // clone groups, the dead set, the public-API set. Yet neither `kCacheVersion` nor `kParserVer` appeared in // the blob header OR the filename key. Commit `28c7d32` bumped kParserVer 28→30 for a `qualifierOf` fix that // corrected **80 wrong canonical ids** without touching kQSnapCacheScheme: the ingest blob self-heals on its // own header guard, the qsnap blob does NOT — it was simply re-served, wrong canonIds and all. Layered on the // r26 origin split (`fbc527e`) that is the nasty part: a stale baseline holds the wrong canonId → the working // tree's correct canonId is absent from `base.locBySym` → a REAL regression classifies `origin="new-symbol"` // → it does not gate. The origin split MASKS the poisoned cache instead of surfacing it. // // THE FIX, in both places (belt and braces, the same two-guard discipline the family already documents): // 1. FILENAME KEY — folded in below, so an old-extraction blob is never NAMED again (no purge needed; the // owner's call is that correctness must come from the key, not from deleting blobs — disk is cheap and a // purge is a one-shot that the next bump re-opens). // 2. BLOB HEADER — serializeSnapshot/deserializeSnapshot carry and verify the pair, so even a blob reached // by some other route (a hand-copied file, a hash collision) is rejected rather than believed. // // WHY A MIRROR, AND WHY IT CANNOT DRIFT: `kCacheVersion`/`kParserVer` live in ingest.cpp (a .cpp), not in // ingest.h, so a header cannot link to them. Mirroring a constant is exactly the failure mode that produced // this bug, so the mirror is not trusted — `test/qextractionkeycheck.sh` parses BOTH files and FAILS the // suite the moment the two disagree, and `test/qschemetripcheck.sh` (which previously hashed only quality.h // functions and never looked at ingest.cpp — precisely why this shipped) now hashes the ingest-side constant // lines too. Bumping kParserVer without updating these two lines is a hard gate failure, not a silent miss. // The FOLLOW-UP this note asked for is done the other way round: ingest_cache.h holds // `static_assert( quality::kIngestParserVerMirror == kParserVer && … )`, so a missed mirror now fails the build. It does // not include this header; it relies on ingest.cpp including quality.h (line 13) before ingest_cache.h, and a reorder // that broke that fails the build on the undeclared name rather than passing. constexpr std::uint32_t kIngestCacheVersionMirror = 53; // MUST equal ingest.cpp's kCacheVersion (gated); 53 = lane rust-self-chain placeholder (LocalBindKind RecvCall), 52 = lane failure-default (construct-hit failure-default tag), 51 = lane qd-constructs (FILE record construct-hit family), 50 = lane clones-persist (Function/Method def record clone key), 49 = lane warm-direct (FILE record head family counts), 48 = train 42b (alias-import LocalBindKind ReExport; its placeholder 47), 46 = train 40 (js-def-naming JsObjectLiteral; its placeholder 45), 44 = train 37b (rust-degraded FileHealth::useBoundsBlanked; its placeholder 42), 43 = train 36 (#155 trailingLambda ref byte; above main 40, #438's placeholder 41, rust-degraded's 42), 40 = train 34 (fc3-js-rebind JsRebind; above main 39), 39 = train 33 (above main 36 and l6-iface 38), 38 = train 32 lane l6-iface fix round 1: LocalBindKind ImplBlock (train renumbers), 37 = train 32 lane l6-iface: LocalBindKind DispatchType (train renumbers), 36 = train 30 (above call-result-typing's and fcall-forward's 33, name-template-dispatch's 35, main's 34), 34 = train 29 (above lane arity-min's and call-result-typing's 33), 33 = train 29 lane arity-min: def record paramsMin (the train renumbers), 33 = lane call-result-typing: RawBind resultIndex + unwrapDepth, 33 = lane fcall-forward: ref `forwarded` byte, 35 = lane name-template-dispatch: RefRole Pattern 11, 32 = train 28: RefRole Subscript 9 + Inert 10, 31 = train 27: lego-transitive's inherit-ref baseBind (the lane's 30), 29 = FE-B ref memberPath/memberCtor + 4 bind kinds, 28 = FE-A ref memberCall/memberRoot, 27 = corrected fnScope values, 26 = function-local def scope span (25 = #157 + #150) constexpr std::uint32_t kIngestParserVerMirror = 333; // MUST equal ingest.cpp's kParserVer (gated) // 333 = 2026-11-18 (train 1117d2 on train 1117d1, rich 334; members below, each was a placeholder) // std-namesake (placeholder 317): a Rust binding written as a standard type keeps its spine on the tombstone // rust-self-chain (placeholder 319; kCacheVersion 53): Rust RecvCall records for member calls on a call's result, async ReturnType bit // rust-macro-args (placeholder 315): calls inside Rust macro arguments are references // 331 = 2026-11-18 (train 1117d1, rich 332; members below, each was a placeholder) // go-cpp-edges (placeholder 317): a Go generic result type `Set[T]` records its ReturnType as the instantiated class // cpp-ptr-alias (placeholder 321): a C++ Type / ParamType record whose declarator names the variable carries kDirectDeclaratorBit // overload-split (placeholder 329): a Go qualified generic instantiation keeps its package qualifier // small-edges-1118 (placeholder 323): a Go method expression `(*T).m` in a value position is a Value row (GO-METHOD-EXPR) // edge-strays-1118 (placeholder 327): Rust `::m` calls are qualified by T, else by Trait // 313 = 2026-11-17 (TRAIN-1117b, one number for two members, above main 311/312 (#420 via #686); rich 314; // see the kParserVer note): #446 round 2 (@SeddonShen, lane land-606, its placeholder 316): Java base clauses as // @reference.base captures; #355 (PR #426 by @conka8, its placeholders 216 then 311): tags-pass string predicates + // Elixir keyword tables in tags.scm // 311 = 2026-11-17 (#358 C# 1a, @LaimaWu, lands #420: using directives as shared @import.path captures; rich 312) // 309 = 2026-11-13 (lane macro-p0 placeholder: C-family macro invocations read as typeless declarators are uses, not defs; + macro-p1 trailing annotation macros; rich 310) // 307 = 2026-11-11 (lane rust-macro-path placeholder: Rust path macro sites + `$crate::m!` in transcribers; rich 308) // 305 = 2026-11-10 (#446 round 1: C++ base clauses as @reference.base captures; above main 303 and PR head 304; rich 306) // 303 = 2026-11-06 (lane proto-index, placeholder above main 301 and #538's 302; rich 304): .proto indexed // 301 = 2026-11-04 (#478 gap 2, PLACEHOLDER: an aliased Python import records `a.b`, not `a.b as c`; rich 302) // 299 = 2026-11-03 (lane index-alias-const main merge, above lane 293/294 and main 297/298; rich 300) // 297 = 2026-11-03 (lane edge-prelude-veto fix: a Rust macro_rules' textual-scope bit) // 293 = 2026-11-03 (lane index-alias-const: C++ alias forms are definitions; rich 294) // 291 = 2026-11-03 (lane docs-rest #506 re-bump above main's 289/290; rich 292) // 285 = 2026-11-02 (lane rule3-member-guard fix 4, placeholder: a Rust path call's whole written qualifier) // 287 = 2026-11-02 (lane docs-rest: the reST/Sphinx tier, after #504's 285/286; merged under main's 289, the train renumbers) // 283 = 2026-10-31 (train 43b: registrar + string-import extraction; above the lane placeholders up to 281, rich 282) // 271 = 2026-10-30 (train 42b: iface-peel alias pointee / dyn-result / template-param // member records and alias-import ReExport records, placeholders 259, 260, 261; above 41b's 269/270) // 269 = 2026-10-29 (train 41b: fn-slot-s2 C/C++ member-pointer / nested-designator / // macro-cast slot extraction, placeholders 257, 259, 260; above train 41's 259/260) // 259 = 2026-10-28 (train 41: fn-slot-2 Rust slot records / py-split-marker `?name`, // placeholders 249, 255; above fn-slot-s2's 257/258) // 251 = 2026-10-27 (train 40: js-def-naming / string-keyed / fn-slot extraction, // placeholders 238, 241, 247; above train 39's 239/240 and fn-slot-2's 249) // 239 = 2026-10-27 (train 39: receiver-fixes typing, placeholder 237/238; above train 38 // 235/236; see the kParserVer note) // 235 = 2026-10-27 (train 38: queue-hop keyword tag on a Python queue call, placeholder // 228/229; above train 37b 233/234; see the kParserVer note) // 233 = 2026-10-26 (train 37b: rust-degraded use<..> re-parse, placeholder 229/230; // above train 36 231/232; see the kParserVer note) // 231 = 2026-10-25 (train 36: above main 226/227, #438 228, rust-degraded 229/230; // see the kParserVer note) // 226 = 2026-10-24 (train 34: above main / #432 / ind4b 224/225, ind5 222/223, // fc3 218/219; see the kParserVer note) // 224 = 2026-10-23 (train 33: above main 220/221, ind5 222/223, #420 214/215, fc1 216/217, // ind4b 218/219, l6-iface 212/213; see the kParserVer note) // 220 = 2026-10-22 (train 32b: above main 212/213, ix1-slot 204/205, #420 214/215, // #426 / fc1 216/217, ind4b 218/219, l6-iface 212/213; see the kParserVer note) // 212 = 2026-10-21 (train 32a: above main 206/207, rust-receivers 202/203, ix1-slot // 204/205, l6-iface 210/211; #420 reserves 214/215; see the kParserVer note) // 212 = 2026-10-21 (lane l6-iface fix round 1: ImplBlock records; rich 213; see the kParserVer note) // 210 = 2026-10-19 (train 32 lane l6-iface: DispatchType; strictly above main 206/207; see the kParserVer note) // 206 = 2026-10-18 (#409, PR #414, renumbered again at merge: above main 196/197, // train 31 198/199, rust-receivers 202/203, ix1-slot 204/205; see the kParserVer note) // 202 = lane rust-receivers (reservation 202/203; the train renumbers): Rust written-type // RecvType / MemberType, the written qualifier path of a call result, `-> Self` results // 198 = 2026-10-18 (train 31: above main 196/197 and h1-annot // 194/195; see the kParserVer note) // 194 = lane h1-annot (reservation 194/195; the train renumbers): // qualified-annotation importedName, AugAssign / OperatorResult binds // 185 = 2026-10-18 (#409): cross-file markdown links carry their written path#slug // (memberPath); graph.h pins the exact heading. 185, not 184: 184 is train 29. // Rich file tag 186. kCacheVersion stays 34. // 204 = lane ix1-slot (reservation 204/205; the train renumbers): C/C++ struct-field // slots (memberPath/memberCtor), Through calls via a field, slot facts // 196 = 2026-10-18 (train 30: above call-result-typing 180/181, fcall-forward // 188/189, go-local-var 190/191, name-template-dispatch 192/193, h1-annot // 194/195; see the kParserVer note) // 192 = lane name-template-dispatch (IX-3; reservation 192/193; the train renumbers): // RefRole::Pattern name-template records // 190 = lane go-local-var (reservation 190/191; the train renumbers): // Go/Rust/GDScript var and const captures anchored to item/package scope // 188 = 2026-10-17 (train 30 lane fcall-forward, rich 189; train renumbers) // 184 = 2026-10-17 (train 29: above arity-min 178/179, call-result-typing // 180/181, go-scope 182/183; see the kParserVer note) // 182 = 2026-10-16 (train 29 L5 go-scope reservation, #403: Go method / // interface-member scope; the train renumbers) // 180 = lane call-result-typing (reservation 180/181; the train renumbers): // call-result / return-type binds // 178 = train 29 lane arity-min (reservation 178/179; the train renumbers): // defs extract paramsMin for the B2.2 minimum-arity exclusion // 176 = 2026-10-15 (train 28: above main 173/174, grep-carrier 173/174, // ruby-pair 174/175, #380 145, the other lanes 171; see the kParserVer note) // 173 = 2026-10-15 (slice 4a, #400): Ruby's mixin directives onto the shared // base-relations path — queries/ruby/tags.scm captures them as @reference.mixin // and captureTagsFacts emits the inherit reference; captureRubyMixinBases // retired. Output byte-identical, extraction path changed. 173, not 172: 172 // is 171's rich file tag. // 173 = 2026-10-14 (train 28 grep-carrier: value refs through ?? || && / or and) // 174 = lane ruby-pair (train 28: Ruby/Python subscript references, Ruby main-object mixins) // 171 = 2026-10-13 (PR #349 Clojure lands above main's 167 / rich tag 168 and the // branch's own 169 / rich tag 170; see the kParserVer note) // 167 = 2026-10-11 (train 27 release: lane fix27-cpp-subscript's 166 renumbered above the lane build; // see the kParserVer note) // 164 = 2026-10-11 (train 27: lego-transitive's 162 renumbered above every live build, up to 162 / rich tag 163; // see the kParserVer note) // 162 = 2026-10-10 lane lego-transitive fix 1 (inherit-ref base binding; above 160's // rich tag 161; the train renumbers) // 160 = 2026-10-10 lane lego-transitive (JS/TS class factory; above 156's // rich tag 157 and train 26c's 158/159; the train renumbers) // 158 = 2026-10-09 (train 26c: PR #339 Rails schema columns; above 156 / rich tag 157; see the // kParserVer note) // 156 = 2026-10-08 (train 26b: above every lane build, up to 154 / rich tag 155; see the // kParserVer note) // 148 = 2026-10-04 (train 26a: PR #373 merged; above the branch's 145 and the 145–147 // lanes in flight, see kParserVer note; kIngestCacheVersionMirror stays main's 28) // 145 = lane honesty-small-068 (lane-local; the train renumbered it) // 145 = lane train25-cr2-followup (train 25 re-review fixes; lane-local, the train renumbered it) // 150..154 = lane FE-B on train 26a (lane-local; the train renumbered it; 146/145 = earlier // lane FE-B builds; kIngestCacheVersionMirror 29 is FE-B's) // 141 = 2026-10-04 (train 25: above FE-A's 134/135 and refval-edges' 140, see kParserVer // note; kIngestCacheVersionMirror 28 from FE-A, kQSnapCacheScheme 17 from refval-edges) // 140 = lane refval-edges (reference-as-value rows; see kParserVer note) // 135 = 2026-10-03 (lane FE-A fix round, see kParserVer note) // 134 = 2026-10-03 (lane FE-A, see kParserVer note; 133 is train 24's) // --- PR #373 branch numbers (lane-local; its 130–132 are NOT main's) --- // 145 = 2026-10-04 (Ruby include and extend sides, see kParserVer // note; kIngestCacheVersionMirror stays 27) // 142 = 2026-10-04 (the Ruby method-lookup branch on main 2720d1c5: // above main's 133, train 25's 141 and the branch's carried 130–137, // see kParserVer note; kIngestCacheVersionMirror stays 27) // 132 = 2026-10-02 (Ruby typed receivers, see kParserVer note; // kIngestCacheVersionMirror stays 27) // 131 = 2026-10-02 (Ruby mixins are ancestors, see kParserVer note; // kIngestCacheVersionMirror stays 27) // 130 = 2026-10-01 (Ruby bare-word calls, see kParserVer note; // kIngestCacheVersionMirror stays 27) // --- end of PR #373 branch numbers; main's history continues --- // 133 = 2026-10-02 (train 24: above the merged lanes' 130 and 131 extraction // changes and train 23's 132, see kParserVer note; kIngestCacheVersionMirror stays 27) // 132 = 2026-10-02 (train 23: cache-key hygiene above every branch // build's number, see kParserVer note; kIngestCacheVersionMirror stays 27) // 129 = 2026-09-30 (train 22: #338 + #325 after fn-literal's 128, see kParserVer // note; kIngestCacheVersionMirror stays 27) // 128 = 2026-09-29 (fn-literal-bodies, see kParserVer note) // 125 = 2026-09-27 (#338, RSpec described_class, see kParserVer note; // kIngestCacheVersionMirror stays 25) // 122 = 2026-09-25 (#320/#67, Astro frontmatter, see kParserVer note; // kIngestCacheVersionMirror stays 25) // 121 = 2026-09-24 (#310, Ruby attr DSL, see kParserVer note) // 120 = 2026-09-23 (#150): RawRef::qualifierRootsStd + // RawDef::scopeRootsStd, folded together with a // same-lane F1/F2 correctness fix (2026-09-24) that // briefly used 121 before collapsing back into this // 120 — 121 never reached main or a release, and // caches are per-worktree — see ingest_cache.h's own // kParserVer/kCacheVersion history for the full note. // 119 = 2026-09-20 (T13/fix3): queries/java + queries/kotlin // tags.scm import captures moved @reference.call -> // @reference.import (RefRole::Import) — an import is a // dependency edge, not a call-graph edge. // 118 = 2026-09-19 (CodeRabbit follow-up, thread 4053600599: // isJsxIntrinsicTagIdentifier now tests ASCII-lowercase // directly, so `_Widget`/`$Widget` are components, not // intrinsic tags; see src/ingest_cache.h) // 117 = 2026-09-19 (train 7, both members: extract-partial // re-extraction; #285 JSX element calls + the .tsx query; see src/ingest_cache.h) // 116 = 2026-09-18 (issue #287 round 2: // capturePythonRebindShadowDecls' rebind // veto evidence; see src/ingest_cache.h) // 115 = 2026-09-18 (issue #287: RawBind::importedName // marks a Python Import bind "module" vs a // from-import member; see src/ingest_cache.h) // 114 = 2026-09-17 (reference-returning definitions, test/narrowcheck.sh // arms 61-63): a definition returning `T&`/`T&&` records its // parameters; an attributed declarator its VarDecl. The // full note sits beside ingest_cache.h's declaration. // 113 = 2026-09-17 (smart-pointer members, PR #282): a std smart // pointer member records its pointee, a call records `->`; // the ref record grows a u8 (cache version 24 above). // See ingest_cache.h's kParserVer note. // 112 = 2026-09-17 (type aliases, PR #280): a typedef / using alias // of a named class records its target for the base walk. // See ingest_cache.h's kParserVer note. // 111 = 2026-09-17 (block-scope direct-initialized locals, // test/narrowcheck.sh arms 52-60). See ingest_cache.h's kParserVer note. // 110 = 2026-09-17 (Java catch/enhanced-for/resource shadows, #235 // follow-up). See ingest_cache.h's kParserVer note. // 109 = 2026-09-17 (Ruby constant receivers, PR #267): a constant or // scope_resolution receiver is NamedVar with its final segment. // See ingest_cache.h's kParserVer note. // 108 = 2026-09-17 (GDScript, PR #233): a new grammar, tags.scm and // `.gd` crawl row. See ingest_cache.h's kParserVer note. // 107 = 2026-09-17 (Java Type::method, issue #74, PR #235): its two // steps below (declared 97, 98) land as one on integration/train-3. // PR step 98, 2026-09-15 (Java Type::method review): // Java shadow binds carry lexical spans and inferred // lambda parameters are captured. See ingest_cache.h. // PR step 97, 2026-09-15 (Java Type::method candidates): // method_reference member capture plus indexed-class + // no-shadow resolver gating. #216 spent 96, so this // RE-BUMPS. See ingest_cache.h's kParserVer note. // 106 = 2026-09-17 (assignment types, PR #278): a C++ assignment's bind // record carries isFromAssignment (cache version 23). // See ingest_cache.h's kParserVer note. // 105 = 2026-09-17 (A4, found-items 2026-09-17): `.hxx` // gained a kLangTable row (src/ingest_crawl.h), so a // tree that spells its headers `.hxx` now yields NEW // files/symbols/edges a pre-bump cache never saw. // See ingest_cache.h's kParserVer note. // 104 = 2026-09-17 (template arguments in a receiver's type): a // declaration records its type's last name through the // grammar's fields. See ingest_cache.h's kParserVer note. // 103 = 2026-09-17 (TS/JS signed numeric literal receivers, train 1b // #277). See ingest_cache.h's kParserVer note. // 102 = 2026-09-17 (C++ template scopes, test/cpptmplscopecheck.sh, // PR #256). See ingest_cache.h's kParserVer note. // 101 = 2026-09-17 (member template calls, test/cppqualcheck.sh // §12, PR #243): `r.f()` / `x.template f()` mint call // references; the `template` disambiguator leaves names and // qualifiers. See ingest_cache.h's kParserVer note. // 100 = 2026-09-17 (TS/JS literal receivers, issue #163, PR #244): RecvKind // Lit* appended; extraction identity moves, cache format does not. // 99 = 2026-09-16 (std-typed member fields): a field's compose // record carries its written namespace as its qualifier. // See ingest_cache.h's kParserVer note. // 98 = 2026-09-16 (std-qualified receivers): a C++ assignment's // constructor records its qualified text too. // See ingest_cache.h's kParserVer note. // 97 = 2026-09-16 (parameter receivers): a declaration's qualified // written type rides its Type/ParamType RawBind (importedName). // See ingest_cache.h's kParserVer note. // 96 = 2026-09-13 (internal linkage, test/decltodefcheck.sh arm B2): // See ingest_cache.h's kParserVer note. // 95 = 2026-09-12 (Elixir module/name/arity resolution, PR #81): // RE-BUMPED from the branch's 87 over #139's 93 and #172's 94. // See ingest_cache.h's kParserVer note. // 94 = 2026-09-11 (#62/#72 follow-up): the decided-dead `#if 0` // filter now covers every --uses role, the Include record, and // DEFINITIONS — the extracted set shrinks on any C-family tree // with a literal `#if 0`/`#if 1`. See ingest_cache.h's // kParserVer note. Renumbered 93 -> 94 on the merge with // main 558a2e03, where #139 had spent 93. // 93 = 2026-09-11 (Ruby argument + rescue constants): a // constant argument of a call/super/yield and a rescue // class are directives. See ingest_cache.h's note. // 92 = 2026-09-11 (yaml unsigned-char, PR #140): the yaml scanner's // status type. SCN_FAIL (-1) returned through plain `char` came // back as 255 wherever `char` is unsigned (aarch64 Linux, the // linux-arm64 release asset), parsing a malformed %-escape in a // tag differently from every signed-`char` build. See // ingest_cache.h's kParserVer note. // 91 = 2026-09-11 (Kotlin, PR #126): a twenty-fourth grammar, its // extraction arms, two scanner patches that change a parse, and the // string-nesting refusal. See ingest_cache.h's kParserVer note. // 90 = 2026-09-11 (member-macro re-parse): a C-family file // whose first parse holds error bytes may be extracted from // a re-parse with its member macro invocations blanked. // 89 = 2026-09-11 (extent honesty): each def carries the // `recovered` extraction bit. See ingest_cache.h's note. // 78 = 2026-09-07 (Elixir): a twenty-second grammar and its // definition/call filters. // 79 = 2026-09-07 (ES import facts): named import aliases and // `export { f }` clause exports. See ingest_cache.h's note. // 80 = 2026-09-07 (Ruby scope + setters): every Ruby def carries // its enclosing class/module as scope, and `def name=` is // indexed with `obj.name = v` renamed to it. // 77 = 2026-09-03 (Phase 5): Python super() receiver kind + // import-name bindings. See ingest_cache.h's kParserVer note. // 74 = 2026-08-30 (objc-sniff lane): looksObjC masks comments // and string literals before testing @interface/@protocol/ // @implementation, so a C++ .h that merely MENTIONS them is no // longer rerouted to objc. See ingest_cache.h's kParserVer note. // 72 = 2026-08-24 (fnbody-require lane): CommonJS require()/dynamic // import() captured inside a TS/JS function body, not just at the // top level — Include gains `bool isLazy`. See ingest.cpp's own // kParserVer note for the per-container detail. // 70 = 2026-08-22 test-macro blocks (LB-E): a known doctest/Catch2 // block-forming test macro (`TEST_CASE( "title" ) { … }` and kin) // extracts as a t="fn" symbol named by its title literal, spanning // through the sibling compound_statement, testScope=1 — so the calls // inside the body finally attribute to a symbol and the tested= / // --test-gate / --affected lenses see the test→subject edges. The // extracted SET grows on any C++ tree using those harnesses, so a // v69 blob misses rows and must be rejected, not served. See // test/testmacrocheck.sh and ingest.cpp's own ladder note. // 69 = TWO independent extraction changes that both landed on 68 in // separate branches, RE-BUMPED to one free number at the 2026-08-21 // wave-2 merge (ingest.cpp's ladder carries the same note). No released // binary wrote a 68 blob; a v67 blob is missing BOTH sets of rows. // (a) the PHP + Lua language port: two new vendored grammars // (tree-sitter-php v0.24.2 `php/`, tree-sitter-lua v0.5.0) and two // new tags queries, so the extracted SET grows on any tree holding // a .php/.phtml/.lua file — those files used to leave the index as // unsupported-ext. A v67 blob on such a tree is missing every one // of those rows -> reject. Existing corpora are byte-identical: // every shared-path edit in that commit is Lang-gated. // (b) the receiver-guard misfire fix: receiverOf widens by ONE // intermediate field hop (RecvKind FieldOfThis/FieldOfVar, the field // name carried in the call ref's otherwise-free fieldName slot), so // the five `recv == None` guard sites stop misreading a chained // receiver as a BARE name (Rule 1 bareCish wrong-narrow + shadow // deletion). Extraction VALUES change (the wire format does not) and // MOVE edges=/ambiguous= — a v67 blob holds None where this binary // expects a chain, so it must be rejected rather than served. // 67 = 2026-08-20 RefRole::Type use-sites: usesVisitNode's accept // set widens from bare `identifier` to `type_identifier` too, so a // bare TYPE mention becomes a recorded use-site. The extracted SET // of references grows on any C/C++/ObjC tree; the role stays OUT of // the CSR (buildGraph admits Call|Macro only) and the pass is // RICH-family only, so the default map is unchanged. A v66 rich // blob holds no type rows and must be rejected, not served. // 65 = 2026-08-15 C++ nested out-of-line defs: queries/cpp/tags.scm // gains a second out-of-line definition pattern, so a C++ def // written with two or more qualifier segments // (`void nsD::OuterD::InnerD::deep3(){}`) is indexed instead of // silently dropped — the extracted SET grows on any C++ tree // using that spelling, so a v64 blob must be rejected. See // test/cppqualcheck.sh §11. // 64 = 2026-08-14 in-file test scope: every def carries a new // syntactic testScope bit (Rust #[cfg(test)] mod / #[test] fn, // Python class Test* / module-level def test_*, JS/TS // describe(/it(/test( blocks, C# [Fact]/[Test]/[TestMethod]) // written into the cache record — a v63 blob has no such // field, so it must be rejected. See test/testscopecheck.sh. // 63 = 2026-08-12 markdown section tier: .md/.markdown parse // with the vendored block grammar — headings (ATX + setext) // become sections with REAL SPANS, parent-heading scopes and // link/mention edges; the extracted SET and the spans change // on any md-bearing tree, so v62 blobs must be rejected. // 62 = 2026-08-12 module-constant round: C/C++ const-qualified // module constants (and class-static constants) index // case-blind — the extracted SET grows on any C/C++ tree, // so a v61 blob misses rows (this file's own // kIngestParserVerMirror is in the newly indexed family). // 61 = 2026-08-11 YAML config-key tier: .yml/.yaml mapping // keys (mdepth<=2, sequences transparent) indexed as t="sec" // for the first time — changes the extracted SET on any // YAML-bearing tree. // 60 = 2026-08-10 language-port round (one shared bump): // Python shapes (11 new tags.scm patterns, .pyi routing, the // gated enum-member kind), Swift shapes (hand port of bb78f97) // and the TypeScript #private gap, plus the shared finalSegment // leading-'<' carve-out. All change the extracted SET -- see // ingest.cpp kParserVer's own note for the per-language detail. // The same 60 also carries the CUDA memory-space module // bindings (cudacheck 7b close-out) -- uninitialized // `__constant__`/`__device__`/`__managed__` tables now // extract. All four land in one wave, so one bump covers // them; a v59 blob misses rows on any of those trees. // 59 = +TOML (.toml) config-key tier: a new grammar // and a new .scm change the extracted SET. // 47 (L3, 2026-08-08 audit) = `locals` counts // DECLARATORS not declaration statements — see // ingest.cpp kParserVer's own note. // 46 = integration/quality-fleet merge of TWO independent // 45s (the integrated ppalt+nestcal 45 below, and ev(G)'s // 45 on feat/nest-profile) — fresh number, neither's blobs // may be served. // 45 (feat/nest-profile numbering) = essential complexity (44 was taken by the sibling // nesting-quirk round; see ingest.cpp): RawDef/Symbol gain // ev (u16 FLOOR) + evWhy (8×u8), a per-file def-record // FORMAT change, and Swift guard_statement joins // isDecisionType (a Swift cx VALUE change) — old caches // hold numbers this build would not produce. // 45 = integration/quality-fleet merge of the ppalt // line (43 there) and the nestcal r1 line (44 there): // the merged extraction matches neither, fresh number. // 43 = ppalt disclosure: RawDef/Symbol gained a ppAlt // field (def-record FORMAT change) — was 42 on its own // branch, renumbered 43 at integration (collision with // the independent 42 below). // 42 = nested-closure span attribution: the tags-pass // body-climb no longer adopts an ancestor whose body // CONTAINS the def — cached JS/TS spans/metrics for // nested closures were wrong, old blobs must miss. // 41 = Phase 1 local-variable-indexing // (docs/LOCALS_INDEXING.md): Symbol/RawDef gained a `locals` // FLOOR field (C/C++ only), a per-file RawDef cache blob // FORMAT change — old caches must be rejected. // 40 = captureIncludes descends into import CONTAINERS: a // `#if`-guarded #include/#import/`using`, a Python import under // `if TYPE_CHECKING:` / `except ImportError:` / any body, a Rust // `use` inside mod/fn/impl/trait, and a C# `using` inside a // block-scoped namespace were all never visited by the old // top-level-only scan, so v39 blobs carry SHORT include lists // (and a --cochange surprising="1" false positive on any file // that wraps its imports in one of them). // 36 = H4 W3 V3-fixup L-1: a Rust container no longer scopes ITSELF // (`mod util` was published as `util::util`) — per-def `scope` is a // cached field, so v35 blobs carry the old ids and must be retired. // 35 = H4 W3 MERGE (two in-flight 34s, never-reuse rule): RUST // qualified-call widening (patterns + per-ref qualifier + per-def // scope + method-span fix) AND the W2b-fixup operator re-split. // 33 = H4 W2b (C++ qualified-call widening). // 32 = H4 wave-2a (C# ?.-calls + TS/JS/Java qualified-new + ObjC field // parity) — BOTH lanes bumped kParserVer and neither mirrored it; the // orchestrator's merge missed it too, qschemetripcheck/qextractionkeycheck // caught it post-merge (fixed on main; W2b hit the same drift in its // worktree independently). Mirror in the SAME diff, every time. // The extraction-identity tag folded into every sha-keyed filename key below. One string, one place. inline std::string extractionIdentityTag() { return "x" + std::to_string( kIngestCacheVersionMirror ) + "." + std::to_string( kIngestParserVerMirror ); } // ─── the PRODUCER IDENTITY — which build computed a cached Snapshot ───────────────────────────────────── // // THE BUG THIS CLOSES. A qsnap blob's dead set is a function of CALL RESOLUTION, not only of extraction: // isDeadCandidate reads g.inEdges, and pythonDispatchedMethodIds reads the graph. The key above holds the // extraction identity, and a resolution change moves none of it — by rule, since a resolver runs over cached // ingest facts (d39554dd's std::-qualified call guard said so in its own message: "no graph or edge blob is // cached"). So two builds that resolve differently, sharing one cache dir on one repo HEAD, served each other's // dead set. Measured on main a55b118e with that guard switched off in a second build, over a two-file fixture: // a cold run reports regressions="0"; the same run after the unguarded build warmed the cache reports a GATING // dead-code row on an untouched symbol and exits 2. The other order HIDES a real gating regression (exit 2 // cold, exit 0 warm). test/qsnapproducercheck.sh pins both directions. // // WHY DERIVED, NOT A kResolverVer TO BUMP. A constant holds only while every lane remembers it, and this cache's // record says how that goes: B10.1a's isDeadCandidate exemption (retired late, at v3) and 28c7d32's kParserVer // bump (P0.2) each changed what a blob means without the bump that would have retired it, and none of the twelve // scheme versions below cites a resolution change — d39554dd weighed the caches and still missed this one. The // identity is instead the SHA-256 of every file under src/ and queries/ (cmake/source_identity.cmake, computed on // every build), so ANY change to what a Snapshot means — resolution, the dead predicate, clone identity, a key // rule the qschemetrip manifest does not list — names a new blob without anyone deciding to. The price is that an // edit which changes no meaning renames the blob too: one cold HEAD snapshot after a rebuild that touched a source // file. The ingest blob underneath (qheadsnap) stays on the extraction identity alone, because it holds // extraction facts only, so that cold snapshot re-reads a warm ingest. // // Folded into the qsnap and qbody filename keys (qsnapExclHex, qbodyExclHex) and carried in the shared blob // header, the same two guards P0.2 gave the extraction identity: never NAMED again, and REFUSED if reached. inline std::string_view producerIdentity() noexcept { return std::string_view( rw::kRipwireSourceIdentity ); } inline std::uint64_t producerIdentityHash() noexcept { return fnv1a64( producerIdentity() ); } // The 16-hex EXCLUDES-config key: fnv1a64 of the exact exclude set + the family's scheme tag + the extraction // identity + the file-size ceiling. This is the SECOND filename field so eviction groups per (repo, config) — // different --exclude sets are independent cache families that never evict one another (mirrors the // auto-cache's lean/rich split), while HEAD-sha churn is capped WITHIN a family. \x1f field separators keep // "a","bc" distinct from "ab","c". One shared body for the qheadsnap/qsnap/qbody (and mergescout/gitoracle) // families; each passes its own scheme tag so a format bump renames only its family. // // `maxFileBytes` (P0.2, second half): computeHeadSnapshot threads --max-file-size into the HEAD ingest but the // key folded only `excludes` — so a default run followed by a `--max-file-size=100M` run warm-HIT the first // blob and answered with the smaller file SET. It is a first-class part of "which files were extracted", so it // belongs in the key exactly like excludes. Families with no size ceiling of their own (mergescout's "qms", // gitoracle's "qhist") take the default and are unaffected. inline std::string exclConfigHex( const std::vector& excludes, const std::string& schemeTag, std::size_t maxFileBytes = kDefaultMaxFileBytes ) { std::string keyMat; for( const std::string& e : excludes ) { keyMat += e; keyMat.push_back( '\x1f' ); } keyMat += schemeTag; keyMat.push_back( '\x1f' ); keyMat += extractionIdentityTag(); // P0.2: a kParserVer/kCacheVersion bump renames every blob keyMat.push_back( '\x1f' ); keyMat += std::to_string( maxFileBytes ); // P0.2: the file-size ceiling changes the extracted SET char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( fnv1a64( keyMat ) ) ); return std::string( hex ); } inline std::string headSnapExclHex( const std::vector& excludes, std::size_t maxFileBytes = kDefaultMaxFileBytes ) { return exclConfigHex( excludes, std::to_string( kHeadSnapCacheScheme ), maxFileBytes ); } // Y4 — BLOB-COUNT SHARDING. The 2 GiB low-water sweep (kMaxCacheDirBytes below) bounds cache-dir // BYTES but not blob COUNT: production shows 23,502 ripwire-*.bin blobs (mostly qheadsnap/qsnap/qbody churn — // a new blob per commit per repo, across the ~20 parallel agent sessions this machine runs) sitting FLAT in // one cache dir, so every sweep's directory listing is O(N) over a single huge readdir(). Shard by a // 2-hex-char subdir keyed on the BLOB'S OWN FILENAME hash — the same technique git's object store uses for // exactly the same reason — giving 256 buckets (~92 files each at today's production count), so both the // common-case open() (one blob → one shard → no scan of the others) and the sweep's own readdir() (256 small // listings instead of one huge one) stay cheap as the population grows. // // BACKWARD COMPATIBLE by construction, no migration step: `resolveCacheBlobPath` is the ONE choke point every // blob-path builder below (and `defaultCachePath` in main.cpp) routes through, for BOTH reads and writes — an // existing FLAT blob (written before this change) is found and reused right where it already is; a key is // only WRITTEN into its shard the next time it is (re)computed. A blob absent from both locations is a clean // miss, created fresh, in its shard. `evictOldCacheFamily` below sweeps both layouts, so an old flat blob // still ages out on schedule even if its key is never rewritten. // A 64-bit key spelled as its 16 lowercase hex digits — the ack ledger's key (ackMapKey), the shard below, and the // ingest's per-root sidecar names. inline std::string hex16( std::uint64_t key ) { char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( key ) ); return hex; } inline std::string blobShardHex( std::string_view filename ) { return hex16( fnv1a64( filename ) ).substr( 14 ); // the low byte, two hex digits: "{:02x}" of ( hash & 0xff ) } inline std::string resolveCacheBlobPath( const std::string& dir, const std::string& filename ) { namespace fs = std::filesystem; std::string flatPath = dir + "/" + filename; // not const: moved out on either early return std::error_code existsEc; if( fs::exists( fs::path( flatPath ), existsEc ) && !existsEc ) { return flatPath; // legacy flat blob — keep using it in place } const std::string shardDir = dir + "/" + blobShardHex( filename ); std::error_code mkEc; fs::create_directory( fs::path( shardDir ), mkEc ); if( mkEc ) { return flatPath; // degrade: couldn't make the shard dir (e.g. dir missing/unwritable) — fall back to flat rather than lose caching entirely } return shardDir + "/" + filename; } // Deterministic per-(repo, excludes, sha) cache filename: ripwire----.bin, // resolved through the shard-aware `resolveCacheBlobPath` above. The (family, repo, excl) prefix is the // eviction group; the sha suffix distinguishes commits within it. Every field is a fixed-width hex hash of // git-controlled / realpath'd input → no path-injection into the filename. One shared body for the // qheadsnap/qsnap/qbody families. inline std::string shaKeyedCachePath( const char* family, const std::string& repoHex, const std::string& exclHex, const std::string& sha ) { const std::uint64_t shaKey = fnv1a64( sha ); char tail[ 96 ]; rw::formatTo( tail, sizeof( tail ), "ripwire-{}-{}-{}-{:016x}.bin", family, repoHex.c_str(), exclHex.c_str(), static_cast( shaKey ) ); return resolveCacheBlobPath( cacheDirLadder(), tail ); } inline std::string headSnapCachePath( const std::string& repoHex, const std::string& exclHex, const std::string& headSha ) { return shaKeyedCachePath( "qheadsnap", repoHex, exclHex, headSha ); } // ─── THE BUILD TAG — which ingest format a root-keyed blob holds, spelled in its NAME ───────────────────────── // // #334 (follow-up). Both root-keyed families were keyed by root and verb class only, so two builds of different // formats — an installed release and a local build, or two installed versions — that alternate on one tree // refused and rewrote each other's blob on EVERY run (`format-version — not used`, reparsed=N reused=0, one path). // The auto names now carry the pair that decides whether a blob is readable at all, (kCacheVersion, the class's // parserVer): `ripwire--lean-cp.bin`, `ripwire--rich-cp.bin` and // `ripwire-mcp--cp.cache`, the rich/MCP parser number being the lean one + 1. Two builds of one format still share a blob (a rebuild of the same // tree must not go cold); two formats never meet at one path. // // THE TAG IS NEVER 16 HEX: `cp` always holds a 'p', so cacheBlobRootKey's "first 16-hex field" // rule below still reads the root key and nothing else, in every shape. Only [a-z0-9.-] appear, so the name // stays valid on NTFS. An explicit `--cache=PATH` is NOT tagged: that file is the user's, named by them, and is // often a committed `--index-out` artifact a CI job consumes by its exact name. // // The mirror pair lives in this header (see kIngestParserVerMirror); ingest_cache.h static_asserts that // `ingestParserVerFor` agrees with its own parserVerFor for both classes, so the tag cannot drift from the // header stamp the blob carries. inline constexpr std::uint32_t ingestParserVerFor( bool captureValueUses ) noexcept { return kIngestParserVerMirror + ( captureValueUses ? 1u : 0u ); } // The families whose whole key IS the root — the main parse cache's two verb classes (main.cpp::defaultCachePath) // and the MCP index (mcpindex.h::mcpCachePath, always the rich class) — as ONE table: the builder and the eviction // pin below read the same rows, so "is this blob this build's?" cannot disagree with "what does this build write?". enum class RootBlobFamily : std::uint8_t { Lean, Rich, Mcp, Count }; struct RootBlobShape { std::string_view prefix; // before the 16-hex root key std::string_view classField; // between the key and the build tag ("" for the MCP index) std::string_view ext; bool rich; // which parserVer the tag names }; inline constexpr RootBlobShape kRootBlobShapes[] = { { "ripwire-", "-lean", ".bin", false }, { "ripwire-", "-rich", ".bin", true }, { "ripwire-mcp-", "", ".cache", true }, }; static_assert( std::size( kRootBlobShapes ) == static_cast( RootBlobFamily::Count ), "one shape per root-keyed family" ); // Everything after the root key, build tag included: `-lean-cp.bin`, `-rich-cp.bin`, // `-cp.cache`. inline std::string rootBlobTail( const RootBlobShape& shape ) { return std::format( "{}-c{}p{}{}", shape.classField, kIngestCacheVersionMirror, ingestParserVerFor( shape.rich ), shape.ext ); } // The builder for every root-keyed family. They sat in different translation units and each open-coded the same // three lines around its own copy of the hash, which is exactly how the two root spellings drifted apart in the // first place; one body means a future family joins by adding a row rather than by re-deriving a key. inline std::string rootKeyedCachePath( const std::string& root, RootBlobFamily family ) { EXPECTS( family < RootBlobFamily::Count ); const RootBlobShape& shape = kRootBlobShapes[ static_cast( family ) ]; const std::string after = rootBlobTail( shape ); // Bounded: the longest prefix is "ripwire-mcp-" (12), the key is 16 hex, and the longest tail is // "-rich-cp.bin" (32 at ten digits a side) — 60 of the 63 usable bytes. EXPECTS( shape.prefix.size() + 16 + after.size() < 64, "a root-keyed cache name is a fixed-width prefix, key and build-tagged tail" ); char tail[ 64 ]; rw::formatTo( tail, sizeof( tail ), "{}{}{}", shape.prefix, cacheRootKeyHex( root ), after ); return resolveCacheBlobPath( cacheDirLadder(), tail ); } // This build's tagged tails, one per family, built once per sweep rather than once per blob. using OwnBuildBlobTails = std::array( RootBlobFamily::Count )>; inline OwnBuildBlobTails ownBuildBlobTails() { static_assert( std::tuple_size_v == 3, "one tail per kRootBlobShapes row, in row order" ); return OwnBuildBlobTails{ rootBlobTail( kRootBlobShapes[ 0 ] ), rootBlobTail( kRootBlobShapes[ 1 ] ), rootBlobTail( kRootBlobShapes[ 2 ] ) }; } // `cp` — the tag shape, and nothing else. inline bool isCacheBuildTagField( std::string_view field ) noexcept { const std::size_t p = field.find( 'p' ); if( field.size() < 4 || field.front() != 'c' || p == std::string_view::npos || p < 2 || p + 1 >= field.size() ) { return false; } const auto allDigits = []( std::string_view s ) noexcept { return std::all_of( s.begin(), s.end(), []( const char c ) noexcept { return c >= '0' && c <= '9'; } ); }; return allDigits( field.substr( 1, p - 1 ) ) && allDigits( field.substr( p + 1 ) ); } // A root-keyed blob ANOTHER build wrote, read off its name alone: // * a build tag that is not one of this build's tails (another kCacheVersion or parserVer), or // * a pre-tag name — `ripwire-<16hex>-lean.bin`, `ripwire-<16hex>-rich.bin`, `ripwire-mcp-<16hex>.cache` — // which from this change on only an older release writes. // Every other name (qheadsnap/qsnap/qbody/qchurn/…, whose keys already fold the extraction identity) answers // false and keeps exactly the pin it had. // A name THIS build writes for one of its root-keyed families (any root). inline bool isThisBuildRootBlobName( std::string_view name, const OwnBuildBlobTails& own ) noexcept { for( std::size_t f = 0; f < own.size(); ++f ) { if( name.starts_with( kRootBlobShapes[ f ].prefix ) && name.ends_with( own[ f ] ) ) { return true; } } return false; } inline bool isOtherBuildRootBlob( std::string_view name, const OwnBuildBlobTails& own ) noexcept { if( !name.starts_with( "ripwire-" ) || isThisBuildRootBlobName( name, own ) ) { return false; } const bool isMcp = name.starts_with( "ripwire-mcp-" ); const std::size_t dot = name.rfind( '.' ); const std::string_view stem = name.substr( 0, dot ); const std::string_view ext = dot == std::string_view::npos ? std::string_view{} : name.substr( dot ); const std::size_t dash = stem.rfind( '-' ); const std::string_view last = dash == std::string_view::npos ? stem : stem.substr( dash + 1 ); if( isCacheBuildTagField( last ) ) { return true; // tagged, and not with this build's tag } // the pre-tag shapes, matched exactly: "ripwire-" (8) + 16 hex + "-lean"/"-rich" (5) + ".bin", or "ripwire-mcp-" (12) + 16 hex + ".cache" const bool legacyClass = ext == ".bin" && stem.size() == 8 + 16 + 5 && ( stem.ends_with( "-lean" ) || stem.ends_with( "-rich" ) ); const bool legacyMcp = isMcp && ext == ".cache" && stem.size() == 12 + 16; return legacyClass || legacyMcp; } // P1-1 (2026-09-10 full audit) — THE PIN KEY. Every cache blob's filename carries the SAME 16-hex root // field, and since the follow-up round it really is the same one: `defaultCachePath` writes // `ripwire--{lean,rich}-.bin`, `mcpCachePath` writes `ripwire-mcp--.cache` and // `shaKeyedCachePath` writes `ripwire----.bin`, all three through the ONE // canonical `cacheRootKeyHex` above — so ONE root's every family (lean, rich, mcp, qheadsnap, qsnap, qbody, // qhist, qms, qchurn, stier) spells the same key in the same place. That makes "which root does this blob // belong to?" answerable from the NAME alone, with no plumbing: the byte-budget sweep reads the key off the // very blob it is about to write (`keepPath`) and pins its siblings. // // The rule is positional-free on purpose: return the FIRST '-'-delimited field that is exactly 16 hex // digits. No family tag is 16 characters of hex ("qheadsnap", "qsnap", "qbody", "qhist", "qms", "qchurn", // "stier", "mcp"), and no build tag is either (`cp` always holds a 'p'), so the first such field is the root // key in every filename shape, and a foreign or legacy blob that carries no such field yields "" — which pins // nothing and evicts exactly as it did before. // // TWO FAMILIES ARE EXCEPTIONS, and they are NAMED rather than guessed at — their 16-hex field is a real // key, just not a key over a ROOT: // * `ripwire-docmd-.bin` (ingest_docpass.h) is CONTENT-addressed: fnv1a64 of the DOCUMENT'S // BYTES, so one PDF extracted under two checkouts is cached once. // * `ripwire-stier--…` (ingest_astquery.h::spanTierMemoPath) is FILE-addressed: it passes a // per-file disk path to cacheRootKeyHex, one memo per source file above a 32 KiB floor. An llvm --for // leaves ~30 of them beside the three root-keyed blobs, each with its own key. // Reading either as a root key would be a wrong answer about OWNERSHIP — it names a document or a file, // not the tree the blob belongs to — and at 1-in-2^64 could pin a blob to an unrelated root. Both are // excluded here rather than renamed: their names are correct for what they identify, and renaming would // orphan the most expensive thing in this directory to rebuild (a docmd blob costs a markitdown popen and // a Python start, seconds per file). They yield "" and are treated as unowned, which is what they are — // the byte-budget sweep may take them, and that is the right policy for a per-file memo whose recompute // cost is one file, not one tree. // // KEEP THE LIST HONEST: test/evictioncheck.sh arm (k) mirrors these prefixes in shell and FAILS if the two // lists disagree, so a family added later with a non-root 16-hex field is a gate failure rather than a // blob quietly pinned to a stranger. inline constexpr std::string_view kNonRootKeyedBlobPrefixes[] = { "ripwire-docmd-", "ripwire-stier-" }; inline bool isNonRootKeyedBlob( std::string_view blobName ) noexcept { return std::any_of( std::begin( kNonRootKeyedBlobPrefixes ), std::end( kNonRootKeyedBlobPrefixes ), [ blobName ]( const std::string_view prefix ) noexcept { return blobName.starts_with( prefix ); } ); } inline std::string cacheBlobRootKey( std::string_view blobName ) noexcept { const auto isHex16 = []( std::string_view f ) noexcept { if( f.size() != 16 ) { return false; } for( const char c : f ) { if( !std::isxdigit( static_cast( c ) ) ) { return false; } } return true; }; if( isNonRootKeyedBlob( blobName ) ) { return std::string{}; // content- or file-addressed, root-independent by design — see above } // A field ends at the next '-' OR at the '.' that opens the suffix. The dash-only scan this replaces // could not read `ripwire-mcp-.cache` (mcpindex.h::mcpCachePath): its last field came out as // `.cache`, 22 bytes, not hex16, so the function returned an EMPTY key for the one family // whose name is nothing but a root key. The consequence is in evictBySizeBudget — an empty key pins // nothing, so the byte-budget sweep would evict the MCP index blob of the very root it was serving // while pinning that root's lean and rich blobs, and the MCP server paid a full re-parse for it. // (CodeRabbit #127 / 3985249706. test/evictioncheck.sh's shell mirror `blobrootkey` already stripped // `\.(bin|cache)$` before splitting, so the gate's reading and the binary's had silently diverged — // arm (k) never primed an MCP blob, which is why nothing caught it.) std::size_t at = 0; while( at < blobName.size() ) { const std::size_t sep = blobName.find_first_of( "-.", at ); const std::string_view field = blobName.substr( at, sep == std::string_view::npos ? std::string_view::npos : sep - at ); if( isHex16( field ) ) { return std::string( field ); } if( sep == std::string_view::npos ) { break; } at = sep + 1; } return std::string{}; } // One matching cache artifact as the sweep sees it: what it costs, how old it is, where it is. Hoisted out // of evictOldCacheFamily's body so the byte-budget pass below can be its own function rather than a third // in-line pass inside an already-long one. struct CacheBlobStat { std::filesystem::file_time_type mtime; std::uintmax_t byteSize; std::string path; }; // The byte-budget pass's eviction ORDER (evictBySizeBudget below): each blob's tier, read off its name ONCE — a // comparator that re-derived it would parse every name O(n log n) times — then sorted by tier, oldest first within a // tier. Tier 0: another root's blob, or one no root owns. Tier 1: another ripwire build's blob of the root being // written (isOtherBuildRootBlob). Tier 2 (kEvictTierPinned): this build's blobs of that root, and keepPath itself. inline constexpr std::uint8_t kEvictTierPinned = 2; struct RankedBlob { std::uint8_t tier; std::size_t blobIndex; // into the vector that was ranked }; inline std::uint8_t evictionTier( const std::string& blobPath, const std::string& keepPath, const std::string& pinRootKey, const OwnBuildBlobTails& ownTails ) { if( blobPath == keepPath ) { return kEvictTierPinned; } const std::string name = std::filesystem::path( blobPath ).filename().string(); if( pinRootKey.empty() || cacheBlobRootKey( name ) != pinRootKey ) { return 0; } return isOtherBuildRootBlob( name, ownTails ) ? std::uint8_t( 1 ) : kEvictTierPinned; } inline std::vector rankBlobsForEviction( const std::vector& blobs, const std::string& keepPath ) { const std::string pinRootKey = cacheBlobRootKey( std::filesystem::path( keepPath ).filename().string() ); const OwnBuildBlobTails ownTails = ownBuildBlobTails(); std::vector order; order.reserve( blobs.size() ); for( std::size_t i = 0; i < blobs.size(); ++i ) { order.push_back( RankedBlob{ evictionTier( blobs[ i ].path, keepPath, pinRootKey, ownTails ), i } ); } std::sort( order.begin(), order.end(), [ &blobs ]( const RankedBlob& a, const RankedBlob& b ) { return a.tier != b.tier ? a.tier < b.tier : blobs[ a.blobIndex ].mtime < blobs[ b.blobIndex ].mtime; } ); ENSURES( order.size() == blobs.size(), "every blob is ranked exactly once" ); return order; } // P1-1 (2026-09-10 full audit) — THE BYTE-BUDGET PASS: delete until the family is under a LOW-WATER mark of // 7/8 budget, in THREE TIERS, oldest-first within each: (0) other roots' blobs and unowned ones, (1) another // ripwire build's blobs of the root being written, (2) never — this build's blobs of that root and `keepPath`. // Returns the blobs that survived. `mine` arrives unsorted. // // THE LOW-WATER MARK is F6's live-cache finding (B7.4, 2026-07-14): trimming to exactly the budget left the // dir hovering AT the ceiling, so every subsequent process re-crossed it on its first write and paid // deletion work on every save — sweeping to low water buys ~12% burst headroom and makes the common // next-process sweep a scan-only no-op. // // WHOSE BLOB GOES FIRST. Oldest-first alone is wrong at scale, and it was measured wrong: one llvm-project // root needs 1.76 GB for its OWN two families (rich 1.19 GB + lean 0.57 GB) against a 2 GB budget, so a // second corpus — or one --edit-check HEAD snapshot (0.52 GB) — made the sweep delete the SIBLING FAMILY OF // THE ROOT THE USER IS WORKING IN, the one thing they are certain to need next. Identical argv, same // session, same binary: `--grep` 20 s → 206 s, `--for` 19 s → 268 s, and SELF-SUSTAINING, because each cold // run's own save then evicts the other family again. `keepPath` alone never covered it: the blob being // written is precisely the family we are NOT about to need. src/main.cpp:181-189 already records the same // mechanism as a registered negative for a different key change ("the cache directory's 2 GiB cap evicts the // blob a running gate is about to reuse"). The BUDGET IS NOT LOWERED (owner rule // `quality-first-caps-are-blowup-guards`) — the ORDER is what changes, and the pin costs no state and no // stat: the root key is read off `keepPath`, i.e. whoever is writing IS the most-recently-used root. // // WHY ONLY THIS PASS IS PINNED. The age pass stays unpinned deliberately: a blob nobody has touched in 30 // days is stale by that policy's own definition and losing it costs ONE cold parse, not a ping-pong — // whereas a blob evicted here is, by construction, one this very root just used. // // DISCLOSURE, and the reason P1-1 stayed invisible: all four measured 250 s runs wrote 0 bytes to stderr. // Conditional by construction — a sweep that frees nothing and is not over budget on its pinned set alone // says nothing at all, so no ordinary run, and no gate that compares stderr, grows a line. Plain emits, // NEVER DISCLOSE: NDEBUG compiles that out, and a Release binary is exactly where a 10x // slowdown needs to be visible. // // ANOTHER BUILD'S BLOBS OF THIS ROOT ARE TIER 1, NEITHER PINNED NOR FIRST (#334 follow-up). Since the auto names // carry the build tag, one root can hold a blob per build that ran on it (isOtherBuildRootBlob above). // * Pinning them would make every upgrade leave the previous version's blobs pinned for the 30 days the age pass // waits — on llvm-project 1.76 GB of them against a 2 GiB budget, the self-sustaining "kept anyway" state this // pass exists to avoid. // * Taking them oldest-first WITH other roots' blobs (the first cut of this change) evicted blobs still in use: // a live MCP server of another build indexing this root, or the other build's class when two builds alternate, // while evicting another root alone would have been enough. Measured by review: the server's next rebuild went // from reparsed=1 to reparsed=5 of 5 files. // So they go only after every other root's blob is gone and the dir is still over the low-water mark. The cost that // remains: where one root's blobs from two builds do not fit the budget together (llvm-project, 1.76 GB per build), // the other build's blobs of it are evicted and that build re-parses on its next run — the pre-tag cost, paid now // only in that regime, and after every other root's blob was spent first. // The same tier also holds the version upgraded FROM: on the first save after an upgrade its blobs of this root outrank // every other root's, current-format ones included, so near the budget one upgrade can cost every other root a cold run. // Name and mtime cannot tell that version from a live one: a "superseded by this build's newer blob of the class" rule // fixes the upgrade case but brings the alternation thrash back (both measured by review). inline std::vector evictBySizeBudget( std::vector& mine, const std::string& dir, const std::string& keepPath, std::uintmax_t maxTotalBytes ) { namespace fs = std::filesystem; EXPECTS( maxTotalBytes > 0, "a zero budget means 'no size pass' and evictOldCacheFamily never calls this pass with it" ); std::uintmax_t totalBytes = 0; for( const CacheBlobStat& b : mine ) { totalBytes += b.byteSize; } if( totalBytes <= maxTotalBytes ) { return std::move( mine ); } const std::uintmax_t lowWaterBytes = maxTotalBytes - maxTotalBytes / 8; const std::vector order = rankBlobsForEviction( mine, keepPath ); std::vector kept; kept.reserve( mine.size() ); std::size_t evictedCount = 0; std::uintmax_t pinnedBytes = 0; for( const RankedBlob& r : order ) { ASSUME( r.blobIndex < mine.size(), "rankBlobsForEviction returns one entry per index of mine" ); const CacheBlobStat& b = mine[ r.blobIndex ]; if( r.tier == kEvictTierPinned ) { pinnedBytes += b.byteSize; } else if( totalBytes > lowWaterBytes ) { std::error_code de; fs::remove( fs::path( b.path ), de ); totalBytes -= b.byteSize; ++evictedCount; continue; } kept.push_back( b ); } constexpr std::uintmax_t kMiB = 1024ull * 1024; if( evictedCount > 0 ) { rw::emitTo( stderr, "ripwire: cache {}: over its {} MiB budget — evicted {} blob(s) of other roots or other ripwire builds (this build's blobs for this root are kept)\n", dir.c_str(), maxTotalBytes / kMiB, evictedCount ); } if( totalBytes > maxTotalBytes ) { rw::emitTo( stderr, "ripwire: cache {}: this build's blobs for this root are {} MiB, past the {} MiB budget — kept anyway (evicting one costs a full re-parse)\n", dir.c_str(), pinnedBytes / kMiB, maxTotalBytes / kMiB ); } return kept; } // Hygiene: within one (repo, excludes) FAMILY, keep at most `keep` HEAD-snapshot cache files (newest by mtime); // delete older ones so HEAD-sha churn (a new file per commit) cannot grow the cache dir without bound. Scoping // per family (repoHex-exclHex prefix) — not per bare repo — means alternating --exclude configs do not evict // one another (the lean/rich lesson). `keepPath` (the file we are about to use) is always retained regardless of // mtime granularity. Degrade-only: any filesystem error is swallowed via the error_code overloads — eviction is // best-effort hygiene, never a correctness or crash risk. // The prefix-generic body: keep the `keep` newest ".bin"/".cache" files whose name begins with `prefix`, delete older // ones, always retain `keepPath`. Both the qheadsnap (ingest) and qsnap (Snapshot) cache families share this // (rule-of-three: two families that evict identically → one evictor, not two copies that must stay in sync). // // A5 (cache-dir hygiene) generalization: a THIRD shape of sweep showed up (see sweepStaleCacheBlobsOnce below) — // age-then-size across the WHOLE "ripwire-*" family rather than a keep-N-newest cap on one sub-family — so this // is the rule-of-three consolidation the paragraph above already anticipated, not a second copy-pasted sweeper. // Two independent, optional passes run BEFORE the original count cap (each a no-op at its zero default, so the // qheadsnap/qsnap call sites below are byte-for-byte unaffected): // maxAgeDays > 0 — delete any matching blob older than that many days outright. // maxTotalBytes > 0 — if the family's surviving total still exceeds it, delete oldest-first until under. // `keepPath` is never deleted by any pass, in every case. // // Y4: covers BOTH blob layouts — the legacy flat one (matching entries directly under `dir`) and the // sharded one `resolveCacheBlobPath`/blobShardHex now write into (matching entries under `dir`'s 2-hex-char // subdirectories, "00".."ff") — so a family's blobs are found and evicted correctly regardless of which // layout wrote them, and a mid-migration mix of both is swept as one set. The 256 shard names are an EXACT, // bounded set (never an open-ended recursive walk of a shared $TMPDIR that may hold unrelated large trees). // // P1-1: the byte-budget pass additionally PINS the root `keepPath` belongs to (see evictBySizeBudget). That // needs no new parameter and no plumbing — the pin key is a function of `keepPath`, which every call site // already passes — and it cannot reach the keep-N call sites below, which run with maxTotalBytes == 0. inline void evictOldCacheFamily( const std::string& dir, const std::string& prefix, const std::string& keepPath, std::size_t keep, double maxAgeDays = 0.0, std::uintmax_t maxTotalBytes = 0 ) { namespace fs = std::filesystem; std::vector mine; const auto matches = [ & ]( const std::string& name ) { if( name.size() < prefix.size() || name.compare( 0, prefix.size(), prefix ) != 0 ) { return false; } return ( name.size() >= 4 && name.compare( name.size() - 4, 4, ".bin" ) == 0 ) || ( name.size() >= 6 && name.compare( name.size() - 6, 6, ".cache" ) == 0 ); }; // best-effort scan of ONE directory for matching cache artifacts, appending them to `mine`. Never aborts // the whole sweep on a per-shard error — a single unreadable shard just contributes nothing this round. const auto scanOneDir = [ & ]( const fs::path& d ) { std::error_code sec; fs::directory_iterator sit( d, sec ), send; if( sec ) { return; } for( ; sit != send; sit.increment( sec ) ) { if( sec ) { return; } const std::string name = sit->path().filename().string(); if( !matches( name ) ) { continue; } std::error_code te; const auto mt = fs::last_write_time( sit->path(), te ); if( te ) { continue; } std::error_code se; const auto sz = sit->file_size( se ); mine.push_back( CacheBlobStat{ mt, se ? std::uintmax_t( 0 ) : sz, sit->path().string() } ); // size-stat failure degrades to 0 (age/count passes still see the file) } }; // top-level pass: flat legacy blobs directly under `dir`, PLUS collect the 2-hex-char shard subdir names // to recurse into afterward (one bounded extra readdir() per shard, never deeper). std::error_code ec; std::vector shardDirs; fs::directory_iterator it( fs::path( dir ), ec ), end; if( ec ) { return; // unreadable cache dir → nothing to evict, no crash } for( ; it != end; it.increment( ec ) ) { if( ec ) { return; } const std::string name = it->path().filename().string(); if( name.size() == 2 && std::isxdigit( static_cast( name[0] ) ) && std::isxdigit( static_cast( name[1] ) ) ) { std::error_code isdirEc; if( it->is_directory( isdirEc ) && !isdirEc ) { shardDirs.push_back( it->path() ); } continue; } if( !matches( name ) ) { continue; } std::error_code te; const auto mt = fs::last_write_time( it->path(), te ); if( te ) { continue; } std::error_code se; const auto sz = it->file_size( se ); mine.push_back( CacheBlobStat{ mt, se ? std::uintmax_t( 0 ) : sz, it->path().string() } ); // size-stat failure degrades to 0 (age/count passes still see the file) } for( const fs::path& sd : shardDirs ) { scanOneDir( sd ); } // age pass: outright delete anything past the cutoff (disabled when maxAgeDays == 0). if( maxAgeDays > 0.0 ) { const auto ageBudget = std::chrono::duration_cast( std::chrono::duration>( maxAgeDays ) ); const auto cutoff = fs::file_time_type::clock::now() - ageBudget; std::vector kept; kept.reserve( mine.size() ); for( const CacheBlobStat& b : mine ) { if( b.mtime < cutoff && b.path != keepPath ) { std::error_code de; fs::remove( fs::path( b.path ), de ); // best-effort; a failed unlink just leaves an extra file continue; } kept.push_back( b ); } mine.swap( kept ); } // size pass — the byte budget, its eviction order and its disclosure all live in evictBySizeBudget // above (disabled when maxTotalBytes == 0, which is every keep-N call site below). if( maxTotalBytes > 0 ) { mine = evictBySizeBudget( mine, dir, keepPath, maxTotalBytes ); } // count pass (the original behavior): keep only the `keep` newest, delete the rest (disabled via keep == max()). if( keep != std::numeric_limits::max() && mine.size() > keep ) { std::sort( mine.begin(), mine.end(), []( const CacheBlobStat& a, const CacheBlobStat& b ){ return a.mtime > b.mtime; } ); // newest first for( std::size_t i = keep; i < mine.size(); ++i ) { if( mine[i].path == keepPath ) { continue; } std::error_code de; fs::remove( fs::path( mine[i].path ), de ); // best-effort; a failed unlink just leaves an extra file } } } // A5 (cache-dir hygiene) — --doctor measured ~11,914 ripwire-* blobs / 2.4 GB in the cache-ladder dir on a // machine that runs ~20 parallel agent sessions across many repos. Only the qsnap/qheadsnap families above were // ever capped (keep-2-newest); the MAIN parse cache (ripwire--lean/rich.bin, defaultCachePath in main.cpp) // shares the SAME "ripwire-" prefix and dir but had no evictor at all — every distinct (repo, verb-class) pair // this machine has ever touched leaves a blob forever. // // Policy (decided): at saveCache time, at most once per process, best-effort and silent — first delete any // ripwire-* blob older than kMaxCacheBlobAgeDays, THEN (only if the dir is still over budget) delete oldest- // first until the dir total is under kMaxCacheDirBytes. `keepPath` (the blob this call is about to use/rewrite) // is NEVER deleted by either pass, so a run can never evict the cache entry it is itself relying on. // // Concurrency is safe by CONSTRUCTION, not by locking: loadCache self-heals a missing/torn file to a cold // reparse, and saveCache publishes via tmp-then-rename, so a blob another process deletes out from under a // concurrent reader just looks like a cold miss — never a corrupt read. Two sweepers racing on the same file // both call fs::remove, and a double-remove is a benign no-op (the second just gets ENOENT via the error_code // overload). This sweep matches "ripwire-" (not a narrower family prefix), so it also backstops qsnap/qheadsnap // blobs that outlive their own keep-2 cap between runs — one dir-wide safety net under the per-family caps. constexpr double kMaxCacheBlobAgeDays = 30.0; constexpr std::uintmax_t kMaxCacheDirBytes = 2ull * 1024 * 1024 * 1024; // 2 GB constexpr std::size_t kMaxCacheBlobCount = 4096; // bound every future hygiene scan // 2026-09-06 stranger audit: the advisory edit locks (mcpedit.h editLockPath — /locks//ripwire-edit- // .lock, one per distinct target path ever edited) are deliberately never unlinked by their holder, and the // blob sweep above deliberately never enters locks/. Nothing else did either: one machine had 45,765 of them. // A lock file is reclaimable when nobody holds it — flock(LOCK_EX|LOCK_NB) succeeding IS that test — and it // is old enough that a fresh open is unlikely to be racing us; the age bound keeps a lock created seconds ago // by a peer that has not yet flock'd it out of reach. The residual (a peer opens the path between our unlink // and our close, and a third process then opens a new inode) is the same window mcpedit.h already documents // as covered by its re-check-before-rename; the lock is the fast path, never the correctness floor. constexpr double kMaxEditLockAgeDays = 1.0; inline std::vector staleEditLockPaths( const std::string& dir ) { namespace fs = std::filesystem; std::vector stale; std::error_code ec; const auto now = fs::file_time_type::clock::now(); fs::recursive_directory_iterator it( fs::path( dir ) / "locks", fs::directory_options::skip_permission_denied, ec ), end; for( ; !ec && it != end; it.increment( ec ) ) { std::error_code sec; const std::string name = it->path().filename().string(); if( name.rfind( "ripwire-edit-", 0 ) != 0 || !it->is_regular_file( sec ) || sec ) { continue; } const auto mt = fs::last_write_time( it->path(), sec ); if( !sec && std::chrono::duration( now - mt ).count() / 86400.0 >= kMaxEditLockAgeDays ) { stale.push_back( it->path().string() ); } } return stale; } inline void sweepStaleEditLocks( const std::string& dir ) { for( const std::string& path : staleEditLockPaths( dir ) ) { const int fd = os::open( path.c_str(), O_RDWR ); if( fd < 0 ) { continue; } if( os::flock( fd, LOCK_EX | LOCK_NB ) == 0 ) { os::unlink( path.c_str() ); // unheld and old: reclaim; a later editor recreates it on demand } os::close( fd ); } } inline void sweepStaleCacheBlobsOnce( const std::string& dir, const std::string& keepPath ) { static std::atomic swept{ false }; bool expected = false; if( !swept.compare_exchange_strong( expected, true ) ) { return; // only the first saveCache in this process sweeps } evictOldCacheFamily( dir, "ripwire-", keepPath, kMaxCacheBlobCount, kMaxCacheBlobAgeDays, kMaxCacheDirBytes ); sweepStaleEditLocks( dir ); } // The HEAD-snapshot INGEST cache family (ripwire-qheadsnap---.bin), capped per (repo,excl). inline void evictOldHeadSnapCaches( const std::string& dir, const std::string& repoHex, const std::string& exclHex, const std::string& keepPath, std::size_t keep = 2 ) { evictOldCacheFamily( dir, "ripwire-qheadsnap-" + repoHex + "-" + exclHex + "-", keepPath, keep ); } // A4-P1 (round 2) — the HEAD-snapshot *Snapshot* cache. The qheadsnap INGEST cache above only skips the parse; // everything computeSnapshot then does on the HEAD tree — above all findClones + findClonesType3 (~2.3-2.7 s // post-interning) and the per-symbol metric fold — is ALSO immutable for a given (HEAD sha, excludes, scheme), // yet was recomputed on every --quality-delta. So we cache the computed HEAD-side Snapshot itself: on a warm hit // we deserialize it and RETURN — skipping git archive, ingest, buildGraph, AND clone detection entirely. The // working-tree side legitimately still pays its own clone pass + ingest (it changes between runs). // // NEVER-STALE, on the same two independent guards the ingest cache uses: // 1) FILENAME key = (realpath repo-root, HEAD sha, excludes, a qsnap scheme tag, the extraction identity, the // producer identity) — a different HEAD / repo / --exclude set / scheme / BUILD names a different file → the // wrong Snapshot can never be loaded. The producer identity (v14) is what keeps two builds that resolve // calls differently apart; see producerIdentity. // 2) Blob self-validation: a magic + scheme-version header, an embedded fnv1a64(headSha) that must match the // live HEAD, and an fnv1a64 content checksum trailer over the whole body. Any mismatch/truncation → the blob // is rejected and the full compute runs (which then rewrites a correct blob) — a stale/foreign blob can // never inject wrong facts. // // DETERMINISM (the hard contract — "faster must never change the answer"): the blob is serialized in the maps' // sorted (btree) iteration order and the vectors' already-sorted order, so it is byte-stable run-to-run; more // importantly the RESTORED Snapshot is field-for-field identical to a freshly-computed one (same hashes, same // values, vectors re-sorted on load), and computeDelta consults `base` only by key lookup + binary_search — so // a cached delta is byte-identical to an uncached one. Native-endian POD is fine: the det-gate is same-machine, // and a foreign-arch blob simply fails the checksum → cold recompute (never wrong output). // v2: the signal-to-noise round changed the SEMANTICS of a cached Snapshot's dead set (fixture paths exempt), // so v1 blobs must never be served to a v2 binary (two binary versions sharing one cache dir would otherwise // answer differently depending on who wrote first — a determinism hole). The scheme is in the filename key, // so old blobs are simply never named again (and age out via the A5 sweep). // v3 (F2/X4) — B10.1a (ffcc618) added `isTestScriptPath` to `isDeadCandidate` (shell test-runner // scripts join header-exported symbols and fixture paths as dead-code-exempt) WITHOUT bumping this constant — // exactly the determinism hole the v2 comment above exists to prevent: a pre-ffcc618 binary's qsnap blob // (dead set computed under the OLD, narrower exemption) served to a current binary yields phantom // quality-delta regressions on shell test-runner helpers. Bumped 2 → 3 here to retire every blob written // before this fix. THE RULE (repeated from v2, now with teeth — see the tripwire below): any change to the // SEMANTICS of what a cached Snapshot means — what counts as dead, what a clone group's identity is, what the // serialized fields mean — requires a bump. A change that touches these functions' TEXT but not their // MEANING (a rename, a reflow, a comment edit) does not. // // TRIPWIRE (test/qschemetripcheck.sh): hashes the concatenated source text of the manifest below and compares // against a pinned hash committed beside it (`test/qschemetrip.hash`). A mismatch fails the gate with // instructions: did the *semantics* of what a cached Snapshot represents change? → bump kQSnapCacheScheme AND // re-pin the hash in the same diff. Refactor-only (no behavior change)? → just re-pin. Keep this manifest // SMALL and edit it here (nowhere else) if the semantic surface grows: // pythonMethodOwners (quality.h) — enclosing-class evidence // pythonReceiverParameters (quality.h) — conventional first receiver parameter // pythonDispatchRequests (quality.h) — eligible receiver-call evidence // pythonDispatchClasses (quality.h) — downward-only inheritance reachability // pythonDispatchedMethodIds (quality.h) — Python inherited receiver-call evidence for the dead set // isDeadCandidate (quality.h) — the dead-set predicate itself // uncalledBody (quality.h) — isDeadCandidate's structural half: a body that no edge, file-scope call or Python dispatch reaches // codeLocByNode (quality.h) — the locBySym VALUES (code lines per body) // measureCallableNotItsContainer (quality.h) — EXTENT-CTOR: a container sharing a callable's id lends it no extent // moveCidOf (quality.h) — MOVED-BODY: the move identity moveCidBySym stores // moveSketchOf (quality.h) — MOVES: the clone sketch moveSketchBySym stores (clones.h cloneSketchOfStream builds it) // recordMoveSketches (quality.h) — MOVES: which overload's sketch a key keeps // recordMoveIdentity (quality.h) — QD-RENAME-IDENTITY: the per-key MAX moveCidBySym and bodyCidBySym record // pythonFrameworkInvokedSymbol (quality.h) — the framework-hook exemption isDeadCandidate calls into (#228) // pythonRecordParent (quality.h) — fills the closure host and owner that pythonReceiverScope reads (#228) // pythonReceiverScope (quality.h) — which method a self./cls. call in a closure belongs to (#228) // isFixturePath (quality.h) — a fixture-path exemption isDeadCandidate calls into // rustDropImplMethodIds (quality.h) — the Rust Drop::drop exemption SET isDeadCandidate consults (#494): a method of a Drop impl block // isTestScriptPath (quality.h) — the test-script exemption isDeadCandidate calls into (the exact // helper B10.1a added without a bump — the finding this guards) // topLevelCalleeNameHashes (quality.h) — the file-scope (top-level script statement) call-site evidence // isDeadCandidate consults (W1-S2) // serializeSnapshot (quality.h) — the on-disk blob shape // deserializeSnapshot (quality.h) — the on-disk blob shape, read side // computeSnapshot (quality.h) — the dead-set BUILDER (baseline side) // bodyHashesBySym (quality.h) — the bodyHashBySym KEY semantics (the v6 keying change landed // without this line watching it — the exact drift this guards) // readRegisterMacrosConfig (quality.h) — the .ripwire_config register_macros= parse feeding // registeredMacroNames (P2.2) // registeredMacroNames (quality.h) — the built-in + .ripwire_config name list isDeadCandidate's // register-macro exemption is scoped to (P2.2) // startsWithRegisteredMacro (quality.h) — the macro-call text match registeredMacroSymbolIds calls into // registeredMacroSymbolIds (quality.h) — the per-symbol exemption SET isDeadCandidate consults (P2.2). // NOTE (disclosed limitation): kBuiltinRegisterMacros itself is a // constexpr array, not a function, so this manifest mechanism // cannot hash IT — a future edit that only changes the built-in // NAME LIST (not these functions' text) will not trip this gate. // registersItself (quality.h) — the self-registration exemption --dead-code and --quality-delta share (a registered macro call, or a Rust test attribute above) // rustTestAttributed (quality.h) — the backward scan over blank, comment and attribute lines that finds a #[test] or #[tokio::test] above a Rust definition // isRustTestAttribute (quality.h) — whole-token check that an attribute's text is `test` or `tokio::test`, with or without an argument list // classifyRustAttributeLine (quality.h) — splits a line into its top-level #[...] attributes and tests each one (CodeRabbit on #668) // rustAttributeClose (quality.h) — the `]` that closes one attribute: brackets nest, a double-quoted string is opaque // rustCodeOfAttributeLine (quality.h) — an attribute line without its trailing // comment (a // inside a double-quoted string does not start one) // defectSitesOf (quality.h) — the defect-shape site identity (anchor + facet + normalized text) // the baseline stores. NOTE (disclosed limitation): the scanners it // calls live in defectshape.h, outside this manifest, so a change // to what a scanner reports must bump kQSnapCacheScheme by hand. // v4 (r27 P0.2) — the blob header gained the EXTRACTION IDENTITY (kIngestCacheVersionMirror + // kIngestParserVerMirror; see the long note at their declaration). Everything a Snapshot contains is a // function of tree-sitter extraction, so a parserVer bump must retire the blob — it did not, and 28c7d32's // 80 corrected canonIds were served from stale qsnaps for a whole round. Both the header AND the filename key // now carry the pair, so a pre-r27 blob is neither named nor believed. A HEADER SHAPE change → bump. // v5 — the Snapshot gained `defsBySym`, the overload set's CARDINALITY, because every other per-symbol kind // is a MAX over that set and a MAX cannot see the set shrink (see computeSnapshot, and --edit-check's // defs_was= which reads it). That is a BLOB SHAPE change AND a change to what a cached Snapshot contains, so // a v4 blob deserialized here would be short by one map and must never be served: bumped, which renames every // file through the excludes key as well. // v6 (W1-S2, 2026-08-11) — bodyHashBySym's KEYS changed meaning: pathQualifiedKey (path\0scope\0name) // instead of hash(canonicalId), which degrades to the bare name for scope-less symbols and folded every // same-named one ACROSS FILES into one churn-join identity (a new rows() in one file flagged churn against // the rows() in an untouched file). A v5 blob's body keys live in a different key space, so serving one to // a v6 binary would make every scope-less symbol read as absent-from-baseline (churn silently disarmed): // bumped, which renames every file through the excludes key as well. // v6 (W1-S2, 2026-08-11) — `isDeadCandidate` gained the top-level-invocation exemption (a symbol invoked // from FILE SCOPE — a bash/script top-level statement — is alive; see topLevelCalleeNameHashes above the // predicate): the SEMANTICS of a cached Snapshot's dead set narrowed, so a v5 blob's dead set (computed // without the exemption) served to this binary would resurrect the exact false positives the fix retires. // No extraction change (the file-scope references were always captured — buildGraph just never turned them // into edges), so kParserVer/the mirrors deliberately did NOT move. // v7 (2026-08-25, the scope-less fold round) — the KEY SPACE of every per-symbol map in a Snapshot changed. // ccx/loc/nest/params/defs/mask/dead/api were keyed by `fnv1a64( baselineCanonId(...) )`, which inherits // canonicalId's bare-name degrade and folds every scope-less symbol across files; they are keyed by // pathQualifiedKey now (see qualityKey). This is the purest possible case of "the semantics of what a cached // Snapshot MEANS changed": a v6 blob's keys are computed from a different byte string, so served to this // binary EVERY symbol reads as absent from the baseline and the whole tree reports as new. Bumped 6 -> 7 to // retire every blob written before the fix. // v8 (P2.2, agent-friction round, 2026-08-29) — `isDeadCandidate` gained the register-macro exemption: a // symbol whose OWN signature text is a registered self-registering test/benchmark macro call (built-in // list + .ripwire_config's register_macros=) is no longer a dead-set member. Exactly the v3 shape again // (a new isDeadCandidate exemption landing without a bump is the determinism hole v2's comment exists to // prevent): a pre-v8 blob's dead set was computed WITHOUT this exemption and would resurrect the exact // false positives this round fixes (doctest/Catch2 TEST_CASE, GoogleTest TEST/TEST_F/TEST_P, Google // Benchmark BENCHMARK bodies reported as newly-dead the moment an agent added a test). No extraction // change — the underlying symbols were always indexed; only the dead-SET predicate narrowed — so // kParserVer/the mirrors deliberately did NOT move. Bumped 7 -> 8 to retire every blob written before it. // v9 (Q-DIAL-2, 2026-09-10) — `isDeadCandidate`'s header exclusion was REPLACED by languageInvokedSymbol, // so the dead SET both grew (every header symbol with no caller is now eligible) and shrank (constructors, // destructors, operators, bare types and main are out). Same shape as v6/v8 in the opposite direction, and // the direction is what makes the bump load-bearing rather than hygienic: a v8 blob's dead set was computed // while 96.8% of this repo's source was invisible to the predicate, so served to this binary every // newly-eligible dead symbol would read as ABSENT from the baseline dead set and be reported as freshly // dead — a whole tree of phantom regressions on the first run after an upgrade. No extraction change (the // symbols were always indexed; only the dead-SET predicate moved), so kParserVer and its mirrors deliberately // did NOT move. Bumped 8 -> 9 to retire every blob written before it. // v10 (Q-DIAL-3, 2026-09-10) — locBySym's VALUES are CODE lines now, not the physical span. Keys unchanged, // which is exactly what makes a stale blob dangerous rather than obvious: a v9 blob deserializes cleanly and // every symbol reads as having SHRUNK (its recorded physical loc exceeds the current code count), so the // verbosity kind reports NOTHING and says nothing about why. Bumped 9 -> 10. // v11 (PR #81 review item 4, 2026-09-12) — pathQualifiedKey( relPath, Symbol ) folds an Elixir `name/N` arity // OUT of the key: run/1 and run/2 are one piece of source, as C++ overloads of `f` are, so an arity edit is a // params movement on one identity instead of a dead symbol beside a new one. The v6/v7 shape again (the keys // hash a different byte string), confined to one language: a v10 blob's Elixir entries are absent from every // lookup this binary makes, so each Elixir symbol would read as new. Extraction is unchanged (parser version // 95 stays), so kParserVer and its mirror deliberately did NOT move. Bumped 10 -> 11. // v12 — Python inherited self/cls dispatch excludes possible overrides from the dead set on both sides. // v13 (#228, root-spelling invariance) — the HEAD side always ingests at an absolute temp root, and until this // round that spelling decided answers: Python's root-relative import probe was inert there (the name ladder bound // a same-directory def instead), and isFixturePath / isTestScriptPath read the directories ABOVE the temp root. // Both now read model.h::rootRelPath, so the dead set and every call edge a v12 blob was computed from can differ // for an UNCHANGED sha — and served to this binary, the pre-fix Snapshot is exactly the phantom row #228 reported // (test/rootspellingcheck.sh arm 5 watched it served: exit 2 on an unchanged four-file tree). No extraction // change: parser version and its mirror stay. Bumped 12 -> 13. // v14 (2026-09-16) — the blob header gained the PRODUCER IDENTITY after the extraction identity, and // qsnapExclHex folds it: a HEADER SHAPE change, so bumped by the v4 rule. The defect it closes is one this // rule could not have caught: a dead set is a function of call resolution, no version in the key moved with // resolution, and so two builds that resolve differently served each other's dead set (see producerIdentity). // Since v14 a bump is no longer what keeps two builds' blobs apart — any source change renames every blob — so // a semantics change that lands without one leaves this history incomplete, not a wrong answer across builds. // v15 (2026-09-26, lane/builtin-bind-065) — isDeadCandidate no longer counts a definition dead when a call the // builtin-method name gate DECLINED could have meant it (graph.h BuiltinMethodGate, Graph::gateDeclinedTarget): // the dead SET moved, as in v9/v12. The producer identity already keeps this build's blobs apart from older ones; // bumped 14 -> 15 so the history above stays complete. No extraction change: kParserVer 122 and its mirror stay. // v16 (2026-09-27, the masking/placeholder round) — the blob gained two per-symbol count maps after // maskBySym (maskReportBySym, placeholderBySym), and maskBySym itself now counts the widened handler shapes // (log-only, rethrow-only): a BLOB SHAPE change and a change to what a cached Snapshot's mask counts mean. // A v15 blob is short two maps and its mask counts are low, so served here it would read every widened shape // as newly added. Bumped by the v4/v5 rule. // v17 (lane/refval-edges, reference-as-value round) — the dead set no longer holds a function a table, field or // argument holds as a VALUE (valuerefindex.h ValueRefIndex::isValueReferenced, checked after every other exemption, // counted as value-ref-excluded= like --dead-code): the dead SET moved, as in v9/v12/v15. kParserVer moved with // the extraction (the Value/Through rows) and its mirror moved with it. Bumped 16 -> 17. // v18 (2026-10-04, train 25 re-review fixes) — isValueReferenced ignores a value reference made inside the function // itself (`timer_set( tick )` in tick), as the CSR drops a recursive self-call: the dead SET moved, as in v9/v12/v15/v17. // kParserVer moved too (145: prototype parameters, the depth-cut record). Bumped 17 -> 18. // v19 (lane/cr-qd-kinds-068, the defect-shape kind; the lane's own number was 18, which the cr2 follow-up above also took for // a different scheme — train 26b renumbers it 19, both notes kept) — the blob gained the defect-shape (anchor, site) records // after publicApi: a BLOB SHAPE change. A v17 blob has none, so served here it would read every format-arity // site in the tree as newly added. Bumped by the v4/v5 rule (the producer identity already keeps this build's // blobs apart; the bump keeps the history above complete). Fix round 1 of the same lane, still the lane's scheme 18 (18 never // shipped): defectSitesOf passes the tree's macro names to the C++ scanner, and the scanners skip more calls (an // argument that may be a macro, a directive inside the call, #if 0, a brace-spelling escape) and guard more // vacuous-assert absences — fewer records, the same blob shape; the producer identity keeps the builds apart. // v20 (2026-10-11, train 27) — no blob shape change; the dead SET's inputs moved. pythonDispatchedMethodIds walks // pythonDispatchClasses over g.implementors, and lane lego-transitive changed which Python classes extend which: a base // clause is read as Python evaluates it (`class A( Outer.B )` extends B only, `Generic[K]` extends Generic and not K, // `metaclass=` and computed bases name none), so the set of methods an inherited receiver call keeps alive can differ // for an UNCHANGED sha. kParserVer moved with that extraction (164, its mirror with it), and the producer identity // already keeps this build's blobs apart; bumped 19 -> 20 so the history above stays complete and the scheme sits above // every live value (19 on every branch). The lane's own note said the walk itself is a refactor (same class set and // order for the same g.implementors) — true; what moved is g.implementors. // v21 (2026-10-15, train 28) — no blob shape change; the dead SET's inputs moved again. Lane ruby-pair makes a proven element // access a call of the receiver class's subscript operator (Ruby `[]`/`[]=`, Python `__getitem__`/`__setitem__`) and PR #380 // makes an Elixir `unquote(...)` call under `quote` live, so the calls that keep a definition alive can differ for an // UNCHANGED sha. kParserVer moved with those extractions (176, its mirror with it), and the producer identity already keeps // this build's blobs apart; bumped 20 -> 21 so the history above stays complete and the scheme sits above every live value // (20 on main and every lane). Lane qd-memory-degrade's KindScope builds the default scope's records unchanged (its note). // v22 (2026-10-16, lane rust-std-rows, #405; train 29 renumbers on a collision) — no blob shape change; the dead SET's inputs moved: // the standard-member gate gained a Rust row (graph.h kStdMemberNames), so a Rust definition a DECLINED call could have meant is // no dead candidate (Graph::gateDeclinedTarget), as v15 did for the builtin-method gate. No extraction change: kParserVer and its // mirror stay. The producer identity already keeps this build's blobs apart; bumped 21 -> 22 so the history above stays complete. // v23 (2026-10-24, #228: Django/unittest hooks and closure dispatch) — no blob shape change; the dead SET's inputs moved. // isDeadCandidate exempts Python framework entry points (pythonFrameworkInvokedSymbol: setUp, tearDown, setUpClass, // tearDownClass, setUpTestData, setUpModule, tearDownModule, load_tests, and test* methods in test modules), and // pythonDispatchedMethodIds keeps a self./cls. call inside a closure nested in a method live: the overrides of the called name on that method's class and its subclasses. // The producer identity already keeps this build's blobs apart; bumped 22 -> 23 so the history above stays complete. // v24 (2026-10-25, train 36) — #228's v23 was the PR's placeholder; renumbered above every live value (main / train 35 / every // other ref 22, #437 23). No further shape change. // v25 (2026-11-01, land-472, #466 / #472) — filter.h's isTestPath reads the hyphen test names `test-*.sh`, `*-test.sh` (and the // other shell/batch suffixes) and `.e2e-spec.` / `.perf-spec.` as tests, and isTestScriptPath calls it, so a shell test script the // dead-set exemption did not cover before is covered now. A v24 blob holds the old dead set. Renumbered above every live value (24). // v26 (2026-11-10, lane qd-fixes-1) — no blob shape change; two record SETS moved. The dead set: isDeadCandidate exempts Go and Rust // test-runner entry points (testRunnerInvokedSymbol). The clone set: baselineCloneGroupHashes also holds every pair its clone // relation implies (pushExactGroupPairs / pushTwinWidenedPairs, QD-CLONE-FALSE-GATE), so a v25 blob holds neither. Bumped 25 -> 26. // v27 (2026-11-12, lane entry-ceiling, EXTENT-CTOR) — no blob shape change; the locBySym VALUES moved: a class that shares its // canonical id with its constructor (C++ Foo::Foo) no longer lends the id its class extent (measureCallableNotItsContainer). A v26 // blob holds the class extent there, and would read every such constructor as shrunk. Bumped 26 -> 27. // v28 (2026-11-12, lane entry-ceiling, MOVED-BODY) — a BLOB SHAPE change: the Snapshot gained moveCidBySym (one hash map after // bodyHashBySym). A v27 blob is short by one map. Bumped 27 -> 28. // v29 (2026-11-13, lane entry-ceiling, MOVES) — a BLOB SHAPE change: the Snapshot gained moveSketchBySym (key + 128-byte clone sketch // records after moveCidBySym), and a VACATED body now includes a key that shrank under the bars. Bumped 28 -> 29. // v30 (2026-11-14, lane qd-rename-identity) — a BLOB SHAPE change: the Snapshot gained bodyCidBySym (one hash map after moveCidBySym, // moveCidOf of every callable, the identity a rename or move keeps). A v29 blob is short by one map. Bumped 29 -> 30. // v31 (2026-11-14, lane failure-default; landed as v31 in TRAIN-1111h over qd-rename-identity's v30) — a BLOB SHAPE change: the Snapshot gained failureDefaultBySym (one count map after // maskReportBySym), and maskBySym / maskReportBySym now count the failure-default facet. A v30 blob is short by one map and its // mask counts are low, so it would read every failure-default site as added. Bumped 30 -> 31. // v32 (2026-11-02, #493 / #499: Rust test-attribute functions; landed as v32 above main's v31 in lane land-499-500) — no blob // shape change; the dead SET's inputs moved. registeredMacroSymbolIds, which isDeadCandidate's register-macro exemption reads, // now also holds a Rust definition that a #[test] or #[tokio::test] attribute stacks above (registersItself). The harness // calls such a function, so it is no dead candidate. Bumped 31 -> 32. // v33 (2026-11-02, #494 maintainer review; landed as v33 above #499's v32 in lane land-499-500) — a Rust method named drop is // exempt only as a DIRECT member of a Drop impl block (rustDropImplMethodIds: an ImplBlock whose trait is Drop). A v32 blob reports // every Drop::drop as dead, and this scheme changes that dead set, so a v32 blob is rejected. Bumped 32 -> 33. kParserVer stays: // no extraction change. // v34 (2026-11-15, lane land-499-500 fix 1, CodeRabbit on #668) — no blob shape change; the dead SET's inputs moved for Rust. // rustTestAttributed tests EVERY top-level attribute on a line (classifyRustAttributeLine), so `#[tokio::test(x)] #[allow(unused)]` // now exempts the fn below it, and a `#[` inside a string is text, so `#[doc = "#[tokio::test(x)]"]` no longer does. A v33 blob // holds the old set, so it is rejected. Bumped 33 -> 34. kParserVer stays: no extraction change. constexpr std::uint32_t kQSnapCacheScheme = 34; constexpr char kQSnapMagic[4] = { 'Q', 'S', 'N', 'P' }; // The qsnap EXCLUDES-config key folds the qsnap SCHEME (independent of the ingest cache's kHeadSnapCacheScheme) // so a qsnap-format bump renames every file → old-scheme blobs are simply never named again. It also folds the // extraction identity + maxFileBytes (see exclConfigHex). // v14: and the PRODUCER identity, because a Snapshot's dead set depends on call resolution (producerIdentity). inline std::string qsnapExclHex( const std::vector& excludes, std::size_t maxFileBytes = kDefaultMaxFileBytes ) { return exclConfigHex( excludes, "qsnap" + std::to_string( kQSnapCacheScheme ) + '\x1f' + std::string( producerIdentity() ), maxFileBytes ); } // a distinct "qsnap" family prefix so the ingest and Snapshot families never collide and evict independently. inline std::string qsnapCachePath( const std::string& repoHex, const std::string& exclHex, const std::string& headSha ) { return shaKeyedCachePath( "qsnap", repoHex, exclHex, headSha ); } // Cap the qsnap family to the 2 newest per (repo, excludes) — same hygiene, same shared evictor as qheadsnap. inline void evictOldQSnapCaches( const std::string& dir, const std::string& repoHex, const std::string& exclHex, const std::string& keepPath, std::size_t keep = 2 ) { evictOldCacheFamily( dir, "ripwire-qsnap-" + repoHex + "-" + exclHex + "-", keepPath, keep ); } // Signal-to-noise round — the WINDOW-REF body-hash cache family ("ripwire-qbody-"): the per-canonId raw-body // hashes of the tree at gitWindowRefSha, the committed-thrash evidence side of short-horizon-churn. Immutable // for a given (repo, excludes, ref sha) exactly like the HEAD snapshot, cached with the SAME two never-stale // guards (sha-keyed filename + the self-validating qsnap blob format — we reuse serializeSnapshot with only // bodyHashBySym populated, validated against the REF sha). A distinct filename family so qbody blobs are never // read as full HEAD Snapshots or vice versa, and the two families evict independently. // v2 (r27 P0.2): the shared qsnap blob header gained the extraction identity — a body-hash blob is just as // extraction-derived as a full Snapshot, so this family retires with it. // v3 (W1-S2): bodyHashBySym keys became pathQualifiedKey (see kQSnapCacheScheme v6). The blob header's // scheme check would already reject a v2 blob — but as CORRUPT (alert + stderr), not a clean miss; bumping // the family renames every file so old blobs are simply never named again. // v4 (2026-09-16): the shared blob header gained the producer identity (kQSnapCacheScheme v14), so this family // retires with it, as it did at v2. Its facts are extraction-only, yet the key folds the producer identity too: // deserializeSnapshot refuses a foreign producer for BOTH families, and a key without it would turn every // rebuild's first read into a "corrupt" alert instead of a clean miss. constexpr std::uint32_t kQBodyCacheScheme = 4; inline std::string qbodyExclHex( const std::vector& excludes, std::size_t maxFileBytes = kDefaultMaxFileBytes ) { return exclConfigHex( excludes, "qbody" + std::to_string( kQBodyCacheScheme ) + '\x1f' + std::string( producerIdentity() ), maxFileBytes ); } inline std::string qbodyCachePath( const std::string& repoHex, const std::string& exclHex, const std::string& refSha ) { return shaKeyedCachePath( "qbody", repoHex, exclHex, refSha ); } // append one POD to the blob buffer (native layout; see the determinism note above). CONSTRAINED, not merely asserted // trivially copyable: a trivially copyable struct can still carry padding bytes, whose values are indeterminate, and a // float has more than one byte spelling of one value (-0.0 beside 0.0, many NaNs). Either would write a blob whose // bytes differ between two runs over the same facts. Every call site passes a fixed-width integer, and the constraint // keeps it that way: has_unique_object_representations is false for any type with padding or a floating-point member. template requires( std::has_unique_object_representations_v && !rw::isPoolId ) // a pool id is 4 unique bytes whose value is thread timing inline void qsnapPut( std::string& buf, const T& v ) { buf.append( reinterpret_cast( &v ), sizeof( T ) ); } // read one POD, advancing `p`; false (no advance) if fewer than sizeof(T) bytes remain before `end`. template inline bool qsnapGet( const char*& p, const char* end, T& out ) { if( end - p < static_cast( sizeof( T ) ) ) { return false; } std::memcpy( &out, p, sizeof( T ) ); p += sizeof( T ); return true; } // A record COUNT read out of a blob is the blob's claim, not a fact: bound it by the bytes that remain BEFORE // anything is sized from it. `minRecordBytes` is the smallest encoding one record can have, so a count that // passes cannot reserve more records than the blob could possibly hold. Without it a checksum-valid blob // whose count reads 0xFFFFFFFF reached `reserve` — 32 GiB for a u64 vector — and on a host that will not // overcommit that is std::bad_alloc, which nothing on the CLI path catches: SIGABRT on every run until the // blob was evicted. The twin of loadCache's countFits (ingest_cache.h), for the qsnap-format readers. inline bool qsnapCountFits( const char* p, const char* end, std::uint32_t count, std::size_t minRecordBytes ) noexcept { if( count <= static_cast( end - p ) / minRecordBytes ) { return true; } DISCLOSE( Diagnostics::answerUnchanged, "the rejected blob is recomputed from the tree: same answer, slower", "quality: a cache blob's record count exceeds its remaining bytes — blob rejected" ); return false; } // Serialize a Snapshot to a self-validating blob: [magic][scheme][cacheVer][parserVer][producer][fnv(headSha)] then each // field as a uint32 count followed by its flat records (btree maps in sorted key order, vectors as-is; the // defect-shape records last, as anchor+site pairs), then an fnv1a64 checksum over all preceding bytes. // Byte-stable for a fixed Snapshot. // P0.2 (r27): cacheVer/parserVer are the EXTRACTION IDENTITY every field below is a function of — see the note // at kIngestCacheVersionMirror. They are in the filename key too; carrying them here as well means a blob // reached by any other route (hand-copied, collided) is REJECTED rather than believed. // v14: `producer` is fnv1a64 of the producer identity — the build that computed the dead set (producerIdentity). inline std::string serializeSnapshot( const Snapshot& s, const std::string& headSha ) { std::string buf; buf.append( kQSnapMagic, 4 ); qsnapPut( buf, kQSnapCacheScheme ); qsnapPut( buf, kIngestCacheVersionMirror ); qsnapPut( buf, kIngestParserVerMirror ); qsnapPut( buf, producerIdentityHash() ); qsnapPut( buf, fnv1a64( headSha ) ); const auto putValMap = [ & ]( const gtl::btree_map& m ) { qsnapPut( buf, std::uint32_t( m.size() ) ); for( const auto& [ k, v ] : m ) { qsnapPut( buf, k ); qsnapPut( buf, v ); } }; const auto putHashMap = [ & ]( const gtl::btree_map& m ) { qsnapPut( buf, std::uint32_t( m.size() ) ); for( const auto& [ k, v ] : m ) { qsnapPut( buf, k ); qsnapPut( buf, v ); } }; const auto putVec = [ & ]( const std::vector& v ) { qsnapPut( buf, std::uint32_t( v.size() ) ); for( std::uint64_t x : v ) { qsnapPut( buf, x ); } }; putValMap( s.ccxBySym ); putValMap( s.locBySym ); putValMap( s.nestBySym ); putValMap( s.paramsBySym ); putValMap( s.defsBySym ); putValMap( s.maskBySym ); putValMap( s.maskReportBySym ); putValMap( s.failureDefaultBySym ); // v31 (failure-default) putValMap( s.placeholderBySym ); putHashMap( s.bodyHashBySym ); putHashMap( s.moveCidBySym ); // v28 (MOVED-BODY) putHashMap( s.bodyCidBySym ); // v30 (QD-RENAME-IDENTITY) qsnapPut( buf, std::uint32_t( s.moveSketchBySym.size() ) ); // v29 (MOVES): key, then the 128 sketch bytes for( const auto& [ k, sk ] : s.moveSketchBySym ) { qsnapPut( buf, k ); qsnapPut( buf, sk ); } putVec( s.cloneGroups ); putVec( s.dead ); putVec( s.publicApi ); qsnapPut( buf, std::uint32_t( s.defectSites.size() ) ); // v18: the defect-shape (anchor, site) records, in sorted order for( const DefectSiteKey& d : s.defectSites ) { qsnapPut( buf, d.anchor ); qsnapPut( buf, d.site ); } const std::uint64_t sum = fnv1a64( std::string_view( buf.data(), buf.size() ) ); qsnapPut( buf, sum ); return buf; } // Deserialize + validate. Returns false (leaving `out` untouched) on any short/corrupt/mismatched blob — the // caller then treats a present-but-invalid file as corrupt (alert + recompute) and an absent file as a clean // miss. Vectors are re-sorted so computeDelta's binary_search invariant holds regardless of on-disk order. inline bool deserializeSnapshot( const std::string& blob, const std::string& headSha, Snapshot& out ) { if( blob.size() < 4 + 3 * sizeof( std::uint32_t ) + 3 * sizeof( std::uint64_t ) ) { return false; // smaller than magic+scheme+cacheVer+parserVer+producer+sha+trailer } const char* data = blob.data(); const std::size_t bodyLen = blob.size() - sizeof( std::uint64_t ); // trailer = last 8 bytes std::uint64_t stored = 0; std::memcpy( &stored, data + bodyLen, sizeof( std::uint64_t ) ); if( stored != fnv1a64( std::string_view( data, bodyLen ) ) ) { return false; // checksum } const char* p = data; const char* end = data + bodyLen; // never parse into the trailer if( std::memcmp( p, kQSnapMagic, 4 ) != 0 ) { return false; } p += 4; std::uint32_t scheme = 0; if( !qsnapGet( p, end, scheme ) || scheme != kQSnapCacheScheme ) { return false; } // P0.2 — the EXTRACTION IDENTITY guard. Every field below is a function of tree-sitter extraction, so a // blob written by a binary with a different kCacheVersion/kParserVer describes a DIFFERENT corpus and must // be rejected outright (self-healing recompute), never merged or trusted. std::uint32_t blobCacheVer = 0, blobParserVer = 0; if( !qsnapGet( p, end, blobCacheVer ) || blobCacheVer != kIngestCacheVersionMirror ) { return false; } if( !qsnapGet( p, end, blobParserVer ) || blobParserVer != kIngestParserVerMirror ) { return false; } // v14 — the PRODUCER guard. The dead set is a function of call resolution as well as extraction, so a blob // another build computed describes a different graph; the key already never names one, this refuses one // reached any other way (see producerIdentity). std::uint64_t blobProducer = 0; if( !qsnapGet( p, end, blobProducer ) || blobProducer != producerIdentityHash() ) { return false; } std::uint64_t shaHash = 0; if( !qsnapGet( p, end, shaHash ) || shaHash != fnv1a64( headSha ) ) { return false; } Snapshot s; const auto getValMap = [ & ]( gtl::btree_map& m ) -> bool { std::uint32_t n = 0; if( !qsnapGet( p, end, n ) ) { return false; } for( std::uint32_t i = 0; i < n; ++i ) { std::uint64_t k; std::uint32_t v; if( !qsnapGet( p, end, k ) || !qsnapGet( p, end, v ) ) { return false; } m[k] = v; } return true; }; const auto getHashMap = [ & ]( gtl::btree_map& m ) -> bool { std::uint32_t n = 0; if( !qsnapGet( p, end, n ) ) { return false; } for( std::uint32_t i = 0; i < n; ++i ) { std::uint64_t k, v; if( !qsnapGet( p, end, k ) || !qsnapGet( p, end, v ) ) { return false; } m[k] = v; } return true; }; const auto getSketchMap = [ & ]( gtl::btree_map& m ) -> bool // v29 (MOVES) { std::uint32_t n = 0; if( !qsnapGet( p, end, n ) || !qsnapCountFits( p, end, n, sizeof( std::uint64_t ) + sizeof( CloneSketch ) ) ) { return false; } for( std::uint32_t i = 0; i < n; ++i ) { std::uint64_t k; CloneSketch sk; if( !qsnapGet( p, end, k ) || !qsnapGet( p, end, sk ) ) { return false; } m[k] = sk; } return true; }; const auto getVec = [ & ]( std::vector& v ) -> bool { std::uint32_t n = 0; if( !qsnapGet( p, end, n ) || !qsnapCountFits( p, end, n, sizeof( std::uint64_t ) ) ) { return false; // a corrupt blob: the caller's "cache corrupt — recomputing" path } v.reserve( n ); for( std::uint32_t i = 0; i < n; ++i ) { std::uint64_t x; if( !qsnapGet( p, end, x ) ) { return false; } v.push_back( x ); } return true; }; const auto getDefectSites = [ & ]( std::vector& v ) -> bool { std::uint32_t n = 0; if( !qsnapGet( p, end, n ) || !qsnapCountFits( p, end, n, 2 * sizeof( std::uint64_t ) ) ) { return false; // a corrupt blob: the caller's "cache corrupt — recomputing" path } v.reserve( n ); for( std::uint32_t i = 0; i < n; ++i ) { DefectSiteKey d; if( !qsnapGet( p, end, d.anchor ) || !qsnapGet( p, end, d.site ) ) { return false; } v.push_back( d ); } return true; }; if( !getValMap( s.ccxBySym ) || !getValMap( s.locBySym ) || !getValMap( s.nestBySym ) || !getValMap( s.paramsBySym ) || !getValMap( s.defsBySym ) || !getValMap( s.maskBySym ) || !getValMap( s.maskReportBySym ) || !getValMap( s.failureDefaultBySym ) || !getValMap( s.placeholderBySym ) || !getHashMap( s.bodyHashBySym ) || !getHashMap( s.moveCidBySym ) || !getHashMap( s.bodyCidBySym ) || !getSketchMap( s.moveSketchBySym ) || !getVec( s.cloneGroups ) || !getVec( s.dead ) || !getVec( s.publicApi ) || !getDefectSites( s.defectSites ) ) { return false; } std::sort( s.cloneGroups.begin(), s.cloneGroups.end() ); // computeDelta binary_searches these — enforce order std::sort( s.dead.begin(), s.dead.end() ); std::sort( s.publicApi.begin(), s.publicApi.end() ); std::sort( s.defectSites.begin(), s.defectSites.end() ); // computeDelta merges these in key order out = std::move( s ); return true; } // Read a qsnap blob whole: its bytes for a readable non-empty file, nullopt for absent/empty/unreadable/not-a-regular-file // (a CLEAN miss — no alert). A present-but-invalid blob is still returned here; deserializeSnapshot then rejects it, // and the caller alerts. Binary-safe (no getline/text translation). inline std::optional readQSnapBlob( const std::string& path ) { // L1 (Linux runtime probe): opening a DIRECTORY succeeds on Linux/glibc and fails on macOS, so a // non-regular file at a cache-blob path is a platform-split hazard rather than a clean miss — it cost // ingest.cpp's loadCache an abort (see isRegularFileAt there). A qsnap blob is always a REGULAR file // (atomicWriteFile renames one into place); every other shape is a miss on every platform, which is // exactly what this function's nullopt already means, so it stays silent and the caller recomputes. { os::stat_t probe; if( os::stat( path.c_str(), &probe ) != 0 || !S_ISREG( probe.st_mode ) ) { return std::nullopt; } } std::ifstream f( path, std::ios::binary | std::ios::ate ); if( !f ) { return std::nullopt; } const std::streamsize sz = f.tellg(); if( sz <= 0 ) { return std::nullopt; } std::string out( static_cast( sz ), '\0' ); f.seekg( 0 ); if( !f.read( out.data(), sz ) ) { return std::nullopt; } return out; } // ─── Phase-M concurrency seam ─────────────────────────────────────────────────────────────────────── // // ingest() writes PROCESS-GLOBAL caches (ingest.cpp: compiledQueryCache / queryFor's static table) that are // single-writer BY DESIGN — populated single-threaded, then read lock-free by the parse pool. The long-lived // MCP server's Phase-M qsnap PREFETCH worker is the first source of a CONCURRENT ingest: a background // HEAD-snapshot warm that can overlap a request thread's own ingest (a getIndex rebuild, or a lazy // quality_delta). Because ingest.cpp is out of edit scope, we serialize at every ingest CALL SITE in the // server with this one process-wide mutex. Uncontended (the common single-request-thread case) it is ~20 ns; // when the worker and a request both need to ingest, one waits — correct, since both produce byte-identical // facts. Held ONLY around the ingest-heavy region, NEVER around a warm qsnap cache HIT (those stay lock-free). inline std::mutex& headSnapshotIngestMutex() { static std::mutex m; return m; } // Atomic publish (§2b atomic-publish gate: no partial blob is ever visible at the destination). Write the // bytes to a UNIQUE tmp file (pid + a monotone counter → distinct even between the request thread's lazy write // and the prefetch worker's write of the SAME sha), flush, then rename() — POSIX rename is atomic within a // directory, so a concurrent reader (readQSnapBlob here, or a separate ripwire process) sees either the OLD // complete file or the NEW complete file, never a torn half-written one. This REPLACES the direct // `ofstream(..., trunc)` that was torn-read-prone (a reader could observe a zero-length / partially-written // blob mid-write and reject a perfectly good sha), hardening the lazy path too. Degrade-only: any IO failure // unlinks the tmp and returns false → the next lazy/prefetch pass simply rewrites it. // // F-04 (round-4 audit): NAMED FOR THE MECHANISM, not for its first caller. It is a pure tmp+rename byte // publish with no qsnap knowledge in it, and `.ripwire_quality_acks` needs exactly the same guarantee for // exactly the same reason — a reader (git diff, an editor, a plain --quality-delta) must never observe a // half-written ledger. Reused rather than copied: a second tmp+rename would be two places for the unlink // and degrade rules to drift, which is the clone kind --quality-delta gates on. inline bool atomicWriteFile( const std::string& path, const std::string& blob ) { // Round 5 (rw::pathguard): the temp is created EXCLUSIVELY and WITHOUT following a link, under an // unpredictable name beside the target, refusing an existing entry at that name. The RAII holder removes // the temp on any failure // path below; commit() renames it into place. The name keeps its `.tmp.` infix (a *.tmp.* residue glob // still matches) and 0666 preserves the ofstream default mode; the kernel applies the umask exactly as // the stream did. The fd-based write replaces the ofstream, which cannot express O_EXCL. rw::pathguard::ExclTempFile temp = rw::pathguard::createExclTempFile( path + ".tmp.", "", 0666 ); if( !temp.ok() || !temp.write( blob ) ) { return false; // temp removed by the holder's destructor } return temp.commit( path ); } // ─── shared plumbing for the two archived-tree consumers (HEAD snapshot / churn window-ref) ───────────── // probe one qsnap-format blob: 1 = valid hit (`out` filled), 0 = clean miss (absent/empty/unreadable), // -1 = present but corrupt/mismatched (caller decides whether to alert). Never throws. inline int probeSnapshotBlob( const std::string& path, const std::string& sha, Snapshot& out ) { const std::optional blob = readQSnapBlob( path ); if( !blob ) { return 0; } return deserializeSnapshot( *blob, sha, out ) ? 1 : -1; } // RAII owner of a materialized commit tree — keep alive while reading file bytes through its ingest result. struct TmpTreeGuard { std::string p; ~TmpTreeGuard() { if( !p.empty() ) { std::error_code e; std::filesystem::remove_all( std::filesystem::path( p ), e ); } } }; // Materialize `committish`'s committed tree into a fresh pid-suffixed temp dir under the hardened cache // ladder (per-user; never the repo) via `git archive` followed by `tar -x`. Returns the temp root, or "" on // any failure (degrade-alerted; a half-made dir is cleaned up here — on success the CALLER owns cleanup via // TmpTreeGuard). // What materializeCommitTree hands back: the temp root, or EMPTY — the one field every caller reads as "no tree". It is // the DISCLOSE sink for the four ways the tree is not made; each caller then refuses, or marks its own answer. // // ARCHIVE AND EXTRACT ARE TWO SEPARATE COMMANDS, EACH CHECKED ON ITS OWN EXIT STATUS — not one shell pipeline // (mergescout.h's own commitTreeIsEmpty comment first named the ambiguity this closes). `git archive … | tar -x …` // piped straight through reports the PIPELINE's exit status as `tar`'s alone (no `pipefail`): that reads 0 // whether the tar stream had zero entries because the tree is genuinely empty OR because `git archive` failed // upstream and piped nothing downstream at all — `tar -x` on an empty stream is not itself an error. Writing the // archive to a file first, then extracting that file as its own command, makes ArchiveFailed mean what it says: // git's own exit status, independent of whatever tar does with the result. A caller can then trust that a // materialize which returns a non-empty root really READ the tree, so an ingest of that root coming back empty is // the tree's own content (no supported files, every path excluded, or a genuinely empty commit), never a masked // archive failure — indexCommittish no longer needs a second, indirect signal (the removed commitTreeIsEmpty) to // tell the two apart. struct MaterializedTree { enum class DisclosureWhy : std::uint8_t { RevisionUnresolved, TempDirUnavailable, ArchiveFailed, ExtractFailed, }; std::string root; void disclose( DisclosureWhy ) noexcept { root.clear(); } }; // The crawl denylist (ingest.h kCrawlSkipDirs / isSkippedCrawlDir) spelled as `git archive` exclude pathspecs, each // single-quoted and space-led. A caller that only INGESTS the tree (merge-scout's per-arm index) gains nothing from // extracting a subtree the crawl prunes by name anyway, and on this repository that subtree is most of the bytes: // third_party/ is 249 MB of a 325 MB archive, so every scouted arm wrote and deleted a quarter-gigabyte it never read // (--stray-content --plan: 12 arms, 116 s, timed out a 60 s caller with nothing printed). `glob` magic keeps `*` inside // one path component, the leading `**/` matches the root level too, and an exclude-only pathspec list still means // "everything else" (git >= 2.13). The one crawl prune a pathspec cannot express — a directory holding CMakeCache.txt — // is still extracted and still pruned by the crawl. What the prune CAN change is a tracked SYMLINK: one whose target sits // under a pruned directory (`src/v.c -> ../vendor/lib/v.c`) dangles in the pruned tree, and the crawl drops a dangling // link silently where the full tree indexed it. So a tree holding any symlink (mode 120000) is never pruned // (treeHasNoSymlink); with that guard the ingest result is the one an unpruned archive gives. // True only when `rev`'s tree provably holds no symlink: `git ls-tree -r` lists every entry's mode, and none is 120000. // An empty listing (an empty tree, or a git too old for --format) is not proof, so it answers false: the plain archive. inline bool treeHasNoSymlink( const std::string& root, const std::string& rev ) { const std::string modes = gitOneLine( root, "ls-tree -r " + shSingleQuote( "--format=%(objectmode)" ) + " " + shSingleQuote( rev ) + " 2>/dev/null" ); return !modes.empty() && modes.find( "120000" ) == std::string::npos; } inline std::string crawlSkipDirPathspecs() { std::string specs; for( const std::string_view dir : kCrawlSkipDirs ) { specs += " " + shSingleQuote( ":(exclude,glob)**/" + std::string( dir ) + "/**" ); } specs += " " + shSingleQuote( ":(exclude,glob)**/cmake-build-?*/**" ); // isSkippedCrawlDir: the prefix plus at least one byte specs += " " + shSingleQuote( ":(exclude,glob)**/?*.dSYM/**" ); // isSkippedCrawlDir: a name longer than the suffix return specs; } inline std::string materializeCommitTree( const std::string& root, const std::string& committish, const char* tag, bool pruneCrawlSkipDirs = false ) { namespace fs = std::filesystem; MaterializedTree tree; // r27 (Lane C routing) — RESOLVE THE REVISION FIRST. `git archive --output=FILE` really does write a file // (measured), so this is the P0.1 shape one careless caller away from being the same data-loss bug. Every // caller today passes "HEAD" or a rev-list sha, so this is a latent hole, not a live one — which is // exactly when it is cheapest to close. Resolving through `rev-parse --verify` and requiring a bare // object name is the real defense; quoting is not, and a LEADING `--` is not either (git would read the // revision as a pathspec and the command would silently archive nothing — Lane C measured that too), so // the separator goes AFTER the revision. const std::string rev = gitResolveCommitSha( root, committish ); if( rev.empty() ) { DISCLOSE( tree, MaterializedTree::DisclosureWhy::RevisionUnresolved, "quality: commit-tree revision does not resolve to a commit — refusing to archive" ); return tree.root; } // F1 (HISTORY-WALK-HANG): on a partial clone `git archive` of a tree with an absent blob parses every object of the promisor pack // before it fails (ClickHouse: past 90 s; gitmine.h gitIsPartialClone). The blobs are asked about first, by a read that fetches // nothing and does not scan the pack; archive is not started unless every blob of the tree is here. -1 (not told in time) refuses too. if( gitIsPartialClone( root ) ) { const long absent = gitAbsentBlobCount( root, rev ); if( absent != 0 ) { DISCLOSE( tree, MaterializedTree::DisclosureWhy::ArchiveFailed, "quality: partial clone, the commit tree has blobs this clone does not hold - git archive not started" ); return tree.root; } } std::error_code ec; std::string tmpRoot = cacheDirLadder() + "/ripwire-" + tag + "-" + std::to_string( os::getpid() ); // not const: moved out on return fs::remove_all( fs::path( tmpRoot ), ec ); // stale leftover from a crashed prior run if( !fs::create_directories( fs::path( tmpRoot ), ec ) && ec ) { DISCLOSE( tree, MaterializedTree::DisclosureWhy::TempDirUnavailable, "quality: cannot create commit-tree temp dir" ); return tree.root; } // Two SEPARATE commands, each checked on its own exit status (see the struct comment above for why: a // piped `archive | tar -x` masks a failed archive behind tar's own, unrelated, successful exit on an // empty stream). The intermediate .tar is a sibling of tmpRoot under the same cache ladder, named off the // same tag+pid tmpRoot already is (so it inherits the same per-process uniqueness contract §3619 documents // for tmpRoot itself), and is removed here regardless of outcome — it is never part of what the caller's // TmpTreeGuard owns. const std::string archiveFile = tmpRoot + ".tar"; const std::string archiveCmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " archive --format=tar --output=" + shSingleQuote( archiveFile ) + " " + shSingleQuote( rev ) + " -- "; // The pruned archive is an optimisation, never a new way to fail: git refuses an exclude-only pathspec over an // EMPTY tree ("pathspec … did not match any files", measured on git 2.50), which is a legal base. Any refusal of // the pruned form falls back to the plain archive, whose exit status then decides as it always did. // A tree with a symlink is archived whole (see crawlSkipDirPathspecs: a link into a pruned subtree would dangle). const bool archivedPruned = pruneCrawlSkipDirs && treeHasNoSymlink( root, rev ) && os::system( ( archiveCmd + crawlSkipDirPathspecs() + " 2>/dev/null" ).c_str() ) == 0; if( !archivedPruned && os::system( ( archiveCmd + " 2>/dev/null" ).c_str() ) != 0 ) { DISCLOSE( tree, MaterializedTree::DisclosureWhy::ArchiveFailed, "quality: git archive failed — committed tree unavailable" ); std::error_code e; fs::remove_all( fs::path( tmpRoot ), e ); fs::remove( fs::path( archiveFile ), e ); return tree.root; } // Feed the file through stdin: GNU tar treats a Windows drive colon in -f as a remote host. const std::string extractCmd = "tar -x -f - -C " + shSingleQuote( tmpRoot ) + " < " + shSingleQuote( archiveFile ) + " 2>/dev/null"; const int extractRc = os::system( extractCmd.c_str() ); std::error_code rmEc; fs::remove( fs::path( archiveFile ), rmEc ); // never leave the intermediate .tar behind, success or failure if( extractRc != 0 ) { DISCLOSE( tree, MaterializedTree::DisclosureWhy::ExtractFailed, "quality: tar extract failed — committed tree unavailable" ); std::error_code e; fs::remove_all( fs::path( tmpRoot ), e ); return tree.root; } // The intermediate .tar this function wrote is never handed back — `rmEc` above already removed it // (best-effort; a leftover .tar sibling is cache-ladder litter the sweep still reclaims, never something // a caller reads: ingest() below only ever walks `tmpRoot`, a directory, not a `.tar` sibling of it). return tmpRoot; } // ─── ONE ref-spec parse, shared by every verb that compares two TREES ─────────────────────────────────── // // `--dmm=VALUE` and `--quality-delta=VALUE` accept exactly the same three spellings, and they share ONE // implementation for the reason the R3 selectBaseline story above records: two arms each carrying their own // copy of a git-resolution rule is precisely how the two --quality-delta floors drifted apart and reported // 31 phantom regressions against zero. The spellings: // "" the working tree against HEAD (each verb's bare default) // "REV" REV against its FIRST PARENT (the per-commit form) // "A..B" B against A (an explicit range; an EMPTY side means HEAD) // `A...B` (symmetric difference) is REFUSED rather than quietly read as `A..B`: for a TREE comparison the two // spellings mean different things, and guessing which was meant is the substitution this tool does not ship. // Every token resolves through gitResolveCommitSha — which requires a bare object NAME — before it reaches // git a second time, so the P0.1 shape materializeCommitTree guards against cannot be smuggled in here either. enum class RefSpecStatus : std::uint8_t { Ok, // baseSha, plus either targetSha or targetIsWorkingTree, are usable NoGit, // environment: not a repo, or no commit on HEAD — `reason` says which BadRange, // USER error: the three-dot form — `badToken` is the spec verbatim BadRev, // USER error: `badToken` does not resolve to a commit NoParent, // environment: the REV form landed on a root commit or a shallow boundary — `reason` says which }; struct RefSpec { RefSpecStatus status = RefSpecStatus::Ok; std::string baseSha; // the EARLIER tree std::string targetSha; // the LATER tree — empty iff targetIsWorkingTree bool targetIsWorkingTree = false; std::string badToken; // BadRev/BadRange only: the offending token, verbatim std::string reason; // NoGit/NoParent only: the environment sentence }; // The NoParent sentence: a shallow clone's boundary commit is named as one (its parent exists upstream and was not // fetched), a true root commit keeps the sentence it always had. inline std::string noParentReason( const std::string& root, const std::string& sha ) { if( gitIsShallowBoundary( root, sha ) ) { return "shallow clone: that commit's parent was not fetched, so there is no earlier tree here to be a delta against " "(it is the shallow boundary, not a root commit; " + std::string( kShallowDeepenHint ) + ")"; } return "that commit has no parent — a root commit has no earlier tree to be a delta against"; } inline RefSpec resolveRefSpec( const std::string& root, std::string_view spec ) { RefSpec r; if( !gitRepoHasHistory( root ) ) { r.status = RefSpecStatus::NoGit; r.reason = "not a git repository, or no commit on HEAD — there is no earlier tree to compare against"; return r; } if( spec.empty() ) { r.targetIsWorkingTree = true; r.baseSha = gitResolveCommitSha( root, "HEAD" ); if( r.baseSha.empty() ) { r.status = RefSpecStatus::NoGit; r.reason = "HEAD does not resolve to a commit — there is no earlier tree to compare against"; } return r; } if( spec.find( "..." ) != std::string_view::npos ) { r.status = RefSpecStatus::BadRange; r.badToken = std::string( spec ); return r; } if( const std::size_t sep = spec.find( ".." ); sep != std::string_view::npos ) { const std::string baseRef = sep == 0 ? std::string( "HEAD" ) : std::string( spec.substr( 0, sep ) ); const std::string targetRef = sep + 2 >= spec.size() ? std::string( "HEAD" ) : std::string( spec.substr( sep + 2 ) ); r.baseSha = gitResolveCommitSha( root, baseRef ); r.targetSha = gitResolveCommitSha( root, targetRef ); if( r.baseSha.empty() || r.targetSha.empty() ) { r.status = RefSpecStatus::BadRev; r.badToken = r.baseSha.empty() ? baseRef : targetRef; } return r; } const std::string targetRef = std::string( spec ); r.targetSha = gitResolveCommitSha( root, targetRef ); if( r.targetSha.empty() ) { r.status = RefSpecStatus::BadRev; r.badToken = targetRef; return r; } // The per-commit form: the commit against its FIRST parent. A root commit has none — an environment fact, // not a typo, so it degrades with a stated reason rather than refusing. 0.6.6: so does a shallow clone's // BOUNDARY commit, whose parent exists but was never fetched; calling that "a root commit" was false // (--quality-delta=HEAD and --dmm=HEAD on every depth-1 clone), so the reason names which one it is. r.baseSha = gitResolveCommitSha( root, r.targetSha + "^" ); if( r.baseSha.empty() ) { r.status = RefSpecStatus::NoParent; r.reason = noParentReason( root, r.targetSha ); } return r; } // One move identity into a key's record: the MAX over the key's overloads, so the record is order-independent; 0 (none) records nothing. inline void recordMoveIdentity( gtl::btree_map& m, std::uint64_t key, std::uint64_t cid ) { if( cid != 0 ) { std::uint64_t& slot = m[ key ]; slot = std::max( slot, cid ); } } // MOVES (2026-11-13): the baseline half of a near-identical move — beside each key's recorded move identity, the sketch of the body // that identity came from (the overload whose cid is the recorded MAX, so the pair stays order-independent). Keys moveCidBySym does // not hold (outside the baseline's files, no canonical id) get no sketch either. inline void recordMoveSketches( Snapshot& snap, const MoveIdentities& ids, const std::vector& keyOf ) { for( const auto& [ i, sketch ] : ids.sketch ) { const auto it = i < keyOf.size() ? snap.moveCidBySym.find( keyOf[i] ) : snap.moveCidBySym.end(); if( it != snap.moveCidBySym.end() && it->second == ids.cid[i] ) { snap.moveSketchBySym[ it->first ] = sketch; } } } // T0.1 — build a quality Snapshot from the HEAD version of the tree, so `--quality-delta` (and the MCP // quality_delta verb) works at "before I push" with ZERO start-of-task ritual when no explicit // `.ripwire_quality_baseline` sidecar exists. Mechanism: `git archive HEAD` streams a tar of the committed // tree, extracted into a fresh temp dir under the hardened cacheDirLadder(); we ingest + buildGraph + // computeSnapshot on that temp root and clean it up. The temp root is passed as the snapshot's own `root`, so // every baseline key is the SAME root-RELATIVE baselineCanonId (relForHash) the working-tree side produces — // the two sides compare key-for-key regardless of where the HEAD tree was materialized (S2 spelling-independence). // // Determinism: HEAD content is fixed, so the extracted tree, its ingest, and the snapshot are byte-stable // run-to-run on a fixed tree state → the delta is byte-identical. The HEAD side goes through the IDENTICAL // computeSnapshot / per-canonId MAX aggregation as the working tree, so overloads collapse to one canonId with // the MAX metric on BOTH sides — a low-metric overload can never manufacture a phantom regression. // // Degrade (never throw): non-git root, no HEAD (unborn / detached with no committed tree), git unavailable, or // a failed archive/extract/ingest → returns {snapshot, false}. rootPath is shell-escaped (shSingleQuote) and // quotepath=false — no injection, deterministic path handling. inline Snapshot computeSnapshot( const IngestResult& ing, const Graph& g, std::string_view root, const std::vector* fileInBaseline = nullptr, // fwd — defined below; computeHeadSnapshot reuses it const KindScope& scope = KindScope(), TreePasses* passes = nullptr ); // QD-IDENTITY-ONCE: pure passes shared with the delta side (see TreePasses) // no braces here: qschemetripcheck's extractor reads them as a body // `excludes` MUST mirror the working-tree side's cfg.excludes (A4-F5): the HEAD snapshot is compared key-for-key // against the working tree, and any in-edge-derived kind (dead-code, api-surface) diverges if one side honors // --exclude and the other does not — e.g. a helper called only from tests/ is dead on a --exclude=tests working // tree but alive on an unfiltered HEAD → a phantom "dead-code" regression + exit 2 on an untouched tree. Default // {} keeps every existing call site (mcp.h, the CLI before it threads cfg.excludes) compiling and unchanged. inline std::pair computeHeadSnapshot( const std::string& root, const std::string_view* cacheNever = nullptr, std::size_t maxFileBytes = kDefaultMaxFileBytes, const std::vector& excludes = {} ) { (void)cacheNever; // 1) require a git repo with a resolvable HEAD tree — the SAME windowless `rev-parse --verify HEAD` probe // gitRepoHasHistory runs (one source of truth; was an inline copy of it before F13 dedup). if( !gitRepoHasHistory( root ) ) { return { Snapshot {}, false }; } // Cache keys, computed ONCE and shared by both the Snapshot cache (this step) and the ingest cache (step 3). const std::string headSha = gitHeadSha( root ); // non-empty: gitRepoHasHistory passed above const bool useCache = !headSha.empty(); const std::string repoHex = useCache ? cacheRootKeyHex( root ) : std::string{}; const std::string exclHex = useCache ? headSnapExclHex( excludes, maxFileBytes ) : std::string{}; // ingest-cache family const std::string qExclHex = useCache ? qsnapExclHex( excludes, maxFileBytes ) : std::string{}; // Snapshot-cache family const std::string qsnapPath = useCache ? qsnapCachePath( repoHex, qExclHex, headSha ) : std::string{}; // 1b) SNAPSHOT cache probe — a warm hit returns the fully-computed HEAD Snapshot and skips git archive, // ingest, buildGraph, AND clone detection entirely (the ~2.4 s the ingest cache alone could not save). // Absent/empty file → clean miss (no alert); present-but-invalid → corrupt (alert) → fall through to a // full recompute that rewrites a correct blob. if( useCache ) { Snapshot cached; const int hit = probeSnapshotBlob( qsnapPath, headSha, cached ); if( hit == 1 ) { return { std::move( cached ), true }; // HIT } if( hit == -1 ) { // the fprintf is the visible line in ALL build types (test/qsnapcachecheck.sh (e) gates on it); // DISCLOSE compiles out under NDEBUG. rw::emitRaw( stderr, "ripwire: quality: HEAD Snapshot cache corrupt — recomputing\n" ); DISCLOSE( Diagnostics::answerUnchanged, "the corrupt cache is recomputed from the tree: same answer, slower", "quality: HEAD Snapshot cache corrupt — recomputing" ); } } // Phase-M: serialize the ingest-heavy region against a concurrent ingest (the qsnap prefetch worker vs a // request thread), since ingest() writes single-writer process-global query caches (§2b). Held from here // through the atomic write below; the warm cache-probe above stays OUTSIDE the lock (lock-free hit). std::lock_guard ingestLk( headSnapshotIngestMutex() ); // Re-probe under the lock: whoever else held it (the lazy path or the prefetch worker) may have JUST // written the qsnap for this exact sha — take that hit instead of redundantly recomputing (worker + lazy // converge on one compute). Same validation as the pre-lock probe; a corrupt blob still falls through. if( useCache ) { Snapshot cached2; if( probeSnapshotBlob( qsnapPath, headSha, cached2 ) == 1 ) { return { std::move( cached2 ), true }; // HIT (won by the thread we waited on) } } // 2) materialize HEAD into a private temp dir under the hardened cache ladder (per-user; not the repo). // A unique suffix (pid) keeps concurrent runs from colliding. Cleaned up via RAII teardown. const std::string tmpRoot = materializeCommitTree( root, "HEAD", "qhead" ); if( tmpRoot.empty() ) { return { Snapshot {}, false }; } TmpTreeGuard guard{ tmpRoot }; // 3) ingest + graph + snapshot the HEAD tree. The HEAD tree is immutable for a given HEAD sha, so we hand // the ingest an incremental content-hash cache keyed on (repo, HEAD sha, excludes) — a warm re-run is a // pure cache hit instead of a ~12.5 s cold parse (A4-P1). The blob self-validates (parserVer + checksum // + per-file content hash) and is stored root-relative, so it can NEVER serve stale/foreign facts and is // portable across the pid-suffixed tmpRoot. Any cache IO failure degrades inside ingest() to a cold // parse — byte-identical output either way. The working-tree side's excludes are applied here too // (A4-F5) so both trees see the same file set. (Keys were computed once in step 1.) const std::string cachePath = useCache ? headSnapCachePath( repoHex, exclHex, headSha ) : std::string{}; IngestResult headIng = ingest( tmpRoot.c_str(), excludes, useCache ? std::string_view( cachePath ) : std::string_view{}, maxFileBytes ); // Hygiene: cap each (repo, excludes) family to the 2 newest files (delete older sha's). Done AFTER the // ingest so the file we just wrote/used is the newest → always retained. Best-effort; never throws. if( useCache ) { evictOldHeadSnapCaches( cacheDirLadder(), repoHex, exclHex, cachePath, 2 ); } if( headIng.symbols.empty() && headIng.files.empty() ) { DISCLOSE( "quality: HEAD tree ingested empty — falling back to run --quality-baseline first" ); return { Snapshot{}, false }; } // #350: a HEAD tree the memory guard cut is never scored and never persisted as the qsnap — a partial floor would // be served as complete by every later run. The no-snapshot path leaves the stop UNANSWERED, so the CLI backstop // exits 5 with its line and the MCP envelope carries _memory_stop (memguard.h). A stopped FOLD below is a failed build: // buildGraph throws FileGraphStopped, which skips the scoring and the qsnap write, and reaches the surface's own catch // (dispatchMain: exit 5; the MCP envelope: a refusal; the prefetch worker: dropped, nothing written). if( headIng.memoryStop.isSet() ) { return { Snapshot{}, false }; } const Graph headG = buildGraph( headIng, nullptr ); // root = tmpRoot so keys are root-relative and match the working-tree side key-for-key (S2). Snapshot snap = computeSnapshot( headIng, headG, tmpRoot ); // Persist the computed Snapshot so the NEXT --quality-delta on this HEAD skips everything above (clone // detection included). Best-effort: a failed write just means the next run recomputes — never a crash. The // written file is the newest in its family, so eviction (below) always retains it. if( useCache ) { const std::string blob = serializeSnapshot( snap, headSha ); atomicWriteFile( qsnapPath, blob ); // tmp+rename — never a torn read (§2b atomic publish) evictOldQSnapCaches( cacheDirLadder(), repoHex, qExclHex, qsnapPath, 2 ); } return { std::move( snap ), true }; } // ─── QD-PAIR-BASE-CACHE: the BASE side of --quality-delta=A..B, cached by its sha ───────────────────────────────── // On a warm `A..B` the base side was 59-70 % of the run (ML Stage 0 11-13): loadRefTree passes an ingest cache only when // the sha is HEAD, so the base commit was archived, cold-parsed, graphed and scored on EVERY call — and agents repeat // `origin/main..HEAD` with one base. Everything the comparison takes from that side is two values (verbs_quality.h // scoreBaseCommit): the base Snapshot for the selected kinds and the base tree's C-family macro names. Both are pure // functions of (repo, base sha, excludes, maxFileBytes, the selected kinds, the extraction and producer identity), so they // are stored in one blob of the "qbase" family keyed by exactly that, with the qsnap family's two never-stale guards: // 1) the FILENAME key is the qsnap one (qsnapExclHex: excludes, maxFileBytes, the qsnap scheme, the producer identity) // plus the kind mask, the sha the suffix (verbs_quality.h scoreBaseCommit) — another sha, exclude set, kind selection // or build names another file; // 2) the blob self-validates: its own magic and an fnv1a64 trailer over the whole body, and inside it a whole qsnap // blob (magic, scheme, ingest format mirrors, producer hash, sha hash, its own trailer). A blob that fails either // is refused, recomputed and rewritten (the caller alerts, the HEAD qsnap's corrupt-cache way). // Capped at two blobs per (repo, key) like qsnap: a working base and one previous. constexpr char kQBaseMagic[4] = { 'Q', 'B', 'A', 'S' }; struct BaseCommitScore { Snapshot snapshot; std::vector macros; // cFamilyMacroNames of the base tree, in its order }; // May a base commit's score be stored? Only when its ingest refused no file for nesting and extracted none partially // (CodeRabbit 4572576455 on #655). Such a base still answers, but its disclosures (the stderr notes, the --skipped rows) // come from the ingest a hit never runs, so a stored score would replay the answer without them. Every writer of the qbase // blob asks this, wherever it runs (verbs_quality.h scoreBaseCommit). inline bool baseScoreStorable( const IngestResult& baseIngest ) noexcept { return baseIngest.crawlSkips.nestRefusedFiles == 0 && baseIngest.crawlSkips.extractPartialFiles == 0; } inline std::string qbaseCachePath( const std::string& repoHex, const std::string& exclHex, const std::string& baseSha ) { return shaKeyedCachePath( "qbase", repoHex, exclHex, baseSha ); } // magic, the qsnap blob (length-prefixed), the macro names (count, then length-prefixed each), an fnv1a64 trailer inline std::string serializeBaseCommitScore( const BaseCommitScore& score, const std::string& baseSha ) { const std::string inner = serializeSnapshot( score.snapshot, baseSha ); std::string buf; buf.append( kQBaseMagic, 4 ); qsnapPut( buf, std::uint64_t( inner.size() ) ); buf.append( inner ); qsnapPut( buf, std::uint32_t( score.macros.size() ) ); for( const std::string& name : score.macros ) { qsnapPut( buf, std::uint32_t( name.size() ) ); buf.append( name ); } qsnapPut( buf, fnv1a64( buf ) ); return buf; } // false on ANY mismatch: short, bad trailer, bad magic, a length past the body, a qsnap blob that does not validate for // this sha, or bytes left over. Never throws. inline bool deserializeBaseCommitScore( const std::string& blob, const std::string& baseSha, BaseCommitScore& out ) { if( blob.size() < 4 + sizeof( std::uint64_t ) + sizeof( std::uint32_t ) + sizeof( std::uint64_t ) ) { return false; } const std::size_t bodyLen = blob.size() - sizeof( std::uint64_t ); std::uint64_t stored = 0; std::memcpy( &stored, blob.data() + bodyLen, sizeof( std::uint64_t ) ); if( stored != fnv1a64( std::string_view( blob.data(), bodyLen ) ) || std::memcmp( blob.data(), kQBaseMagic, 4 ) != 0 ) { return false; } const char* p = blob.data() + 4; const char* end = blob.data() + bodyLen; std::uint64_t innerLen = 0; if( !qsnapGet( p, end, innerLen ) || innerLen > std::uint64_t( end - p ) || !deserializeSnapshot( std::string( p, std::size_t( innerLen ) ), baseSha, out.snapshot ) ) { return false; } p += innerLen; std::uint32_t count = 0; if( !qsnapGet( p, end, count ) || count > std::uint64_t( end - p ) / sizeof( std::uint32_t ) ) { return false; // every name costs at least its length word } out.macros.clear(); out.macros.reserve( count ); for( std::uint32_t nameIndex = 0; nameIndex < count; ++nameIndex ) { std::uint32_t len = 0; if( !qsnapGet( p, end, len ) || len > std::uint64_t( end - p ) ) { return false; } out.macros.emplace_back( p, len ); p += len; } return p == end; } // ─── R-I: one materialized commit tree, ingested AND graphed, with an EXPLICIT lifetime ───────────────── // // `--quality-delta=A..B` reads file bytes through each materialized tree after this call returns: computeSnapshot // builds the floor from A, and computeDelta reads B. So the temp dir must OUTLIVE the call. It need not outlive the // other side's: the caller scores A and releases it before materializing B (#387). dmm.h's ingestCommitTree // deliberately lets its TmpTreeGuard fire at return (its profileOf touches only symbol metrics); that is NOT safe here, so the guard belongs to the CALLER and // this function only fills it — the lifetime is stated in the signature instead of being a comment someone // has to find. // // `out.root` is the materialized temp root, and it is the ONLY spelling that side's root-relative keys and // its displayed symbols may be taken against. Two reasons, and both are load-bearing: keys spelled against // the repo root would not match the other tree's (S2 key-for-key comparison), and the temp root carries a PID // suffix — letting it reach stdout would make the output differ run to run, which is a determinism bug even // when the findings are right. // // Cache policy mirrors dmm::ingestCommitTree exactly rather than inventing a second one: the HEAD sha reuses // --quality-delta's own (repo, excludes, sha) ingest-cache family, so a pair with a HEAD endpoint is a warm // blob read; any OTHER revision parses COLD on purpose, because that family is capped at two files per // (repo, excludes) and letting arbitrary ref pairs sweep it would trade the primary verb's warm path for // this one's on every run. Degrade (never throws): a failed archive/extract/ingest returns Unavailable, having // already alerted, and the caller reports the environment failure rather than a half-built comparison. An ingest the // memory guard stopped returns MemoryStopped before any graph is built: a partial tree is never scored (#350, #387). An // ingest that leaves the process at or over the guard's hard line returns OverHardLimit, also before the graph is built. enum class RefTreeLoad : std::uint8_t { Loaded, Unavailable, MemoryStopped, // out.ing.memoryStop says where and why OverHardLimit, // memguard::overHardLimit() read true after the ingest; the caller names the phase }; struct RefTree { std::string root; // the materialized temp root — empty until this call succeeds IngestResult ing; Graph g; FileGraphStop graphStop = FileGraphStop::None; // set when buildGraph's fold stopped: OverHardLimit with no graph }; // `tag` MUST differ between the two sides of a pair. materializeCommitTree spells its temp root // `/ripwire--` and REMOVES that path before extracting into it, so two calls sharing a tag // within one process land on the same directory and the second silently deletes the first. That is not a // hypothetical: the first cut of this function passed one tag for both sides, and the base tree's clone // detection — which re-reads file BYTES rather than trusting the in-memory index — then scored tree B's // bodies against tree B, inflating the duplication kind from 5 findings to 66. The two sides are named // separately here so the collision cannot be reintroduced by a caller that forgets. inline RefTreeLoad loadRefTree( const std::string& repoRoot, const std::string& sha, const std::vector& excludes, std::size_t maxFileBytes, const char* tag, TmpTreeGuard& guard, RefTree& out ) { ASSUME( tag != nullptr && *tag != '\0' ); const std::string tmpRoot = materializeCommitTree( repoRoot, sha, tag ); if( tmpRoot.empty() ) { return RefTreeLoad::Unavailable; // materializeCommitTree already alerted } guard.p = tmpRoot; // teardown is the CALLER's from here, success or not std::string cachePath; if( sha == gitHeadSha( repoRoot ) ) { cachePath = headSnapCachePath( cacheRootKeyHex( repoRoot ), headSnapExclHex( excludes, maxFileBytes ), sha ); } { // ingest() writes single-writer process-global query caches — serialize on the SAME mutex every other // materialized-tree reader in this file uses, rather than introducing a second lock order. std::lock_guard ingestLk( headSnapshotIngestMutex() ); out.ing = ingest( tmpRoot.c_str(), excludes, cachePath.empty() ? std::string_view {} : std::string_view( cachePath ), maxFileBytes ); } if( out.ing.memoryStop.isSet() ) { return RefTreeLoad::MemoryStopped; } if( out.ing.symbols.empty() && out.ing.files.empty() ) { DISCLOSE( Diagnostics::answerRefused, "the only caller, --quality-delta=A..B, refuses with the sha named; nothing is scored", "quality: a materialized commit tree ingested empty" ); return RefTreeLoad::Unavailable; } if( memguard::overHardLimit() ) { return RefTreeLoad::OverHardLimit; } try { out.g = buildGraph( out.ing, nullptr ); } catch( const FileGraphStopped& stopped ) // a failed build: no graph, so nothing is scored; the range form records the phase and degrades { out.graphStop = stopped.why(); return RefTreeLoad::OverHardLimit; } out.root = tmpRoot; return RefTreeLoad::Loaded; } // ─── qd-memory-degrade: a commit pair's CHANGED FILES, and their trees ───────────────────────────────────────── // When the memory guard stops either commit's full tree, or projects that the target phase will not fit, the range form // re-asks the question of each commit's CHANGED files only. That answer is exact for a kind only if every file that // could yield a row of it is in the set, and is materialized exactly as the full archive materializes it. So the set is // the paths `git diff --no-renames` names (per side, those that exist there as files), plus the control files the crawl // reads to decide those paths, and the pair is REFUSED by name when an archive or a crawl would treat a path git does not // list differently: // * a symlink anywhere in either tree — the crawl follows in-root links, so an UNCHANGED link to a changed file rows // the link's path too (and a changed link to an unchanged file dangles in a partial tree); // * an export-subst attribute in either tree — `git archive` rewrites the bytes of files git calls unchanged; // * a changed .gitattributes that carries an export attribute on either side — an export-ignore flip adds or removes // files the diff does not name. // The one crawl verdict decided by another file is the build-tree prune: a directory holding CMakeCache.txt is skipped // whole (ingest_crawl.h), so a changed path under such a directory brings that CMakeCache.txt along. Nothing else in // the crawl of a materialized tree reads another file: .gitignore is consulted through `git ls-files`, which a temp // tree does not answer, and .ripwire_config feeds only dead-code (a skipped kind). What it does not cover, stated: // attributes from $GIT_DIR/info/attributes or core.attributesFile (outside the tree, so the same on both sides). struct ChangedFiles { std::vector base; // root-relative paths to materialize at the base commit (sorted, unique) std::vector target; // ... at the target commit std::vector targetTree; // every file of the target commit, sorted — filled only when asked (--scope's test) std::string refusal; // non-empty: why the changed files cannot stand in for the trees (the line names it) bool ok = false; // git answered every question this needed enum class DisclosureWhy : std::uint8_t { GitFailed, // a diff, ls-tree or export-attribute grep over the pair did not complete: the set is unknown, and the caller refuses }; void disclose( DisclosureWhy ) noexcept { ok = false; } }; // Stream one git command's NUL-separated records into `onRecord`; true when git exited 0, or with the one other exit code // `alsoClean` names (git grep's 1 = no hit). Never holds the whole listing: on a large tree `ls-tree -r` is tens of // megabytes, and this runs exactly when memory is short. template inline bool forEachGitNulRecord( const std::string& root, const std::string& args, OnRecord&& onRecord, int alsoClean = 0 ) { const std::string cmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " " + args + " 2>/dev/null"; std::FILE* pipe = os::popen( cmd.c_str(), "r" ); if( pipe == nullptr ) { return false; } std::string record; char buf[ 16384 ]; std::size_t got = 0; while( ( got = std::fread( buf, 1, sizeof( buf ), pipe ) ) > 0 ) { for( std::size_t at = 0; at < got; ) { const char* nul = static_cast( std::memchr( buf + at, '\0', got - at ) ); const std::size_t end = nul == nullptr ? got : std::size_t( nul - buf ); record.append( buf + at, end - at ); if( nul == nullptr ) { break; } onRecord( std::string_view( record ) ); record.clear(); at = end + 1; } } if( !record.empty() ) { onRecord( std::string_view( record ) ); } const int status = os::pclose( pipe ); return status == 0 || ( alsoClean != 0 && decodedExitCode( status ) == alsoClean ); } // The changed files of `baseSha`..`targetSha` (two resolved commit names), with the refusals above decided. inline ChangedFiles changedFilesBetween( const std::string& root, const std::string& baseSha, const std::string& targetSha, bool wantTargetTree ) { ChangedFiles out; // 1. what git says changed: "\0\0" pairs; --no-renames reports a move as its delete and its add std::vector changed; std::vector statusOf; { bool wantPath = false; char status = 0; const bool ran = forEachGitNulRecord( root, "diff --no-renames --no-ext-diff --no-textconv --name-status -z " + shSingleQuote( baseSha ) + " " + shSingleQuote( targetSha ), [ & ]( std::string_view rec ) { if( !wantPath ) { status = rec.empty() ? 0 : rec.front(); wantPath = true; return; } changed.emplace_back( rec ); statusOf.push_back( status ); wantPath = false; } ); if( !ran ) { DISCLOSE( out, ChangedFiles::DisclosureWhy::GitFailed, "quality: git diff over the commit pair failed — the changed files are unknown" ); return out; } } // 2. each side's tree: which changed paths exist there as FILES (a submodule's gitlink is no file), the build-tree // sentinels, the attribute files, and any symlink at all. One streamed `ls-tree -r` per side. std::vector order( changed.size() ); for( std::size_t k = 0; k < order.size(); ++k ) { order[k] = k; } // rw::sortutil::svLess, not operator<: libstdc++'s string_view compare trips -fsanitize=integer (splitNulPaths' note) std::sort( order.begin(), order.end(), [ & ]( std::size_t a, std::size_t b ) { return rw::sortutil::svLess( changed[a], changed[b] ); } ); const auto changedIndex = [ & ]( std::string_view path ) -> std::size_t { const auto it = std::lower_bound( order.begin(), order.end(), path, [ & ]( std::size_t k, std::string_view p ) { return rw::sortutil::svLess( changed[k], p ); } ); return ( it != order.end() && changed[ *it ] == path ) ? *it : SIZE_MAX; }; const auto readSide = [ & ]( const std::string& sha, std::vector& existsHere, std::vector& cmakeDirs, std::vector* tree ) -> bool { existsHere.assign( changed.size(), 0 ); return forEachGitNulRecord( root, "ls-tree -r -z --full-tree " + shSingleQuote( sha ), [ & ]( std::string_view rec ) { const std::size_t tab = rec.find( '\t' ); if( tab == std::string_view::npos || tab < 7 ) { return; } const std::string_view mode = rec.substr( 0, 6 ); const std::string_view path = rec.substr( tab + 1 ); if( mode == "120000" && out.refusal.empty() ) { out.refusal = "the commit " + sha.substr( 0, 12 ) + " holds a symlink (" + std::string( path ) + "), which the crawl follows into files git diff does not name"; } const bool isFile = mode == "100644" || mode == "100755"; if( isFile && ( path == "CMakeCache.txt" || ( path.size() > 15 && path.substr( path.size() - 15 ) == "/CMakeCache.txt" ) ) ) { cmakeDirs.emplace_back( path.substr( 0, path.size() - 14 ) ); // the directory with its trailing '/', "" for the root } if( const std::size_t k = changedIndex( path ); k != SIZE_MAX && isFile ) { existsHere[k] = 1; } if( tree != nullptr && isFile ) { tree->emplace_back( path ); } } ); }; std::vector atBase, atTarget; std::vector cmakeBase, cmakeTarget; if( !readSide( baseSha, atBase, cmakeBase, nullptr ) || !readSide( targetSha, atTarget, cmakeTarget, wantTargetTree ? &out.targetTree : nullptr ) ) { DISCLOSE( out, ChangedFiles::DisclosureWhy::GitFailed, "quality: git ls-tree over a commit of the pair failed — the changed files are unknown" ); return out; } // 3. export attributes: ":\0\n" per hit (exit 1 = no hit, a clean answer; any other exit — a bad // object, git missing — is a failed read, never "no attribute") const auto exportAttrs = [ & ]( const std::string& sha, std::vector& files ) -> bool { std::string text; bool first = true; const bool ran = forEachGitNulRecord( root, "grep -I -z -o -e export-subst -e export-ignore " + shSingleQuote( sha ) + " -- " + shSingleQuote( "*.gitattributes" ), [ & ]( std::string_view rec ) { if( !first ) { text += '\0'; // the records are rejoined: the parse below reads the line shape } first = false; text.append( rec ); }, /*alsoClean=*/1 ); if( !ran ) { return false; } for( std::size_t at = 0; at < text.size(); ) { const std::size_t nl = std::min( text.find( '\n', at ), text.size() ); const std::string_view line( text.data() + at, nl - at ); const std::size_t nul = line.find( '\0' ); if( nul != std::string_view::npos && line.size() > sha.size() + 1 ) { const std::string_view path = line.substr( sha.size() + 1, nul - sha.size() - 1 ); const std::string_view match = line.substr( nul + 1 ); if( match == "export-subst" && out.refusal.empty() ) { out.refusal = "the commit " + sha.substr( 0, 12 ) + " carries an export-subst attribute (" + std::string( path ) + "), which rewrites files git diff calls unchanged"; } files.emplace_back( path ); } at = nl + 1; } return true; }; std::vector attrFiles; if( !exportAttrs( baseSha, attrFiles ) || !exportAttrs( targetSha, attrFiles ) ) { DISCLOSE( out, ChangedFiles::DisclosureWhy::GitFailed, "quality: git grep for export attributes over a commit of the pair failed — the changed files are unknown" ); return out; } for( const std::string& p : changed ) { if( out.refusal.empty() && std::find( attrFiles.begin(), attrFiles.end(), p ) != attrFiles.end() ) { out.refusal = "the pair changes " + p + ", which carries an export attribute (an export-ignore flip adds or removes files git diff does not name)"; } } // 4. the per-side lists, each changed path that is a file there, plus the CMakeCache.txt of any ancestor directory std::sort( cmakeBase.begin(), cmakeBase.end() ); std::sort( cmakeTarget.begin(), cmakeTarget.end() ); const auto addWithSentinels = [ & ]( const std::string& path, const std::vector& cmakeDirs, std::vector& list ) { list.push_back( path ); for( std::size_t slash = path.find( '/' ); slash != std::string::npos; slash = path.find( '/', slash + 1 ) ) { const std::string dir = path.substr( 0, slash + 1 ); if( std::binary_search( cmakeDirs.begin(), cmakeDirs.end(), dir ) ) { list.push_back( dir + "CMakeCache.txt" ); } } }; for( std::size_t k = 0; k < changed.size(); ++k ) { if( atBase[k] ) { addWithSentinels( changed[k], cmakeBase, out.base ); } if( atTarget[k] ) { addWithSentinels( changed[k], cmakeTarget, out.target ); } } for( std::vector* list : { &out.base, &out.target } ) { std::sort( list->begin(), list->end() ); list->erase( std::unique( list->begin(), list->end() ), list->end() ); } std::sort( out.targetTree.begin(), out.targetTree.end() ); out.ok = true; return out; } // Materialize `paths` of `sha` (already-resolved, each a file there) into a fresh temp tree: the same archive-then-extract // discipline as materializeCommitTree, in chunks so no command line grows with the change. Each path is a :(literal) // pathspec, so a name with glob characters is itself. An empty list is an empty tree (an empty diff is a legal question). // Returns the temp root, or "" on any failure (the guard the caller passes removes a partial tree). inline std::string materializeCommitSubset( const std::string& root, const std::string& sha, const std::vector& paths, const char* tag, TmpTreeGuard& guard ) { namespace fs = std::filesystem; std::error_code ec; const std::string tmpRoot = cacheDirLadder() + "/ripwire-" + tag + "-" + std::to_string( os::getpid() ); fs::remove_all( fs::path( tmpRoot ), ec ); if( !fs::create_directories( fs::path( tmpRoot ), ec ) && ec ) { DISCLOSE( Diagnostics::answerRefused, "the range form refuses with the sha named; nothing is scored", "quality: cannot create the changed-files temp dir" ); return {}; } guard.p = tmpRoot; const std::string archiveFile = tmpRoot + ".tar"; constexpr std::size_t kChunkBytes = 64 * 1024; // well under every ARG_MAX this builds on for( std::size_t at = 0; at < paths.size(); ) { std::string cmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " archive --format=tar --output=" + shSingleQuote( archiveFile ) + " " + shSingleQuote( sha ) + " --"; const std::size_t first = at; while( at < paths.size() && ( at == first || cmd.size() + paths[at].size() < kChunkBytes ) ) { cmd += " " + shSingleQuote( ":(literal)" + paths[at] ); ++at; } const bool archived = os::system( ( cmd + " 2>/dev/null" ).c_str() ) == 0; // Feed the file through stdin: GNU tar treats a Windows drive colon in -f as a remote host (same fix as materializeCommitTree). const bool extracted = archived && os::system( ( "tar -x -f - -C " + shSingleQuote( tmpRoot ) + " < " + shSingleQuote( archiveFile ) + " 2>/dev/null" ).c_str() ) == 0; fs::remove( fs::path( archiveFile ), ec ); if( !extracted ) { DISCLOSE( Diagnostics::answerRefused, "the range form refuses with the sha named; nothing is scored", "quality: archiving a commit's changed files failed" ); return {}; } } return tmpRoot; } // The changed files of one commit, ingested and graphed — loadRefTree's shape with three differences: never through an // ingest cache (a subset must not read a full-tree blob or write one under the commit's key — checklist 21), an empty // subset is a legal answer, and `tag` names it apart from the full trees. inline RefTreeLoad loadRefSubset( const std::string& repoRoot, const std::string& sha, const std::vector& paths, const std::vector& excludes, std::size_t maxFileBytes, const char* tag, TmpTreeGuard& guard, RefTree& out ) { ASSUME( tag != nullptr && *tag != '\0' ); const std::string tmpRoot = materializeCommitSubset( repoRoot, sha, paths, tag, guard ); if( tmpRoot.empty() ) { return RefTreeLoad::Unavailable; } { std::lock_guard ingestLk( headSnapshotIngestMutex() ); out.ing = ingest( tmpRoot.c_str(), excludes, std::string_view {}, maxFileBytes ); } if( out.ing.memoryStop.isSet() ) { return RefTreeLoad::MemoryStopped; } if( memguard::overHardLimit() ) { return RefTreeLoad::OverHardLimit; } try { out.g = buildGraph( out.ing, nullptr ); } catch( const FileGraphStopped& stopped ) // a failed build: no graph, so nothing is scored; the range form records the phase and degrades { out.graphStop = stopped.why(); return RefTreeLoad::OverHardLimit; } out.root = tmpRoot; return RefTreeLoad::Loaded; } // Signal-to-noise round — the committed-thrash evidence for short-horizon-churn: the per-canonId RAW-body // hashes of the tree at the churn-window reference commit (gitWindowRefSha). A symbol whose baseline (HEAD) // body differs from this ref's body — or that is absent here but present at HEAD — was already written/ // rewritten by COMMITS inside the window; only such a symbol may flag churn when the working tree rewrites it // again. Same materialize-ingest-hash pipeline as computeHeadSnapshot, minus the graph/clone/metric passes it // does not need, and cached in its own qbody family (warm re-runs are a blob read). Degrade (never throw): // no history / no ref / failed archive/ingest → {empty, false}, and the churn kind simply reports nothing. inline std::pair, bool> computeWindowRefBodyHashes( const std::string& root, std::uint32_t days, const std::vector& excludes = {}, std::size_t maxFileBytes = kDefaultMaxFileBytes ) { if( !gitRepoHasHistory( root ) ) { return { {}, false }; } const std::string refSha = gitWindowRefSha( root, days ); if( refSha.empty() ) { return { {}, false }; } const std::string repoHex = cacheRootKeyHex( root ); const std::string exclHex = headSnapExclHex( excludes, maxFileBytes ); // ingest-cache family (shared with qheadsnap) const std::string qbExclHex = qbodyExclHex( excludes, maxFileBytes ); const std::string qbodyPath = qbodyCachePath( repoHex, qbExclHex, refSha ); // warm probe (lock-free, same discipline as the qsnap probe): absent/empty → clean miss; corrupt → alert + // recompute. The blob validates against the REF sha, so a foreign/stale blob can never serve wrong facts. { Snapshot cached; const int hit = probeSnapshotBlob( qbodyPath, refSha, cached ); if( hit == 1 ) { return { std::move( cached.bodyHashBySym ), true }; } if( hit == -1 ) { rw::emitRaw( stderr, "ripwire: quality: window-ref body cache corrupt — recomputing\n" ); DISCLOSE( Diagnostics::answerUnchanged, "the corrupt cache is recomputed from the tree: same answer, slower", "quality: window-ref body cache corrupt — recomputing" ); } } // Phase-M: ingest() writes single-writer process-global caches — serialize like computeHeadSnapshot (§2b). std::lock_guard ingestLk( headSnapshotIngestMutex() ); // re-probe under the lock: another thread may have just published this exact ref. { Snapshot cached2; if( probeSnapshotBlob( qbodyPath, refSha, cached2 ) == 1 ) { return { std::move( cached2.bodyHashBySym ), true }; } } const std::string tmpRoot = materializeCommitTree( root, refSha, "qref" ); if( tmpRoot.empty() ) { return { {}, false }; } TmpTreeGuard guard{ tmpRoot }; // the ref tree is immutable for its sha → reuse the qheadsnap INGEST cache family keyed by refSha (the // family's keep-2 cap holds exactly the HEAD blob + this ref blob between commits). const std::string ingestCachePath = headSnapCachePath( repoHex, exclHex, refSha ); IngestResult refIng = ingest( tmpRoot.c_str(), excludes, std::string_view( ingestCachePath ), maxFileBytes ); evictOldHeadSnapCaches( cacheDirLadder(), repoHex, exclHex, ingestCachePath, 2 ); if( refIng.symbols.empty() && refIng.files.empty() ) { DISCLOSE( "quality: churn-window ref tree ingested empty — churn evidence unavailable" ); return { {}, false }; } if( refIng.memoryStop.isSet() ) // #350: a cut ref tree is never persisted as the qbody (see computeHeadSnapshot) { return { {}, false }; } Snapshot bodyOnly; bodyOnly.bodyHashBySym = bodyHashesBySym( refIng, tmpRoot ); // pathQualifiedKey on EVERY side of the churn join (baseline, this ref, working tree, per-node lookup) — a one-sided keying change makes every symbol read as rewritten // root = tmpRoot → root-relative keys (S2) atomicWriteFile( qbodyPath, serializeSnapshot( bodyOnly, refSha ) ); evictOldCacheFamily( cacheDirLadder(), "ripwire-qbody-" + repoHex + "-" + qbExclHex + "-", qbodyPath, 2 ); return { std::move( bodyOnly.bodyHashBySym ), true }; } // ─── Y2 (P2) — the qchurn family: memoizes gitmine::gitLogNameOnlyRaw's `git log --name-only` ────────── // walk (431 ms on a large private C++ corpus; every rich verb — --for, --metrics, --exemplar — pays it once // per invocation, main.cpp:5392/5404). DECIDED key ("Y2 churn-memo key"): // (realpath(root), HEAD sha, window-months, gitWindowRefSha). Concretely: `coSince` stands in for // "window-months" — it IS the window (currently always "18 months ago"), kept as the verbatim string // rather than an int-parse so any future caller's window text is captured exactly, not just the ones // shaped like " months ago"; and `gitmine::gitWindowBoundarySha(root, coSince)` is the "gitWindowRefSha" // component, adapted to THIS window's actual semantics — `coSince` resolves against WALL-CLOCK now() (git's // approxidate parser), unlike quality.h's own HEAD-epoch-anchored short-horizon window, so a cheap fresh // boundary probe (see its doc comment) is what makes (headSha, coSince) alone insufficient and the 4th key // component necessary — without it a cache written yesterday would silently keep serving today's `--for` // after the "18 months ago" cutoff has quietly moved a day's worth of commits across the boundary. // // Committed-history-only (the memo never sees uncommitted state): gitLogNameOnlyRaw is a pure `git log` // walk — no working-tree inspection at all — and the cached RAW per-commit (epoch, path) stream is resolved // against the CALLER's current `ing` fresh on every call (never itself cached), so a dirty file added/ // removed since the cache was written still resolves correctly; only the committed-history walk is skipped // on a hit. Review point (opus): no current rich-verb consumer of gitCoChangeAndChurn threads any // uncommitted/dirty signal INTO it — main.cpp's two call sites (5392/5404) pass only root/ing/coSince/ // maxFiles/churnMonths/onlyRoot, none of which reflect working-tree diffs; the amp= metric's OTHER half // (qmetrics.callerCount) comes from the live in-memory graph, not from this function, so folding uncommitted // state in here would be both unnecessary and (per the decided key) explicitly out of scope. // // No excludes component: gitLogNameOnlyRaw never looks at `ing` or --exclude (it is the raw, unresolved git // history stream) — exclusion is applied later, in resolveCommitStream, against the live `ing`. // SCHEME 2 (2026-07-31, the H4 round's merge-churn lane): gitLogNameOnlyRaw's walk now carries // gitmine::kMergeDiffArgs, so the RAW per-commit (epoch, paths) stream it caches has different CONTENT for // the same (root, HEAD sha, coSince, boundarySha) — a merge commit now names the files it introduced itself. // None of the four key components can see that, so without this bump a blob written by a merge-blind binary // would keep serving the old stream to a fixed binary: the exact silent-zero the fix removes, restored by // cache. Bumping the scheme makes every pre-existing blob a clean miss (deserialize checks it), not a wrong // answer. This is the qchurn cache's OWN version — not kParserVer, which keys extraction and is untouched. // SCHEME 3 (2026-10-10, train 26c, K51): a binary before K51 stored a walk git could not finish (an empty stream, or the // newest prefix of the window) as if it were the window, and the key cannot tell that blob from a real read. K51 never // stores one, but a blob already on disk would keep serving its silent zero or prefix, with no history_unread=, until HEAD // moved. The bump makes every pre-K51 blob a clean miss; the cost is one cold walk per repository. // SCHEME 4 (2026-10-23, the git-porcelain-framing lane): the walk's READER was rebuilt — the line-framed // `__C__` marker parse became one NUL-framed reader with a whole-field sentinel and one field of lookahead // (test/gitframingcheck.sh). On a repository whose committed paths spell the marker bytes, carry a // newline, or sort after a path that does, the OLD reader's stream was corrupted (forged commit headers, // swallowed paths), so a blob written by a pre-lane binary would keep serving that corrupted stream to a // fixed one until HEAD moved — the same wrong-answer-from-cache as scheme 2, one layer down: there the // COMMAND changed under an unchanged key, here the PARSE did. Neither is visible to the key, which is why // this bump is manual. On ordinary trees the two readers' streams are byte-identical (the lane's golden // arm over owners/hotspots/cochange), so the bump costs those repos one cold walk and changes no answer. // SCHEME 5 (2026-11-01, HISTORY-WALK-HANG): the COMMAND changed under an unchanged key again (--no-renames, gitLogRecordsCmd: // a rename now lists its old path too), the scheme 2 case. The blob also carries the walk's budget cut, so a cached prefix // still says it is one. constexpr std::uint32_t kQChurnCacheScheme = 5; constexpr char kQChurnMagic[4] = { 'Q', 'C', 'H', 'N' }; inline std::string serializeRawCommitStream( const RawCommitStream& raw, const std::string& keyMat ) { std::string buf; buf.append( kQChurnMagic, 4 ); qsnapPut( buf, kQChurnCacheScheme ); qsnapPut( buf, fnv1a64( keyMat ) ); qsnapPut( buf, std::uint32_t( raw.cut ) ); qsnapPut( buf, std::uint32_t( raw.commits.size() ) ); for( const RawCommitStream::Commit& c : raw.commits ) { qsnapPut( buf, c.epoch ); qsnapPut( buf, std::uint32_t( c.paths.size() ) ); for( const std::string& p : c.paths ) { qsnapPut( buf, std::uint32_t( p.size() ) ); buf.append( p.data(), p.size() ); } } const std::uint64_t sum = fnv1a64( std::string_view( buf.data(), buf.size() ) ); qsnapPut( buf, sum ); return buf; } inline bool deserializeRawCommitStream( const std::string& blob, const std::string& keyMat, RawCommitStream& out ) { if( blob.size() < 4 + sizeof( std::uint32_t ) + sizeof( std::uint64_t ) + sizeof( std::uint64_t ) ) { return false; } const char* data = blob.data(); const std::size_t bodyLen = blob.size() - sizeof( std::uint64_t ); std::uint64_t stored = 0; std::memcpy( &stored, data + bodyLen, sizeof( std::uint64_t ) ); if( stored != fnv1a64( std::string_view( data, bodyLen ) ) ) { return false; // checksum } const char* p = data; const char* end = data + bodyLen; if( std::memcmp( p, kQChurnMagic, 4 ) != 0 ) { return false; } p += 4; std::uint32_t scheme = 0; if( !qsnapGet( p, end, scheme ) || scheme != kQChurnCacheScheme ) { return false; } std::uint64_t keyHash = 0; if( !qsnapGet( p, end, keyHash ) || keyHash != fnv1a64( keyMat ) ) { return false; } // Every commit record is at least its epoch plus its path count, and every path at least its length prefix; // both counts are measured against the bytes left before either sizes a reserve (qsnapCountFits). constexpr std::size_t kMinCommitRecordBytes = sizeof( RawCommitStream::Commit::epoch ) + sizeof( std::uint32_t ); constexpr std::size_t kMinPathRecordBytes = sizeof( std::uint32_t ); std::uint32_t cutCode = 0; if( !qsnapGet( p, end, cutCode ) || cutCode > std::uint32_t( GitWalkCut::Time ) ) { return false; } std::uint32_t nCommits = 0; if( !qsnapGet( p, end, nCommits ) || !qsnapCountFits( p, end, nCommits, kMinCommitRecordBytes ) ) { return false; } RawCommitStream r; r.cut = GitWalkCut( cutCode ); r.commits.reserve( nCommits ); for( std::uint32_t i = 0; i < nCommits; ++i ) { RawCommitStream::Commit c; if( !qsnapGet( p, end, c.epoch ) ) { return false; } std::uint32_t nPaths = 0; if( !qsnapGet( p, end, nPaths ) || !qsnapCountFits( p, end, nPaths, kMinPathRecordBytes ) ) { return false; } c.paths.reserve( nPaths ); for( std::uint32_t j = 0; j < nPaths; ++j ) { std::uint32_t len = 0; if( !qsnapGet( p, end, len ) ) { return false; } if( end - p < static_cast( len ) ) { return false; } c.paths.emplace_back( p, len ); p += len; } r.commits.push_back( std::move( c ) ); } out = std::move( r ); return true; } // The memoized raw stream, WITHOUT any ingest: the git probes, the qchurn blob and, on a miss, the walk — everything // the amp=/churn= computation needs before it resolves paths against an `ing`. It reads nothing but the repo's committed // history and the blob, so a caller that wants the walk's wall time hidden behind its own ingest starts it first // (main.cpp does, for --for/--metrics/--exemplar) and resolves the result once `ing` exists. A cache hit skips the walk // (blob self-validates against `keyMat`; any mismatch — wrong headSha, wrong coSince, drifted boundary, or a // corrupt/foreign blob — is a clean miss that falls through to a full recompute, never a wrong answer). No git repo // degrades to an empty stream; no resolvable HEAD to the uncached walk (which itself degrades to an empty stream — // gitLogNameOnlyRaw's contract). Thread-safe: every memo it reaches (the HEAD anchor, the toplevel) takes its own // mutex, and the blob write is an atomic rename. K51: a walk git could not complete comes back with `unread` set and is never stored. // A prefix the BUDGET cut (gitmine.h THE BUDGET) is stored only when it is worth keeping: a Time cut under kMinStoredTimeCutCommits is a git // that stalled, not a slow repo, and `noCache` (--no-cache) neither reads nor writes any cut, so the flag that asks for a fresh answer gets one. inline constexpr std::size_t kMinStoredTimeCutCommits = 1024; inline RawCommitStream gitRawCommitStreamCached( const std::string& root, const char* coSince, bool noCache = false ) { if( !hasEnclosingGitRepo( root ) ) { return RawCommitStream{}; } const std::string headSha = gitHeadSha( root ); if( headSha.empty() ) { // No resolvable HEAD: an unborn branch has no history to read, and git log's failure there (git's own fatal exit, // 128) is that fact, not an I/O error — so that walk is "read, empty" (K51 floor: a HEAD that is corrupt rather than // unborn exits 128 too and reads the same here). Any OTHER failure means git did not answer at all — not on PATH // (the shell's 127), not executable, no popen — and gitHeadSha's "" was that, not an unborn branch: it stays unread. RawCommitStream noHead = gitLogNameOnlyRaw( root, coSince ); if( noHead.unread && noHead.exitCode == 128 ) { noHead.unread = false; } else if( noHead.unread ) { noHead.notRun = true; } return noHead; } const std::string repoHex = cacheRootKeyHex( root ); const std::string boundary = gitWindowBoundarySha( root, coSince ); // cheap — no --name-only std::string keyMat = headSha; keyMat.push_back( '\x1f' ); keyMat += coSince; keyMat.push_back( '\x1f' ); keyMat += boundary; keyMat += "qchurn" + std::to_string( kQChurnCacheScheme ); // The budget is in the key: a prefix cut under one budget must not answer a run that raised it. keyMat.push_back( '\x1f' ); keyMat += std::to_string( gitWalkMaxCommits() ); keyMat.push_back( '\x1f' ); keyMat += std::to_string( gitWalkMaxSeconds() ); const std::string cachePath = shaKeyedCachePath( "qchurn", repoHex, std::string{}, keyMat ); RawCommitStream raw; const std::optional blob = readQSnapBlob( cachePath ); if( blob && deserializeRawCommitStream( *blob, keyMat, raw ) && !( noCache && raw.cut != GitWalkCut::None ) ) { return raw; // warm hit — no walk } raw = RawCommitStream{}; // a stored cut that --no-cache refused to read is walked again raw = gitLogNameOnlyRaw( root, coSince ); // cold — the 431 ms walk if( raw.unread || gitWalksAbandoned() ) { // K51: a walk that could not be read is NOT stored. Stored, its empty stream would answer "read, no commits" under this // (repo, HEAD, window) key for as long as HEAD stayed put; unstored, the next call walks again and the caller discloses. // The flag rides the returned stream to main.cpp's amp=/churn= block, which DISCLOSEs it into the document (historyread.h). // An abandoned read (a memory-guard refusal stopped the walk) is a prefix too, even when git exited 0: never cached. return raw; } if( raw.cut != GitWalkCut::None && ( noCache || ( raw.cut == GitWalkCut::Time && raw.commits.size() < kMinStoredTimeCutCommits ) ) ) { return raw; // --no-cache keeps no cut; a clock that ran out within the first ~1,000 commits is a stalled git, not a prefix worth keeping until HEAD moves } // A cut prefix IS stored (a Commits cut, or a Time cut of a slow repo): re-walking would cost the whole budget on every call of a repo // that will only cut again, and the blob carries the cut, so the next answer still discloses it. Where the clock decided, WHICH commits // it reached moves with machine load, so the answer says so (renderHistoryUnread). It is the same prefix until HEAD moves. atomicWriteFile( cachePath, serializeRawCommitStream( raw, keyMat ) ); // best-effort; a failed // write just recomputes next time return raw; } // One root's amp=/churn= history, fetched without an ingest: the root it was walked for and its raw 18-month stream. // main.cpp starts one per root beside the ingest and resolves each against `ing` afterwards. struct HistoryWalk { std::string root; RawCommitStream raw; }; inline HistoryWalk gitHistoryWalk( std::string root, bool noCache = false ) { RawCommitStream raw = gitRawCommitStreamCached( root, "18 months ago", noCache ); return HistoryWalk{ std::move( root ), std::move( raw ) }; } // The resolve half, the memoized drop-in for gitCoChangeAndChurn on the 18-month window main.cpp's amp=/churn= block // reads (commits with more than 30 files dropped from the sets): `walk` resolved against the CALLER's current `ing`. // Pure in-memory work except the HEAD anchor's memo (one `git log -1` the first time a root asks); a root with no // enclosing repo never reaches that anchor at all. inline std::vector> resolveHistoryWalk( const HistoryWalk& walk, const IngestResult& ing, unsigned churnMonths = 0, std::vector* outChurn = nullptr, std::uint32_t onlyRoot = UINT32_MAX ) { constexpr std::size_t kMaxFilesPerCommit = 30; // F1: the churn sub-window's cutoff, resolved ONCE from HEAD's own committer epoch — the same anchor the // co-change window (inside gitLogNameOnlyRaw) uses, so the two horizons this one walk yields agree. // AFTER the no-repo check, so a non-git root never reaches the anchor read at all. const std::int64_t churnCutoff = hasEnclosingGitRepo( walk.root ) ? rw::defaultWindowCutoffEpoch( walk.root, churnMonths ) : 0; return resolveCommitStream( walk.raw, ing, kMaxFilesPerCommit, churnCutoff, outChurn, onlyRoot ); } // `root` = the ingest root exactly as invoked (cfg.rootPath). It is folded into every baseline key via // baselineCanonId so the written sidecar is root-spelling-independent (S2). g.canonId is still consulted only // as the "has a canonical id" presence gate — the HASHED key is the root-relative baselineCanonId, never g's. // ── computeSnapshot's BASELINE-MEMBERSHIP filter, in three named pieces ────────────────────────────────── // // `fileInBaseline`, when non-null, is a per-fileId flag: 0 means "this file is NOT part of the baseline the // snapshot stands for". The IDENTITY BASIS (computeHeadBasis, below) is its only caller — it builds the HEAD // baseline out of the WORKING TREE's own ingest and has to leave out the files HEAD does not track, so their // symbols stay ABSENT at baseline and keep reading as new. It is a MEMBERSHIP filter, never a metric change: // a file that is in the baseline contributes exactly the records it always did, computed from exactly the same // graph. A null filter is the pre-#228 behaviour, branch for branch, which is what lets computeHeadSnapshot // keep writing a cached Snapshot that means exactly what it always meant (see test/qschemetripcheck.sh). // // Out-of-range fileIds read as IN-baseline: a short or absent vector can then only ever widen the baseline, // never narrow it, so a plumbing mistake cannot invent a regression. inline bool fileIsInBaseline( const std::vector* fileInBaseline, std::uint32_t fileId ) noexcept { return fileInBaseline == nullptr || fileId >= fileInBaseline->size() || ( *fileInBaseline )[ fileId ] != 0; } // A clone group is a SET identity (see cloneGroupHash), so a member the baseline does not contain makes the // whole set something the baseline never held: the group is left out rather than re-hashed without it. inline bool cloneGroupIsInBaseline( const CloneGroup& cg, const IngestResult& ing, const std::vector* fileInBaseline ) noexcept { for( NodeId m : cg.members ) { if( m < ing.symbols.size() && !fileIsInBaseline( fileInBaseline, ing.symbols[m].fileId ) ) { return false; } } return true; } // constructCountsBySym and bodyHashesBySym walk EVERY symbol, so the membership filter reaches their results // here, on their keys. The key space is path-qualified (qualityKey), so a key belongs to exactly ONE file: // dropping a non-baseline file's key can never take a baseline file's record with it. inline void dropNonBaselineKeys( Snapshot& snap, const IngestResult& ing, std::string_view root, const std::vector* fileInBaseline ) { if( fileInBaseline == nullptr ) { return; } std::vector dropKeys; for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( !fileIsInBaseline( fileInBaseline, ing.symbols[i].fileId ) ) { dropKeys.push_back( qualityKey( ing, i, root ) ); } } std::sort( dropKeys.begin(), dropKeys.end() ); const auto dropped = [ & ]( std::uint64_t k ) noexcept { return std::binary_search( dropKeys.begin(), dropKeys.end(), k ); }; for( gtl::btree_map* m : { &snap.maskBySym, &snap.maskReportBySym, &snap.failureDefaultBySym, &snap.placeholderBySym } ) { for( auto it = m->begin(); it != m->end(); ) { it = dropped( it->first ) ? m->erase( it ) : std::next( it ); } } for( auto it = snap.bodyHashBySym.begin(); it != snap.bodyHashBySym.end(); ) { it = dropped( it->first ) ? snap.bodyHashBySym.erase( it ) : std::next( it ); } } // The duplication baseline = both exact (Type-1/2) AND gapped (Type-3) groups, folded into one set. A Type-3 // pair hashes by its sorted member canonIds exactly like an exact group, so introducing a NEW near-clone // changes the set and the delta flags it. Both passes are deterministic, so the set is stable. // // QD-CLONE-FALSE-GATE (P5 pilot 2026-11-10, reports/qd-catch-rate-pilot-1110.md: 7/410 seeded runs gated on a clone pair the // edit did not make): the SET identity alone reads two re-shapes of the SAME baseline duplication as new. // (1) A group SHRINKS. Exact {a,b,c}; an edit to a leaves exact {b,c} (and a near pair {a,b}): neither set is {a,b,c}, so both // gated, on b and c the edit never touched (tmux options_get_*). // (2) A near pair's member is an EXACT TWIN. findClonesType3 keeps one representative per distinct token stream (the first id), // so with f1 == f2 exact and g near f1 the baseline holds {f1,g} and never {f2,g}; an edit to f1 makes f2 its own stream and // {f2,g} reads as new although f2 was g's near clone all along (promgo NewConst*: 8 gating rows from one 3-line insert). // So the baseline also holds every PAIR its clone relation implies: each pair inside an exact group, and each near pair widened // to the exact twins of both members. The delta then treats a current group as held when its own set is in the baseline or every // pair of its members is (cloneGroupHeldAtBaseline). Same hash space: a pair hashes exactly like a two-member group, so a pair // row in the set means "these two were clones at the baseline". A NEW member still makes a pair the baseline never held, so a // third copy, a copy of a function and a near clone of an untouched function still gate. Bounded: a group or widened pair with // more than kClonePairExpandCap pairs adds none (its re-shapes keep the set identity, a floor). inline constexpr std::size_t kClonePairExpandCap = 512; // Where the held pairs go: one pair hash per two members, both in baseline files (the cloneGroupIsInBaseline rule, per pair). struct HeldClonePairSink { std::vector& out; const IngestResult& ing; std::string_view root; const std::vector* fileInBaseline; void push( NodeId x, NodeId y ) const { const bool known = x != y && x < ing.symbols.size() && y < ing.symbols.size(); if( known && fileIsInBaseline( fileInBaseline, ing.symbols[x].fileId ) && fileIsInBaseline( fileInBaseline, ing.symbols[y].fileId ) ) { out.push_back( cloneMemberSetHash( { baselineCanonId( ing, x, root ), baselineCanonId( ing, y, root ) } ) ); } } }; // `pred( a, b )` for every index pair a < b < n, in order, stopping at the first false; true when none was false. template inline bool everyIndexPair( std::size_t n, Pred&& pred ) { for( std::size_t a = 0; a < n; ++a ) { for( std::size_t b = a + 1; b < n; ++b ) { if( !pred( a, b ) ) { return false; } } } return true; } // (1) every pair inside an exact group of three or more (a two-member group's pair hash is already its own). inline void pushExactGroupPairs( const HeldClonePairSink& sink, const std::vector& exact ) { for( const CloneGroup& cg : exact ) { const std::size_t n = cg.members.size(); if( n < 3 || n * ( n - 1 ) / 2 > kClonePairExpandCap ) { continue; } (void) everyIndexPair( n, [ & ]( std::size_t a, std::size_t b ) { sink.push( cg.members[a], cg.members[b] ); return true; } ); } } // (2) every near pair widened to the exact twins of both members: twins of a x twins of b (a member with no twin stands alone). inline void pushTwinWidenedPairs( const HeldClonePairSink& sink, const std::vector& exact, const std::vector& type3 ) { constexpr std::uint32_t kNoGroup = ~0u; std::vector exactGroupOf( sink.ing.symbols.size(), kNoGroup ); for( std::uint32_t gi = 0; gi < exact.size(); ++gi ) { for( NodeId m : exact[gi].members ) { if( m < exactGroupOf.size() ) { exactGroupOf[m] = gi; } } } const auto twinsOf = [ & ]( const NodeId& m RW_LIFETIMEBOUND ) -> std::span { const std::uint32_t gi = m < exactGroupOf.size() ? exactGroupOf[m] : kNoGroup; return gi == kNoGroup ? std::span( &m, 1 ) : std::span( exact[gi].members ); }; for( const CloneGroup& cg : type3 ) { if( cg.members.size() != 2 ) { continue; } const std::span sa = twinsOf( cg.members[0] ), sb = twinsOf( cg.members[1] ); if( ( sa.size() == 1 && sb.size() == 1 ) || sa.size() * sb.size() > kClonePairExpandCap ) { continue; // no twin: the pair's own hash is the whole relation; over the cap: a floor } for( NodeId x : sa ) { for( NodeId y : sb ) { sink.push( x, y ); } } } } inline std::vector baselineCloneGroupHashes( const IngestResult& ing, std::string_view root, const std::vector* fileInBaseline, TreePasses& passes ) { std::vector out; const std::vector& exact = passes.exactClones( ing ); const std::vector& type3 = passes.type3Clones( ing ); for( const CloneGroup& cg : exact ) { if( cloneGroupIsInBaseline( cg, ing, fileInBaseline ) ) { out.push_back( cloneGroupHash( cg, ing, root ) ); } } for( const CloneGroup& cg : type3 ) { if( cloneGroupIsInBaseline( cg, ing, fileInBaseline ) ) { out.push_back( cloneGroupHash( cg, ing, root ) ); } } const HeldClonePairSink sink{ out, ing, root, fileInBaseline }; pushExactGroupPairs( sink, exact ); pushTwinWidenedPairs( sink, exact, type3 ); std::sort( out.begin(), out.end() ); out.erase( std::unique( out.begin(), out.end() ), out.end() ); return out; } // Every pair of the member ids `ids` (three or more, under kClonePairExpandCap pairs) is in the baseline set. inline bool everyClonePairHeld( const std::vector& ids, const std::vector& baseCloneGroups ) { const std::size_t n = ids.size(); if( n < 3 || n * ( n - 1 ) / 2 > kClonePairExpandCap ) { return false; } return everyIndexPair( n, [ & ]( std::size_t a, std::size_t b ) { return std::binary_search( baseCloneGroups.begin(), baseCloneGroups.end(), cloneMemberSetHash( { ids[a], ids[b] } ) ); } ); } // The delta's side of QD-CLONE-FALSE-GATE (see HeldClonePairSink and the two passes after it): a current clone group is the baseline's when its own // member set is in the baseline set, or when every pair of its members is (a group the edit only shrank or re-paired). A // two-member group's pair IS its set, so only a group of three or more reads the pairs. `h` = cloneGroupHash( cg ). inline bool cloneGroupHeldAtBaseline( const CloneGroup& cg, std::uint64_t h, const std::vector& baseCloneGroups, const IngestResult& ing, std::string_view root ) { if( std::binary_search( baseCloneGroups.begin(), baseCloneGroups.end(), h ) ) { return true; } const std::size_t n = cg.members.size(); if( n < 3 || n * ( n - 1 ) / 2 > kClonePairExpandCap ) { return false; } std::vector ids; ids.reserve( n ); for( NodeId m : cg.members ) { if( m >= ing.symbols.size() ) { return false; } ids.push_back( baselineCanonId( ing, m, root ) ); } return everyClonePairHeld( ids, baseCloneGroups ); } // QD-GIT-RENAME-HEAL — a current clone group with a member in a file git recorded as renamed is the baseline's when, re-spelled // at the earlier paths (`renamedFrom`: depth d takes each moved member's d-th earlier path, or its oldest), its member set or every // pair of it is in the baseline set (cloneGroupHeldAtBaseline). The record names the file, the member keeps its scope and name, // so twins elsewhere do not matter. A member that is new, or renamed inside the moved file, still makes a set the baseline never // held, so a genuinely new clone still gates. using EarlierPaths = std::vector*>; // per member: its file's recorded earlier paths, or nullptr // Each member's recorded earlier paths, and in `depth` the longest chain among them (0: no member sits in a renamed file). inline EarlierPaths membersEarlierPaths( const CloneGroup& cg, const gtl::btree_map>& renamedFrom, const IngestResult& ing, std::string_view root, std::size_t& depth ) { EarlierPaths earlier( cg.members.size(), nullptr ); depth = 0; for( std::size_t k = 0; k < cg.members.size(); ++k ) { const NodeId m = cg.members[k]; if( m >= ing.symbols.size() || ing.symbols[m].fileId >= ing.files.size() ) { depth = 0; // a member the index cannot place: no re-spelling is claimed return earlier; } const auto it = renamedFrom.find( std::string( relForHash( ing.files[ ing.symbols[m].fileId ], root ) ) ); if( it != renamedFrom.end() && !it->second.empty() ) { earlier[k] = &it->second; depth = std::max( depth, it->second.size() ); } } return earlier; } // The members' baseline ids with each moved member spelled at its d-th earlier path (or its oldest, when its chain is shorter). inline std::vector cloneIdsAtRenameDepth( const CloneGroup& cg, const EarlierPaths& earlier, std::size_t d, const IngestResult& ing, std::string_view root ) { std::vector ids; ids.reserve( cg.members.size() ); for( std::size_t k = 0; k < cg.members.size(); ++k ) { const Symbol& s = ing.symbols[ cg.members[k] ]; ids.push_back( earlier[k] ? canonicalId( ( *earlier[k] )[ std::min( d, earlier[k]->size() ) - 1 ], s.scope, s.name ) : baselineCanonId( ing, cg.members[k], root ) ); } return ids; } inline bool cloneGroupHeldAcrossRenames( const CloneGroup& cg, const std::vector& baseCloneGroups, const gtl::btree_map>& renamedFrom, const IngestResult& ing, std::string_view root ) { if( renamedFrom.empty() ) { return false; } std::size_t depth = 0; const EarlierPaths earlier = membersEarlierPaths( cg, renamedFrom, ing, root, depth ); for( std::size_t d = 1; d <= depth; ++d ) { const std::vector ids = cloneIdsAtRenameDepth( cg, earlier, d, ing, root ); if( std::binary_search( baseCloneGroups.begin(), baseCloneGroups.end(), cloneMemberSetHash( ids ) ) || everyClonePairHeld( ids, baseCloneGroups ) ) { return true; } } return false; } // Every defect-shape site in the tree, anchored on the innermost enclosing definition (byte-span containment, // the same rule error-masking counts by) or on the file. Languages: C++ (format-arity, utf8-cut, // dedup-first), Python (format-arity), Bash under a test-script path (vacuous-assert). Each scanned file also // leaves its presence record; a file that does not read leaves the unreadable record instead and contributes // no site (a partial read is evidence of nothing, forEachSymbolBody's rule) — the delta then judges no current // site in that file against it. Sorted by key; deterministic (files in id order, scanners pure). // format-arity's F1 skip input: every macro NAME the index holds in a C-family file, tree-wide (a call in one file may // use a macro another file defines). Sorted, unique: the scanner binary-searches it. Also what a degraded // --quality-delta=A..B keeps of the base commit's full tree (names only) so the changed files are scanned against the // tree's set rather than their own (qd-memory-degrade). inline std::vector cFamilyMacroNames( const IngestResult& ing ) { std::vector names; for( const Symbol& s : ing.symbols ) { if( s.kind == SymKind::Macro && ( s.lang == Lang::Cpp || s.lang == Lang::C || s.lang == Lang::ObjC ) ) { names.push_back( s.name ); } } std::sort( names.begin(), names.end() ); names.erase( std::unique( names.begin(), names.end() ), names.end() ); return names; } // `macroOverride`, when given, is the macro-name set to scan C++ files against instead of this index's own — the whole // tree's, when this index holds only some of its files (a degraded --quality-delta=A..B's changed files). inline std::vector defectSitesOf( const IngestResult& ing, std::string_view root, const std::vector* fileInBaseline, const std::vector* macroOverride = nullptr ) { std::vector out; const SymbolsByFile byFile = symbolsByFileInIdOrder( ing, []( const Symbol& s ) { return s.endByte > s.sigStartByte && s.kind != SymKind::ModuleScope; } ); const std::vector ownMacros = macroOverride == nullptr ? cFamilyMacroNames( ing ) : std::vector{}; const std::vector& treeMacros = macroOverride == nullptr ? ownMacros : *macroOverride; for( std::uint32_t f = 0; f < ing.files.size(); ++f ) { if( !fileIsInBaseline( fileInBaseline, f ) ) { continue; } const std::string_view rel = relForHash( ing.files[f], root ); const Lang lang = langOfPath( rel ); if( lang != Lang::Cpp && lang != Lang::Python && !( lang == Lang::Bash && isTestScriptPath( rel ) ) ) { continue; } const std::uint64_t fileAnchor = defectFileAnchor( rel ); std::optional bytes = docparse::detail::readWholeFile( diskPath( ing, f ) ); if( !bytes ) { out.push_back( { { fileAnchor, kDefectFileUnreadable }, kNoNode, f, 0 } ); continue; } out.push_back( { { fileAnchor, kDefectFilePresent }, kNoNode, f, 0 } ); const std::string_view src = *bytes; std::vector fnSpans; if( f < byFile.size() ) { for( NodeId i : byFile[f] ) { const Symbol& s = ing.symbols[i]; if( ( s.kind == SymKind::Function || s.kind == SymKind::Method ) && s.endByte <= src.size() ) { fnSpans.push_back( { s.sigStartByte, s.endByte } ); } } } std::vector sites; if( lang == Lang::Cpp && defectshape::cppMayHoldShapes( src ) ) { sites = defectshape::scanCpp( src, fnSpans, &treeMacros ); } else if( lang == Lang::Python && src.find( ".format" ) != std::string_view::npos ) { sites = defectshape::scanPython( src ); } else if( lang == Lang::Bash && src.find( "grep" ) != std::string_view::npos ) { sites = defectshape::scanBashTestScript( src, fnSpans ); } for( const defectshape::Site& st : sites ) { ASSUME( st.startByte < src.size(), "a scanner reports a site at a byte of the file it scanned" ); const NodeId owner = enclosingDefOf( ing, byFile, f, st.startByte ); const std::uint64_t anchor = owner == kNoNode ? fileAnchor : qualityKey( ing, owner, root ); const std::uint32_t line = static_cast( 1 + std::count( src.begin(), src.begin() + st.startByte, '\n' ) ); out.push_back( { { anchor, defectSiteValue( st.facet, st.text ) }, owner, f, line } ); } } std::stable_sort( out.begin(), out.end(), []( const DefectSiteAt& a, const DefectSiteAt& b ) { return a.key < b.key; } ); return out; } // The dead set of a snapshot: every dead-code candidate the --dead-code verb's rule leaves dead, keyed like every per-symbol // record. Its own pass (and its four evidence structures) so a snapshot computed for kinds without dead-code skips it. inline void addDeadSet( Snapshot& snap, const IngestResult& ing, const Graph& g, std::string_view root, const std::vector* fileInBaseline ) { const std::vector topLevelCallees = topLevelCalleeNameHashes( ing ); // W1-S2: dead-kind evidence, built once const std::vector macroNames = registeredMacroNames( root ); // P2.2: built-ins + .ripwire_config const std::vector macroIds = registeredMacroSymbolIds( ing, macroNames ); const std::vector dropIds = rustDropImplMethodIds( ing ); // issue #494: Drop::drop by its impl block const std::vector pythonDispatch = pythonDispatchedMethodIds( ing, g ); const ValueRefIndex valueRefs( ing ); // a value-held function is not dead for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() || !fileIsInBaseline( fileInBaseline, ing.symbols[i].fileId ) ) { continue; } if( isDeadCandidate( ing, g, i, topLevelCallees, macroIds, pythonDispatch, dropIds ) && !declinedCallMayReach( g, i ) && !valueRefs.isValueReferenced( i ) ) { snap.dead.push_back( qualityKey( ing, i, root ) ); } } } // The snapshot's whole-file passes, each only for the kinds it feeds (see computeSnapshot): clone groups, construct // counts, defect sites, body hashes. inline void addKindPasses( Snapshot& snap, const IngestResult& ing, std::string_view root, const std::vector* fileInBaseline, const KindScope& scope, TreePasses* shared ) { TreePasses own; TreePasses& passes = shared != nullptr ? *shared : own; // QD-IDENTITY-ONCE: the caller's, when the delta side reads the same ingest if( ( scope.kinds & ( kindBit( "duplication" ) | kindBit( "new-clone-of-reused-helper" ) ) ) != 0 ) { snap.cloneGroups = baselineCloneGroupHashes( ing, root, fileInBaseline, passes ); } // §D#4 error-masking + placeholder baseline: per-canonId counts (the SUMs the delta compares), from one pass. if( ( scope.kinds & ( kindBit( "error-masking" ) | kindBit( "placeholder" ) ) ) != 0 ) { ConstructCounts counts = passes.constructCounts( ing, root ); // a copy: a shared value is read again by the delta snap.maskBySym = std::move( counts.mask ); snap.maskReportBySym = std::move( counts.maskReport ); snap.failureDefaultBySym = std::move( counts.failureDefault ); snap.placeholderBySym = std::move( counts.placeholder ); } // the defect-shape baseline: every offending site (a sorted multiset of anchor + site identity) and each // scanned file's presence record. Filtered to the baseline files inside defectSitesOf (IDENTITY BASIS). if( kindSelected( scope.kinds, "defect-shape" ) ) { const std::vector sites = defectSitesOf( ing, root, fileInBaseline, scope.macroOverride ); snap.defectSites.resize( sites.size() ); std::ranges::transform( sites, snap.defectSites.begin(), &DefectSiteAt::key ); } // §D#4 short-horizon-churn baseline: per-canonId RAW-body hash so the delta detects a rewrite that moved no // metric (a literal-only edit). Compared, never bar-checked — presence-or-difference IS the rewrite signal. if( kindSelected( scope.kinds, "short-horizon-churn" ) ) { snap.bodyHashBySym = bodyHashesBySym( ing, root ); } } // `scope` (qd-memory-degrade): the kinds this snapshot will be compared for. A pass that feeds only unselected kinds is // not run and its records stay empty — the dead set without dead-code, the clone groups without either clone kind, the // construct counts without error-masking or placeholder, the defect sites without defect-shape, the body hashes without // short-horizon-churn. The per-symbol metric maps always run (locBySym is every kind's existence oracle). The default // scope is every pass, the snapshot this function has always returned; its macroOverride: see defectSitesOf. inline Snapshot computeSnapshot( const IngestResult& ing, const Graph& g, std::string_view root, const std::vector* fileInBaseline, const KindScope& scope, TreePasses* passes ) { Snapshot snap; MoveIdentities moveIds; // MOVED-BODY: the move identity of every body over a bar std::vector codeLoc = codeLocByNode( ing, &moveIds ); // Q-DIAL-3: the verbosity kind's metric is CODE lines const std::vector& moveCid = moveIds.cid; std::vector keyOf( ing.symbols.size(), 0 ); // path-qualified ALWAYS — see qualityKey for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i < g.canonId.size() && !g.canonId[i].empty() ) { keyOf[i] = qualityKey( ing, i, root ); } } measureCallableNotItsContainer( ing, keyOf, codeLoc ); // EXTENT-CTOR: the same rule computeDelta applies for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } const Symbol& s = ing.symbols[i]; if( !fileIsInBaseline( fileInBaseline, s.fileId ) ) { continue; // IDENTITY BASIS: not a baseline file — every record below would be a phantom } const std::uint64_t key = keyOf[i]; // overloads share a canonical id (scope+name) → keep the MAX of each per-symbol metric per id, not // last-writer-wins; otherwise a low-metric overload written last makes every later delta report a // phantom regression forever (THE trap). Every new per-symbol kind mirrors this MAX exactly. { std::uint32_t& slot = snap.ccxBySym[ key ]; slot = std::max( slot, s.ccx ); } { std::uint32_t& slot = snap.locBySym[ key ]; slot = std::max( slot, codeLoc[i] ); } // Q-DIAL-3: CODE lines, not the physical span { std::uint32_t& slot = snap.nestBySym[ key ]; slot = std::max( slot, std::uint32_t( s.maxNest ) ); } { std::uint32_t& slot = snap.paramsBySym[ key ]; slot = std::max( slot, std::uint32_t( s.params ) ); } recordMoveIdentity( snap.moveCidBySym, key, moveCid[i] ); // overloads share a key: the MAX, so the record is order-independent recordMoveIdentity( snap.bodyCidBySym, key, moveIds.body[i] ); // QD-RENAME-IDENTITY: every callable (an overload set never matches) // THE ONE KIND THAT IS NOT A MAX, and the reason is the MAX itself. Every metric above collapses the // overload set to its largest member, which makes the set's CARDINALITY unrecoverable — so removing an // overload whose metrics are below the max moves nothing at all, on either side of a comparison, while // a call site that used it stops binding. --edit-check reads this count as defs_was to see exactly that // (editcheck.h). A COUNT is overload-collision-proof for the opposite reason a MAX is: it is the one // number a collision cannot hide. (maskBySym is the other non-MAX kind; it sums for its own reason.) { std::uint32_t& slot = snap.defsBySym[ key ]; slot += 1; } if( isPublicApi( ing, i ) ) { snap.publicApi.push_back( key ); } } recordMoveSketches( snap, moveIds, keyOf ); // MOVES: the sketch beside each recorded move identity if( kindSelected( scope.kinds, "dead-code" ) ) { addDeadSet( snap, ing, g, root, fileInBaseline ); // sorted below with the rest; its order of insertion never reaches a reader } addKindPasses( snap, ing, root, fileInBaseline, scope, passes ); dropNonBaselineKeys( snap, ing, root, fileInBaseline ); // IDENTITY BASIS membership, on the two key-built maps std::sort( snap.dead.begin(), snap.dead.end() ); std::sort( snap.cloneGroups.begin(), snap.cloneGroups.end() ); std::sort( snap.publicApi.begin(), snap.publicApi.end() ); snap.publicApi.erase( std::unique( snap.publicApi.begin(), snap.publicApi.end() ), snap.publicApi.end() ); // overloads collapse to one canonId return snap; } // ─── THE IDENTITY BASIS — a no-op diff is empty BY CONSTRUCTION, not by luck (issue #228, part 1) ──────── // // THE DEFECT. `--quality-delta`'s auto-baseline builds the HEAD side by `git archive HEAD` into a temp dir and // re-ingesting it (computeHeadSnapshot). That tree is NOT "the working tree with my changes undone" — it is a // DIFFERENT POPULATION, and a dead-code verdict is a property of the whole population, not of the symbol's own // file. So a file that exists on one side only moves a verdict on a symbol in a file both sides share. Measured // on a nine-file fixture whose working tree is identical to HEAD (this binary, before the fix): // // shape rows exit why the populations differ // untracked file defining a same-named function 1 2 the archive cannot hold an untracked file // an untracked nested git repo 2 2 same, times every file under it // a tracked file marked `export-ignore` 1 2 `git archive` applies export attributes // sparse checkout hiding a tracked caller 2 2 the crawl cannot see it; the archive holds it // `git update-index --skip-worktree` on a caller 1 2 the index says clean; the bytes are not // // That is the reporter's shape exactly: a Django monolith with untracked directories, `git status` clean of // modifications, 58 gating `preexisting-worse` dead-code rows, exit 2. A pre-commit hook that fires on an // unchanged tree is unusable, and the escape hatch is blocked too (`--quality-baseline` refuses to pin over a // tree that "already holds N gating findings"). NOT the cause, measured: a shallow clone (it reads 0 on its // own — the reporter's `+shallow` is a bystander), the caches (cold, warm and `--no-cache` runs were // byte-identical), and resolver tie-breaks (d9ad3e84 fixed the root-spelling half already). // // THE FIX. When the working tree's TRACKED files are identical to HEAD, stop materializing a second tree: the // working tree IS HEAD, so the baseline is the working tree's own snapshot, taken from the ingest and graph // the delta side is about to be computed from. The comparison is then a snapshot against ITSELF, and // computeDelta cannot find a regression in it — no metric can differ from itself, no key can be absent from a // map that contains every key, no clone group can be new. Empty by construction, and it costs a `git diff // --quiet` instead of an archive, a tar and a full re-ingest. // // WHAT THE BASELINE LEAVES OUT, and why it is not a fudge. Files the working tree holds that HEAD does not // TRACK — untracked files, an untracked nested repo, a checked-out submodule's contents — are still ingested // and still in the graph (they are part of the tree the user is asking about), but they are NOT in the // baseline: baselineFileMaskAtHead marks them, computeSnapshot's membership filter leaves their symbols out, // and they keep reading as NEW exactly as they do against an archived HEAD today. So the new-file debt the // verb has always reported is unchanged; only the PHANTOM rows on tracked symbols go away. The honest // statement of the basis is "HEAD's tracked content, read in this working tree, alongside the files you have // not added yet" — which is what a user comparing a clean tree actually means, and it is said on stderr // whenever the count is non-zero. // // WHY IT DOES NOT TOUCH THE CACHES. This path never probes and never writes the `qsnap`/`qheadsnap` blobs: it // has no archived tree to key them to. computeHeadSnapshot is untouched, so a blob written by any binary still // means exactly what it meant. That is also why this change needs no kQSnapCacheScheme bump. // // WHAT IT DOES NOT COVER, stated so the next reader does not mistake the scope: a tree that DOES carry tracked // modifications still takes the archive path, so a population divergence can still move a verdict there (the // reporter's second observation — 28 rows in unrelated files for a one-file commit — is that case). Making the // archive path's population equal by construction is the follow-on, and the starter kit // (prompts/help-wanted/quality-delta-unchanged-tree-zero.md) is where its per-class decisions live. // THE FAST PRE-CHECK, and ONLY that. `git diff --quiet HEAD -- .` answers staged and unstaged changes, // additions and deletions of tracked paths, in one exit code with no output to parse — but it is SPECIFIED to // be blind to two index bits, and being blind is the whole point of them: // // * `git update-index --skip-worktree PATH` — "the file on disk is not the file I committed; do not look" // * `git update-index --assume-unchanged PATH` — "trust the stat cache; do not read the bytes" // // A tracked file carrying either one can hold a REAL change — an edit that deletes a function's only caller, // or the file's outright DELETION — and `git diff` still exits 0. Trusting that exit code alone as "the working tree IS HEAD" turned a // genuine gating dead-code regression into `gating="0"` exit 0, silently: a false NEGATIVE, which is a worse // answer than the false positive the identity basis exists to remove. So this function is the cheap FIRST of // two conditions, and `indexHidesTrackedContent` below is the second; `computeHeadBasis` requires both. // // The `-- .` pathspec scopes the question to the crawl root when the root is a SUBDIRECTORY of the repository, // so an edit elsewhere in the repo cannot take the basis away from a root that never crawls it. Untracked // files are deliberately NOT a difference here — they are handled by the baseline mask below. Any git failure // (not a repo, unborn HEAD, git absent) reads as "not identical" and falls back to the archived baseline. inline bool workingTreeMatchesHead( const std::string& root ) { const std::string cmd = gitCmd( " -c core.quotepath=false -C " ) + shSingleQuote( root ) + " diff --no-ext-diff --no-textconv --ignore-submodules=dirty --quiet HEAD -- . >/dev/null 2>&1"; return os::system( cmd.c_str() ) == 0; } // Split one `sep`-separated git listing (NUL for a -z form, '\n' for a line one) into SORTED root-relative // views over it, dropping `prefix` // (the crawl root's position inside the repository) from each. The views alias `listing`, which therefore has // to outlive them — the one caller keeps it in scope for exactly that reason. A trailing newline is trimmed // because popenTrimmed re-joins its reads on '\n' and a -z listing carries none inside. inline std::vector splitNulPaths( const std::string& listing, const std::string& prefix, char sep = '\0' ) { std::vector out; for( std::size_t start = 0; start < listing.size(); ) { const std::size_t nul = listing.find( sep, start ); const std::size_t end = ( nul == std::string::npos ) ? listing.size() : nul; std::string_view p( listing.data() + start, end - start ); while( !p.empty() && ( p.back() == '\n' || p.back() == '\r' ) ) { p.remove_suffix( 1 ); } if( !prefix.empty() && p.size() > prefix.size() && p.compare( 0, prefix.size(), prefix ) == 0 ) { p.remove_prefix( prefix.size() ); } if( !p.empty() ) { out.push_back( p ); } start = end + 1; } // rw::sortutil::svLess, not the default comparator: a string_view's operator< goes through // char_traits::compare, whose libstdc++ implementation subtracts two size_t lengths and trips // -fsanitize=integer on the Linux G1 leg the moment two compared views differ in length. Same total // order, so nothing about the resulting sequence changes — and the binary_search over this exact // vector in baselineFileMaskAtHead below MUST pass the same comparator, or the search is looking in // an order the sort did not produce. test/portablebuildcheck.sh arm #6b holds both halves. std::sort( out.begin(), out.end(), rw::sortutil::svLess ); return out; } // THE SECOND CONDITION: does any tracked path carry an index bit that hides it from the check above? // // `git ls-files -v` is the one command that reports the two bits git's own diff will never mention: an `S` // tag is skip-worktree, a LOWERCASE tag is assume-unchanged. A path carrying either can differ from HEAD in // ANY way — edited, or deleted outright — with `git status` and `git diff` both silent. So the answer here is // as blunt as it can be: **any flagged path at all, present or absent, means no identity basis.** // // IT TOOK THREE REVIEWS TO GET HERE, AND THE HISTORY IS THE ARGUMENT. Round 1 refused only when the flagged // path was still ON DISK; that was defeated by `rm`-ing it, because the bit hides a deletion exactly as it // hides an edit. Round 2 kept an exception for cone-mode sparse checkout — where git sets the same bit and // legitimately removes the file — by deciding for itself which paths the cone includes; that was defeated by // a file sitting in an ANCESTOR of a listed directory, which real cone mode materializes and this file's copy // of the rule did not know about. Each fix was defeated the first time it was attacked, in the same shape: // a real regression invisible, `head_basis="identity"` asserted over it, `--quality-baseline` pinning it. // // THE LESSON IS THE ONE THIS FILE ALREADY WROTE DOWN FOR THE NON-CONE CASE, then broke for the cone one: // re-implementing git's matcher to decide a correctness question is a second, unargued copy of git's rules, // and a partial copy is worse than none because it reads as complete. `git sparse-checkout check-rules` would // be authoritative, but it lands in git 2.42 and this tool still degrades gracefully on 2.31 (see // docs/SUBSTITUTION_METER.md), so on much of the supported range it would refuse anyway — the same outcome // as this rule, reached with a version gate, a temp file and a subprocess. So the exception is GONE, and with // it sparseConeDirs and sparseConeIncludes. There is nothing left here to model wrongly. // // WHAT A SPARSE-CHECKOUT USER GETS, stated plainly because it is a real cost and not a neutral one: the // archived-HEAD comparison, which is NOT sparse-aware — `git archive HEAD` materializes the excluded files — // so a cone-excluded caller can still read as vanished and gate. That is the SAME population divergence this // lane removes for untracked content, left in place for this one shape, and it is the pre-existing behaviour // on main rather than anything this lane introduces. It belongs to slice 2 of // prompts/help-wanted/quality-delta-unchanged-tree-zero.md, where making the archived side's population equal // by construction is the actual fix. `head_basis="archived-index-hidden"` on the root is how a user finds out // that this is the branch they are on, instead of guessing from silence. // // COST: one `git ls-files -v` on every identity attempt — one child, the same order as the crawl itself. inline bool isBlindIndexTag( char tag ) noexcept { return tag == 'S' || ( tag >= 'a' && tag <= 'z' ); // skip-worktree; lowercase = assume-unchanged } // true = refuse the identity basis. A git failure returns true — "assume it hides something" — so an // unreadable index can only ever COST the identity basis, never grant it. inline bool indexHidesTrackedContent( const std::string& root ) { const std::string listing = gitOneLine( root, "ls-files -v -z -- . 2>/dev/null" ); if( listing.empty() ) { return !gitOneLine( root, "ls-files -z -- . 2>/dev/null" ).empty(); // empty because nothing is tracked, or because git failed? } const std::vector entries = splitNulPaths( listing, std::string{} ); // " " — no prefix to strip return std::any_of( entries.begin(), entries.end(), []( std::string_view e ) noexcept { return e.size() >= 3 && e[1] == ' ' && isBlindIndexTag( e[0] ); } ); } // Per-fileId flags for computeSnapshot: 1 = this crawled file is TRACKED AT HEAD and therefore part of the // baseline, 0 = it is not. `outNotAtHead` receives the count of crawled files HEAD does not track — the number // the stderr disclosure reports. Returns false when git could not answer at all, in which case the caller MUST // fall back to the archived baseline: an empty answer here is indistinguishable from "HEAD tracks nothing", // and acting on it would report every symbol in the tree as new. inline bool baselineFileMaskAtHead( const std::string& root, const IngestResult& ing, std::string_view rootPath, std::vector& outMask, std::size_t& outNotAtHead ) { EXPECTS( outMask.empty(), "the mask is built here, never appended to a caller's" ); // -z: NUL-separated, so a path containing a newline or a quote arrives as its own bytes rather than as // git's C-quoted rendering (core.quotepath=false alone does not stop ls-tree quoting those). const std::string listing = gitOneLine( root, "ls-tree -r --name-only -z HEAD -- . 2>/dev/null" ); if( listing.empty() ) { return false; // no answer — NOT "HEAD is empty". The caller degrades to the archived baseline. } // A subdirectory root: ls-tree answers in REPOSITORY-relative paths while every ingest path is // ROOT-relative, so the repo prefix comes off before the two are compared. const std::vector tracked = splitNulPaths( listing, gitOneLine( root, "rev-parse --show-prefix 2>/dev/null" ) ); outMask.assign( ing.files.size(), 0 ); outNotAtHead = 0; for( std::size_t f = 0; f < ing.files.size(); ++f ) { // relForHash is the SAME root-relative spelling every quality key is built from (qualityKey), so a // file's membership here and its key there cannot drift apart. const std::string_view rel = relForHash( ing.files[f], rootPath ); // The SAME comparator splitNulPaths sorted `tracked` with. A search under a different order than // the sort produced is a silent wrong answer — here it would drop a tracked file out of the // baseline mask and make its symbols read as new. Both are svLess; neither may change alone. if( std::binary_search( tracked.begin(), tracked.end(), rel, rw::sortutil::svLess ) ) { outMask[f] = 1; } else { ++outNotAtHead; } } ENSURES( outMask.size() == ing.files.size(), "one flag per crawled file — computeSnapshot indexes it by fileId" ); return true; } // The HEAD baseline for a WORKING-TREE comparison, through ONE seam. Every surface that compares a working // tree with HEAD calls this — the CLI `--quality-delta`, the CLI `--quality-baseline` dirty-pin verdict and // the MCP `quality_delta` verb — so the three cannot answer the same tree differently in the same second, // which is the §B6 M5 / R3 lesson this file already carries twice. // // TWO CALLERS OF computeHeadSnapshot DELIBERATELY STAY ON IT, and the reason is stated so the next reader // cannot mistake it for an oversight: `--edit-check` (editcheck.h) asks a per-symbol contract question whose // answer on an unchanged tree is `status="unchanged"` either way — measured on the untracked-file shape, // identical on both bases — and its warm path is budgeted on the qsnap hit the identity basis does not take; // and the MCP qsnap PREFETCH worker (mcpindex.h) exists precisely to warm that archived blob and has no // working-tree ingest to build an identity basis from. // `basis` is the value of head_basis= on the root, or nullptr when the attribute is ABSENT. Three states, and // the absent one is deliberately the ordinary case so a normal run pays nothing: // "identity" — the baseline is this working tree's own snapshot (see above) // "archived-index-hidden" — the identity basis was REFUSED because a tracked path carries skip-worktree or // assume-unchanged, so the archived HEAD tree answered. A user whose fast path // vanished can read WHY off the answer instead of guessing from silence, and it // is the one refusal reason they can act on (clear the bit, or accept that a // sparse checkout's population differs from HEAD's). // nullptr — the archived HEAD tree answered for the ordinary reason: the tree carries // tracked modifications, which is what every git-HEAD marker has always meant. struct HeadBasis { Snapshot snapshot; bool ok = false; // false: no HEAD tree to compare against at all (non-git, unborn, no tree) bool identity = false; // true: the baseline is this working tree's own snapshot (see above) const char* basis = nullptr; // static storage; head_basis= value, or nullptr when the attribute is absent std::size_t notAtHead = 0; // crawled files HEAD does not track (identity basis only); 0 = none }; // `passes` (QD-IDENTITY-ONCE): under the identity basis the snapshot reads `ing` itself, so a caller that will // computeDelta over the same `ing` hands one TreePasses to both and the clone and construct passes run once. inline HeadBasis computeHeadBasis( const std::string& root, const IngestResult& ing, const Graph& g, std::string_view rootPath, std::size_t maxFileBytes = kDefaultMaxFileBytes, const std::vector& excludes = {}, TreePasses* passes = nullptr ) { HeadBasis out; // THREE conditions, cheapest first, and all three are required. The third — indexHidesTrackedContent — is // not a refinement of the second: `git diff` is SPECIFIED to answer "clean" for a skip-worktree or // assume-unchanged path, so without it a real change in such a file is compared against a baseline that // already contains it, and vanishes. See the two functions' own comments. const bool hasHistory = gitRepoHasHistory( root ); if( hasHistory && workingTreeMatchesHead( root ) ) { if( indexHidesTrackedContent( root ) ) { // The one refusal a user can act on, so it is named ON THE ANSWER rather than left to silence. out.basis = "archived-index-hidden"; } else { std::vector mask; if( baselineFileMaskAtHead( root, ing, rootPath, mask, out.notAtHead ) ) { out.identity = true; out.ok = true; out.basis = "identity"; out.snapshot = computeSnapshot( ing, g, rootPath, out.notAtHead != 0 ? &mask : nullptr, KindScope(), passes ); ENSURES( out.notAtHead <= ing.files.size(), "the not-at-HEAD count is a subset of the crawled files it was counted over" ); return out; } DISCLOSE( Diagnostics::answerUnchanged, "the archived HEAD baseline still answers, just without the identity guarantee", "quality: cannot list HEAD's tracked paths — falling back to the archived HEAD baseline" ); } } auto [ snap, ok ] = computeHeadSnapshot( root, nullptr, maxFileBytes, excludes ); out.snapshot = std::move( snap ); out.ok = ok; return out; } // THE ONE PLACE THE QUALITY BASELINE SIDECAR IS OPENED, and the whole of its CWE-59/CWE-367 story. // // `path` is a fixed name inside a crawled repository and the write TRUNCATES, so a link planted at it turns // the tool's own write into an arbitrary-file overwrite. The refusal is the OPEN itself — O_NOFOLLOW, one // syscall, nothing between deciding and creating for a replacement to land in. The first fix asked lstat and // then opened anyway, which is check-then-open; see src/pathguard.h. // // It is a named seam rather than four lines inside writeBaseline for a reason a reviewer should be able to // check: acquiring a safe descriptor and serializing a snapshot are two jobs, and the security-relevant one // should be readable without scrolling through ten record loops. The two alerts are the two failure kinds // this site has always had, unchanged, and they stay macros HERE so each keeps its own file/line. inline int openBaselineSidecar( const std::string& path ) { auto [ fd, openErr ] = rw::pathguard::openNoFollowTruncate( "the quality baseline sidecar", path ); if( fd < 0 ) { if( openErr == ELOOP ) { DISCLOSE( Diagnostics::answerRefused, "the baseline write fails on every surface: pathguard names the refused link, and the CLI exits non-zero", "quality: refusing to write the baseline sidecar through a symlink" ); } else { DISCLOSE( Diagnostics::answerRefused, "the baseline write fails on every surface: pathguard names the OS reason, and the CLI exits non-zero", "quality: cannot write baseline file" ); } } return fd; } // `absorbedGating` (H11, capture-audit 2026-09-04) is the number of GATING findings this tree already held // against HEAD when the pin was taken. Non-zero only under --allow-dirty — the bare form REFUSES rather // than absorb — and it is written as two records the snapshot reader skips as unknown kinds (`dirty 1`, // `absorbed N`), exactly like the `head` stamp above: the fact has to outlive the process that knew it, // because the report it changes the meaning of is every LATER --quality-delta, not this run. // A key -> hash record family of a baseline sidecar: " ", both hex, one per record (bodyq, movec). template inline void writeHexPairLines( std::ostream& f, std::string_view tag, const HexMap& m ) { for( const auto& [h, v] : m ) { f << tag << ' ' << std::hex << h << ' ' << v << std::dec << '\n'; } } // MOVES: "moves ", the key in hex and the 128 sketch bytes as 256 hex digits, one per record. inline void writeMoveSketchLines( std::ostream& f, const gtl::btree_map& m ) { static constexpr char kHex[] = "0123456789abcdef"; for( const auto& [ k, sk ] : m ) { f << "moves " << std::hex << k << std::dec << ' '; for( const std::uint8_t b : sk ) { f << kHex[ b >> 4 ] << kHex[ b & 15 ]; } f << '\n'; } } // The defect-shape records of a baseline sidecar: "defect ", both hex, one per record. inline void writeDefectSiteLines( std::ostream& f, const std::vector& sites ) { for( const DefectSiteKey& d : sites ) { f << "defect " << std::hex << d.anchor << ' ' << d.site << std::dec << '\n'; } } inline bool writeBaseline( const Snapshot& s, const std::string& path, std::string_view headSha = {}, std::size_t absorbedGating = 0 ) { const int fd = openBaselineSidecar( path ); if( fd < 0 ) { return false; } // The record stream is assembled in memory and handed to the descriptor in one write. The bytes below // are unchanged, line for line — only their destination moved off a stream that cannot say O_NOFOLLOW. std::ostringstream f; // v2 adds the Q1 kinds (loc/nest/params/api). Format is line-oriented + kind-tagged, so a v1 baseline (no // loc/nest/params/api lines) reads fine here — readBaseline skips unknown kinds and treats absent kinds as // empty; a v2 baseline read by an OLD binary likewise skips lines it doesn't know. Re-baseline after an // upgrade (a v1 baseline lacking the new lines makes every current public/large symbol a fresh "was 0" // regression by design — that is the intended re-baseline prompt, not a bug). // v3 (W1-S2): the body-hash record is `bodyq` — pathQualifiedKey keys, replacing the bare-canonId-keyed // `body` record. The TAG is renamed with the keying so the two key spaces can never mix: an old // baseline's `body` lines are skipped as unknown here (churn quietly reports nothing until the next // re-baseline — precision-first, same degrade as no-git), and an old binary skips `bodyq` symmetrically. // v4 (2026-08-25): every per-symbol key is pathQualifiedKey, not fnv1a64(baselineCanonId). readBaseline // REFUSES v3 and older rather than reading it — see there for why a silent read would be the dishonest // option here. // v5 (Q-DIAL-3, 2026-09-10): the `loc` record's VALUE changed meaning — CODE lines, not the physical span // (codeLinesInBody). The key space is untouched, so a v4 sidecar would read perfectly and be WRONG in one // direction only: its loc values are larger, every symbol reads as having SHRUNK, and the verbosity kind // silently reports nothing at all. A kind that quietly stops firing is the worst of the three outcomes, so // this is a version refusal like v4's, not a graceful skip. // v6 (2026-09-16): the `producer` record below. Its absence is not a graceful skip either: a v5 sidecar can // only have been written by a build that predates the stamp, so it is foreign to every build that reads the // record, and an OLD binary reading a v6 sidecar refuses it rather than skipping the stamp it cannot check. f << "# ripwire quality baseline v6 — regenerate with --quality-baseline; do not hand-edit\n"; // PRODUCER STAMP: the identity of the build that computed this snapshot (producerIdentity). The `dead` // records are a function of CALL RESOLUTION, which the head stamp below says nothing about, so at one HEAD // a floor pinned by one build and a working tree judged by another disagreed about which symbols had // callers: a gating dead-code row on an untouched symbol, or a real one hidden. selectBaseline honors the // sidecar only for the build this names (test/qbaselineproducercheck.sh). f << "producer " << producerIdentity() << '\n'; // STALENESS STAMP: the HEAD commit the baseline was pinned at. --quality-delta compares this to the // current HEAD and, if they differ (a baseline left by an abandoned/parallel session, or from before a // commit), IGNORES the sidecar and falls back to the git-HEAD auto-baseline instead of reporting a wall // of false regressions against a floor that no longer describes this tree. Empty in a non-git root // (then the current HEAD is empty too → they match → the deliberately-pinned baseline is honored). The // "head" record is an unknown kind to readBaseline, so it is skipped by the snapshot reader on both old // and new binaries — only readBaselineHeadSha consults it. if( !headSha.empty() ) { f << "head " << headSha << '\n'; } if( absorbedGating > 0 ) { f << "dirty 1\n"; f << "absorbed " << absorbedGating << '\n'; } for( const auto& [h, v] : s.ccxBySym ) { f << "ccx " << std::hex << h << std::dec << ' ' << v << '\n'; } for( const auto& [h, v] : s.locBySym ) { f << "loc " << std::hex << h << std::dec << ' ' << v << '\n'; } for( const auto& [h, v] : s.nestBySym ) { f << "nest " << std::hex << h << std::dec << ' ' << v << '\n'; } for( const auto& [h, v] : s.paramsBySym ) { f << "params " << std::hex << h << std::dec << ' ' << v << '\n'; } for( const auto& [h, v] : s.maskBySym ) { f << "mask " << std::hex << h << std::dec << ' ' << v << '\n'; // §D#4 error-masking count } for( const auto& [h, v] : s.maskReportBySym ) { f << "maskr " << std::hex << h << std::dec << ' ' << v << '\n'; // the report-only part of that count } for( const auto& [h, v] : s.failureDefaultBySym ) { f << "maskfd " << std::hex << h << std::dec << ' ' << v << '\n'; // the failure-default part of it } for( const auto& [h, v] : s.placeholderBySym ) { f << "stub " << std::hex << h << std::dec << ' ' << v << '\n'; // the placeholder count } for( const auto& [h, v] : s.defsBySym ) { f << "defs " << std::hex << h << std::dec << ' ' << v << '\n'; // overload-set CARDINALITY (a count, not a max) } writeHexPairLines( f, "bodyq", s.bodyHashBySym ); // §D#4 short-horizon-churn raw-body hash, pathQualifiedKey-keyed writeHexPairLines( f, "movec", s.moveCidBySym ); // MOVED-BODY: the move identity of a body over a bar writeHexPairLines( f, "bodyc", s.bodyCidBySym ); // QD-RENAME-IDENTITY: the same identity for every callable writeMoveSketchLines( f, s.moveSketchBySym ); // MOVES: the clone sketch of that body for( std::uint64_t h : s.cloneGroups ) { f << "clone " << std::hex << h << std::dec << '\n'; } for( std::uint64_t h : s.dead ) { f << "dead " << std::hex << h << std::dec << '\n'; } for( std::uint64_t h : s.publicApi ) { f << "api " << std::hex << h << std::dec << '\n'; } writeDefectSiteLines( f, s.defectSites ); // Was an unconditional `return true`: a stream that failed to flush still reported a written baseline. // The descriptor answers for the bytes, so a full disk is now a failure the caller can report. return rw::pathguard::writeAllAndClose( fd, f.str() ); } // Returns true only when `path` is a file that actually LOOKS like a baseline. r27 SUSPICION-A, second half: // this used to return true for a 0-byte (or wholly unrecognizable) file purely because the ifstream opened — // so a truncated sidecar, a failed write, or an `: > .ripwire_quality_baseline` left behind by a script became // "a valid baseline in which nothing existed". Combined with the empty-baseline oracle fix in computeDelta, // that would classify EVERY finding new-symbol and gate nothing, silently. A file that yields no comment // header, no `head` stamp and no record line is not an empty baseline — it is a broken one; report it absent // (alerting), and the caller falls back to the git-HEAD auto-baseline, which is the correct floor. // // THE VERSION REFUSAL (2026-08-25, the scope-less fold round). Every other unknown record in this format is // skipped gracefully so forward/backward versions never crash, and for a KEY-SPACE change that posture would // be actively wrong. A v3 sidecar's per-symbol keys are `fnv1a64(baselineCanonId)` while this binary computes // pathQualifiedKey (see qualityKey), so reading one yields a baseline in which no current symbol exists: every // function in the tree reports as brand-new debt, with nothing to indicate anything went wrong. Refusing is // the honest degrade — an unrecognizable baseline makes the caller fall back to git HEAD, and that fallback is // already named on every report through `baseline=`. The sidecar is generated and gitignored, so the whole // cost of refusing is one `--quality-baseline` re-pin. // // v6 moved the accepted version for the producer stamp (see writeBaseline), and the refusal carries it: a v5 // sidecar has no stamp to check, and the build that wrote it cannot be this one. inline bool baselineHeaderIsForeign( const std::string& line ) noexcept { return line.rfind( "# ripwire quality baseline v", 0 ) == 0 && line.find( " v6 " ) == std::string::npos; } // 2026-09-06 stranger audit: the sidecar readers dropped what they could not parse with no trace a Release // binary keeps. These files are COMMITTED and MERGED, so a bad line is ordinary; what the reader did about it // has to reach the document (baseline_bad_lines=, acks_bad_lines=) and the marker has to distinguish "no // sidecar" from "a sidecar I could not read". struct BaselineReadStats { bool present = false; // the file opened bool symlinkRefused = false; // a SYMLINK sits at the name: refused unopened (pathguard.h round 3), so `present` stays false bool unrecognizable = false; // opened, but no line of the format's structure in it bool olderFormat = false; // opened, and its header names another format version: refused unread bool preQ1 = false; // structure, but no per-symbol loc records: origin cannot be classified std::size_t badLines = 0; // lines of a known kind whose payload did not parse — skipped std::string producer; // the `producer` record: 64 lowercase hex, or "" when absent or malformed // The DISCLOSE sink for the read's degrades: each sets the field selectBaseline turns into the root's baseline= // marker or baseline_bad_lines=, so a refused, empty or partly unparsed sidecar is never read as a clean one. enum class DisclosureWhy : std::uint8_t { SymlinkRefused, // a link at the name, refused unopened MalformedLine, // a known record kind whose payload did not parse (skipped) Unrecognizable, // opened, but no line of the format's structure }; void disclose( DisclosureWhy why ) noexcept { switch( why ) { case DisclosureWhy::SymlinkRefused: symlinkRefused = true; break; case DisclosureWhy::MalformedLine: ++badLines; break; case DisclosureWhy::Unrecognizable: unrecognizable = true; break; } } }; // The v6 `producer` record's payload, into `stats.producer` when it is identity-shaped (64 lowercase hex). Only the // SHAPE is judged here — whether it names THIS build is selectBaseline's question. The file is committed DATA, so a // payload of any other shape is a bad line and leaves `producer` empty, which no build's identity equals; the first // well-formed record wins, as the head stamp's does. inline void readProducerRecord( std::istream& is, BaselineReadStats& stats ) { std::string value; is >> value; const auto isLowerHexDigit = []( char c ) { return ( c >= '0' && c <= '9' ) || ( c >= 'a' && c <= 'f' ); }; if( value.size() != 64 || !std::all_of( value.begin(), value.end(), isLowerHexDigit ) ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine, "quality: malformed baseline producer line skipped" ); return; } if( stats.producer.empty() ) { stats.producer = std::move( value ); } } // THE ONE PLACE THE BASELINE SIDECAR IS READ — shared by readBaseline, readBaselineHeadSha and // readBaselineAbsorbed, and openBaselineSidecar's other half with the same answer to a link: O_NOFOLLOW, refused // in the open itself. A link here used to be followed on the way in, so the link chose which file was honored as // the floor. Why an in-tree link is refused too is round 3 of src/pathguard.h. inline rw::pathguard::NoFollowRead readBaselineSidecar( const std::string& path, BaselineReadStats& stats ) { rw::pathguard::NoFollowRead sidecar = rw::pathguard::openNoFollowRead( "the quality baseline sidecar", path ); if( sidecar.refused ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::SymlinkRefused, "quality: refusing to read the baseline sidecar through a symlink" ); } return sidecar; } // MOVES: one "moves <256 hex digits>" record (writeMoveSketchLines). A malformed line degrades and is skipped, like every record. inline void readMoveSketchLine( std::istream& is, gtl::btree_map& m, BaselineReadStats& stats ) { std::uint64_t key = 0; std::string hex; is >> std::hex >> key >> std::dec >> hex; const auto nib = []( char c ) -> int { return c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : -1; }; CloneSketch sk{}; if( !VALIDATE( !is.fail(), "a moves record reads a hex key and a sketch" ) || !VALIDATE( hex.size() == 2 * sk.size(), "a moves record's sketch is 256 hex digits" ) ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); return; } for( std::size_t j = 0; j < sk.size(); ++j ) { const int hi = nib( hex[ 2 * j ] ), lo = nib( hex[ 2 * j + 1 ] ); if( !VALIDATE( hi >= 0 && lo >= 0, "a moves record's sketch is lowercase hex digits" ) ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); return; } sk[j] = std::uint8_t( ( hi << 4 ) | lo ); // both digits checked first: a bad one never builds a byte } m[ key ] = sk; } inline bool readBaseline( const std::string& path, Snapshot& out, BaselineReadStats& stats ) { stats = BaselineReadStats{}; // "no sidecar" and "a sidecar refused unopened" are different answers: the seam's sink records the refusal rw::pathguard::NoFollowRead sidecar = readBaselineSidecar( path, stats ); if( !sidecar.opened ) { return false; } stats.present = true; std::size_t recognizedLineCount = 0; std::string line; while( sidecar.readLine( line ) ) { if( line.empty() ) { continue; } if( baselineHeaderIsForeign( line ) ) // pre-pathQualifiedKey sidecar — refused, see above { // The refusal is a USER-FACING disclosure, so it must survive NDEBUG: behind only a // DISCLOSE a Release binary refuses SILENTLY and the caller reads "no baseline // found" — a refusal that hides its reason misleads exactly like the misread it prevents. rw::emitRaw( stderr, "ripwire: quality: baseline sidecar predates this binary's baseline format — refused, re-pin with --quality-baseline\n" ); // ...and the caller's marker has to say a sidecar is THERE. Without this flag the refusal read as // Absent, so the CLI reported baseline="git-HEAD" ("no sidecar existed") and printed "no " // one line under the refusal that named it. Since v6 every pre-stamp sidecar lands here. stats.olderFormat = true; out = Snapshot{}; return false; } if( line[0] == '#' ) { ++recognizedLineCount; continue; } // the format's own header comment counts as structure std::istringstream is( line ); std::string kind; is >> kind; // per-symbol MAX metrics: " ". A malformed line degrades + skips (never the // silent hash-0 insert). An UNKNOWN kind (e.g. a future record read by this binary) is skipped // gracefully so forward/backward baseline versions never crash. const auto readValMap = [ & ]( gtl::btree_map& m ) { std::uint64_t h = 0; std::uint32_t v = 0; is >> std::hex >> h >> std::dec >> v; if( is.fail() ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); return; } m[h] = v; }; const auto readSet = [ & ]( std::vector& v ) { std::uint64_t h = 0; is >> std::hex >> h; if( is.fail() ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); return; } v.push_back( h ); }; // " " — both 64-bit hex (the raw-body-hash map). Malformed → degrade + skip. const auto readHashMap = [ & ]( gtl::btree_map& m ) { std::uint64_t h = 0, v = 0; is >> std::hex >> h >> v; if( is.fail() ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); return; } m[h] = v; }; if( kind == "ccx" || kind == "loc" || kind == "nest" || kind == "params" || kind == "mask" || kind == "maskr" || kind == "maskfd" || kind == "stub" || kind == "body" || kind == "clone" || kind == "dead" || kind == "api" || kind == "head" || kind == "defs" || kind == "producer" || kind == "defect" ) { ++recognizedLineCount; // structure seen — this file IS a baseline } if( kind == "ccx" ) { readValMap( out.ccxBySym ); } else if( kind == "loc" ) { readValMap( out.locBySym ); } else if( kind == "nest" ) { readValMap( out.nestBySym ); } else if( kind == "params" ) { readValMap( out.paramsBySym ); } else if( kind == "mask" ) { readValMap( out.maskBySym ); } else if( kind == "maskr" ) { readValMap( out.maskReportBySym ); } else if( kind == "maskfd" ) { readValMap( out.failureDefaultBySym ); } else if( kind == "stub" ) { readValMap( out.placeholderBySym ); } else if( kind == "defs" ) { readValMap( out.defsBySym ); } else if( kind == "bodyq" ) // v3 tag — a v2 `body` line is bare-canonId-keyed (a different key space) and falls through to the unknown-kind skip { readHashMap( out.bodyHashBySym ); } else if( kind == "movec" ) // MOVED-BODY; a sidecar written before it has none, and then no move is recognized { readHashMap( out.moveCidBySym ); } else if( kind == "bodyc" ) // QD-RENAME-IDENTITY; a sidecar written before it has none, and then no rename or move is matched by body { readHashMap( out.bodyCidBySym ); } else if( kind == "moves" ) // MOVES; a sidecar written before it has none, and then only exact moves are recognized { readMoveSketchLine( is, out.moveSketchBySym, stats ); } else if( kind == "clone" ) { readSet( out.cloneGroups ); } else if( kind == "dead" ) { readSet( out.dead ); } else if( kind == "api" ) { readSet( out.publicApi ); } else if( kind == "defect" ) { DefectSiteKey d; is >> std::hex >> d.anchor >> d.site >> std::dec; if( is.fail() ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::MalformedLine ); } else { out.defectSites.push_back( d ); } } else if( kind == "producer" ) { readProducerRecord( is, stats ); } // else: unknown kind (older/newer format) → skip silently, do not crash. } if( recognizedLineCount == 0 ) { DISCLOSE( stats, BaselineReadStats::DisclosureWhy::Unrecognizable, "quality: baseline file is empty/unrecognizable — treating it as absent" ); out = Snapshot{}; return false; } // A pre-Q1 sidecar has per-symbol records but no `loc` rows, so no finding's ORIGIN can be classified // (computeDelta would gate every one and name phantom findings). Refuse it the way the foreign-header // sidecar above is refused: loudly, with the re-pin, instead of comparing against a floor it cannot read. const bool whollyEmpty = out.locBySym.empty() && out.ccxBySym.empty() && out.nestBySym.empty() && out.paramsBySym.empty() && out.maskBySym.empty() && out.placeholderBySym.empty() && out.bodyHashBySym.empty() && out.cloneGroups.empty() && out.dead.empty() && out.publicApi.empty(); if( out.locBySym.empty() && !whollyEmpty ) { stats.preQ1 = true; out = Snapshot{}; return false; } std::sort( out.cloneGroups.begin(), out.cloneGroups.end() ); std::sort( out.dead.begin(), out.dead.end() ); std::sort( out.publicApi.begin(), out.publicApi.end() ); std::sort( out.defectSites.begin(), out.defectSites.end() ); return true; } // The HEAD sha a baseline was pinned at (the "head " record written by writeBaseline), or "" if the // file is absent, predates the staleness stamp, or does not carry a bare object name. // // r27 TRUST BOUNDARY (Lane C routing). This value came out of `.ripwire_quality_baseline`, which is a // COMMITTED file — so on a cloned repo its contents are attacker-influenceable — and it used to flow VERBATIM // into `gitIsAncestor`'s `git merge-base --is-ancestor '' …` argv (the old stale-sidecar self-heal; the // R3 ruling below removed that reachability hop, so today the value only ever reaches a STRING COMPARE against // `gitHeadSha` inside `selectBaseline` — no argv at all). `shSingleQuote` blocked the shell but not git's own // option parsing, which is precisely the shape of the P0.1 `--pr-context=--output=FILE` data-loss defect. Only // `merge-base`'s lack of a file-writing option kept this one benign. The shape check stays regardless: a // pinned sha is 40/64 hex or it is not a pinned sha, anything else is dropped here, and the empty result // routes into the documented "unstamped pin is stale" path — i.e. a tampered sidecar is DISTRUSTED, never // obeyed. `writeBaseline` only ever writes `gitHeadSha`'s output, so no legitimate sidecar is affected. inline std::string readBaselineHeadSha( const std::string& path ) { BaselineReadStats unread; // no channel here: readBaseline's own read records the refusal the report prints rw::pathguard::NoFollowRead sidecar = readBaselineSidecar( path, unread ); if( !sidecar.opened ) { return {}; } std::string line; while( sidecar.readLine( line ) ) { if( line.rfind( "head ", 0 ) == 0 ) { std::string sha = line.substr( 5 ); while( !sha.empty() && ( sha.back() == '\r' || sha.back() == ' ' || sha.back() == '\t' ) ) { sha.pop_back(); } if( isBareCommitSha( sha ) ) { return sha; } DISCLOSE( "quality: baseline head stamp is not a bare commit sha — ignoring the pin" ); return {}; } } return {}; } // H11 — the absorbed-debt stamp a --allow-dirty pin left behind, or 0 (absent, unstamped, or malformed). // Same posture as readBaselineHeadSha above and for the same reason: the sidecar is a COMMITTED file, so a // value read out of it is DATA, never trusted structure — anything that is not a plain positive decimal is // dropped to 0, which routes into the "no absorbed stamp" story rather than into a fabricated count. The // `dirty 1` companion record is deliberately NOT consulted: one fact, one reader, and `absorbed N` is the // one the report has something to say about. inline std::size_t readBaselineAbsorbed( const std::string& path ) { BaselineReadStats unread; // no channel here: readBaseline's own read records the refusal the report prints rw::pathguard::NoFollowRead sidecar = readBaselineSidecar( path, unread ); if( !sidecar.opened ) { return 0; } std::string line; while( sidecar.readLine( line ) ) { if( line.rfind( "absorbed ", 0 ) != 0 ) { continue; } std::size_t n = 0; bool anyDigit = false; for( const char c : std::string_view( line ).substr( 9 ) ) { if( c == '\r' || c == ' ' || c == '\t' ) { break; } if( c < '0' || c > '9' || n > 100000000u ) { return 0; // not a plain count — distrust it, exactly as a non-sha head stamp is distrusted } n = n * 10 + std::size_t( c - '0' ); anyDigit = true; } return anyDigit ? n : 0; } return 0; } // ─── R3 (owner ruling, 2026-07-29) — the ONE baseline-selection seam, shared by BOTH arms ─────────────── // // `--quality-delta` (main.cpp) and the `quality_delta` MCP verb (mcpverbs.h) each used to decide for // themselves whether a `.ripwire_quality_baseline` sidecar still describes this tree, and they DISAGREED: // • MCP: any pinned sha != current HEAD sha ⇒ STALE (drop it, auto-baseline vs git HEAD). // • CLI: stale ONLY when the pinned sha was also UNREACHABLE from HEAD (`gitIsAncestor` false) — the // B10.1b "reachable ancestor = a deliberately-pinned floor" carve-out. // The incident that ended the argument: a PARALLEL session's sidecar, pinned at a commit that happened to be // an ancestor of this session's HEAD, made the CLI report 31 phantom regressions on a tree the MCP verb (same // binary, same repo, same second) correctly reported as clean. A floor pinned at some OTHER commit describes // some OTHER tree; everything committed since then reads as a working-tree regression. The carve-out is // REVOKED — STRICT sha equality is the rule on both arms, and it lives HERE so there is exactly one copy. // // What stays per-arm is POLICY, expressed by `removeStaleFile`, not the staleness test: // • CLI passes true → the stale sidecar is silently UNLINKED (self-heal: the next run sees no file at all // rather than rediscovering the same dead pin), marker "git-HEAD (stale sidecar removed)" — but ONLY when // the unlink actually landed; a FAILED unlink reports "…ignored" like the read-only arm (see below). // • MCP passes false → read-only verb, the file is left alone, marker "git-HEAD (stale sidecar ignored)". // Both cases are recorded ONLY in the `baseline=`/`"baseline"` marker — no stderr spam, which is the B10.1b // noise fix that survives the ruling intact. // // NON-GIT ROOTS: `gitHeadSha` returns "" and an unstamped sidecar's pin reads "", so ""=="" and the sidecar is // honored — the only floor such a tree can have (there is no HEAD to fall back to) — provided THIS build pinned it. // // THE PRODUCER RULE (v6, 2026-09-16) — the head stamp's twin, for the other thing a floor depends on. A sidecar's // `dead` records are a function of CALL RESOLUTION, so at one HEAD a floor pinned by one build and a working tree // judged by another disagreed about which symbols had callers. Measured with two real builds (the std::-qualified // call guard on and off) over one fixture: a gating dead-code row on an untouched symbol (exit 2 where the same // build reports 0), and in the other direction a real gating regression hidden (exit 0 where the same build // reports 2). The qsnap cache had the same defect (producerIdentity); this is the file a user writes on purpose. // So the sidecar is honored only when its `producer` record equals this build's identity, and one that does not // is FOREIGN. Its policy differs from Stale's on purpose: a stale pin can never describe this HEAD again, while // a foreign one is still the right floor for the build that wrote it (a PATH binary and ./build/ripwire in turn), // so NEITHER arm deletes it. Demoting the dead-code rows instead of falling back was weighed and rejected: it // cannot un-hide a regression whose row never appears, and a different build can compute any kind differently. enum class BaselineSource : std::uint8_t { Sidecar = 0, // a readable sidecar pinned at the CURRENT HEAD sha (or a non-git root) by THIS build — honored as the floor Stale = 1, // a readable sidecar pinned at ANY other sha — dropped (R3); the caller falls back to git HEAD Absent = 2, // no readable sidecar (missing, or empty/unrecognizable per readBaseline) — caller falls back Foreign = 3, // a readable sidecar pinned at the CURRENT HEAD by ANOTHER build (or unstamped) — ignored, never removed; caller falls back }; // The seam's answer. `snapshot` carries the pinned floor and is EMPTY unless `source == Sidecar`; `marker` is // the `baseline=` value both arms report verbatim (one spelling table, so the two surfaces cannot drift again). // // `staleFileRemoved` closes the w1 MED finding: it reports what happened ON DISK, not what the caller asked // for, so a caller can word its own messages truthfully. It is true only when a stale sidecar is genuinely // gone after this call — never on the read-only (`removeStaleFile=false`) arm, whose stale file always // survives, and never when the unlink failed. struct BaselineSelection { Snapshot snapshot; // the pinned floor — meaningful only when isSidecarHonored() BaselineSource source = BaselineSource::Absent; const char* marker = "git-HEAD"; // static storage; safe to hold as a bare pointer bool staleFileRemoved = false; // Stale only: the unlink LANDED (file gone from disk) bool sidecarUnreadable = false; // a sidecar EXISTS but could not be read (unrecognizable or pre-Q1): ignored, named bool sidecarSymlinkRefused = false; // a SYMLINK sits at the name and was refused unopened (pathguard.h round 3): ignored, named std::size_t sidecarBadLines = 0; // honored sidecar: lines skipped as unparseable bool isSidecarHonored() const noexcept { return source == BaselineSource::Sidecar; } bool isSidecarStale() const noexcept { return source == BaselineSource::Stale; } bool isSidecarForeign() const noexcept { return source == BaselineSource::Foreign; } // "the stale pin is STILL sitting there" — true on the read-only arm, and on the CLI arm when the unlink // failed. This is the predicate a caller's user-facing wording must branch on (never `removeStaleFile`). bool isStaleFileOnDisk() const noexcept { return source == BaselineSource::Stale && !staleFileRemoved; } }; // A readable sidecar pinned at the CURRENT HEAD: the floor for the build that pinned it, FOREIGN to every other (the // producer rule — see BaselineSource). Asked only once the head matches, because a pin at another sha is stale for // EVERY build, and the stale verdict and its self-heal take precedence. A foreign pin is never unlinked, on either arm. inline BaselineSelection selectPinnedAtHead( BaselineSelection sel, std::string_view producer ) { if( producer == producerIdentity() ) { sel.source = BaselineSource::Sidecar; sel.marker = "sidecar"; return sel; } sel.snapshot = Snapshot{}; sel.source = BaselineSource::Foreign; sel.marker = "git-HEAD (foreign sidecar ignored)"; return sel; } // Read `sidecarPath` and decide whether it is still a valid floor for `root`'s CURRENT HEAD. `removeStaleFile` // = the CLI's self-heal policy: a best-effort unlink of a stale sidecar. The unlink can FAIL (read-only parent // dir, permissions, a racing sibling run) and the marker then tells the truth about the DISK rather than the // intent — "git-HEAD (stale sidecar ignored)", the same honest string the read-only arm uses, because // ignored-not-removed is exactly what happened — plus one DISCLOSE so the plain build can observe // the degrade. `staleFileRemoved` carries the same fact to the caller, which needs it to word its own fatal // message (a "no " message is false while the file is still on disk). `sidecarPath` must already be // ROOT-QUALIFIED by the caller (baselinePath) — this function can DELETE it, and a bare relative name would // resolve against the process CWD (D1). inline BaselineSelection selectBaseline( const std::string& root, const std::string& sidecarPath, bool removeStaleFile ) { ASSUME( !sidecarPath.empty() ); BaselineSelection sel; BaselineReadStats readStats; if( !readBaseline( sidecarPath, sel.snapshot, readStats ) ) { sel.snapshot = Snapshot{}; // readBaseline already clears on the unrecognizable path; belt and braces sel.source = BaselineSource::Absent; sel.marker = "git-HEAD"; if( readStats.symlinkRefused ) { // Round 3 (pathguard.h): a link at the name is refused on read as on write. Never "no sidecar existed" // (the git-HEAD marker) about an entry that is right there, and never "unreadable" about bytes that // were deliberately not opened. sel.sidecarSymlinkRefused = true; sel.marker = "git-HEAD (symlinked sidecar refused)"; } else if( readStats.present && ( readStats.unrecognizable || readStats.olderFormat || readStats.preQ1 ) ) { sel.sidecarUnreadable = true; // 2026-09-06: never "no sidecar existed" about a file that is right there sel.marker = "git-HEAD (sidecar unreadable)"; } return sel; } sel.sidecarBadLines = readStats.badLines; // R3: STRICT equality, no reachability hop. Note the ordering — gitHeadSha's ~15 ms popen is paid only // when a sidecar actually exists, exactly as before. const std::string pinnedSha = readBaselineHeadSha( sidecarPath ); const std::string headSha = gitHeadSha( root ); if( pinnedSha == headSha ) { return selectPinnedAtHead( std::move( sel ), readStats.producer ); } // Stale. The DEFAULT marker is the read-only truth ("ignored") and the self-heal upgrades it to "removed" // only after the unlink is confirmed — so the marker can never claim a removal that did not happen. sel.snapshot = Snapshot{}; sel.source = BaselineSource::Stale; sel.marker = "git-HEAD (stale sidecar ignored)"; if( removeStaleFile ) { // best-effort unlink; ROOT-qualified, never a foreign cwd's sidecar. remove() answers true when IT // unlinked the file; false with a CLEAR error_code means the path was already gone (a racing sibling // run self-healed it first — also "removed" as far as the disk is concerned); false with a SET // error_code (read-only parent dir, EACCES, EPERM) means the file SURVIVED this call. The ec is read, // not swallowed — the whole point of the finding is that an unread ec let the marker lie. std::error_code delEc; const bool didUnlink = std::filesystem::remove( std::filesystem::path( sidecarPath ), delEc ); const bool isStillHere = !didUnlink && static_cast( delEc ); if( !isStillHere ) { sel.staleFileRemoved = true; sel.marker = "git-HEAD (stale sidecar removed)"; } // §B12.11: "the baseline still falls back to git HEAD" is only true when this tree HAS a git HEAD — // a sidecar can be Stale (pinned at a real, non-empty sha) on a tree where `headSha` is now "" (no // git HEAD: not a repo, or git unavailable), and the unqualified claim is then false in the exact // state it fires in. The caller's own fatal already gets this right (mcpverbs.h's "no // .ripwire_quality_baseline and no git HEAD to auto-compare against"), so no consumer is misled // today — but the alert itself should not assert a fallback that does not exist. else if( headSha.empty() ) { DISCLOSE( Diagnostics::answerRefused, "with no git HEAD either, the run refuses and names the sidecar that stayed on disk", "quality: could not unlink the stale .ripwire_quality_baseline sidecar — it STAYS on disk and is merely IGNORED this run; this tree has no git HEAD to fall back to either, so this run has no baseline floor at all" ); } else { DISCLOSE( Diagnostics::answerUnchanged, "the stale sidecar is ignored either way and the baseline is git HEAD; the marker says ignored, not removed", "quality: could not unlink the stale .ripwire_quality_baseline sidecar — it STAYS on disk and is merely IGNORED this run; the baseline still falls back to git HEAD" ); } } return sel; } // ─── B10.2d — short-horizon-churn SELF vs AMBIENT split ──────────────────────────────────────────────── // // The three existing gates (file churn-hot / this diff rewrites the symbol / committed thrash evidence) // establish that a symbol IS short-horizon churn. This pass answers a NARROWER question about the CURRENT // uncommitted edit specifically: how many COMMITTED commits inside the churn window last wrote the // pre-existing lines this edit modifies. One or more ⇒ the edit touches hot content, facet churn="self"; none // (the edit only ADDS lines, or touches lines that predate the window) ⇒ churn="ambient". // // Q-DIAL-1 (2026-09-10) — SEVERITY no longer follows that facet. BOTH facets are informational; what GATES is // the count reaching kShortHorizonMinCommits, i.e. "rewritten by >= 2 COMMITTED commits inside the window, the // working edit not counted". SELF-gates was measured at 0% precision over twelve landed commits (135 of 171 // gating rows, audit Q1 §2b/§2d) for a structural reason: on an active branch every symbol you wrote this week // and are touching again modifies a line you yourself committed inside the window. // // Mechanism: `git diff --unified=0 HEAD -- path` gives zero-context unified-diff hunks // ("@@ -oldStart[,oldCount] +newStart[,newCount] @@"; git omits a count of 1). A hunk with oldCount==0 is a // PURE INSERTION — no old line touched, can never itself prove SELF ("the diff only ADDS lines", verbatim). // For an oldCount>0 hunk whose NEW-side range overlaps the symbol's CURRENT [line, line+loc-1] span (from the // working-tree ingest — the only line numbers ripwire has), `git blame --porcelain HEAD -L // oldStart,+oldCount -- path` reports each touched OLD line's real last-commit committer-time; ANY such time // inside the window ⇒ SELF. No external diff/blame library — parsed by hand (sscanf against the two // count-optional header forms), consistent with the rest of this file's popen-based git mining. // // Degrade-only, in every direction: an unparseable hunk header is skipped (that hunk contributes nothing); // a failed diff/blame subprocess (no git, no HEAD, path absent at HEAD) yields no output, so the loop simply // never sets `hot` → AMBIENT, the safe default that never inflates severity on missing evidence. Deterministic // for a fixed HEAD + fixed working tree (both diff and blame are pure functions of on-disk/committed state). // ── the AMBIENT-CONFIG SEAM, and why every git invocation here pins it ───────────────────────────────── // `git blame` does NOT read only on-disk/committed state: it also reads the repository's own config, and // `blame.ignoreRevsFile` there rewrites which commit a line is attributed to — and therefore which // committer-time this function compares against the window. Repo-local git config is never cloned, so a // developer who ran this repo's own one-time `git config blame.ignoreRevsFile .git-blame-ignore-revs` // measured a DIFFERENT churn facet than a fresh checkout of the same shas: CI, whose config is empty, read // the mechanical brace sweep 208611f8 as in-window thrash (SELF) where every configured worktree read // through it to the older real author (AMBIENT). That is one gating row of drift on ripwire's own history // (2026-08-15 wave: 19 rows on CI, 18 everywhere a developer looked), and it made the paragraph above // FALSE as written. The fix is to stop inheriting: the ignore list is pinned to TRACKED state — the // conventionally-named `.git-blame-ignore-revs` at the judged root when it exists, and explicitly EMPTY // when it does not, so ambient config can never reach the measurement in either direction. Content the // tree itself carries is exactly the "committed state" the purity claim means; a developer's config is not. // An unresolvable sha inside the file is git's problem and it degrades to a warning, not a failed blame. inline std::string gitBlameConfigPins( const std::string& root ) { std::error_code ec; const std::string ignoreRevs = root + "/.git-blame-ignore-revs"; const bool hasFile = std::filesystem::exists( std::filesystem::path( ignoreRevs ), ec ) && !ec; return hasFile ? " -c blame.ignoreRevsFile=" + shSingleQuote( ignoreRevs ) : std::string( " -c blame.ignoreRevsFile=" ); } // Blame `root`'s HEAD over `relPath`'s [startLine, startLine+lineCount-1] and APPEND, to `outShas`, the // fnv1a64 of every DISTINCT commit that last wrote a line in that range at or after `windowCutoffEpoch` (the // same cutoff basis gitFileCommitCountsInDayWindow and gitWindowRefSha use: HEAD's own committer epoch minus // the window, never wall-clock). // // Q-DIAL-1 (2026-09-10) — this used to answer a BOOL ("is any line in this range hot"), which is the SELF vs // AMBIENT question and nothing more. The churn kind's GATING question is narrower and needs a count: was this // symbol rewritten by >= kShortHorizonMinCommits COMMITTED commits inside the window, not counting the working // edit? One in-window commit is a single touch — the branch you are on — and gating on it made 135 of 171 // gating rows on twelve landed commits the agent's own footprint (audit Q1 §2b/§2d). Blame runs on HEAD, so // the uncommitted edit is excluded BY CONSTRUCTION rather than by subtraction. // // The accumulator is a caller-owned vector rather than a return value because one symbol spans several diff // hunks and a commit that wrote lines in two of them must count ONCE; the caller sorts + uniques the union. // Ordering: blame output order, which is deterministic for a fixed HEAD + path, and the caller's sort makes // the count order-independent anyway. NO short-circuit any more (the bool arm could stop at the first hot // line): the whole range is read, which costs the rest of ONE already-spawned blame and no extra subprocess. // // PORCELAIN SHAPE, and why the sha is tracked separately from the time: `git blame --porcelain` prints a // commit's metadata (committer-time among it) only the FIRST time that commit appears; later lines from the // same commit carry the bare " " header alone. So the header line sets the CURRENT // sha and the committer-time line decides whether that sha counts — a repeat header with no metadata needs no // second decision, because the sha is already in (or already out of) the set. // // hwh-fix4 (N1): returns false when git did not answer (spawn failed, or blame exited non-zero: on a partial clone an absent // intermediate blob fails it in about a second). A failed blame is not "no window commit": the caller says unknown. inline bool gitBlameRangeWindowCommits( const std::string& root, const std::string& relPath, std::uint32_t startLine, std::uint32_t lineCount, std::int64_t windowCutoffEpoch, std::vector& outShas ) { if( startLine == 0 || lineCount == 0 ) { return true; } const std::string cmd = gitCmd( " -c core.quotepath=false" ) + gitBlameConfigPins( root ) + " -C " + shSingleQuote( root ) + " blame --no-ext-diff --no-textconv --porcelain -L " + std::to_string( startLine ) + ",+" + std::to_string( lineCount ) + " HEAD -- " + shSingleQuote( relPath ) + " 2>/dev/null"; std::FILE* pipe = os::popen( cmd.c_str(), "r" ); if( !pipe ) { return false; } const std::size_t shasBefore = outShas.size(); std::uint64_t curSha = 0; char buf[ 512 ]; while( std::fgets( buf, sizeof( buf ), pipe ) ) { std::string_view ln( buf ); while( !ln.empty() && ( ln.back() == '\n' || ln.back() == '\r' ) ) { ln.remove_suffix( 1 ); } // a porcelain block-header line: 40 lowercase-hex sha, then " [ ]". const bool isHeaderSha = ln.size() >= 40 && std::all_of( ln.begin(), ln.begin() + 40, []( char c ){ return std::isxdigit( static_cast( c ) ); } ) && ( ln.size() == 40 || ln[40] == ' ' ); if( isHeaderSha ) { curSha = fnv1a64( ln.substr( 0, 40 ) ); // the sha itself carries no date — wait for its committer-time line continue; } if( ln.rfind( "committer-time ", 0 ) == 0 ) { const std::int64_t t = std::strtoll( std::string( ln.substr( 15 ) ).c_str(), nullptr, 10 ); if( t >= windowCutoffEpoch && curSha != 0 ) { outShas.push_back( curSha ); } } } if( os::pclose( pipe ) != 0 ) { outShas.resize( shasBefore ); // a failed blame's partial output is not evidence either way return false; } return true; } // DiffHunk / DiffHunkMemo / gitDiffHunksVsHead / diffHunksMemoized / parseHunkHeaderLine — MOVED to // diffhunks.h (2026-09-27) when --situ grew the symbol-granular change set and needed the same primitive: // one hunk parser, both consumers (this churn lens and situ.h's change-set narrowing), zero clones. The // types and both per-path accessors are unchanged; churnEditWindowCommitCount below consumes them as before. // HOW MANY DISTINCT in-window COMMITS last wrote the pre-existing lines that the CURRENT uncommitted edit to // `relPath` (vs HEAD) modifies inside the symbol's [symStart, symStart+symLoc-1] span. See the section comment // above for the full mechanism. `symStart`/`symLoc` come straight from the working-tree Symbol (s.line / // s.loc). `memo` is the caller-owned per-run hunk cache (P3). // // Q-DIAL-1: the two facts the churn kind reads off this ONE number, so they cannot drift apart — // >= 1 the edit touches hot content at all → churn="self" (informational; it was the GATING rule until // 2026-09-10, and it is the agent's own edit window on any active branch); // >= kShortHorizonMinCommits the lines were rewritten by that many COMMITTED commits inside the window, // the working edit excluded (blame is on HEAD) → this is the rewrite-thrash the kind exists to name, // and the only form of it that gates. // 0 (no hunk) stays AMBIENT. hwh-fix4 (N1): a hunk diff or a blame git refused sets `unreadOut` — the count is then not known // (it may be short of the truth), and the caller reports churn="unknown", never ambient: a failed read is not "no window commit". inline std::uint32_t churnEditWindowCommitCount( DiffHunkMemo& memo, const std::string& root, const std::string& relPath, std::uint32_t symStart, std::uint32_t symLoc, std::int64_t windowCutoffEpoch, bool& unreadOut ) { unreadOut = false; if( symStart == 0 ) { return 0; } std::vector shas; const std::uint32_t symEnd = symStart + ( symLoc > 0 ? symLoc - 1 : 0 ); const DiffHunkRead& read = diffHunksMemoized( memo, root, relPath ); if( !read.ok ) { unreadOut = true; return 0; } for( const DiffHunk& h : read.hunks ) { if( h.oldCount == 0 ) { continue; // pure insertion — never SELF by itself ("adds lines") } // Overlap test in NEW-file (working-tree) coordinates, matching the symbol's own line numbers. // // r27 PURE-DELETION FIX: a deletion hunk is `@@ -o,c +n,0 @@` — it has NO new-side lines, and git // reports n = the line AFTER which the deleted text sat. Computing the end as `n + newCount - 1` // collapsed that to the EMPTY range [n,n], which considers the line BEFORE the seam and never the line // AFTER it. That asymmetry has no justification in the diff format: the edit's footprint is the SEAM // between new lines n and n+1, and BOTH adjacent lines are equally "next to what was removed". Under // the old collapse a deletion at a symbol's leading edge (n = symStart-1) fell entirely before the // symbol, was never blamed, and the row silently downgraded from churn="self" (major, GATES) to // churn="ambient" (sev=minor, does not gate) — a gating finding lost to an off-by-one. // HONESTY, measured (r27): the asymmetry is real, but no fixture was found in which fixing it flips an // emitted row — the churn kind's gate 2 requires the symbol's own raw body to have changed, which in // practice always produces a second hunk that already overlaps. So this is a correctness fix to the // hunk math with a conservative blast radius, not a behavior change with a demonstrated before/after. // It cannot manufacture noise on its own either: SELF still requires `git blame` to prove the deleted // lines were themselves last committed inside the churn window. const std::uint32_t hunkNewStart = h.newStart; const std::uint32_t hunkNewEnd = ( h.newCount > 0 ) ? hunkNewStart + h.newCount - 1 : hunkNewStart + 1; if( hunkNewEnd < symStart || hunkNewStart > symEnd ) { continue; // this hunk falls outside the symbol } if( !gitBlameRangeWindowCommits( root, relPath, h.oldStart, h.oldCount, windowCutoffEpoch, shas ) ) { unreadOut = true; // keep reading the other hunks: their commits still count, but the total is now a floor } } std::sort( shas.begin(), shas.end() ); shas.erase( std::unique( shas.begin(), shas.end() ), shas.end() ); // a commit spanning two hunks of one symbol counts ONCE return std::uint32_t( shas.size() ); } // one reported regression (something the change made WORSE). struct Regression { std::string kind; // "complexity" | "duplication" | "dead-code" | "verbosity" | "nesting" | "params" | "api-surface" // | "error-masking" | "short-horizon-churn" | "new-clone-of-reused-helper" (§D#4) | "placeholder" | "defect-shape" std::string sym; // canonical id (or, for duplication, the space-joined member ids) std::uint32_t was = 0; std::uint32_t now = 0; std::uint64_t key = 0; // STABLE identity for the ack ratchet: the per-symbol baselineCanonId hash, or the clone-group hash (root-spelling-independent, never display text). // short-horizon-churn rows carry pathQualifiedKey instead (W1-S2): a bare canonId folds scope-less same-named symbols across files, so one ack would suppress — and one finding would name — the WRONG file's symbol bool isMinor = false;// materiality tier: true = below the kind's minor-delta bar → reported sev="minor", does not gate exit 2 std::string facet; // B10.2 — optional classification facet (attribute NAME chosen by the kind in main.cpp): // short-horizon-churn: "self" | "ambient"; api-surface: "new-symbol" | "contract-change"; // defect-shape: "format-arity" | "utf8-cut" | "dedup-first" | "vacuous-assert". Empty = no facet. bool isNewSymbol = false;// r26 ORIGIN axis: true = the finding exists ONLY because the code is new (emitted origin="new-symbol", // counted in new-symbol=, never gates); false = preexisting-worse. See the ORIGIN block in computeDelta. bool isMoved = false;// MOVED-BODY: a new-symbol row whose body this diff REMOVED from another name or file (emitted // origin="moved" instead of origin="new-symbol"; still counted in new-symbol=; never gates). std::uint32_t ceiling = 0; // QD-ENTRY-CEILING: the new-function ceiling (newSymbolCeiling of the kind's bar) this NEW, // unmoved, non-test complexity/verbosity row reached — emitted ceiling="N", and it GATES. 0 = none. // P2.5 (r27) — the LOCATOR. `sym` is a canonical id whose display tail is often a bare, one-letter local // (`sym="cc"`), so the report the agent is told to run at every "done" moment named findings it could not // grep for. path is ROOT-RELATIVE (the same relForHash spelling every other sidecar key uses), line is the // defining symbol's 1-based start line; together they are emitted as p="path:line". For the two clone // kinds (a relation over a member SET, not one symbol) this is the member whose canonId sorts FIRST — the // same member that leads the members= list, so the two agree. Empty path = no locator available (a symbol // with no file, or a degraded lookup) → the attribute is simply omitted, never faked. std::string path; std::uint32_t line = 0; // P1 SCOPE — the two CLONE kinds only: the root-relative path of EVERY member of the group, sorted and // deduplicated. `path` above is one member (the first-sorting one), and a clone group is a relation over // the whole set, so the ownership partition needs all of them to answer "does any member live in this // scope". It cannot be recovered from `sym`: a canonId degrades to a BARE NAME for a scope-less free // function, so the members= text carries no path segment for exactly the symbols most likely to clone. // Empty for every other kind (their `path` IS the whole answer) and empty when no member resolved. std::vector memberPaths; // P0.3 (r27) — ZERO MAGNITUDE. A finding with was == now == 0 carries no magnitude at all, so the ack // ratchet's `now <= ackNow` test degenerates to `0 <= 0` = "always suppressed" — a permanent blank check, // which the ack contract explicitly promises never to be. See ackKindToken below for the fix. bool isZeroMagnitude() const noexcept { return was == 0 && now == 0; } }; // THE EXIT PREDICATE, in one place: every surface that says what gates — the XML gating= count and per-row // gating attribute, the --json / MCP "gating", the exit code, --ack-only=gating, the scoped-out would-gate // count, the allow-dirty absorbed count and the stderr naming line — asks this. A row gates when it is major // (not sev="minor") AND either preexisting-worse or a defect-shape format-arity row: new-symbol rows never // gate, except defect-shape format-arity, because a placeholder/argument mismatch is a defect, not debt, and a new function at the // ceiling (Regression::ceiling, QD-ENTRY-CEILING), because a function that starts that large is how the 1,000-line function starts. // The origin= attribute VALUE every surface (XML, --json, MCP) emits; nullptr = preexisting-worse, which carries none. inline const char* originValue( const Regression& r ) noexcept { return !r.isNewSymbol ? nullptr : r.isMoved ? "moved" : "new-symbol"; } inline bool rowGates( const Regression& r ) noexcept { return !r.isMinor && ( !r.isNewSymbol || r.ceiling != 0 || ( r.kind == "defect-shape" && r.facet == defectshape::facetName( defectshape::Facet::FormatArity ) ) ); } // B10.2 — kind → the ATTRIBUTE NAME its facet value is emitted under. `Regression::facet` carries only the // VALUE, so exactly one place decides what to call it. That place used to be THREE places (the XML // quality-delta emitter, its --json twin, and the MCP quality_delta emitter each held the same conditional // chain), which is the shape --quality-delta's own duplication kind exists to name; adding the fourth row // below is what made keeping three copies indefensible. nullptr = this kind publishes no facet attribute. // A declarative table, not a conditional chain (CONTRIBUTING.md §3). Scanned via findRowByKind (ACK // PROVENANCE / RE-SCORE, near kMaterialityBars above) rather than a hand-rolled loop: the loop spelling is // the single most re-derived body in this tree (serialize.h's bytesPerTokenFor, namingconsistency's // groupFor, lanes' findClaimByKey, ingest's lookupLang all carry it), and this function's OWN find_if was // reported as a fifth copy of it the moment it was first written that way — sharing findRowByKind with // rescoreNumericMajor's own kMaterialityBars lookup (a genuine sibling: same file, same "kind → its // declarative row" shape, same reason to exist) resolves that without forcing a shared abstraction onto the // other four, unrelated ones. struct FacetAttr { std::string_view kind; const char* attr; }; inline constexpr FacetAttr kFacetAttrs[] = { { "short-horizon-churn", "churn" }, // self / ambient { "api-surface", "surface" }, // new-symbol / contract-change { "duplication", "idiom" }, // the recognized clone-body shape (cloneidiom.h) { "defect-shape", "defect" }, // format-arity / utf8-cut / dedup-first / vacuous-assert { "error-masking", "facet" }, // failure-default: the growth includes a read failure returned as an empty success { "params", "similar" }, // QD-SWAP-1117: the longest run of adjacent same-typed parameters (similarargs.h) { "complexity", "monster" }, // QD-MONSTER-GROWTH: "1" when isMonsterGrowth made (or would make) the row major { "new-clone-of-reused-helper", "idiom" }, // T13/fix2 gave this kind duplication's idiom demotion (Regression::facet // is populated the same way, from the same CloneIdiomVerdict); this row was // missing, so a demoted row's idiom name never reached the reader even // though sev="minor" fired correctly — a disclosure gap, not a gating one. }; inline const char* facetAttrName( std::string_view kind ) noexcept { const FacetAttr* const hit = findRowByKind( std::begin( kFacetAttrs ), std::end( kFacetAttrs ), kind ); return hit != nullptr ? hit->attr : nullptr; } // §P6.6: `sym` is a canonical id `path::scope::name` (resolve.h::canonicalId) whose PATH segment is // `ing.files[...]` AS THE CALLER SPELLED THE ROOT — an absolute root then makes sym= carry a 150+ char // absolute prefix, while `path` above is already root-relative (relForHash, the same spelling every other // sidecar key uses). Normalize sym's path segment the same way, for DISPLAY ONLY: this must never touch // canonId itself, or Regression::key (the ack-ratchet identity) — see arch.h's relForHash comment, the S2 // trap: canonId stays load-bearing for resolution far beyond any one report. Both main.cpp's --json and XML // quality-delta emitters call this so the two stay in lockstep. // // A duplication/new-clone-of-reused-helper row's sym is a space-joined member LIST — normalize each member // independently. A bare name (free function, scope-less — canonicalId's own degrade case) has no "::" and // passes through unchanged. inline std::string displaySym( const std::string& sym, std::string_view root ) { std::string out; out.reserve( sym.size() ); std::size_t tokenStart = 0; while( tokenStart <= sym.size() ) { const std::size_t sp = sym.find( ' ', tokenStart ); const std::string_view token = std::string_view( sym ).substr( tokenStart, sp == std::string::npos ? std::string::npos : sp - tokenStart ); const std::size_t sep = token.find( "::" ); // path never contains "::" — only scope/name do if( sep != std::string_view::npos ) { out += relForHash( token.substr( 0, sep ), root ); out += token.substr( sep ); } else { out += token; } if( sp == std::string::npos ) { break; } out += ' '; tokenStart = sp + 1; } return out; } // ─── P1 SCOPE — the OWNERSHIP partition, for a working tree with more than one writer in it ───────────── // // THE PROBLEM, from the field. ~20 agent sessions edit ONE working tree at once. --quality-delta compares // that tree against HEAD, so every concurrent writer's uncommitted rows land in every agent's report. The // noise costs a manual attribution pass per run — annoying. The DANGER is one bad ack: an agent that acks a // sibling's row writes FOREIGN debt into a committed ledger under its own reason string, and the per-finding // ratchet quietly becomes a rubber stamp. The scope flag partitions findings by the path each one names, so // the exit code — and above all the ack — is about the caller's own subtree. // // WHAT THE GLOB IS, EXACTLY. Stated here, and in the flag's own --help text, because a pattern language that // silently fails to match is worse than a documented prefix match. Each comma-separated pattern is matched // against a finding's ROOT-RELATIVE path (the same spelling p= prints), and the list is an OR: // * a pattern with NO wildcard is a ROOT-ANCHORED path prefix ending on a '/' boundary or at the end of // the path: `alpha` matches `alpha/lib.h` and `alpha` itself, never `alphabet/lib.h`, and never a nested // `src/alpha/lib.h`. Deliberately STRICTER than --dead-code=DIR's component-anywhere match: a scope is a // claim of ownership, and "every directory called alpha, anywhere" is not one. A trailing slash is // optional (`alpha/` is `alpha`), and a leading `./` is stripped, as everywhere else in this tree. // * a pattern containing `*` or `?` is matched against the WHOLE root-relative path, where `*` matches any // run of characters INCLUDING '/' and `?` matches exactly one character. // NOT SUPPORTED, and said out loud rather than half-honored: `**` (it is two `*`, and one `*` already // crosses '/'), character classes `[a-z]`, brace expansion `{a,b}`, and negation. Whitespace and the XML // metacharacters are REFUSED in a pattern (scopeSpecIsSpellable) because the spec is recorded verbatim as a // single whitespace-delimited `by=` token in the ack ledger and echoed into an XML attribute — a pattern // that cannot round-trip through both is refused at the flag rather than mangled at the emitter. inline bool scopeGlobMatch( std::string_view s, std::string_view p ) noexcept { return wildcardMatch( s, p ); // arch.h — one wildcard loop for the scope patterns and resolve.h's workspace globs } // The wildcard-free arm: a root-anchored prefix that must end ON a component boundary, so `alpha` can never // claim `alphabet/`. inline bool scopePrefixMatch( std::string_view path, std::string_view pat ) noexcept { while( !pat.empty() && pat.back() == '/' ) { pat.remove_suffix( 1 ); } if( pat.empty() || pat.size() > path.size() || path.substr( 0, pat.size() ) != pat ) { return false; } return pat.size() == path.size() || path[ pat.size() ] == '/'; } // Every character a scope spec may contain. The set is closed rather than open because this string is written // into a whitespace-delimited ledger token AND into an XML attribute, and both are places where "we will // escape it later" has historically meant "we forgot". inline bool scopeSpecIsSpellable( std::string_view spec ) noexcept { for( const char c : spec ) { if( static_cast( c ) <= ' ' || c == '"' || c == '\'' || c == '<' || c == '>' || c == '&' ) { return false; } } return true; } struct Scope { std::vector patterns; // in argv order; matching is an OR over all of them std::string spec; // the comma-joined spelling AS GIVEN — echoed as scope= and as by= bool active() const noexcept { return !patterns.empty(); } bool matchesPath( std::string_view rel ) const noexcept { for( const std::string& p : patterns ) { const bool wild = p.find( '*' ) != std::string::npos || p.find( '?' ) != std::string::npos; if( wild ? scopeGlobMatch( rel, p ) : scopePrefixMatch( rel, p ) ) { return true; } } return false; } }; inline Scope parseScope( std::string_view spec ) { Scope out; out.spec = std::string( spec ); std::string_view rest = spec; while( !rest.empty() ) { const std::size_t comma = rest.find( ',' ); std::string_view tok = rest.substr( 0, comma ); while( tok.size() >= 2 && tok[ 0 ] == '.' && tok[ 1 ] == '/' ) { tok.remove_prefix( 2 ); } while( !tok.empty() && tok.back() == '/' ) { tok.remove_suffix( 1 ); } if( !tok.empty() ) { out.patterns.emplace_back( tok ); } if( comma == std::string_view::npos ) { break; } rest = rest.substr( comma + 1 ); } return out; } // P1.2 — the RESERVED token. `--scope=diff` means "the files this working tree changes vs the baseline", // expanded by the verb (which is the only place that can read git) into one literal path pattern per changed // INDEXED file. It composes with ordinary patterns by union: `--scope=diff,src/quality.h` is the diff set // plus that file. It is a reserved WORD, so a directory genuinely called `diff` must be spelled `./diff` or // `diff/` — said out loud in the flag's help rather than left to be discovered. // // Wrong on its own in the tree this whole feature is about, and that is not a defect to hide: in a shared // checkout a sibling's edits are "changed" too, so `diff` alone re-admits exactly the rows the scope was // meant to file elsewhere. It is sugar for the single-writer case; compose it with your own paths when the // tree has more than one writer in it. inline constexpr std::string_view kScopeDiffToken = "diff"; inline bool scopeUsesDiffToken( const Scope& sc ) noexcept { return std::find( sc.patterns.begin(), sc.patterns.end(), kScopeDiffToken ) != sc.patterns.end(); } // Is this finding the caller's? A clone group is a RELATION over a member SET, not a fact about one file, so // it is in scope iff ANY member's path matches: the duplicate a sibling just introduced against YOUR helper // is yours to answer for too, and filing the group by its first-sorting member alone (which is all p= names) // would hand it to whichever path happened to sort first. `memberPaths` is what makes that answerable — the // members= TEXT cannot, because a scope-less free function's canonId is a bare name with no path in it. // Every other kind is filed by its own locator, and carries no memberPaths at all. // // FLOOR, disclosed rather than papered over: a finding with NO locator at all (an empty `path` — a symbol // with no file, or a degraded lookup) is filed OUT of scope. Under a scope, the honest reading of "we cannot // say where this is" is "not provably yours", and the ack path names such a row rather than accepting it. inline bool scopeCovers( const Scope& sc, const Regression& r ) { for( const std::string& member : r.memberPaths ) // clone kinds only; empty for every other kind { if( sc.matchesPath( member ) ) { return true; } } return !r.path.empty() && sc.matchesPath( r.path ); } // ─── Signal-to-noise round: the per-finding ACK RATCHET ──────────────────────────────────────────────── // // `.ripwire_quality_acks` — one line per deliberately-accepted finding: // ack <16-hex identity key> // --quality-ack[=REASON] merges every finding the CURRENT delta reports into this file; --quality-delta then // suppresses a finding whose (kind, key) is acked at a magnitude ≥ its current `now` — and RE-REPORTS it the // moment it worsens past that (the ratchet: an ack accepts a finding AT its acked size, never a blank check). // Suppression is always honest: the report header carries acked="N". The map key is " <16hex>" (a plain // string, collision-free, sorted) so the rewritten file is byte-stable. Unknown/malformed lines degrade+skip // exactly like readBaseline. Deliberately NOT pinned to a HEAD sha: an acked finding ("fixture, dead by // design") stays accepted across commits until the file is edited or the finding worsens. // ─── ACK PROVENANCE CONFIDENCE — how the row's was=/now=/facet= were arrived at ──────────────────────── // // A tri-state, not the bool it replaces, because the ledger now has THREE honestly-different states and a // bool can only name two. `Measured` is a row whose provenance the ack path read off the live delta it was // accepting — the finding was in front of the binary at the moment the row was written. `Reconstructed` is // a row a later pass HEALED from facts about the tree as it stands TODAY (backfillCloneAckProvenance), for // a legacy row whose accept-time measurement was never recorded. The two must never be pooled in a // published number: a reconstructed row says "this is what the finding looks like now", which is a // different claim from "this is what was measured when it was accepted", and CLAUDE.md's honesty contract // is exactly the rule that a claim you cannot support must be labelled rather than rounded into one you can. // // `None` is a legacy row — nothing to re-score from, and NOT inferable from was/now alone: 0 is a // legitimate measured value (dead-code and both clone kinds always carry was=0), so an ABSENT token, not a // zero one, is the tell. // // FRESHNESS, the rule that keeps Reconstructed from rotting into a lie. A reconstruction describes the tree // on the day it was taken, and a marker alone would not stop a reader six months later from treating it as // a fact about the row. So it is a CACHE, not a record: backfillCloneAckProvenance RE-DERIVES every // Reconstructed row whose group it can still find, on every --quality-ack, so a value that can be checked // is never older than the last ack. // // A value it CANNOT check is left alone and counted, never cleared. Not finding a group proves nothing — // the scan may be scoped, capped, degraded, or run next to a different tree entirely — and deleting derived // data on the strength of a floor would be a worse error than carrying an unverified one, because it is not // reversible. The disclosure carries the unverified count for exactly this reason. // // Measured rows are never re-derived: a measurement outranks anything a later pass could compute, and that // ordering is what the whole axis means. enum class AckProvenance : std::uint8_t { None = 0, // legacy row — no now=/was= on the line at all Measured, // read off the live delta this row was accepted from Reconstructed, // healed from the CURRENT tree by a backfill pass — see backfillCloneAckProvenance Unknown, // now=/was= present, but prov= names a spelling this binary never wrote — round-tripped // verbatim (AckRecord::provRaw) rather than promoted into either real claim; see // ackProvenanceFor for why guessing either direction is the honesty-contract violation. }; // The token `prov=` carries in the ledger. Omitted entirely for Measured, the same OMIT-when-default rule // cid=/by= follow and for the same reason: a repo whose rows are all measured keeps a ledger byte-identical // to the one it would have without this axis, so adding it moves zero bytes until a backfill actually runs. inline constexpr std::string_view kAckProvReconToken = "recon"; struct AckRecord { std::string kind; std::uint64_t key = 0; std::uint32_t ackNow = 0; // the magnitude the finding was accepted at (the ratchet floor) // R1 IDENTITY — the SCRUBBED CONTENT ID of the symbol this ack was recorded against, or 0 when none was // available (a clone-group ack has no single body; a row written by a pre-R1 binary has no cid at all). // Serialized as an OPTIONAL `cid=<16hex>` token between ackNow and the reason — see readAckRecords for // why that spelling, and why the 443 rows already committed to this repo need no migration. std::uint64_t cid = 0; // P1.4 ACK PROVENANCE — the scope spec (`--scope`'s value, verbatim) the session that wrote this row was // working under, or empty when it was written without one. Serialized as a second OPTIONAL named token, // `by=`, for exactly the reasons cid= is one: a positional field would make every pre-existing row // malformed, and a separate record line would fire the reader's own malformed-line degrade on every one // of them. Empty rows are written byte-identically to the way they are written today. std::string by; // RE-SCORE PROVENANCE (round 2026-09-22) — the measured facet values that decided THIS finding's // severity at the moment it was accepted, so a LATER run can re-evaluate it under a different threshold // (the planned knob sweep) by reading the ledger alone, with no re-ingest and no git history replay. // `was`/`now` are the exact (was,now) pair perSymbolKind compared against the kind's bar/minorDelta — // see rescoreNumericMajor, which is the single formula both the live report and this re-score consult. // `facet` is Regression::facet verbatim (idiom name / self·ambient / new-symbol·contract-change) for the // kinds whose severity is not a bar comparison at all (duplication, new-clone-of-reused-helper — see // kFacetAttrs). `path`/`line` mirror Regression's own P2.5 locator (empty path = none available, same // honesty rule). Serialized as OPTIONAL named tokens (`now=`/`was=`/`facet=`/`p=:`), same // shape and same reasoning as cid=/by= — see readAckRecords for the grammar and the legacy-row handling. // // `hasProvenance` is NOT serialized itself — it is the READ-side fact "did this line carry now=/was= at // all", which is what tells a legacy row (written by a pre-provenance binary, or hand-edited down to the // bare grammar) from a new one. It cannot be inferred from was/now alone: 0 is a legitimate measured // value (dead-code and the two clone kinds always carry was=0), so an ABSENT token, not a zero one, is // the tell. A caller doing mechanical re-scoring (see rescoreAckRecord) must read this flag and count a // false as "cannot answer, legacy row" — never guess, and never treat it as a non-match (the hash key is // still the only identity; this flag only gates whether the OPTIONAL extra facts are trustworthy). // // WHAT A LEGACY ROW CAN AND CANNOT GET BACK, measured on this repo's own 1,623-row ledger rather than // assumed. No row anchors a COMMIT — `cid` identifies the symbol's at-accept-time body for forward // matching, not which tree pair produced was/now, and `by` is an ownership scope, not a ref. That makes // the answer DIFFER BY KIND, and the difference is the whole reason a backfill is possible at all: // // * The two CLONE kinds (duplication, new-clone-of-reused-helper — 288 rows here, 62 of them the // reuse-decline kind) need no commit anchor, because their severity is not a bar comparison over // was/now at all: it is `facet`, the clone idiom verdict. Their ack key IS cloneGroupHash (the // sorted member canonIds), classifyCloneGroupIdioms runs over every clone group in the CURRENT tree // regardless of newness, and `was` is 0 BY CONSTRUCTION at both kinds' push_back sites. So today's // tree answers all three — see backfillCloneAckProvenance, which heals exactly these rows and marks // them AckProvenance::Reconstructed, never Measured. // * The four NUMERIC kinds (complexity/verbosity/nesting/params — 320 rows here) genuinely cannot be // healed from this file or from today's tree. `now` for a legacy row is at best `ackNow` itself (the // ratchet floor, which is exactly r.now at the row's LAST acceptance in the common single-ack case, // but indistinguishable from a stale carried-forward max after a re-ack); `was` has no stand-in and // cannot be recomputed without the two commits that were diffed. Those rows stay AckProvenance::None // and are reported as such rather than given a guessed value. Recovering them is a git-archaeology // pass over the COMMITTED ledger's own blame (320 rows blame to 86 distinct commits at b939ef4f, a // ~13-minute one-time crawl), which is a separate lane and would record a MEASURED was, not a // reconstructed one — a re-diff of the real tree pair is a measurement, so it must not reuse // prov=recon. // * The remaining 1,015 rows (short-horizon-churn, dead-code, api-surface, error-masking) have no // materiality question for a bar sweep to re-ask — none of them has a kMaterialityBars row at all, so // rescoreNumericMajor's lookup misses and no recovered was/now would change a verdict. // // See the ledger's own PROVENANCE header comment (renderAckRecords) for the reader-facing version. std::uint32_t was = 0; std::uint32_t now = 0; std::string facet; std::string path; std::uint32_t line = 0; AckProvenance provenance = AckProvenance::None; std::string reason; // The literal `prov=` token text when `provenance == Unknown` — a spelling neither this binary's // canonical `recon` nor its "absent/live" Measured spelling, so there is nothing true to compute from // it. Kept verbatim so a hand-written or future-binary value ROUND-TRIPS through a read+rewrite instead // of being silently promoted into a false "reconstructed by us" claim or silently dropped. Empty for // every other provenance. See ackProvenanceFor / ackProvenanceTokens. std::string provRaw; // "is there anything here to re-score at all" — the question every pre-existing call site asked of // the bool this replaces, kept as a predicate so adding the confidence axis changed no caller's // meaning. A caller that CARES which kind of provenance it has reads `provenance` directly. bool hasProvenance() const noexcept { return provenance != AckProvenance::None; } }; // The re-score entry point over a whole AckRecord: strips the P0.3 zero-magnitude origin suffix // (`:new-symbol`/`:preexisting`) off `kind` before the table lookup — that suffix is an ACK-IDENTITY // discriminator (ackKindToken), never one of the nine finding kinds rescoreNumericMajor's table knows about // — then defers to it. nullopt covers both "this row cannot be rescored" cases at once: no provenance at // all (a legacy row), or a facet-driven/presence kind rescoreNumericMajor's table does not cover. inline std::optional rescoreAckRecord( const AckRecord& r, std::optional barOverride = std::nullopt, std::optional minorDeltaOverride = std::nullopt ) noexcept { if( !r.hasProvenance() ) { return std::nullopt; } std::string_view bareKind = r.kind; const std::size_t colon = bareKind.find( ':' ); if( colon != std::string_view::npos ) { bareKind = bareKind.substr( 0, colon ); } return rescoreNumericMajor( bareKind, r.was, r.now, barOverride, minorDeltaOverride ); } inline std::string ackMapKey( const std::string& kind, std::uint64_t key ) { return kind + " " + hex16( key ); } // ─── THE LEGACY-ACK BACKFILL — what a row written before provenance existed CAN still get back ───────── // // THE PROBLEM. `--quality-ack` records provenance only for rows it WRITES, so a ledger that predates the // feature heals forward and no further: this repo's own 1,623 rows carry none, and the knob sweep the // provenance exists for can therefore re-score none of its own history. The obvious fix — anchor each row // to a commit and re-diff it — is a real one, but it is aimed at the NUMERIC kinds, and measuring first // showed that is not where the rows are: of the 1,623, only 320 are numeric-bar rows at all. The 288 CLONE // rows (62 of them the reuse-decline kind the sweep specifically wants) would be untouched by ANY recovered // was=, because neither clone kind has a kMaterialityBars row — rescoreNumericMajor's lookup misses, so their // severity is `facet` and no value of was/now changes it. A commit anchor would have been a correct answer // to a different question. // // WHAT MAKES THE CLONE KINDS HEALABLE WITHOUT GIT AT ALL. Three facts line up, and all three are needed: // * their ack identity IS cloneGroupHash — the sorted member canonIds — so a row names a member SET that // can be looked for in any tree, not a magnitude that only meant something against one baseline; // * classifyCloneGroupIdioms runs over every clone group in the current tree regardless of newness, so // the verdict is recomputable now (computeDelta exports it as CloneIdiomFact rather than paying for a // second clone pass); // * `was` is 0 BY CONSTRUCTION at both kinds' push_back sites — it is not being guessed at or defaulted, // it is the only value either kind has ever written. // // WHAT THIS IS NOT. The member-set hash is over member IDENTITIES, not their bodies, so a group can still // hash the same today while the bodies that made it a clone have drifted. A healed facet is therefore the // answer to "would this group's idiom demote it NOW", not "did it demote it THEN" — a different question, // and for a threshold sweep arguably the more useful one, but not the same claim. That is exactly why these // rows are marked AckProvenance::Reconstructed and never Measured: pooling the two would publish a number // nobody can audit, which is the failure mode CLAUDE.md's honesty contract names. // // WHAT STAYS LEGACY, on purpose. A numeric row is not touched — `ackNow` is a plausible stand-in for its // `now`, but `was` has no stand-in at all, and half a triple would be worse than none (rescoreAckRecord // reads presence, not value). Recovering those needs the commit that accepted the row; the committed // ledger's own blame is that anchor, and it is a separate lane — see AckRecord's doc comment for the // measured cost and for why the LAST write, not the first appearance, is the commit to re-diff. // // IDEMPOTENT AND DETERMINISTIC, both by construction rather than by care — but NOT because a row that // already carries provenance is left alone: a Measured row is the only row never rewritten (a measurement // outranks anything this pass could derive, so it can never be downgraded to Reconstructed); a Reconstructed // row IS rewritten on every run whose group is still found (`++out.refreshed`, not skipped), re-derived from // the same deterministic facts about the CURRENT tree. Idempotence therefore holds because that re-derivation // is a pure function of (member-set hash, current tree) and produces the same bytes every time — not because // the row is skipped. `acks` is a btree_map so the walk is (kind,key) sorted, and `facts` is sorted+deduped by // its producer so the lookup is a binary search over a stable sequence. struct AckBackfill { std::size_t resolved = 0; // legacy clone rows reconstructed from the current tree for the first time std::size_t refreshed = 0; // already-reconstructed rows RE-DERIVED against this tree (see the freshness rule) std::size_t unverified = 0; // reconstructions this run could NOT re-derive — left exactly as they were, and said so std::size_t unresolved = 0; // legacy clone rows whose member set does not clone here — honestly left alone std::size_t ineligible = 0; // rows of a kind no current-tree fact can answer for (numeric, churn, presence) // Rows this pass did not CONSIDER: a measurement outranks anything it could derive, so it returns before // any other counter. Carried so the five counts above plus this one account for every row in the ledger — // without it the disclosure prints numbers that visibly do not sum, and a reader who checks (one did) is // left deciding between a transcription error and a real hole. An unexplained gap in a report whose whole // claim is that its floors are honest costs more than the line it takes to close it. std::size_t measured = 0; }; inline AckBackfill backfillCloneAckProvenance( gtl::btree_map& acks, const std::vector& facts ) { // `facts` must arrive sorted by hash — the lookup below binary-searches it. NOT spelled as an EXPECTS: // a promise may only call accessors (test/selfcheckcheck.sh arm C) and std::is_sorted is an O(n) scan, // so asserting it here would cost the whole sequence on every call to restate what its single producer // already guarantees unconditionally (computeDelta sorts and dedupes cloneIdiomsOut before returning). AckBackfill out; for( auto& [ mapKey, rec ] : acks ) { (void) mapKey; // the (kind,key) it was derived from — rec already carries both fields if( rec.provenance == AckProvenance::Measured ) { ++out.measured; // a measurement outranks anything this pass could derive — never rewritten, only counted continue; } // The ':new-symbol' / ':preexisting' suffix is an ACK-IDENTITY discriminator (ackKindToken), not a // finding kind — strip it before the kind test, the same way computeStaleAcks does. std::string_view base = rec.kind; const std::size_t colon = base.find( ':' ); if( colon != std::string_view::npos ) { base = base.substr( 0, colon ); } if( base != "duplication" && base != "new-clone-of-reused-helper" ) { ++out.ineligible; // untouched, including a hand-planted prov= on a kind this pass does not own continue; } const bool wasReconstructed = ( rec.provenance == AckProvenance::Reconstructed ); const auto hit = std::lower_bound( facts.begin(), facts.end(), rec.key, []( const CloneIdiomFact& f, std::uint64_t k ) { return f.hash < k; } ); if( hit == facts.end() || hit->hash != rec.key ) { // ABSENCE IS A FLOOR, NOT A VERDICT — and this is the one place it was tempting to forget it. // An earlier draft WITHDREW a reconstruction whose group it could not find, on the reasoning that // a value the tree cannot support should not survive. That is wrong for the same reason // staleForCloneKind refuses to call a clone target "gone": `facts` carries what this run FOUND, // and a run can fail to find a group because the scan was scoped or excluded, because a file hit // the size cap, because a parse degraded — or because the ledger is simply being read next to a // different tree, which is exactly what qackconcurrencycheck arm 7's transplant probe does, and // what caught this. Destroying 231 rows on the strength of a floor is not a freshness rule, it is // the guess CLAUDE.md's honesty contract forbids, made irreversibly. // // So nothing is cleared. The row keeps the values it had, and the run SAYS it could not verify // them — an unverified count a reader can act on, rather than data silently deleted. ++( wasReconstructed ? out.unverified : out.unresolved ); continue; } // `was` is 0 for both clone kinds at every site that writes one — this is the construction, not a // default. `now` is the ratchet floor, which is the accepted `now` for a row acked once and a // carried-forward max for one re-acked since; it is disclosed as reconstructed either way, and // neither clone kind feeds a bar comparison, so no verdict can turn on the difference. `facet` is // the load-bearing value: it is what decides these kinds' severity. rec.was = 0; rec.now = rec.ackNow; rec.facet = hit->idiom; rec.provenance = AckProvenance::Reconstructed; rec.provRaw.clear(); // this run just derived a REAL reconstruction — any prior unrecognized spelling is superseded ++( wasReconstructed ? out.refreshed : out.resolved ); } // Every row this pass looked at landed in exactly one counter (`continue`d after incrementing it, or // fell through to the resolved/refreshed increment above) — a plain size_t sum with no accessor behind // it, so it costs nothing to state and nothing to check. This is the invariant a reader would otherwise // verify by hand (the review that found this backfill had zero self-checks in +380 lines did exactly // that, over two separate runs, before trusting the six numbers on stderr). ENSURES( out.resolved + out.refreshed + out.unverified + out.unresolved + out.ineligible + out.measured == acks.size(), "every ack row lands in exactly one backfill counter" ); return out; } // ─── ACK RATCHET REASON CLOBBER (round 2026-08-29 fix) ───────────────────────────────────────────────── // // THE BUG. Re-acking an EXISTING (kind,key) row with a new reason used to overwrite `reason` outright. // A finding shared by many unrelated sessions — `printUsage`'s verbosity row is re-acked by every flag // addition, since each addition changes the function's own body — loses whichever session's justification // got there first: two lanes independently wrote and then silently destroyed each other's reasons on the // SAME row. // // THE FIX. When the new reason differs from the row's current one, fold the old reason in rather than // dropping it: ` | prior: `. Two things keep this from becoming its own mess: // * IDENTICAL reasons are a no-op — re-running `--quality-ack='same text'` must not grow the chain (and // returns the row UNCHANGED, so a repeat ack does not even touch the file). // * The chain is capped at ONE hop. A row's reason may already itself be a chain from an earlier // re-ack ("Y | prior: X") — only the immediately-preceding segment ("Y") is compared against and kept; // an older segment ("X") is dropped rather than accumulating across every re-ack this row ever sees. // A committed ledger already changes reason on every unrelated flag addition, so an uncapped chain // would grow without bound; one hop of context (who had it right before you) is what a reader actually // needs to reconstruct a decision, without turning the ledger into an append-only reason log. inline constexpr std::string_view kAckReasonChainSep = " | prior: "; inline std::string composeAckReason( const std::string& priorReason, const std::string& newReason ) { if( priorReason.empty() ) { return newReason; } const std::size_t sep = priorReason.find( kAckReasonChainSep ); const std::string currentReason = ( sep == std::string::npos ) ? priorReason : priorReason.substr( 0, sep ); if( currentReason == newReason ) { return priorReason; // identical reason (ignoring any existing chain) — no-op, chain unchanged } return newReason + std::string( kAckReasonChainSep ) + currentReason; } // ─── P0.3 (r27) — ZERO-MAGNITUDE ACKS ARE NOT A BLANK CHECK ──────────────────────────────────────────── // // THE BUG. `applyAckRatchet` suppresses on `r.now <= ackNow`. The api-surface tier-A push emits was=now=0 for // BOTH `origin="new-symbol"` (additive surface, sev=minor, NEVER gates) and `surface="contract-change"` (a // preexisting symbol flipped private → public: major, GATES) under the SAME (kind, key) ack identity. So // acking the harmless new-code rows — which `--quality-ack` does wholesale, and which is 209 of this repo's // own 402 committed ack lines — means the later, genuine private→public flip on that same symbol hits // `0 <= 0` and is suppressed FOREVER. `dead-code` (always now=0, 6 more lines) has the identical shape. That // is precisely the "an ack accepts a finding AT its acked size, never a blank check" contract, violated. // // THE FIX. A zero-magnitude finding has no magnitude to ratchet on, so it must ack on IDENTITY + ORIGIN // instead: the ack token for such a row carries `:new-symbol` or `:preexisting`, making the two rows two // different acks. An ack recorded against the new-symbol row therefore cannot suppress the contract-change // row. Findings WITH a magnitude (complexity, verbosity, duplication, an api-surface param-arity change, …) // are untouched — their ratchet already works, and splitting them would churn the sidecar for no gain. // // MIGRATION OF THE 215 ALREADY-COMMITTED ROWS (documented, not silent — see also readAckRecords): // a legacy BARE token (`api-surface`/`dead-code`, no `:`) with ackNow == 0 is read as the `:new-symbol` // variant and rewritten in that spelling by the next `--quality-ack`. Rationale, and why this direction: // * ackNow == 0 ⟺ zero-magnitude — every other kind's `now` is a count/tokens/fan-in strictly above its bar, // so the discriminator is exact, not a guess. // * The overwhelming majority of those rows WERE new-symbol rows (that is the class --quality-ack sweeps up). // Keeping them preserves their real meaning: the additive-surface noise stays suppressed. // * The rows we cannot distinguish — a legacy ack that really was recorded against a contract-change — are // re-surfaced and GATE again. That is the FAIL-CLOSED direction: a re-surfaced finding costs one honest // re-ack with a reason; a silently-kept one is the bug being fixed. Never resolve an ambiguity in favour // of "green". // The rewrite is visible in `git diff .ripwire_quality_acks` — the ack file is committed precisely so a // change in what is suppressed is reviewable. inline std::string ackKindToken( const std::string& kind, bool isZeroMagnitude, bool isNewSymbol ) { if( !isZeroMagnitude ) { return kind; } return kind + ( isNewSymbol ? ":new-symbol" : ":preexisting" ); } // QD-ACK-GATING-SPLIT (CodeRabbit 4577036262, #662): an error-masking row whose growth is all report-only shapes (sev="minor") // acks as `error-masking:report-only`, so accepting it cannot hide a later GATING row of the same symbol at the same count // (a failure-default catch made empty). The bare token stays the gating ack; findSuppressingAck lets it cover the // report-only row too (accepted gating debt covers the lesser finding), which also keeps every bare row already committed // suppressing what it did. A bare row written against a report-only row before this split still covers a gating one at // its count: that ambiguity is not resolvable from the ledger, and the split closes it for every ack written from here on. inline constexpr std::string_view kAckReportOnlySuffix = ":report-only"; inline std::string ackKindToken( const Regression& r ) { if( r.kind == "error-masking" && r.isMinor ) { return r.kind + std::string( kAckReportOnlySuffix ); } return ackKindToken( r.kind, r.isZeroMagnitude(), r.isNewSymbol ); } // Read side of the migration above: a bare (colon-free) kind token acked at magnitude 0 is a pre-r27 // zero-magnitude ack → normalize it to the `:new-symbol` variant so it keeps suppressing exactly the class it // was almost certainly recorded for, and so writeAckRecords self-heals the file into the new spelling. inline std::string normalizeLegacyAckKind( const std::string& kind, std::uint32_t ackNow ) { if( ackNow != 0 || kind.find( ':' ) != std::string::npos ) { return kind; } return kind + ":new-symbol"; } // B10.1c — MERGE-FRIENDLY canonical format: one ack per line, `ackMapKey` (kind+hex) order on every write (a // gtl::btree_map iterates sorted by construction, so writeAckRecords below is ALWAYS sorted — never // last-writer-order). Two independent sessions each appending DIFFERENT new findings to an already-sorted // file produce two pure, non-overlapping insertions — exactly what a 3-way text merge resolves cleanly // without a conflict; only two sessions racing to CREATE the file from nothing is a true add/add conflict // (unavoidable by file format alone — see PLAN's evidence). The reader is tolerant of anything a sorted-write // invariant does NOT itself guarantee: lines out of order (e.g. hand-edited, or merged from an older, // unsorted revision), CRLF line endings (a file merged in from a Windows checkout), and blank/comment lines // anywhere — so a round-trip (read whatever is on disk → merge in new findings → write) always SELF-HEALS the // file back to canonical sorted order regardless of what shape it arrived in. Grammar (also the header // line below): `ack <16-hex-key> `. // // D2 — DUPLICATE (kind,key) LINES MERGE BY max(ackNow), never last-wins. The sorted-write invariant // above means a file THIS binary wrote never contains a duplicate key, but the reader must still tolerate one // that arrived some other way (a hand-edit, an unlucky 3-way merge of two divergent ack files, an older // binary's output) — and a naive `out[key] = ...` overwrite lets whichever duplicate happens to sort LAST in // the file silently LOWER an already-accepted ratchet floor (a finding legitimately acked at magnitude 20 // reappears as a fresh regression because a stray "acked at 1" line follows it). The floor may only ever go // up via a duplicate, so keep the max — same MAX-not-last discipline computeSnapshot already uses for // per-symbol metrics (see the comment there). The reason string travels with whichever record wins the max. // R1 IDENTITY — take the OPTIONAL leading `cid=<16hex>` token off an ack line's reason field, returning the // content id (0 when there is none) and leaving `reason` as the human text alone. // // WHY THIS SPELLING, rather than a new record type or a positional field: // * The reason runs to end of line, so a new field can only go BEFORE it. A POSITIONAL one would make // every pre-R1 line malformed — 443 already-committed rows in this repo alone, each carrying a // hand-written justification that is the whole point of the ledger. // * A separate `cid ` RECORD line would instead trip readAckRecords' own "malformed ack // line skipped" degrade on every older binary — 443 alerts on a file it should simply read. The baseline // sidecar can rename a tag (`body`->`bodyq`) because nothing hand-edits it; this file is committed and // reviewed by people. // * As a NAMED token it round-trips through an older binary untouched: that binary reads `cid=...` as the // first word of the reason and writes it straight back out, so a mixed-version team does not silently // strip content identity. test/identitycheck.sh arm (8c) pins the round trip. // // A malformed hash degrades to "no cid" and is LEFT IN the reason rather than guessed at or discarded — the // damage stays visible in a file a human reviews, which is the only place it can be fixed. // The GRAMMAR half, shared by every named token: if `reason` opens with `name`, split its value off and // leave `reason` as the text that follows. Returns false (and touches nothing) when the token is absent. // Only the SPLIT lives here — validation belongs to each token's own reader, because each one accepts a // different language, and a caller that rejects the value restores `reason` itself. inline bool takeAckNamedToken( std::string& reason, std::string_view name, std::string& valueOut ) { ASSUME_NO_ALIAS( reason, valueOut ); if( reason.size() < name.size() || reason.compare( 0, name.size(), name ) != 0 ) { return false; } const std::size_t end = reason.find( ' ' ); valueOut = reason.substr( name.size(), ( end == std::string::npos ? reason.size() : end ) - name.size() ); reason = ( end == std::string::npos ) ? std::string{} : reason.substr( end + 1 ); while( !reason.empty() && reason.front() == ' ' ) { reason.erase( reason.begin() ); } return true; } // The GRAMMAR half shared by every numeric ack token (cid= below, now=/was= further down): parse `name`'s // value off the front of `reason` in `base`; a missing token is `false` with `reason` untouched, and a // PRESENT-but-malformed one is also `false`, `reason` restored to what it was, and `*wasMalformed` (when the // caller wants to know) set so it — not this shared parser — can decide whether that specific case is worth // its own DISCLOSE. It cannot decide that itself: cid='s degrade already has one (a ratchet-grandfathered // site — see takeAckCidPrefix); a brand-new one-argument DISCLOSE is a shape test/selfcheckcheck.sh refuses // on new code, and now=/was= below stay silent on purpose (the malformed text staying visible in `reason` is // still the disclosure a human reviewing the file sees — see takeAckUintPrefix's own comment). inline bool takeAckNumericToken( std::string& reason, std::string_view name, int base, std::uint64_t& valueOut, bool* wasMalformed = nullptr ) { const std::string untouched = reason; std::string digits; if( !takeAckNamedToken( reason, name, digits ) ) { return false; } char* stop = nullptr; const auto v = std::strtoull( digits.c_str(), &stop, base ); if( digits.empty() || stop == nullptr || *stop != '\0' ) { reason = untouched; if( wasMalformed != nullptr ) { *wasMalformed = true; } return false; } valueOut = v; return true; } inline std::uint64_t takeAckCidPrefix( std::string& reason ) { std::uint64_t v = 0; bool malformed = false; if( takeAckNumericToken( reason, "cid=", 16, v, &malformed ) ) { return v; } if( malformed ) { DISCLOSE( "quality: unparseable cid= on an ack line — kept as reason text, content identity unavailable for that row" ); } return 0; } // P1.4 — the provenance twin of takeAckCidPrefix: an optional leading `by=` token. Same degrade // rule as its sibling, and for the same reason: a value this binary could not have written (whitespace, or // an XML metacharacter — see scopeSpecIsSpellable) is LEFT IN the reason rather than guessed at or silently // dropped, so the damage stays visible in the file a human reviews. The two share the split above and differ // only in the language they accept, which is the whole of what makes them two functions. inline std::string takeAckByPrefix( std::string& reason ) { const std::string untouched = reason; std::string val; if( !takeAckNamedToken( reason, "by=", val ) ) { return {}; } if( val.empty() || !scopeSpecIsSpellable( val ) ) { DISCLOSE( "quality: unspellable by= on an ack line — kept as reason text, provenance unavailable for that row" ); reason = untouched; return {}; } return val; } // RE-SCORE PROVENANCE — the read side of AckRecord's was=/now=/facet=/p= tokens (see the struct's own doc // comment for what each carries and why). A plain decimal `` token, same shared parser as cid= above // (takeAckNumericToken) and the same "left in reason, untouched" degrade on a malformed value — but silent: // a value this binary could not have written stays visible as text in the file a human reviews (the same // disclosure cid='s DISCLOSE call spells out loud), without a NEW one-argument DISCLOSE call, a shape // test/selfcheckcheck.sh refuses on code that did not carry one already. // The only integer spelling this binary writes into the ledger's now=/was=/p=: slots: one to ten ASCII // decimal digits, no sign, no whitespace, a value that fits std::uint32_t. Deliberately NOT strtoul/strtoull: // both accept a leading '-' and negate (now=-1 read back as 4294967295), a value past 32 bits was narrowed to // its low half (now=4294967296 read back as 0), and unsigned long is 64 bits on LP64 but 32 on Windows, so the // same committed line read back differently per platform. `out` is written only on success. inline bool parseAckLedgerUint32( std::string_view s, std::uint32_t& out ) noexcept { if( s.empty() || s.size() > 10 ) { return false; } std::uint64_t v = 0; for( const char c : s ) { if( c < '0' || c > '9' ) { return false; } v = v * 10u + static_cast( c - '0' ); } if( v > std::numeric_limits::max() ) { return false; } out = static_cast( v ); return true; } inline bool takeAckUintPrefix( std::string& reason, std::string_view name, std::uint32_t& valueOut ) { const std::string untouched = reason; std::string digits; if( !takeAckNamedToken( reason, name, digits ) ) { return false; } if( !VALIDATE( parseAckLedgerUint32( digits, valueOut ), "an ack ledger now=/was= value is plain decimal that fits 32 bits" ) ) { reason = untouched; // same visible-in-reason degrade as any other malformed token; never a fabricated value return false; } return true; } // `p=:` — the SAME p="path:line" spelling the live report emits (P2.5), read back off one // whitespace-free token. Split on the LAST ':' (repo paths are always '/'-separated — CONTRIBUTING.md's // "paths are /-separated inside the program" — so a genuine ':' inside one is not a spelling this binary // ever writes); when the suffix after it is not all-digits, there is no reliable line boundary, so the // WHOLE token is kept as the path and line stays 0 — a best-effort locator beats none, and a wrong line // number is a much smaller loss than dropping the locator outright. Never disclosed: unlike a malformed // cid=/now=, a mis-split path:line still answers "which file", the question this token exists for. inline void splitAckLocator( const std::string& token, std::string& pathOut, std::uint32_t& lineOut ) { const std::size_t colon = token.rfind( ':' ); if( colon == std::string::npos ) { pathOut = token; return; } std::uint32_t v = 0; if( !VALIDATE( parseAckLedgerUint32( std::string_view( token ).substr( colon + 1 ), v ), "an ack ledger p= line is plain decimal that fits 32 bits" ) ) { pathOut = token; // whole-token fallback: the text stays the path, the line stays unknown return; } pathOut = token.substr( 0, colon ); lineOut = v; } // The five re-score tokens together, ORDER-TOLERANT the same way cid=/by= are: renderAckRecords always // writes them now=,was=,prov=,facet=,p= (in that order), but a hand-edit or a 3-way merge can reorder them, // so the reader tries all five against whatever is left at the front of `reason`, in a loop, until a pass // takes nothing. Provenance is present iff BOTH now= and was= were present — the pair rescoreAckRecord's // table needs together; a lone one (a hand-truncated line) is treated as no provenance rather than a half- // answer. `prov=` then says WHICH of the two confidences it is (AckProvenance); absent means Measured, // which is what keeps a ledger of live-written rows byte-identical to one written without this axis. // `prov=`'s VALUE → the confidence it names, decided in one place so takeAckProvenance below stays a token // loop and nothing else. `hasPair` is "both now= and was= were present", because provenance is the PAIR: // without it there is nothing for a confidence to qualify, whatever prov= says. // // An UNRECOGNIZED value degrades to Unknown, never to Measured and never to Reconstructed. Reading it as // Measured would let a future spelling this binary does not know silently promote itself into the // audited-as-measured population — the exact direction the honesty contract forbids guessing in. Reading it // as Reconstructed (an earlier version of this function did) is the OTHER direction of the same mistake: it // claims backfillCloneAckProvenance verified this row from the current tree, which is false for any row that // pass does not own (every numeric/churn/presence kind — see AckBackfill::ineligible) and unproven for a // clone-kind row whose group this run cannot find either. `writeAckRecords` would then serialize a plain // hand-typed value as the ledger's own canonical `prov=recon` spelling — a claim of verified reconstruction // this binary never performed. AckRecord::provRaw carries the exact bytes instead: caller-side // (`takeAckProvenance`) stores `provToken` there when this function returns Unknown, and // `ackProvenanceTokens` writes `prov=` verbatim, so an unrecognized value ROUND-TRIPS through a // read+rewrite unchanged rather than being rewritten into either claim. A clone-kind row still gets one real // chance to become genuinely Reconstructed: backfillCloneAckProvenance runs on every row regardless of this // function's verdict, and treats Unknown the same as legacy (its member-set hash may still be found in the // CURRENT tree) — so it self-corrects into the real spelling when the tree can prove it, and round-trips // otherwise. It is never withdrawn: the same "absence is a floor, not a verdict" rule that keeps the backfill // from deleting an unverified reconstruction (see backfillCloneAckProvenance) applies here too — an // unrecognized token is unproven, not disproven, and this codebase's ratchet never destroys a row on a floor. inline AckProvenance ackProvenanceFor( bool hasPair, std::string_view provToken ) { if( !hasPair ) { return AckProvenance::None; } if( provToken.empty() || provToken == "live" ) { return AckProvenance::Measured; // absent IS measured — that is what keeps a live-written ledger byte-identical } if( provToken == kAckProvReconToken ) { return AckProvenance::Reconstructed; // the one spelling this binary itself writes for a healed row } // Anything else — a hand-edit, or a spelling some future binary writes — is NOT ours to interpret. It is // also not a trace site: a one-argument DISCLOSE ships nothing (Diagnostics.h §4b), there is no sink in a // pure token parser to pass, and answerUnchanged would be a false claim because this choice DOES change // the row's confidence class. The caller (takeAckProvenance) captures `provToken` verbatim into // AckRecord::provRaw so it round-trips instead. return AckProvenance::Unknown; } // ONE pass of the token loop: take whichever re-score token is at the front of `reason` right now, or // report that none is. Split from the loop below because they are two jobs — which tokens exist and how one // is spelled, versus how many times to look — and the five spellings do not share a type (two uints, two // bare strings, one path:line pair), so a declarative table would have to carry a variant and five setters // to say what five named lines already say. Returns false the moment nothing matches, which is what ends // the loop; each token is guarded by its own "not taken yet" test so a repeated token is left in `reason` // rather than silently overwriting the first one. inline bool takeOneAckProvenanceToken( std::string& reason, AckRecord& rec, bool& gotNow, bool& gotWas, std::string& prov ) { std::string tok; if( !gotNow && takeAckUintPrefix( reason, "now=", rec.now ) ) { gotNow = true; return true; } if( !gotWas && takeAckUintPrefix( reason, "was=", rec.was ) ) { gotWas = true; return true; } if( prov.empty() && takeAckNamedToken( reason, "prov=", prov ) ) { return true; } if( rec.facet.empty() && takeAckNamedToken( reason, "facet=", rec.facet ) ) { return true; } if( rec.path.empty() && takeAckNamedToken( reason, "p=", tok ) ) { splitAckLocator( tok, rec.path, rec.line ); return true; } return false; } inline void takeAckProvenance( std::string& reason, AckRecord& rec ) { bool gotNow = false, gotWas = false; std::string prov; for( int pass = 0; pass < 5; ++pass ) // at most 5 tokens, each taken at most once — 5 passes always suffices { if( !takeOneAckProvenanceToken( reason, rec, gotNow, gotWas, prov ) ) { break; // nothing matched this pass — no more re-score tokens at the front of reason } } rec.provenance = ackProvenanceFor( gotNow && gotWas, prov ); if( rec.provenance == AckProvenance::Unknown ) { rec.provRaw = prov; // round-trip the exact bytes — see ackProvenanceFor for why this is not our call to relabel } } // ─── THE READER-SIDE TWIN OF THE ACK REASON CLOBBER (2nd site, round 2026-08-30) ─────────────────────── // // Two lines for the same (kind,key) in the file are usually two lanes' independent appends meeting in an // ordinary git merge — the ledger is committed and sorted precisely to make that merge clean. D2's rule // stands: max(ackNow) wins the ROW, because the ratchet floor can only ever go UP through a duplicate. But // the losing line's REASON must be reconciled the same way a live re-ack is (composeAckReason, at the // write site in verbs_quality.h), not silently discarded: the winner's own head segment stays the head, // and the loser's head becomes the one-hop `prior:` segment. Both sides may already BE chains from earlier // re-acks — only each side's head participates, so the cap survives any number of merge rounds, and a // byte-identical duplicated line (both-sides-kept merge artifact) is a reason no-op via composeAckReason's // identical-head rule. inline void mergeDuplicateAckRecord( AckRecord& row, AckRecord&& incoming ) { const bool incomingWins = incoming.ackNow > row.ackNow; const std::string& winnerReason = incomingWins ? incoming.reason : row.reason; const std::string& loserReason = incomingWins ? row.reason : incoming.reason; const std::size_t sep = winnerReason.find( kAckReasonChainSep ); const std::string winnerHead = ( sep == std::string::npos ) ? winnerReason : winnerReason.substr( 0, sep ); const std::string folded = winnerHead.empty() ? loserReason : composeAckReason( loserReason, winnerHead ); if( incomingWins ) { row = std::move( incoming ); } row.reason = folded; } inline gtl::btree_map readAckRecords( const std::string& path, std::size_t& badLines ); inline gtl::btree_map readAckRecords( const std::string& path ) { std::size_t ignored = 0; return readAckRecords( path, ignored ); } inline gtl::btree_map readAckRecords( const std::string& path, std::size_t& badLines ) { badLines = 0; gtl::btree_map out; // openRegularFileStream, not a stream opened on the name: a FIFO planted at the ledger's name blocked that open until // a writer appeared, so --quality-delta hung before any output, and a link to /dev/zero never reached end of file. // Anything that is not a regular file now reads as no ledger, and stderr says so (docparse.h). Still one line at a // time, as the std::ifstream it replaces read it: a large ledger is never held whole. rw::pathguard::NoFollowRead ledger = docparse::detail::openRegularFileStream( "the quality-acks ledger", path ); std::string line; while( ledger.readLine( line ) ) { while( !line.empty() && ( line.back() == '\r' || line.back() == '\n' ) ) { line.pop_back(); // CRLF tolerance (merged-in Windows checkout) } if( line.empty() || line[0] == '#' ) { continue; } std::istringstream is( line ); std::string tag, kind; std::uint64_t key = 0; std::uint32_t ackNow = 0; is >> tag >> kind >> std::hex >> key >> std::dec >> ackNow; if( tag != "ack" || is.fail() ) { DISCLOSE( "quality: malformed ack line skipped" ); ++badLines; continue; } kind = normalizeLegacyAckKind( kind, ackNow ); // P0.3 migration — see the note at ackKindToken std::string reason; std::getline( is, reason ); while( !reason.empty() && reason.front() == ' ' ) { reason.erase( reason.begin() ); } std::uint64_t cid = takeAckCidPrefix( reason ); // R1 IDENTITY — the optional cid= field; see takeAckCidPrefix const std::string by = takeAckByPrefix( reason ); // P1.4 PROVENANCE — the optional by= field if( cid == 0 ) { // the two named tokens are read in EITHER order: this binary always writes cid= first, but the file // is hand-edited and 3-way merged, and a reader that only accepts one order silently loses a field cid = takeAckCidPrefix( reason ); } AckRecord rec; rec.kind = kind; rec.key = key; rec.ackNow = ackNow; rec.cid = cid; rec.by = by; takeAckProvenance( reason, rec ); // now=/was=/prov=/facet=/p= — order-tolerant; sets rec.provenance while( !reason.empty() && reason.back() == '\r' ) { reason.pop_back(); // CRLF tolerance on the trailing field too } rec.reason = reason; const std::string mapKey = ackMapKey( kind, key ); const auto it = out.find( mapKey ); if( it == out.end() ) { out[ mapKey ] = std::move( rec ); } else { mergeDuplicateAckRecord( it->second, std::move( rec ) ); } } return out; } // ── F-04 (round-4 audit): THE ACK LEDGER'S CROSS-PROCESS WRITE LOCK ────────────────────────────────── // // WHAT BROKE. `--quality-ack` is a read-modify-write over the WHOLE ledger: read every existing row, heal // the identities, fold this run's accepted findings in, rewrite the file from the in-memory map. Nothing // serialized that, and the rewrite was a bare `ofstream(trunc)`. Three sessions acking DISJOINT rows in one // shared checkout — the exact scenario `--scope` exists for ("N agent sessions sharing one checkout") — // therefore lost two of the three acks on 8 of 8 measured runs: not a partial merge, a full overwrite by // whichever process rewrote the file last. One run in eight additionally left a torn line behind, because // the truncate itself was racing another process's write. // // THE TWO HALVES OF THE FIX, and they close different holes: // * this lock, held by the acking process from BEFORE the ledger is read until AFTER it is written // (verbs_quality.h), so the whole read-modify-write is atomic against another COOPERATING ripwire. // It is taken ONLY on the --quality-ack path: a read-only --quality-delta never blocks and never waits. // * the atomic tmp+rename publish below, which is what protects a READER — including `git diff`, an // editor, or a plain --quality-delta — from ever observing a half-written ledger. A lock alone cannot // do that, because readers do not take it. // // WHY THE LOCK FILE IS NOT `.lock` BESIDE THE LEDGER. That was the audit's suggestion and it is the // one thing here that must NOT be copied from it: a sidecar lock file created next to a COMMITTED file is // permanent git-status litter in the user's repo — the defect A3-F8 already fixed for the MCP edit lock, for // the same reason. Same mechanism as that lock instead (mcpedit.h EditLock): a stable lockfile in the // per-user cache dir under `locks/`, named from a hash of the ledger's path, so two processes still open the // same inode and `flock` still serializes them, with nothing landing in the repo. The path is CANONICALIZED // first, so `ripwire .` and `ripwire /abs/repo` — the two spellings rootQualifiedSidecar already exists to // reconcile — hash to the same lock. // // WHY THE WAIT IS LONG. The critical section spans a whole delta computation (seconds, cold), not a splice, // so mcpedit's ~200 ms budget would time out on essentially every real contention and degrade straight back // into the bug. 60 s of 10 ms polls, then DISCLOSE and proceed lock-free: the pre-fix behavior is // the floor, never a hang. flock is released by the kernel when the fd closes, so a crashed peer cannot // wedge the ledger. // // HONEST LIMIT: advisory. A non-ripwire writer (a human editing the file, a merge tool) is not serialized by // it. The atomic publish still keeps THAT reader from seeing a torn file, but a hand-edit made while a // --quality-ack is mid-flight can still be overwritten — the same residual mcpedit.h records for its own lock. struct SidecarWriteLock { int fd = -1; bool locked = false; explicit SidecarWriteLock( const std::string& sidecarPath, int maxWaitMs = 60000 ) { namespace fs = std::filesystem; std::error_code canonEc; const fs::path canon = fs::weakly_canonical( fs::path( sidecarPath ), canonEc ); const std::string identity = canonEc ? sidecarPath : canon.string(); char name[ 64 ]; rw::formatTo( name, sizeof( name ), "ripwire-sidecar-{:016x}.lock", static_cast( fnv1a64( identity ) ) ); const std::string lockDir = cacheDirLadder() + "/locks"; os::mkdir( lockDir.c_str(), 0700 ); os::chmod( lockDir.c_str(), 0700 ); const std::string lockPath = resolveCacheBlobPath( lockDir, name ); fd = os::open( lockPath.c_str(), O_RDWR | O_CREAT, 0644 ); if( fd < 0 ) { DISCLOSE( "quality: ack-ledger lockfile open failed; proceeding lock-free (a concurrent --quality-ack can lose rows)" ); return; } for( int waitedMs = 0; ; waitedMs += 10 ) { if( os::flock( fd, LOCK_EX | LOCK_NB ) == 0 ) { locked = true; break; } if( errno != EWOULDBLOCK || waitedMs >= maxWaitMs ) { break; } struct timespec ts{ 0, 10 * 1000 * 1000 }; // 10 ms os::nanosleep( &ts, nullptr ); } if( !locked ) { DISCLOSE( "quality: ack-ledger lock contended past the wait budget; proceeding lock-free (a concurrent --quality-ack can lose rows)" ); } } ~SidecarWriteLock() { if( fd >= 0 ) { if( locked ) { os::flock( fd, LOCK_UN ); } os::close( fd ); } } SidecarWriteLock( const SidecarWriteLock& ) = delete; SidecarWriteLock& operator=( const SidecarWriteLock& ) = delete; }; // RE-SCORE PROVENANCE, serialized: the `now= was= [prov=] [facet=] [p=]` run of tokens one ack row carries, // or "" for a legacy row. Its own function rather than four branches inside renderAckRecords, which is a // row FORMATTER and stays one — the ledger has grown three optional token families now (cid=, by=, and this // one), and the third is what made a fourth nested conditional in the writer indefensible. // // now=/was= are written together whenever the row carries provenance AT ALL — even when a value is // legitimately 0 (dead-code and both clone kinds always are). The token's PRESENCE, not its value, is what a // later reader (rescoreAckRecord) uses to tell a provenance-bearing row from a legacy one. // // prov= is written only for the WEAKER confidences. Measured emits nothing, so a ledger whose rows were all // written from a live delta is byte-identical to one written before the confidence axis existed — the same // OMIT-when-default rule cid=/by= follow, and what keeps qackconcurrencycheck arm 7's round-trip over the // real 1,623-row ledger from moving a single byte until a backfill actually runs. Reconstructed writes the // canonical `recon` spelling; Unknown writes AckRecord::provRaw verbatim — never `recon` — so a hand-typed or // future-binary spelling this binary does not understand round-trips through a read+rewrite unchanged // instead of being relabelled as a reconstruction this binary never performed (see ackProvenanceFor). inline std::string ackProvenanceTokens( const AckRecord& r ) { if( !r.hasProvenance() ) { return {}; } EXPECTS( r.provenance != AckProvenance::Unknown || !r.provRaw.empty(), "takeAckProvenance always pairs Unknown with the raw token it was read from" ); std::ostringstream t; t << "now=" << r.now << " was=" << r.was << ' '; if( r.provenance == AckProvenance::Reconstructed ) { t << "prov=" << kAckProvReconToken << ' '; } else if( r.provenance == AckProvenance::Unknown ) { // Never scopeSpecIsSpellable-gated like facet=/p= below: provRaw was read back by takeAckNamedToken, // which only ever takes a single whitespace-delimited token in the first place, so it cannot contain // a space or newline to begin with — there is nothing here a spellability check could catch. t << "prov=" << r.provRaw << ' '; // round-trip verbatim — never our canonical spelling, never claimed as ours } // facet= and p= are single whitespace-delimited tokens, so a value that cannot be spelled as one is OMITTED, // the same closed-set rule by= uses (scopeSpecIsSpellable). A repository path may contain a space: written // verbatim, `p=my dir/a.py:1` read back as path `my`, line 0, with the rest pushed into the reason, and the // next ack committed that damage. A newline would split the record in two. An absent locator is the honest // degrade: nothing reads p= to decide anything, and the finding's own key still identifies the row. if( !r.facet.empty() && scopeSpecIsSpellable( r.facet ) ) { t << "facet=" << r.facet << ' '; } if( !r.path.empty() && scopeSpecIsSpellable( r.path ) ) { t << "p=" << r.path << ':' << r.line << ' '; } return t.str(); } // the ledger's CANONICAL bytes for this map — what writeAckRecords publishes. Exposed on its own (H10, // capture-audit 2026-09-04) so an ack with nothing to accept can tell "the file is already canonical, leave // it alone" from "the file needs healing (duplicate, legacy or misfiled rows) — rewrite it" by comparing // bytes, instead of rewriting unconditionally and moving rows under a run that changed no fact. inline std::string renderAckRecords( const gtl::btree_map& acks ) { std::ostringstream f; f << "# ripwire quality acks v1 — written by --quality-ack; a finding stays suppressed until it worsens past its acked magnitude\n"; f << "# format: ack <16-hex-key> [cid=<16-hex-content-id>] [by=] [now= was=] [prov=recon] [facet=] [p=:] — one per line, kept SORTED by (kind,key) on every write (merge-friendly)\n"; f << "# PROVENANCE: now=/was=/facet=/p= exist only on rows a provenance-aware binary WROTE OR REFRESHED (2026-09-22+); a legacy row heals FORWARD on its next --quality-ack. prov=recon marks a row a backfill RECONSTRUCTED from the CURRENT tree rather than measured when it was accepted: it answers 'would this be gating now', NOT 'was it gating then'. A recon row is a CACHE, not a dated record — every --quality-ack re-derives the ones whose clone group it can still find, so a checkable value is never older than the last ack; one whose group this run did NOT find is left untouched and counted as unverified on stderr, because not finding a group is a floor (scoped scan, capped file, different tree), never proof it is gone. Absent prov= means measured live, and a measurement is never overwritten by a reconstruction. Only the two clone kinds can be reconstructed (their key is a member-set hash, so today's idiom verdict is recomputable); a numeric row's was= still needs the commit that accepted it, which no field here records.\n"; for( const auto& [ mapKey, r ] : acks ) // btree order → byte-stable, always-sorted file (the merge-friendly guarantee) { char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( r.key ) ); f << "ack " << r.kind << ' ' << hex << ' ' << r.ackNow << ' '; // R1: cid= is OMITTED entirely when unavailable rather than written as a zero — a row that never had // a content identity must not be indistinguishable from one whose body hashed to 0, and a repo that // never acks under an R1 binary keeps a byte-identical ledger to the one it has today. if( r.cid != 0 ) { char cidHex[ 20 ]; rw::formatTo( cidHex, sizeof( cidHex ), "{:016x}", static_cast( r.cid ) ); f << "cid=" << cidHex << ' '; } // P1.4: same OMIT-when-unavailable rule cid= follows, and for the same reason — a repo whose sessions // never pass a scope keeps a ledger byte-identical to the one it has today, and an absent by= is // never confusable with a row written under an empty scope. if( !r.by.empty() ) { f << "by=" << r.by << ' '; } f << ackProvenanceTokens( r ) << ( r.reason.empty() ? "(no reason given)" : r.reason ) << '\n'; } return f.str(); } inline bool writeAckRecords( const std::string& path, const gtl::btree_map& acks ) { // F-04: composed into a string and PUBLISHED by tmp+rename (atomicWriteFile) rather than streamed into an // `ofstream(trunc)`. The bytes are identical — same header lines, same btree order, same per-row // formatting — but a reader can no longer observe the file mid-write. That was not hypothetical: one // concurrent run in eight left a single stray character on its own line in the committed ledger. if( !atomicWriteFile( path, renderAckRecords( acks ) ) ) { DISCLOSE( Diagnostics::answerRefused, "both callers report the failed publish and exit non-zero; no ledger is claimed written", "quality: cannot write acks file" ); return false; } return true; } // ─── R1 IDENTITY: ONE KEY SPACE, HEALED FORWARD ──────────────────────────────────────────────────────── // // THE SHAPE OF THIS FIX, and why it is a pre-pass rather than a change to every lookup. // // A finding's identity is `hash(path::scope::name)` (canonId hash) for eight kinds and `pathQualifiedKey` // for short-horizon-churn. Both are path-qualified, so `git mv` destroys them: measured on this repo's own // 0eacce7 — ten headers moved into src/infra/, not one byte of code changed — survival is 0 of 59 canonId // identities, 0 of 59 pathQualifiedKeys, 0 of 4 clone groups. Every ack recorded against those symbols died, // along with the reason someone wrote for accepting each one. // // The obvious repair — teach every baseline lookup and the ack ratchet to try an alias — means touching nine // call sites inside computeDelta plus applyAckRatchet, each an independent chance to get the direction // backwards. The repair actually taken is the opposite: leave every consumer alone and REKEY THE TWO // SIDECARS FORWARD into the identity the current tree uses, once, before anything reads them. The baseline // snapshot and the ack ledger are the only two things that carry a stale identity; heal those and // computeDelta, applyAckRatchet, computeStaleAcks and the --quality-ack writer are all rename-aware with no // edit at all. // // THIS IS AN EXTENSION OF pathQualifiedKey, NOT A SECOND KEY SPACE — the binding constraint from the // d593de3 churn-keying round ("pathQualifiedKey is THE one key space"). Nothing here invents a key. An alias // is the SAME rule (`relPath \0 scope \0 name`, or canonicalId) evaluated at a path the file provably used // to have, and the result is written back into the one space every consumer already reads. After the // pre-pass there is exactly one live identity per symbol, the current one. // // SELF-HEALING, which is what keeps this from being a permanent crutch: --quality-ack writes the rekeyed // ledger back out, so an ack rescued through a rename is stored at the CURRENT key and no longer depends on // the rename window surviving. The mechanism pays for itself once and then gets out of the way — the same // posture normalizeLegacyAckKind's migration takes. // // WHAT IS NOT REMAPPED, stated rather than quietly skipped: the two CLONE kinds. Their key is a hash over // the whole member SET's canonical ids (cloneGroupHash), so re-deriving it at ancestor paths needs the // current groups' membership, which lives inside computeDelta and not in either sidecar. A clone ack still // dies on a rename. Measured cost of that floor on the pre-experiment's five rename commits: 5 clone groups // in total, against 187 per-symbol identities. Recorded as a known floor, not fixed by guessing. struct IdentityAliases { // ancestor-derived key → the key the same symbol has NOW. Holds BOTH key spaces at once: they hash // different strings, so one map serves canonId-hash and pathQualifiedKey lookups without either knowing. gtl::btree_map toCurrent; std::size_t ambiguousDropped = 0; // an ancestor key two current symbols both claim — refused, never guessed // 2026-08-25 SCHEME MIGRATION (the scope-less fold round). Alias sources contributed by addSchemeAliases // rather than by the rename record, kept separate ONLY so the disclosure can say which mechanism moved an // ack — "git recorded a rename" and "the key rule itself changed" are different claims and collapsing them // would hide which one the tool relied on. Both are kept SORTED by addSchemeAliases, and membership is a // plain std::binary_search at the two call sites (one each) — deliberately NOT wrapped in a predicate // member, because a single-use three-line binary_search wrapper is structurally indistinguishable from // every other one in the tree, and --quality-delta correctly reports it as a new clone of a reused helper. std::vector schemeKeys; // old-scheme key → new-scheme key, unambiguously std::vector schemeAmbiguousKeys; // old-scheme identity that FOLDED across files — refused gtl::btree_map> renamedFrom; // current relative path → its recorded earlier paths (Snapshot::renamedFrom) }; // Derive every alias the rename map licenses for the CURRENT tree. Costs nothing when nothing was renamed: // `ancestorsOf` is a single btree miss per FILE (memoized below), and the overwhelmingly common answer is // "no ancestors", which skips the symbol loop entirely. inline IdentityAliases identityAliases( const IngestResult& ing, const Graph& g, std::string_view root, const RenameMap& renames ) { IdentityAliases al; if( !renames.available || renames.previousOf.empty() ) { return al; } // per-FILE memo: ancestorsOf walks a chain, and a file with 200 symbols must not walk it 200 times. std::vector> ancByFile( ing.files.size() ); std::vector ancKnown( ing.files.size(), 0 ); const auto link = [ & ]( std::uint64_t from, std::uint64_t to ) { if( from == to || from == 0 || to == 0 ) { return; // a scope-less canonId degrades to the bare name and is already path-independent } const auto [ it, inserted ] = al.toCurrent.emplace( from, to ); if( !inserted && it->second != to ) { // Two current symbols both claim one ancestor identity (a rename chain that forked, or a file // renamed away and a new one put back at the old path). Which one owns the ack is unknowable // from the rename record alone, so NEITHER does. it->second = 0; ++al.ambiguousDropped; } }; for( NodeId i = 0; i < ing.symbols.size(); ++i ) { const Symbol& s = ing.symbols[i]; if( s.fileId >= ing.files.size() ) { continue; } const std::string rel{ relForHash( ing.files[ s.fileId ], root ) }; if( !ancKnown[ s.fileId ] ) { ancByFile[ s.fileId ] = renames.ancestorsOf( rel ); ancKnown[ s.fileId ] = 1; } if( ancByFile[ s.fileId ].empty() ) { continue; } al.renamedFrom.try_emplace( rel, ancByFile[ s.fileId ] ); const bool hasCanon = ( i < g.canonId.size() && !g.canonId[i].empty() ); const std::uint64_t curCanon = hasCanon ? fnv1a64( canonicalId( rel, s.scope, s.name ) ) : 0; const std::uint64_t curPath = pathQualifiedKey( rel, s ); for( const std::string& anc : ancByFile[ s.fileId ] ) { if( hasCanon ) { link( fnv1a64( canonicalId( anc, s.scope, s.name ) ), curCanon ); } link( pathQualifiedKey( anc, s ), curPath ); } } // drop the entries poisoned by ambiguity above, so no consumer has to know about the 0 sentinel for( auto it = al.toCurrent.begin(); it != al.toCurrent.end(); ) { it = ( it->second == 0 ) ? al.toCurrent.erase( it ) : std::next( it ); } return al; } // THE SCHEME MIGRATION (2026-08-25, the scope-less fold round) — the second alias source, and the reason the // key-space fix does not cost 270 hand-written ack reasons. // // Every quality kind that used to key on `fnv1a64( canonicalId(...) )` now keys on pathQualifiedKey (see // qualityKey). Those hash DIFFERENT strings — `p::s::n` versus `p\0s\0n` — so every committed ack row in this // repo's ledger names a key nothing computes any more. Rather than invalidate them, we REPLAY: for each symbol // in the current tree both keys are pure functions of the same (path, scope, name), so the old→new map is // derivable exactly, with no git history, no similarity threshold and no heuristic. It is fed into the SAME // `toCurrent` map the rename route uses, so remapSnapshotIdentity / remapAckIdentity / computeStaleAcks need // no edit at all — a migration is an old-key → new-key map, which is precisely what that machinery consumes. // // IDEMPOTENT BY CONSTRUCTION, which is what makes it safe to run unconditionally and forever: an ack ALREADY // at its new key is not an alias SOURCE (no symbol's old key equals another's new key — they hash different // byte strings), so a migrated ledger passes through untouched. No ledger version flag, no transition window, // and --quality-ack writes the healed rows back so a rescued ack stops depending on the replay at all. // // WHERE IT REFUSES, and why that is the honest answer. The OLD side is MANY-TO-ONE exactly where this round's // defect was: a scope-less name folded across N files has ONE old key and N new keys, so the ledger cannot say // which file's symbol the human accepted. Those identities are poisoned and recorded in schemeAmbiguousKeys — // never fanned out to all N (that would claim the human acked N findings when they acked one) and never // assigned to an arbitrary one. Measured on this repo at 7a42a67: 6 ack rows land here, and they are NAMED in // the report rather than folded into a total. // // A poisoned identity is counted ONCE, not once per extra claimant — 74 files defining `main` is one // unknowable ack target, not 73 of them. inline void addSchemeAliases( IdentityAliases& al, const IngestResult& ing, const Graph& g, std::string_view root ) { gtl::btree_map mig; for( NodeId i = 0; i < ing.symbols.size(); ++i ) { const Symbol& s = ing.symbols[i]; if( s.fileId >= ing.files.size() || i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } const std::string rel{ relForHash( ing.files[ s.fileId ], root ) }; const std::uint64_t oldKey = fnv1a64( canonicalId( rel, s.scope, s.name ) ); const std::uint64_t newKey = pathQualifiedKey( rel, s ); if( oldKey == newKey || oldKey == 0 || newKey == 0 ) { continue; } const auto [ it, inserted ] = mig.emplace( oldKey, newKey ); if( !inserted && it->second != newKey ) { if( it->second != 0 ) { al.schemeAmbiguousKeys.push_back( oldKey ); // first time this identity forked — record it once } it->second = 0; } } for( const auto& [ from, to ] : mig ) { if( to == 0 ) { continue; // poisoned above — refused, never guessed } // ADD, NEVER OVERWRITE: a rename alias already claiming this source is the more specific statement // (git recorded an actual move) and keeps precedence. if( al.toCurrent.emplace( from, to ).second ) { al.schemeKeys.push_back( from ); } } std::sort( al.schemeKeys.begin(), al.schemeKeys.end() ); std::sort( al.schemeAmbiguousKeys.begin(), al.schemeAmbiguousKeys.end() ); } // The two transient rename facts the delta reads (Snapshot::renamedFrom, Snapshot::renamedKeys), from the RENAME aliases only and // BEFORE remapSnapshotIdentity: a key counts as re-filed only when the alias fills a hole (its source is in the baseline and its // target is not), so a file renamed long before the baseline (the ledger's 400-commit window) marks nothing. inline void noteRenamedIdentities( Snapshot& base, const IdentityAliases& al ) { base.renamedFrom = al.renamedFrom; base.renamedKeys.clear(); for( const auto& [ from, to ] : al.toCurrent ) { if( base.locBySym.contains( from ) && !base.locBySym.contains( to ) ) { base.renamedKeys.push_back( to ); } } std::sort( base.renamedKeys.begin(), base.renamedKeys.end() ); base.renamedKeys.erase( std::unique( base.renamedKeys.begin(), base.renamedKeys.end() ), base.renamedKeys.end() ); } // The defect-shape records: a renamed definition's sites are re-filed under its current anchor, add-never- // overwrite like the per-symbol maps (an anchor the baseline already holds keeps its own records). Whether a site // is NEW never depends on this — that is decided by its text, repo-wide — only the row's was= count does. inline std::size_t healDefectSites( Snapshot& base, const IdentityAliases& al ) { std::size_t healed = 0; std::vector addSites; // ADD, NEVER OVERWRITE, per `to` anchor: two alias sources that converge on one current anchor (a scheme alias and a // rename alias, CodeRabbit on #383) must not both copy their sites under it — the baseline check above only sees // anchors the baseline already held, not ones this loop filled. The first alias in `from` order fills; the rest skip. std::vector filledTo; for( const auto& [ from, to ] : al.toCurrent ) { const auto lo = std::lower_bound( base.defectSites.begin(), base.defectSites.end(), DefectSiteKey{ from, 0 } ); const auto toLo = std::lower_bound( base.defectSites.begin(), base.defectSites.end(), DefectSiteKey{ to, 0 } ); if( toLo != base.defectSites.end() && toLo->anchor == to ) { continue; } if( lo == base.defectSites.end() || lo->anchor != from ) { continue; // nothing to copy: an alias with no recorded sites must not claim the anchor } if( std::find( filledTo.begin(), filledTo.end(), to ) != filledTo.end() ) { continue; } filledTo.push_back( to ); for( auto it = lo; it != base.defectSites.end() && it->anchor == from; ++it ) { addSites.push_back( { to, it->site } ); ++healed; } } if( !addSites.empty() ) { base.defectSites.insert( base.defectSites.end(), addSites.begin(), addSites.end() ); std::sort( base.defectSites.begin(), base.defectSites.end() ); } return healed; } // MOVES: a move record is RE-KEYED by a rename alias, never copied. A copy left the old key behind as a VACATED body (MovedBodies) // while the same body still sits at the new key, so its sketch could pass a new look-alike off as moved (#646 CR). Dropping the old // key only removes a move source, so it can only make a row gate, never exempt one. Add-never-overwrite, as healMap. The count re-keyed. template inline std::size_t rekeyMoveRecords( Map& m, const IdentityAliases& al ) { std::size_t n = 0; for( const auto& [ from, to ] : al.toCurrent ) { const auto src = m.find( from ); if( src == m.end() || m.find( to ) != m.end() ) { continue; } auto v = std::move( src->second ); m.erase( src ); m[ to ] = std::move( v ); ++n; } return n; } // Heal a BASELINE snapshot forward: an entry recorded under a pre-rename identity is re-filed under the // identity the current tree uses, so computeDelta's `was` lookups, its origin oracle and its churn join all // find it without a single edit to any of them. // // ADD, NEVER OVERWRITE. A current key that the baseline ALREADY holds is left exactly as it is: that is a // symbol which genuinely exists at this identity on both sides, and letting a rename alias overwrite it // would substitute one symbol's history for another's. The alias only ever fills a HOLE. inline std::size_t remapSnapshotIdentity( Snapshot& base, const IdentityAliases& al ) { if( al.toCurrent.empty() ) { return 0; } std::size_t moved = 0; const auto healMap = [ & ]( auto& m ) { for( const auto& [ from, to ] : al.toCurrent ) { const auto src = m.find( from ); if( src != m.end() && m.find( to ) == m.end() ) { m[ to ] = src->second; ++moved; } } }; healMap( base.ccxBySym ); healMap( base.locBySym ); healMap( base.nestBySym ); healMap( base.paramsBySym ); healMap( base.defsBySym ); healMap( base.maskBySym ); healMap( base.maskReportBySym ); healMap( base.failureDefaultBySym ); healMap( base.placeholderBySym ); healMap( base.bodyHashBySym ); moved += rekeyMoveRecords( base.moveCidBySym, al ); (void) rekeyMoveRecords( base.bodyCidBySym, al ); // QD-RENAME-IDENTITY: re-keyed like the move record, so the old key is no vacated body (void) rekeyMoveRecords( base.moveSketchBySym, al ); // its sketch follows it; not a separate healed key in the count // the two SORTED SETS — same add-never-overwrite rule, then restore the sorted invariant every // std::binary_search consumer depends on. const auto healSet = [ & ]( std::vector& v ) { std::vector add; for( const auto& [ from, to ] : al.toCurrent ) { if( std::binary_search( v.begin(), v.end(), from ) && !std::binary_search( v.begin(), v.end(), to ) ) { add.push_back( to ); ++moved; } } if( !add.empty() ) { v.insert( v.end(), add.begin(), add.end() ); std::sort( v.begin(), v.end() ); v.erase( std::unique( v.begin(), v.end() ), v.end() ); } }; healSet( base.dead ); healSet( base.publicApi ); // base.cloneGroups is deliberately untouched — see the WHAT IS NOT REMAPPED note above. moved += healDefectSites( base, al ); return moved; } // QD-GIT-RENAME-HEAL — dead-code rows from `from` on whose symbol the git rename record re-filed: non-gating, origin="moved", as a // ContentMoves match reads (a move does not decide reachability; a caller the move left pointing at the old path, or one the // resolver cannot follow to the new one, would otherwise gate as a live function that died). inline void markRenamedDeadRows( std::vector& regs, std::size_t from, const std::vector& renamedKeys ) { for( std::size_t k = from; k < regs.size() && !renamedKeys.empty(); ++k ) { if( !regs[k].isNewSymbol && std::binary_search( renamedKeys.begin(), renamedKeys.end(), regs[k].key ) ) { regs[k].isNewSymbol = regs[k].isMoved = true; } } } // QD-RENAME-IDENTITY (2026-11-14) — A RENAME OR A MOVE KEEPS ITS IDENTITY. The quality key is path::scope::name, so renaming a // function (callers renamed with it) or moving it to a sibling file gave it a new key: every kind read it as new code. Measured on // the QD-CATCH-HONEST neutrals (reports/qd-catch-fresh-2026-11-13.md, ADDENDUM 2026-11-14): 13/45 renames and 5/30 moves left a // row, 4 renames GATED — each renamed function was one member of an existing clone pair, and the pair's member-set hash changed // with the name, so the old pair read as new duplication. The other rows were the renamed or moved body re-reported as new // (params, dead-code, error-masking) or as moved (complexity, nesting, verbosity). // THE ONE MATCHING RULE, for every kind: a baseline key whose body is GONE (no current symbol at the key carries it: the key is gone, // or only a declaration or another body is left there, the MOVES "vacated" rule) and a NEW key (absent // from the baseline) whose one callable carries the SAME body identity (moveCidOf: the body after the signature, whitespace and its // own name scrubbed) are one symbol, when that identity is carried by exactly one gone key and exactly one new key (a tie refuses: // floors, not guesses) and neither key is an overload set. EXACT equality, never similarity: a body that also changed is not // matched here and keeps today's reading (new-symbol, or moved by sketch over a bar), so a worsening carried in with a rename still // shows. The match RE-FILES the baseline forward (remapSnapshotIdentity, the git-rename route's own healing, on a copy), so every // per-symbol kind compares the renamed body with itself and finds nothing — except the short-horizon-churn body hash, which is a // raw-byte hash over the signature too (it would read the rename as a rewrite), and two facts a body does not decide, which stay // non-gating as before: a matched symbol that is dead now reads origin="moved"; one that turned public counts in api-new-surface=. // The two clone kinds keep their member-set hash; a current group the baseline did not hold is held when one member is a matched // symbol and every member's body identity equals its (re-filed) baseline one: the same bodies, so the same duplication. struct ContentMoves { gtl::btree_map toCurrent; // gone baseline key → the new key that carries its body gtl::btree_set targetSet; // the new keys ContentMoves( const Snapshot& base, const std::vector& keyOf, const std::vector& bodyOf ) { std::vector> fresh = newKeyBodies( base, keyOf, bodyOf ); // (identity, key) if( fresh.empty() ) { return; // nothing new: nothing can be a renamed or moved body (the common case, one pass over the keys) } const std::vector> gone = goneKeyBodies( base, keyOf, bodyOf ); // (identity, key), sorted std::sort( fresh.begin(), fresh.end() ); for( std::size_t a = 0; a < fresh.size(); ++a ) { const std::uint64_t cid = fresh[a].first; const bool one = ( a == 0 || fresh[ a - 1 ].first != cid ) && ( a + 1 == fresh.size() || fresh[ a + 1 ].first != cid ); const auto [ lo, hi ] = std::equal_range( gone.begin(), gone.end(), std::pair{ cid, 0 }, []( const auto& x, const auto& y ) { return x.first < y.first; } ); if( one && hi - lo == 1 ) { toCurrent.emplace( lo->second, fresh[a].second ); targetSet.insert( fresh[a].second ); } } } bool empty() const noexcept { return toCurrent.empty(); } bool isTarget( std::uint64_t key ) const { return targetSet.contains( key ); } // The baseline re-filed under the new keys (add-never-overwrite, remapSnapshotIdentity). The churn body hash is not: see above. Snapshot healed( const Snapshot& base ) const { Snapshot out = base; IdentityAliases al; al.toCurrent = toCurrent; (void) remapSnapshotIdentity( out, al ); for( std::uint64_t k : targetSet ) { out.bodyHashBySym.erase( k ); } return out; } // The baseline the delta reads: `baseline` itself when nothing matched, else the healed copy kept in `store`. Pointers // in and out, not a const& handed back from a const& parameter: that one binds a temporary baseline and returns a // reference that dangles past the caller's full expression, while &temporary does not compile. const Snapshot* baseFor( const Snapshot* baseline, std::optional& store ) const { if( empty() ) { return baseline; } return &store.emplace( healed( *baseline ) ); } // Dead-code rows from `from` on: a matched symbol dead now stays non-gating (origin="moved") — a body does not decide reachability. void markMovedDeadRows( std::vector& regs, std::size_t from ) const { for( std::size_t k = from; k < regs.size(); ++k ) { if( !regs[k].isNewSymbol && isTarget( regs[k].key ) ) { regs[k].isNewSymbol = regs[k].isMoved = true; } } } // A current clone group the baseline did not hold by its member set, held because a matched symbol is in it and every member's // body is the one the (re-filed) baseline recorded under its key. `base` is the healed snapshot. bool holdsCloneGroup( const CloneGroup& cg, const Snapshot& base, const std::vector& keyOf, const std::vector& bodyOf ) const { if( empty() ) { return false; } bool matched = false; for( NodeId m : cg.members ) { const std::uint64_t key = m < keyOf.size() ? keyOf[m] : 0; const auto cid = base.bodyCidBySym.find( key ); const auto defs = base.defsBySym.find( key ); if( key == 0 || m >= bodyOf.size() || cid == base.bodyCidBySym.end() || cid->second != bodyOf[m] || defs == base.defsBySym.end() || defs->second != 1 ) { return false; } matched = matched || isTarget( key ); } return matched; } private: // (identity, key) of each baseline key whose one callable's body no current symbol at the key carries, sorted. static std::vector> goneKeyBodies( const Snapshot& base, const std::vector& keyOf, const std::vector& bodyOf ) { std::vector> held; // (key, identity) of every current symbol (identity 0: no callable body) for( NodeId i = 0; i < keyOf.size(); ++i ) { if( keyOf[i] != 0 ) { held.emplace_back( keyOf[i], i < bodyOf.size() ? bodyOf[i] : 0 ); } } std::sort( held.begin(), held.end() ); std::vector> gone; // (identity, key): the key no longer carries that body (gone, or a // declaration or other body left at it: the MOVES "vacated" rule) for( const auto& [ key, cid ] : base.bodyCidBySym ) { const auto defs = base.defsBySym.find( key ); if( defs != base.defsBySym.end() && defs->second == 1 && !std::binary_search( held.begin(), held.end(), std::pair{ key, cid } ) ) { gone.emplace_back( cid, key ); } } std::sort( gone.begin(), gone.end() ); return gone; } // (identity, key) of each new key (absent from the baseline) that one callable alone carries. static std::vector> newKeyBodies( const Snapshot& base, const std::vector& keyOf, const std::vector& bodyOf ) { std::vector> fresh; // (key, node) for( NodeId i = 0; i < keyOf.size(); ++i ) { if( keyOf[i] != 0 && base.locBySym.find( keyOf[i] ) == base.locBySym.end() ) { fresh.emplace_back( keyOf[i], i ); } } std::sort( fresh.begin(), fresh.end() ); std::vector> out; for( std::size_t a = 0; a < fresh.size(); ++a ) { const bool one = ( a == 0 || fresh[ a - 1 ].first != fresh[a].first ) && ( a + 1 == fresh.size() || fresh[ a + 1 ].first != fresh[a].first ); const NodeId i = fresh[a].second; const std::uint64_t body = i < bodyOf.size() ? bodyOf[i] : 0; if( one && body != 0 ) { out.emplace_back( body, fresh[a].first ); } } return out; } }; // Which mechanism rescued a given ack row. Kept per-row (not just as a total) so the report can disclose the // ROUTE — "your ack survived because git recorded the rename" and "because the body is byte-for-byte the // same after scrubbing" are different claims with different trust, and collapsing them would hide which one // the tool actually relied on. enum class AckRescueRoute : std::uint8_t { Rename = 1, Content = 2, Scheme = 3 }; struct AckRemap { gtl::btree_map routeOf; // the REKEYED ack's new mapKey → how it got there std::size_t renameRekeyed = 0; std::size_t contentRekeyed = 0; std::size_t schemeRekeyed = 0; // 2026-08-25: re-filed from the pre-fold-fix canonId key space }; // Heal the ACK LEDGER forward, by the same add-never-overwrite rule, through two routes in strict priority: // // 1. RENAME (exact). git recorded the move; the alias is the same identity rule at a path the file // provably had. 100% recovery on all four structural rename commits in this repo's history. // 2. CONTENT (exact equality on a scrubbed body, and only when nothing else can answer). This is the case // git records NO rename for at all — a symbol relocated between two files that both merely "changed", // which produces no `R` row for route 1 to read. THREE conditions, all required: // (a) the ack's own key names no symbol in the current tree — a LIVE ack is never second-guessed; // (b) the ack carries a cid, i.e. it was written by a binary that records one (see AckRecord::cid — // this route can never rescue the 443 rows already committed here, and the report says so); // (c) the cid is unique in the tree. A body shared by two symbols is a clone pair, and letting one // ack cover either of them would suppress a finding nobody accepted. Ambiguity refuses to // resolve — the same floors-not-guesses rule computeStaleAcks applies to a clone-group key. // // What neither route does is match a body that CHANGED. The scrub erases whitespace and the symbol's own // name and nothing else (see scrubbedBody), so a rewritten body has a different cid and is a different // finding. Identity that follows a rename must not become identity that follows a rewrite; that is the blank // check the ack contract forbids, and test/identitycheck.sh arms (4) and (7) hold the line. inline AckRemap remapAckIdentity( gtl::btree_map& acks, const IdentityAliases& al, const ContentIdIndex* cids ) { AckRemap out; if( acks.empty() ) { return out; } // Collect first, mutate after: rekeying erases and inserts, and doing that under an iterator over the // same btree is exactly the shape that turns a correct rule into an intermittent one. struct Move { std::string fromMapKey; std::uint64_t toKey; AckRescueRoute route; }; std::vector moves; for( const auto& [ mapKey, rec ] : acks ) { const auto alias = al.toCurrent.find( rec.key ); if( alias != al.toCurrent.end() ) { // Same map, two mechanisms — report which one actually moved this row (see IdentityAliases). const bool byScheme = std::binary_search( al.schemeKeys.begin(), al.schemeKeys.end(), rec.key ); moves.push_back( { mapKey, alias->second, byScheme ? AckRescueRoute::Scheme : AckRescueRoute::Rename } ); continue; } if( rec.cid == 0 || cids == nullptr ) { continue; } if( cids->cidByKey.find( rec.key ) != cids->cidByKey.end() ) { continue; // (a) the ack's target is alive at its own key — nothing to rescue } if( !cids->isUnique( rec.cid ) ) { continue; // (c) two symbols share this scrubbed body — refuse to pick one } const auto byCid = cids->keyByCid.find( rec.cid ); if( byCid != cids->keyByCid.end() && byCid->second != rec.key ) { moves.push_back( { mapKey, byCid->second, AckRescueRoute::Content } ); } } for( const Move& m : moves ) { const auto src = acks.find( m.fromMapKey ); if( src == acks.end() ) { continue; } AckRecord rec = src->second; const std::string newKey = ackMapKey( rec.kind, m.toKey ); if( newKey == m.fromMapKey ) { continue; } const auto dst = acks.find( newKey ); if( dst != acks.end() ) { // A row already sits at the destination — the same D2 rule readAckRecords applies to a duplicate: // the ratchet floor may only ever go UP, so keep the max and leave the surviving reason with it. if( rec.ackNow > dst->second.ackNow ) { dst->second.ackNow = rec.ackNow; dst->second.reason = rec.reason; } acks.erase( src ); continue; } rec.key = m.toKey; acks.erase( src ); acks.emplace( newKey, rec ); out.routeOf[ newKey ] = m.route; switch( m.route ) { case AckRescueRoute::Rename: out.renameRekeyed += 1; break; case AckRescueRoute::Content: out.contentRekeyed += 1; break; case AckRescueRoute::Scheme: out.schemeRekeyed += 1; break; } } return out; } // Is `r` currently suppressed by an ack in `acks` — same lookup applyAckRatchet uses (ackKindToken, not the // bare kind: a ZERO-magnitude finding acks on identity + ORIGIN, so an ack against the never-gating // new-symbol row can never suppress the gating contract-change row for the same symbol), factored out so a // caller that needs the ANSWER without mutating the vector (partitionByScope's out-of-scope disclosure, // F-05 fix below) does not re-derive the map key by hand. Returns the record so a caller can also read its // `by=` provenance. inline const AckRecord* findSuppressingAck( const Regression& r, const gtl::btree_map& acks ) { const std::string token = ackKindToken( r ); auto it = acks.find( ackMapKey( token, r.key ) ); if( ( it == acks.end() || r.now > it->second.ackNow ) && token.ends_with( kAckReportOnlySuffix ) ) { it = acks.find( ackMapKey( r.kind, r.key ) ); // QD-ACK-GATING-SPLIT: a gating ack covers the report-only row } return ( it != acks.end() && r.now <= it->second.ackNow ) ? &it->second : nullptr; } // How many findings a rekeyed ack ACTUALLY suppressed, split by route. Counted BEFORE applyAckRatchet erases // them — the honest denominator for the disclosure is the suppression, not the rekey: an ack can be healed // forward and still not hide anything (the finding may have worsened past its floor, or stopped firing). inline void countAckRescues( const std::vector& regs, const gtl::btree_map& acks, const AckRemap& remap, std::size_t& byRename, std::size_t& byContent ) { byRename = byContent = 0; if( remap.routeOf.empty() ) { return; } for( const Regression& r : regs ) { const AckRecord* ack = findSuppressingAck( r, acks ); if( ack == nullptr ) { continue; // not suppressed — the ratchet still fires on it } const auto route = remap.routeOf.find( ackMapKey( ack->kind, ack->key ) ); if( route != remap.routeOf.end() ) { ( route->second == AckRescueRoute::Rename ? byRename : byContent ) += 1; } } } // ─── R1 IDENTITY: the ONE entry point both --quality-delta surfaces call ─────────────────────────────── // // The CLI arm and the MCP quality_delta verb are two surfaces over one computation, and the §B6/R3 lesson // from the baseline-staleness split is that the moment each carries its OWN copy of a rule they answer the // same question differently in the same second. So the whole identity pre-pass is one call, and neither // surface gets to decide any part of it. // // COST, and why it is not paid by default: `renames` costs a few short git spawns; with an empty ledger only the // uncommitted renames (or the range) are read, since the baseline itself must still follow a recorded rename // (QD-GIT-RENAME-HEAL), and the 400-commit window is the ledger's alone. `cids` costs one pass over the corpus's file bytes and is skipped // unless the ledger can actually USE it — i.e. some row carries a cid, or we are about to WRITE cids under // --quality-ack. A repo that has never acked under an R1 binary therefore pays nothing at all, and one that // has pays the pass once per delta. That gating is the reason contentIdsBySym is not folded into // bodyHashesBySym, which the churn kind runs unconditionally. struct IdentityHealing { RenameMap renames; ContentIdIndex cids; IdentityAliases aliases; AckRemap ackRemap; bool cidsComputed = false; bool gitOnly = false; // QD-GIT-RENAME-HEAL: no ledger — only the baseline was re-filed, by the git record alone std::size_t baselineKeysMoved = 0; std::size_t ackedByRename = 0; // filled by countAckRescues, AFTER computeDelta std::size_t ackedByContent = 0; std::size_t schemeAmbiguousAcks = 0; // 2026-08-25: ack rows whose pre-fix identity folded across files }; // TWO ROOTS, deliberately not one. `corpusRoot` is the tree being JUDGED — every key is spelled relative to // it (the S2 root-relative rule), and its bytes are what contentIdsBySym reads. `gitRoot` is where the rename // RECORD lives. They are the same directory in the working-tree form and different in the ref-pair form, // where the judged tree is a materialized temp dir with no git history at all: passing one root there would // silently lose every rename in the very wave being measured, which is the failure mode this round exists to // end. Collapsing them into one parameter is therefore a bug waiting for the next ref-pair caller. // `treeWideRescues` (qd-memory-degrade): false when `ing` holds only the changed files. The scheme re-key and the content-id // rescue both refuse an identity that is ambiguous ACROSS THE TREE (two files defining one scope-less name, two equal // bodies), and a partial index cannot see that ambiguity — it would rescue what the full run refuses. So both are skipped // there (and said: also_skipped= names ack-healing); the git rename route is per-path and runs as always. inline IdentityHealing healIdentity( Snapshot& base, gtl::btree_map& acks, const IngestResult& ing, const Graph& g, const std::string& corpusRoot, const std::string& gitRoot, bool wantContentIds, const std::string& span = {}, bool treeWideRescues = true ) { IdentityHealing h; if( acks.empty() && !wantContentIds ) { // QD-GIT-RENAME-HEAL: no ledger to heal or write, but the BASELINE still follows a git-recorded rename (a whole-file `git mv` // whose functions have twins elsewhere matches no body uniquely, so ContentMoves cannot carry it). Only what can separate // the two sides is read — the uncommitted renames (the baseline is HEAD's), or the range — and nothing the ledger needs // runs: no scheme re-key (it re-files ack rows), no content ids, no ack remap. A tree with no rename pays three small git // spawns; the disclosure stays silent unless a pair was recorded (identityDisclosure). h.gitOnly = true; h.renames = span.empty() ? gitUncommittedRenameMap( gitRoot ) : gitRenameMap( gitRoot, span ); h.aliases = identityAliases( ing, g, corpusRoot, h.renames ); noteRenamedIdentities( base, h.aliases ); h.baselineKeysMoved = remapSnapshotIdentity( base, h.aliases ); return h; } h.renames = gitRenameMap( gitRoot, span ); h.aliases = identityAliases( ing, g, corpusRoot, h.renames ); noteRenamedIdentities( base, h.aliases ); // before the scheme aliases join toCurrent: only what the rename record re-filed // The SCHEME migration is not gated on git: the key rule changed in the binary, not in the history, so a // repo with no rename record at all still needs its committed acks re-filed. Runs after the rename pass so // a git-recorded move keeps precedence over the mechanical rekey (add-never-overwrite). if( treeWideRescues ) { addSchemeAliases( h.aliases, ing, g, corpusRoot ); } h.baselineKeysMoved = remapSnapshotIdentity( base, h.aliases ); // Ack rows whose old identity FOLDED across files — countable only here, where both the ledger and the // poisoned set are in scope. Disclosed, never silently dropped: they stay in the ledger at their old key // and surface through stale= as well, so nothing vanishes without a row saying so. const auto& amb = h.aliases.schemeAmbiguousKeys; for( const auto& [ mapKey, rec ] : acks ) { (void) mapKey; if( std::binary_search( amb.begin(), amb.end(), rec.key ) ) { ++h.schemeAmbiguousAcks; } } const bool ledgerHasCid = std::any_of( acks.begin(), acks.end(), []( const auto& kv ) { return kv.second.cid != 0; } ); if( treeWideRescues && ( wantContentIds || ledgerHasCid ) ) { h.cids = contentIdsBySym( ing, g, corpusRoot ); h.cidsComputed = true; } h.ackRemap = remapAckIdentity( acks, h.aliases, h.cidsComputed ? &h.cids : nullptr ); return h; } // The identity disclosure, as an {XML attrs, JSON attrs} pair. ONE definition for both emitters: an // attribute that exists on one --quality-delta surface and not the other is the §B6 M5 divergence this // codebase has already paid for once, and a report about IDENTITY is the last place to reintroduce it. // // Every attribute is absent entirely when git could not be read at all, and the three TRUNCATION attrs are // absent unless true — the same optional-attribute convention the rest of this root follows, spelled out in // the legend so an absent one is never read as a silent "no". inline std::pair identityDisclosure( const IdentityHealing& h ) { std::string attrs, json; const auto add = [ & ]( const char* name, unsigned long long v ) { attrs += " " + std::string( name ) + "=\"" + std::to_string( v ) + "\""; json += ",\"" + std::string( name ) + "\":" + std::to_string( v ); }; // The SCHEME attrs come FIRST and are NOT gated on the git rename record: the 2026-08-25 key-space change // is a fact about this binary, not about this repo's history, so a tree git cannot be read in still had its // acks re-filed and still deserves to be told. Both are absent unless non-zero (the optional-attribute // convention of this root), so an absent one is never a silent "no". if( h.ackRemap.schemeRekeyed ) { add( "acks_rekeyed_by_scheme", h.ackRemap.schemeRekeyed ); } if( h.schemeAmbiguousAcks ) { add( "scheme_ambiguous", h.schemeAmbiguousAcks ); } if( !h.renames.available || ( h.gitOnly && h.renames.pairsRecorded == 0 ) ) { return { attrs, json }; // QD-GIT-RENAME-HEAL: a no-ledger run that read no rename says nothing (it re-filed nothing) } add( "renames", h.renames.pairsRecorded ); add( "rename_window_commits", h.renames.commitsScanned ); add( "acked_by_rename", h.ackedByRename ); add( "acked_by_content", h.cidsComputed ? h.ackedByContent : 0 ); if( h.renames.truncatedWindow ) { add( "renames_window_truncated", 1 ); } if( h.renames.truncatedPairs ) { add( "renames_truncated", 1 ); } if( h.aliases.ambiguousDropped ) { add( "renames_ambiguous", h.aliases.ambiguousDropped ); } return { attrs, json }; } // Drop every regression already acked at a magnitude ≥ its current `now`; return how many were suppressed // (the honest acked="N" header count). A worsened finding (now > acked floor) survives — the ratchet. inline std::size_t applyAckRatchet( std::vector& regs, const gtl::btree_map& acks ) { if( acks.empty() ) { return 0; } const std::size_t before = regs.size(); regs.erase( std::remove_if( regs.begin(), regs.end(), [ & ]( const Regression& r ) { return findSuppressingAck( r, acks ) != nullptr; } ), regs.end() ); return before - regs.size(); } // ─── L2 — STALE-ACK DISCLOSURE ───────────────────────────────────────────────────────────────────────── // // `.ripwire_quality_acks` has acquisition (--quality-ack) and a worsen-past-acked-magnitude ratchet // (applyAckRatchet above) but no retirement surface: an ack whose target symbol was deleted, or whose // finding kind no longer fires on a symbol that survived, sits in the ledger forever, invisibly. A past // round hand-retired 109 such dead rows out of this repo's own committed acks file — a whole session of // manual audit for a question the tool could answer in one pass. The in-repo precedent for exactly this // shape is --notes: a note whose target no longer resolves is flagged dangling="1" against the LIVE // symbol/file set (main.cpp's --notes handler). This mirrors that pattern for acks. // // The wrinkle notes does not have: an ack's identity is a ONE-WAY HASH (`ackMapKey` = kind + hex(key)), // never the plain canonId, so there is no string to re-resolve — the check has to go the other direction, // hashing every CURRENT candidate and asking whether the acked key is still among them. `Snapshot` already // carries exactly the per-kind key spaces needed, computed once via computeSnapshot on the WORKING TREE // (never the regression baseline — staleness asks "does this still describe reality", not "would it // regress again relative to some floor"): // complexity/verbosity/nesting/params — ccxBySym/locBySym/nestBySym/paramsBySym. locBySym is the // existence oracle (computeSnapshot populates it for EVERY symbol with a canonId, the same fact // computeDelta's r26 origin axis leans on); if the key survives, the matching metric's CURRENT value // decides whether it still crosses that kind's bar. // dead-code / api-surface — locBySym for existence, membership in the current `dead` / `publicApi` set // for whether the state the finding named is still true right now. // error-masking / placeholder — locBySym for existence, `maskBySym[key] > 0` / `placeholderBySym[key] > 0` // for whether a construct is still there (each map only carries symbols with at least one hit — see // constructCountsBySym — so absence IS zero, not "unknown"). // duplication / new-clone-of-reused-helper — the ack key IS a member-set hash (cloneGroupHash), not a // single symbol's key, so there is no one "target" to test existence of; only whether that EXACT group // still clones today is checkable. Its absence is reported finding-gone, never target-gone: decomposing // the hash back to its members is not possible from the ledger alone, and this project reports floors, // not guesses (CLAUDE.md's honesty contract) — claiming a symbol is "gone" with no evidence for it // would be exactly the kind of guess that contract forbids. // short-horizon-churn — the key is pathQualifiedKey, a third space; bodyHashBySym (populated for every // symbol with a real body) is its existence oracle. Whether the churn condition itself still holds // needs a HISTORICAL reference this function does not have, so a churn ack whose key still resolves to // a body is left alone: reporting finding-gone without evidence would be the same forbidden guess. // An unrecognized kind (a future addition, or a hand-edited line) is left unclassified rather than guessed // — same "degrade, do not fabricate" rule readAckRecords already applies to a malformed line. // // Deterministic by construction: `acks` is a gtl::btree_map, so iterating it is already (kind,key) sorted // — the emitted row order needs no extra sort. enum class StaleAckWhy : std::uint8_t { TargetGone, // no symbol/group this key could refer to exists at HEAD/current FindingGone, // the target still exists, but no finding of the acked kind currently fires on it ForeignScope, // P1.4 — the ack applies, but the scope recorded in its by= does not cover the path it is // suppressing: a session accepted debt outside what it was working on }; struct StaleAck { std::string kind; // the RAW ack kind token, including any :new-symbol/:preexisting facet (P0.3) std::uint64_t key = 0; StaleAckWhy why = StaleAckWhy::TargetGone; std::string by; // P1.4 — the recorded provenance, on ForeignScope rows only (empty otherwise) // M21(a) (capture-audit 2026-09-04, lens 0 M0-2) — WHICH ack this is, when the tree can still say. // Empty by default and filled by stampStaleAckIdentity; see it for the rule that decides when. std::string sym; // the display canonical id (baselineCanonId, root-relative) of the live symbol std::string path; // its root-relative file path std::uint32_t line = 0; // its 1-based defining line — emitted with `path` as p="path:line" }; inline const char* staleAckWhyToken( StaleAckWhy why ) noexcept { return why == StaleAckWhy::TargetGone ? "target-gone" : why == StaleAckWhy::FindingGone ? "finding-gone" : "foreign-scope"; } // One per-kind oracle, each returning nullopt for "not stale" — split out so the dispatcher below reads as // a flat kind->oracle table instead of one large branch-and-compute body (that shape was the round's own // first draft, at ccx=64: --quality-delta flagged it against itself, which is the gate this file's own // contract asks for — see the L2 header comment above for the per-kind RATIONALE these implement). // // complexity/verbosity/nesting/params share one shape: locBySym is the existence oracle, then the kind's // own metric map decides whether it still crosses that kind's bar. inline std::optional staleForMetricKind( std::string_view base, std::uint64_t key, const Snapshot& snap ) { if( snap.locBySym.find( key ) == snap.locBySym.end() ) { return StaleAckWhy::TargetGone; } const gtl::btree_map* m = ( base == "complexity" ) ? &snap.ccxBySym : ( base == "verbosity" ) ? &snap.locBySym : ( base == "nesting" ) ? &snap.nestBySym : &snap.paramsBySym; const std::uint32_t bar = ( base == "complexity" ) ? kCcxBar : ( base == "verbosity" ) ? kLocBar : ( base == "nesting" ) ? kNestBar : kParamBar; const auto it = m->find( key ); const std::uint32_t now = ( it == m->end() ) ? 0u : it->second; return ( now <= bar ) ? std::optional( StaleAckWhy::FindingGone ) : std::nullopt; } // dead-code / api-surface share one shape too: locBySym for existence, membership in the CURRENT set // (`dead` / `publicApi`) for whether the state the finding named is still true right now. inline std::optional staleForSetMembership( std::uint64_t key, const Snapshot& snap, const std::vector& liveSet ) { if( snap.locBySym.find( key ) == snap.locBySym.end() ) { return StaleAckWhy::TargetGone; } return std::binary_search( liveSet.begin(), liveSet.end(), key ) ? std::nullopt : std::optional( StaleAckWhy::FindingGone ); } // error-masking and placeholder share one shape: locBySym for existence, then the kind's per-symbol COUNT // map (maskBySym / placeholderBySym, each carrying only symbols with at least one hit, so absence IS zero). inline std::optional staleForConstructCount( std::uint64_t key, const Snapshot& snap, const gtl::btree_map& counts ) { if( snap.locBySym.find( key ) == snap.locBySym.end() ) { return StaleAckWhy::TargetGone; } const auto it = counts.find( key ); return ( it == counts.end() || it->second == 0 ) ? std::optional( StaleAckWhy::FindingGone ) : std::nullopt; } // duplication / new-clone-of-reused-helper: the key IS a member-set hash, not one symbol's key, so a miss // here is always finding-gone — never target-gone (decomposing the hash back to its members is not // possible from the ledger alone; see the L2 header comment for why that is the honest classification). inline std::optional staleForCloneKind( std::uint64_t key, const Snapshot& snap ) { return std::binary_search( snap.cloneGroups.begin(), snap.cloneGroups.end(), key ) ? std::nullopt : std::optional( StaleAckWhy::FindingGone ); } // short-horizon-churn: bodyHashBySym (pathQualifiedKey-keyed) is its existence oracle; whether the churn // condition itself still holds needs a historical reference this function does not have, so a surviving // key is left alone rather than guessed finding-gone (see the L2 header comment). inline std::optional staleForChurn( std::uint64_t key, const Snapshot& snap ) { return ( snap.bodyHashBySym.find( key ) == snap.bodyHashBySym.end() ) ? std::optional( StaleAckWhy::TargetGone ) : std::nullopt; } // defect-shape: the ack key is defectRowKey( anchor, facet, the anchor's site set of that facet ), so the facet // and the very sites are part of the finding's identity (one ack never suppresses a different shape, or a // different defect of the same shape, on the same definition). A key no current (anchor, facet) site set // produces is finding-gone — the acked defect was fixed, or another site of that facet joined or replaced it; // the anchor cannot be recovered from the mixed key, so target-gone is never claimed (the clone kinds' rule). inline std::optional staleForDefectShape( std::uint64_t key, const Snapshot& snap ) { const std::vector& sites = snap.defectSites; // sorted by (anchor, site): one anchor's records are contiguous const auto self = []( const DefectSiteKey& d RW_LIFETIMEBOUND ) -> const DefectSiteKey& { return d; }; for( auto it = sites.begin(); it != sites.end(); ) { const auto end = std::find_if( it, sites.end(), [ & ]( const DefectSiteKey& d ) { return d.anchor != it->anchor; } ); const std::span one( it, end ); for( std::size_t f = 0; f < defectshape::kFacetCount; ++f ) { const auto facet = static_cast( f ); const std::vector vals = defectSiteValsOf( one, it->anchor, facet, self ); if( !vals.empty() && defectRowKey( it->anchor, facet, vals ) == key ) { return std::nullopt; } } it = end; } return StaleAckWhy::FindingGone; } // Which oracle answers whether an ack of kind `base` is stale — one dispatch per finding kind. An unrecognized // kind (a future addition, or a hand-edited line) answers nullopt: left unclassified, never guessed. inline std::optional staleWhyForKind( std::string_view base, std::uint64_t key, const Snapshot& snap ) { std::optional why; if( base == "complexity" || base == "verbosity" || base == "nesting" || base == "params" ) { why = staleForMetricKind( base, key, snap ); } else if( base == "dead-code" ) { why = staleForSetMembership( key, snap, snap.dead ); } else if( base == "api-surface" ) { why = staleForSetMembership( key, snap, snap.publicApi ); } else if( base == "error-masking" ) { why = staleForConstructCount( key, snap, snap.maskBySym ); } else if( base == "placeholder" ) { why = staleForConstructCount( key, snap, snap.placeholderBySym ); } else if( base == "duplication" || base == "new-clone-of-reused-helper" ) { why = staleForCloneKind( key, snap ); } else if( base == "short-horizon-churn" ) { why = staleForChurn( key, snap ); } else if( base == "defect-shape" ) { why = staleForDefectShape( key, snap ); } return why; } inline std::vector computeStaleAcks( const gtl::btree_map& acks, const Snapshot& snap ) { std::vector out; for( const auto& [ mapKey, rec ] : acks ) { (void) mapKey; // the (kind,key) it was derived from — rec already carries both fields // The ':new-symbol' / ':preexisting' suffix (see ackKindToken) is an ORIGIN facet on a // zero-magnitude finding, not a different finding kind — strip it before dispatching so // "dead-code:preexisting" and "dead-code:new-symbol" both resolve to the one dead-code oracle. const std::size_t colon = rec.kind.find( ':' ); const std::string_view base = ( colon == std::string::npos ) ? std::string_view( rec.kind ) : std::string_view( rec.kind ).substr( 0, colon ); const std::optional why = staleWhyForKind( base, rec.key, snap ); // an unrecognized kind (a future addition, or a hand-edited line) is left unclassified rather than // guessed — same "degrade, do not fabricate" rule readAckRecords already applies to a malformed line. if( why.has_value() ) { out.push_back( { rec.kind, rec.key, *why, std::string{} } ); } } return out; } // P1.4 — THE PROVENANCE SWEEP, the thing `by=` exists to make answerable: is a row still SUPPRESSING a // finding whose path the scope that wrote it does not cover? That is a session having absorbed another // session's debt — the failure --scope's ack refusal prevents going forward, reported here for the rows // already in the ledger (this repo's own file carries hundreds, written long before provenance existed). // // Called on the PRE-ratchet finding list, because the question is about acks that are doing work right now: // the suppression predicate below is applyAckRatchet's, verbatim in meaning, so a row that has worsened past // its floor (and is therefore about to reappear anyway) is not reported. // // TWO FLOORS, stated because silence here would read as a guarantee. (1) Only acks currently suppressing a // finding are checkable — a row whose finding does not fire today has no path to test its provenance // against, and is left alone rather than guessed at. (2) A row with NO by= is not checked at all: absence of // provenance is not evidence of foreign provenance, and every row written before this feature existed, plus // every row written without a scope, is in that class. inline std::vector computeForeignAcks( const std::vector& regs, const gtl::btree_map& acks ) { std::vector out; if( acks.empty() ) { return out; } for( const Regression& r : regs ) { if( r.path.empty() ) { continue; // no locator ⇒ nothing to test the recorded scope against } const AckRecord* ack = findSuppressingAck( r, acks ); if( ack == nullptr || ack->by.empty() ) { continue; } const Scope by = parseScope( ack->by ); if( scopeUsesDiffToken( by ) ) { // THIRD FLOOR (P1.2): an AUTO-scope cannot be re-evaluated later. `diff` meant one file set at // ack time and means another now, so re-expanding it here would judge a past decision against a // present tree and manufacture foreign-ack rows out of ordinary progress. Not checked, and // stated rather than silently skipped. continue; } // F-05 fix (audit 2026-09-02, item 3): a clone finding's ONLY locator on the row itself is r.path, // the first-sorting member — but inclusion (scopeCovers, kScopeLegend's own words: "a clone kind is // in scope when ANY member matches, not just the first-sorting one") already uses the whole // memberPaths set. Testing provenance against r.path alone made a legitimate any-member ack — filed // by whichever owner's path happens to sort AFTER the first — read as foreign every time, a false // positive on exactly the shared-ownership case this scope feature exists for. scopeCovers is the // one predicate both questions ("is this finding covered by S") share; asking it of `by` here keeps // inclusion and provenance symmetric. if( !scopeCovers( by, r ) ) { // M21(a): a foreign-scope row is BUILT from a live Regression, so it names itself — no index // lookup, and no chance of the two disagreeing about the same finding's identity. out.push_back( { ack->kind, ack->key, StaleAckWhy::ForeignScope, ack->by, r.sym, r.path, r.line } ); } } return out; } // ── M21(a) — name the ack that went stale, wherever the tree can still name it ───────────────────────── // // `` is a 16-hex hash of an identity the // reader does not have. To act on the row — retire the ack, or look at why the finding stopped firing — // the agent had to open .ripwire_quality_acks and then reverse a hash it cannot reverse. On this repo's own // ledger that was ten rows and ten dead ends, in a document every other row family of which // (the gating rows) carries sym= and p="path:line". // // THE RULE IS DERIVABLE, NOT BEST-EFFORT, and it falls straight out of the oracles above: // * why="finding-gone" was REACHED by finding the key IN the current snapshot (that is precisely how each // oracle told finding-gone from target-gone), so the symbol exists right now and can be named. // * why="target-gone" means it is not there. There is nothing to name, and why= already says exactly that // — a fabricated name would be the worse answer. // * the two CLONE kinds key on a member-SET hash (cloneGroupHash) that no single symbol carries, so they // are never nameable from a symbol index. That is a FLOOR, stated in the legend, not papered over. // * why="foreign-scope" rows come from computeForeignAcks, which already holds the Regression — those are // stamped by their caller from r.sym/r.path/r.line and never reach this index. // So `sym=` present is equivalent to "this key still names a live symbol", which is the one thing a reader // wants to know before deciding what to do with the row. // // The index is qualityKey's OWN space (pathQualifiedKey), the same space locBySym is built in — not a // second keying. Overloads share a key by construction (the key is (path, scope, name)); the lowest node id // wins, which is the forward-walk order every other id-choosing site in this tool uses. inline gtl::btree_map ackIdentityIndex( const IngestResult& ing, std::string_view root ) { gtl::btree_map nodeByKey; for( NodeId i = 0; i < NodeId( ing.symbols.size() ); ++i ) { if( ing.symbols[i].fileId >= ing.files.size() ) { continue; } nodeByKey.try_emplace( qualityKey( ing, i, root ), i ); // first (lowest id) wins } return nodeByKey; } // Fill sym=/p= on every row whose key the index resolves. Rows it cannot resolve are left untouched, which // is what makes the emitted attribute mean what the legend says it means. inline void stampStaleAckIdentity( std::vector& rows, const IngestResult& ing, std::string_view root ) { if( rows.empty() ) { return; // the ledger-free run pays nothing: no walk over ing.symbols at all } const gtl::btree_map nodeByKey = ackIdentityIndex( ing, root ); for( StaleAck& row : rows ) { if( !row.sym.empty() ) { continue; // already named by its own producer (the foreign-scope rows carry a Regression) } const auto found = nodeByKey.find( row.key ); if( found == nodeByKey.end() ) { continue; } const Symbol& s = ing.symbols[ found->second ]; row.sym = baselineCanonId( ing, found->second, root ); // the SAME display id a Regression carries row.path.assign( relForHash( ing.files[ s.fileId ], root ) ); row.line = s.line; } } // The XML `` rows and their JSON `"sa":[...]` sibling, extracted here so neither // caller repeats the loop: main.cpp's runQualityDelta (already well over budget before this feature) would // otherwise carry the branch twice (XML and JSON), and mcpverbs.h's qualityDeltaJson is a THIRD site that // needs the identical JSON shape (test/mcpclidiffcheck.sh LENS2 pins the CLI and MCP surfaces to the same // key set). XML's kind is never escaped, matching the existing `` regression rows (main.cpp // prints those unescaped too) — both are drawn from the closed kind vocabulary, so a hand-edited ack file // can only make it a different plain token, never markup. JSON's kind IS escaped (rw::jsonesc::escapeMcp, // the same posture serialize.h's jsonStr already uses for --json): unlike an XML attribute, one stray `"` // in a hand-edited ack line would otherwise emit syntactically invalid JSON, not just an ugly value. // `esc` is the CALLER's XML escaper, passed in rather than included — the same seam testmap.h's runHint // uses, and for the same reason: this header sits BELOW serialize.h in the include order, and sym= carries // corpus text (a canonical id) that must be escaped, unlike kind=/why=/by=, which are closed vocabularies. template inline std::string staleAcksXml( const std::vector& staleAcks, EscapeFn esc ) { std::string out; for( const StaleAck& sa : staleAcks ) { char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( sa.key ) ); out += ""; } return out; } // idea #11 (lane lean-trio), shared by lane lean2b: stale= split by ack KIND as `kind:N,...`, in first-appearance order of the // ledger's own row order — the stale_by_kind= value of the folded CLI --quality-delta AND of the MCP quality_delta twin, so the // two surfaces cannot count differently. The KIND drops the ack's :new-symbol/:preexisting facet; the rows (--show-stale / // show_stale=true) carry it. Unescaped: each caller escapes for its own dialect. inline std::string staleByKindValue( const std::vector& staleAcks ) { std::vector> byKind; for( const StaleAck& a : staleAcks ) { const std::string kind = a.kind.substr( 0, a.kind.find( ':' ) ); const auto it = std::find_if( byKind.begin(), byKind.end(), [ & ]( const auto& kv ) { return kv.first == kind; } ); if( it == byKind.end() ) { byKind.emplace_back( kind, 1 ); } else { ++it->second; } } std::string kinds; for( const auto& [ kind, n ] : byKind ) { kinds += ( kinds.empty() ? "" : "," ) + kind + ":" + std::to_string( n ); } return kinds; } inline std::string staleAcksJsonArray( const std::vector& staleAcks ) // returns `"sa":[...]`, ready to splice in { std::string out = "\"sa\":["; bool first = true; for( const StaleAck& sa : staleAcks ) { if( !first ) { out += ","; } first = false; char hex[ 20 ]; rw::formatTo( hex, sizeof( hex ), "{:016x}", static_cast( sa.key ) ); out += "{\"kind\":\""; out += rw::jsonesc::escapeMcp( sa.kind ); out += "\",\"key\":\""; out += hex; out += "\",\"why\":\""; out += staleAckWhyToken( sa.why ); if( !sa.sym.empty() ) // M21(a): the XML twin's sym=/p=, key-for-key { out += "\",\"sym\":\""; out += rw::jsonesc::escapeMcp( sa.sym ); if( !sa.path.empty() ) { out += "\",\"p\":\""; out += rw::jsonesc::escapeMcp( sa.path ); out += ":"; out += std::to_string( sa.line ); } } if( !sa.by.empty() ) { out += "\",\"by\":\""; out += rw::jsonesc::escapeMcp( sa.by ); // escaped, matching kind='s posture in this emitter } out += "\"}"; } out += "]"; return out; } // P1 SCOPE — every member's root-relative path, for Regression::memberPaths. A clone row's `path` names only // the first-sorting member, and the ownership partition has to ask "does ANY member live in this scope"; the // members= TEXT cannot answer that, because a canonId degrades to a BARE NAME for a scope-less free function // and carries no path at all (quality::displaySym's own documented case). Sorted and deduplicated, so the // field is deterministic and usually one or two entries. A free function rather than a few lines inside // computeDelta's stampCloneLoc: that body is already the file's largest, and this is a pure map over a group. inline std::vector cloneMemberPaths( const CloneGroup& cg, const IngestResult& ing, std::string_view root ) { std::vector paths; paths.reserve( cg.members.size() ); for( NodeId m : cg.members ) { if( m < ing.symbols.size() && ing.symbols[m].fileId < ing.files.size() ) { paths.emplace_back( relForHash( ing.files[ ing.symbols[m].fileId ], root ) ); } } std::sort( paths.begin(), paths.end() ); paths.erase( std::unique( paths.begin(), paths.end() ), paths.end() ); return paths; } // P1 — the SCOPE disclosure, built once for BOTH emitters, exactly as identityDisclosure is: two surfaces // that can disclose different things about one run eventually will. Returns { xmlAttrs, jsonFields }, each // EMPTY when the corresponding fact is absent, so an unscoped report is byte-identical to one from a binary // that never had this flag. `spec` needs no escaping in either dialect: scopeSpecIsSpellable already // excluded whitespace and the XML metacharacters, which is the reason that check exists. inline std::pair scopeDisclosure( const Scope& scope, std::size_t scopedOut, std::size_t scopedOutGating, std::size_t foreignAcks, std::size_t diffFiles ) { std::pair out; if( scope.active() ) { out.first = " scope=\"" + scope.spec + "\" scoped-out=\"" + std::to_string( scopedOut ) + "\" scoped-out-gating=\"" + std::to_string( scopedOutGating ) + "\""; out.second = ",\"scope\":\"" + scope.spec + "\",\"scoped-out\":" + std::to_string( scopedOut ) + ",\"scoped-out-gating\":" + std::to_string( scopedOutGating ); // P1.2: `diff` is a token whose MEANING is a moment. scope= alone would let a reader quote a number // without knowing what the auto-scope covered, so the expansion's size travels with it. if( diffFiles != 0 ) { out.first += " scope-diff-files=\"" + std::to_string( diffFiles ) + "\""; out.second += ",\"scope-diff-files\":" + std::to_string( diffFiles ); } } if( foreignAcks != 0 ) { out.first += " foreign-acks=\"" + std::to_string( foreignAcks ) + "\""; out.second += ",\"foreign-acks\":" + std::to_string( foreignAcks ); } return out; } // ── similar-argument lists (QD-SWAP-1117, report-only: similarargs.h) ───────────────────────────────── // The longest run of adjacent same-typed parameters of each C or C++ function or method definition, read off its own // signature bytes ([sigStartByte, sigEndByte), the span trailingDefaultByNode reads); 0 where there is none. inline std::vector similarRunByNode( const IngestResult& ing ) { std::vector out( ing.symbols.size(), 0 ); forEachSymbolBody( ing, [ & ]( NodeId i, const Symbol& s, std::string_view body ) { const std::size_t sigLen = s.sigEndByte > s.sigStartByte ? std::size_t( s.sigEndByte - s.sigStartByte ) : 0; const bool isCallable = s.kind == SymKind::Function || s.kind == SymKind::Method; if( sigLen == 0 || sigLen > body.size() || !isCallable || !langFacts( s.lang ).typeFirstParameters ) { return; } out[i] = std::uint8_t( std::min( similarargs::longestSimilarRun( { .text = body.substr( 0, sigLen ), .name = s.name } ), UINT8_MAX ) ); } ); return out; } // One qualityKey's longest run: `at` the definition that holds it (the first, in id order), `maxParams` the key's // parameter count as paramsBySym aggregates it (the MAX over every definition of the key). struct SimilarKeyRun { std::uint64_t key = 0; NodeId at = kNoNode; std::uint32_t run = 0; std::uint32_t maxParams = 0; }; // Every key that holds a run of similarargs::kSimilarRunMin or more, ascending by key. inline std::vector similarRunsByKey( const IngestResult& ing, const Graph& g, const std::vector& keyByNode ) { const std::vector runByNode = similarRunByNode( ing ); std::vector perNode; for( NodeId i = 0; i < ing.symbols.size() && i < keyByNode.size(); ++i ) { if( i < g.canonId.size() && !g.canonId[i].empty() ) { perNode.push_back( { keyByNode[i], i, runByNode[i], std::uint32_t( ing.symbols[i].params ) } ); } } std::ranges::stable_sort( perNode, {}, &SimilarKeyRun::key ); std::vector out; for( const SimilarKeyRun& n : perNode ) { if( out.empty() || out.back().key != n.key ) { out.push_back( n ); continue; } SimilarKeyRun& best = out.back(); best.maxParams = std::max( best.maxParams, n.maxParams ); if( n.run > best.run ) { best.run = n.run; best.at = n.at; } } std::erase_if( out, []( const SimilarKeyRun& r ) { return r.run < similarargs::kSimilarRunMin; } ); return out; } // The rows: a definition whose parameter list holds such a run AND is new or grew since the baseline (the baseline // holds parameter counts only, paramsBySym, so a run made by retyping a parameter at the same count is a stated miss). // A symbol the params kind already reported keeps its row and gains similar="N"; any other gets a params row with // sev="minor": was= and now= are its parameter counts, similar= the run. Report-only, never gating. // What the rows are judged against: the graph (row names), the baseline (parameter counts) and this change's moved bodies. struct SimilarRowContext { const Graph& g; const Snapshot& base; const MovedBodies& moved; }; template inline void appendSimilarArgsRows( std::vector& regs, const SimilarRowContext& cx, const std::vector& runs, ExistedFn&& existedAtBaseline, StampFn&& stampLoc ) { for( const SimilarKeyRun& r : runs ) { const auto baseIt = cx.base.paramsBySym.find( r.key ); const std::uint32_t was = baseIt == cx.base.paramsBySym.end() ? 0u : baseIt->second; const bool isNew = !existedAtBaseline( r.key ); if( !isNew && r.maxParams <= was ) { continue; } const std::string similar = std::to_string( r.run ); const auto row = std::ranges::find_if( regs, [ & ]( const Regression& have ) { return have.kind == "params" && have.key == r.key; } ); if( row != regs.end() ) { row->facet = similar; continue; } regs.push_back( { "params", cx.g.canonId[ r.at ], was, r.maxParams, r.key, /*isMinor=*/true, similar, isNew, isNew && cx.moved.isMoved( r.at ) } ); stampLoc( r.at ); } } // ── defect-shape (the twelfth kind) ─────────────────────────────────────────────────────────────────── // A site is NEW when its identity (facet + normalized text) occurs more often in the current tree than in // the baseline, REPO-WIDE: an untouched, moved or renamed defect is not new, an edited one is, and a swap // (one site fixed and another added in the same definition) still is. The excess of each identity is // credited to the anchors that hold more copies of it now than at the baseline, in anchor-key order // (deterministic). An anchor credited with a new site of a facet gets ONE row for that facet; was= and now= // count the anchor's sites of that facet on each side. format-arity gates on ANY origin — a placeholder / // argument mismatch is a defect, not debt; utf8-cut, dedup-first and vacuous-assert are report-only: // sev="minor" by facet, not by size. A file the baseline could not read judges none of its sites. // Called from computeDelta with its origin oracle (existedAtBaseline) and its locator (stampLoc). template inline void appendDefectShapeRows( std::vector& regs, const IngestResult& ing, const Graph& g, const Snapshot& base, std::string_view root, ExistedFn&& existedAtBaseline, StampFn&& stampLoc, const std::vector* macroOverride = nullptr ) { const std::vector nowSites = defectSitesOf( ing, root, nullptr, macroOverride ); const auto isRealSite = []( std::uint64_t v ) { return v != kDefectFilePresent && v != kDefectFileUnreadable; }; std::vector baseVals, nowVals, baseUnreadable; for( const DefectSiteKey& d : base.defectSites ) { if( isRealSite( d.site ) ) { baseVals.push_back( d.site ); } else if( d.site == kDefectFileUnreadable ) { baseUnreadable.push_back( d.anchor ); } } for( const DefectSiteAt& d : nowSites ) { if( isRealSite( d.key.site ) ) { nowVals.push_back( d.key.site ); } } std::sort( baseVals.begin(), baseVals.end() ); std::sort( nowVals.begin(), nowVals.end() ); std::sort( baseUnreadable.begin(), baseUnreadable.end() ); const auto countOf = []( const std::vector& v, std::uint64_t x ) { const auto r = std::equal_range( v.begin(), v.end(), x ); return static_cast( r.second - r.first ); }; // the repo-wide excess still to credit, per identity std::vector> excess; for( std::size_t k = 0; k < nowVals.size(); ) { const std::uint64_t v = nowVals[k]; const std::uint32_t nN = countOf( nowVals, v ); const std::uint32_t nB = countOf( baseVals, v ); if( nN > nB ) { excess.push_back( { v, nN - nB } ); } k += nN; } const auto baseAnchorCount = [ & ]( std::uint64_t anchor, std::uint64_t site ) { const auto r = std::equal_range( base.defectSites.begin(), base.defectSites.end(), DefectSiteKey{ anchor, site } ); return static_cast( r.second - r.first ); }; const auto facetCount = []( const auto& sites, std::uint64_t anchor, defectshape::Facet f, auto keyOf ) { std::uint32_t n = 0; for( const auto& s : sites ) { const DefectSiteKey& k = keyOf( s ); n += ( k.anchor == anchor && k.site != kDefectFilePresent && k.site != kDefectFileUnreadable && defectFacetOf( k.site ) == f ) ? 1u : 0u; } return n; }; struct Credited { std::uint64_t anchor = 0; defectshape::Facet facet = defectshape::Facet::FormatArity; const DefectSiteAt* first = nullptr; }; std::vector credited; for( std::size_t k = 0; k < nowSites.size(); ) { const DefectSiteKey key = nowSites[k].key; std::size_t e = k; while( e < nowSites.size() && nowSites[e].key == key ) { ++e; } const std::uint32_t headA = static_cast( e - k ); const DefectSiteAt& at = nowSites[k]; k = e; if( !isRealSite( key.site ) || at.fileId >= ing.files.size() || std::binary_search( baseUnreadable.begin(), baseUnreadable.end(), defectFileAnchor( relForHash( ing.files[ at.fileId ], root ) ) ) ) { continue; } const std::uint32_t baseA = baseAnchorCount( key.anchor, key.site ); const auto ex = std::lower_bound( excess.begin(), excess.end(), std::pair{ key.site, 0 } ); if( headA <= baseA || ex == excess.end() || ex->first != key.site || ex->second == 0 ) { continue; } ex->second -= std::min( ex->second, headA - baseA ); const defectshape::Facet f = defectFacetOf( key.site ); const bool seen = std::any_of( credited.begin(), credited.end(), [ & ]( const Credited& c ) { return c.anchor == key.anchor && c.facet == f; } ); if( !seen ) { credited.push_back( { key.anchor, f, &at } ); } } for( const Credited& c : credited ) { const std::uint32_t was = facetCount( base.defectSites, c.anchor, c.facet, []( const DefectSiteKey& d RW_LIFETIMEBOUND ) -> const DefectSiteKey& { return d; } ); const std::uint32_t now = facetCount( nowSites, c.anchor, c.facet, []( const DefectSiteAt& d RW_LIFETIMEBOUND ) -> const DefectSiteKey& { return d.key; } ); const NodeId owner = c.first->owner; const std::string rel( relForHash( ing.files[ c.first->fileId ], root ) ); const bool isNew = ( owner != kNoNode ) ? !existedAtBaseline( c.anchor ) : !std::binary_search( base.defectSites.begin(), base.defectSites.end(), DefectSiteKey{ c.anchor, kDefectFilePresent } ); const std::string sym = ( owner != kNoNode && owner < g.canonId.size() && !g.canonId[owner].empty() ) ? g.canonId[owner] : rel; const std::uint64_t rowKey = defectRowKey( c.anchor, c.facet, defectSiteValsOf( nowSites, c.anchor, c.facet, []( const DefectSiteAt& d RW_LIFETIMEBOUND ) -> const DefectSiteKey& { return d.key; } ) ); regs.push_back( { "defect-shape", sym, was, now, rowKey, !defectshape::facetGatesOnAnyOrigin( c.facet ), std::string( defectshape::facetName( c.facet ) ), isNew } ); if( owner != kNoNode ) { stampLoc( owner ); } else { regs.back().path = rel; regs.back().line = c.first->line; } } } // The dead-code kind's delta pass: a dead candidate the --dead-code verb's rule leaves dead, not dead at the baseline. Its // own function (qd-memory-degrade) so computeDelta runs it, and builds its four evidence structures, only when the kind is // asked for. The three exclusion counts are the disclosed floors computeDelta's caller prints (any may be null). struct DeadExclusionCounts { std::size_t* registerMacro = nullptr; // P2.2: would be dead-code but for the register-macro exemption std::size_t* declinedCall = nullptr; // ... but for a declined call that may reach it std::size_t* valueRef = nullptr; // ... but for a table/field/argument holding it as a value }; template inline void appendDeadCodeRows( std::vector& regs, const IngestResult& ing, const Graph& g, const Snapshot& base, std::string_view root, const std::vector& keyByNode, ExistedFn&& existedAtBaseline, StampFn&& stampLoc, DeadExclusionCounts excluded ) { const std::vector topLevelCallees = topLevelCalleeNameHashes( ing ); // W1-S2: dead-kind evidence, built once const std::vector macroNames = registeredMacroNames( root ); // P2.2: built-ins + .ripwire_config const std::vector macroIds = registeredMacroSymbolIds( ing, macroNames ); const std::vector dropIds = rustDropImplMethodIds( ing ); // issue #494: Drop::drop by its impl block, as addDeadSet const std::vector pythonDispatch = pythonDispatchedMethodIds( ing, g ); const ValueRefIndex valueRefs( ing ); // reference-as-value round: the --dead-code verb's rule for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } bool macroExempt = false; if( !isDeadCandidate( ing, g, i, topLevelCallees, macroIds, pythonDispatch, dropIds, ¯oExempt ) ) { if( macroExempt && excluded.registerMacro ) { ++( *excluded.registerMacro ); // P2.2: would be dead-code but for the macro exemption — disclosed count } continue; } if( declinedCallMayReach( g, i ) ) { if( excluded.declinedCall ) { ++( *excluded.declinedCall ); // would be dead-code but for a declined call that may reach it — disclosed count } continue; } if( valueRefs.isValueReferenced( i ) ) // checked LAST: one entity, one reason (the --dead-code verb's order) { if( excluded.valueRef ) { ++( *excluded.valueRef ); // a table, field or argument holds it as a value — disclosed count } continue; } if( !std::binary_search( base.dead.begin(), base.dead.end(), keyByNode[i] ) ) { regs.push_back( { "dead-code", g.canonId[i], 0, 0, keyByNode[i], false, {}, !existedAtBaseline( keyByNode[i] ) } ); // origin: born uncalled (new) vs lost its last caller (preexisting) stampLoc( i ); } } } // current state vs baseline → only what got worse. // complexity/verbosity/nesting/params: a symbol the change pushed/kept OVER the bar (now > baseline AND // now > BAR; a NEW symbol counts with baseline 0). Each is a per-symbol metric whose overloads share a // canonId → aggregated to the per-id MAX on BOTH sides (mirrors computeSnapshot) so a low-metric overload // can never manufacture a phantom regression (THE trap — do not reintroduce it). // duplication: a clone group whose member-set is not in the baseline. // dead-code: a dead-candidate not in the baseline. // api-surface: a PUBLIC/exported symbol (isPublicApi) whose canonId is not in the baseline set (contract // drift — new exported surface; §1c 2606.21804). A SET signal → overload-collision-proof by construction. // hwh-fix4 (N1) — the history a gating kind needed and could not read. short-horizon-churn is the one kind whose gating input // comes from git history (the window commit counts, the window ref tree, the blame of the edited lines); on a partial clone the // no-download rule refuses the tree and fails the blame, and a budget can cut the walk. Each used to read as "no churn" or // churn="ambient", so a gating row vanished and --quality-delta exited 0. Now each is named on the answer (unread_history=), a // row whose self/ambient split could not be read says churn="unknown", and an answer with no gating row exits 6, never 0. struct HistoryUnread { bool churnWindow = false; // the window commit-count walk ended before the window floor: a file's count is a floor bool churnTree = false; // the window ref tree was refused or failed: no symbol's committed-rewrite evidence was read std::uint32_t churnRows = 0; // rows whose blame or hunk diff git refused: churn="unknown" bool renames = false; // a pinned sidecar floor, and the rename map was refused (partial clone): a baseline row // under a renamed path is not re-filed, so its symbol reads as new and cannot gate bool any() const noexcept { return churnWindow || churnTree || churnRows > 0 || renames; } }; // unread_history= (XML) and "unread_history":[…] (JSON, CLI and MCP alike), built once for every emitter; empty when all was read. // The values, in this order: churn-window, churn-tree, churn-blame, renames. inline std::pair historyUnreadDisclosure( const HistoryUnread& h ) { if( !h.any() ) { return {}; } std::vector parts; if( h.churnWindow ) { parts.push_back( "churn-window" ); } if( h.churnTree ) { parts.push_back( "churn-tree" ); } if( h.churnRows ) { parts.push_back( "churn-blame" ); } if( h.renames ) { parts.push_back( "renames" ); } std::string xml = " unread_history=\"", json = ",\"unread_history\":["; for( std::size_t i = 0; i < parts.size(); ++i ) { xml += ( i ? "," : "" ) + std::string( parts[i] ); json += ( i ? ",\"" : "\"" ) + std::string( parts[i] ) + "\""; } return { xml + "\"", json + "]" }; } // One per-symbol kind's CURRENT side: each key's MAX metric over its overloads (they share a key) and the node that supplies it, // the lowest NodeId on a tie. That node's move status and kind are the row's (#646 CR: not the key's first overload). struct MetricMaxAt { std::uint32_t now = 0; NodeId at = kNoNode; }; template inline ScratchMap metricMaxByKey( const IngestResult& ing, const Graph& g, const std::vector& keyByNode, MetricOf metricOf ) { ScratchMap out( ing.symbols.size() ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } MetricMaxAt& slot = out[ keyByNode[i] ]; const std::uint32_t m = metricOf( i ); if( slot.at == kNoNode || m > slot.now ) { slot = { m, i }; } } return out; } // QD-ENTRY-CEILING: the ceiling a just-pushed row gates at, or 0. Only a NEW, material row of a function or method (`measured`, // the kind of the symbol that supplies the value: a class extent never gates) at or over the kind's ceiling, and not a moved // body or a test driver. inline std::uint32_t newSymbolCeilingGate( const Regression& r, SymKind measured, std::uint32_t ceilingAt ) { const bool callable = measured == SymKind::Function || measured == SymKind::Method; const bool gates = r.isNewSymbol && !r.isMoved && !r.isMinor && callable && ceilingAt != 0 && r.now >= ceilingAt && !r.path.empty() && !isTestPath( r.path ); return gates ? ceilingAt : 0; } // `root` = the ingest root exactly as invoked; every baseline COMPARISON key is the root-relative // baselineCanonId (S2) so a committed baseline matches regardless of how the root was spelled on either run. // The human-readable `Regression.sym` keeps the FULL g.canonId (display only — never hashed/compared), so the // reported symbol string and the emitted `id=` remain byte-identical to before. // `excludes`/`maxFileBytes` mirror the working-tree ingest config and are threaded into the churn kind's // window-ref snapshot (computeWindowRefBodyHashes) so both sides of the evidence compare see one file set — // the same A4-F5 discipline computeHeadSnapshot follows. Defaults keep the MCP call site unchanged. inline std::vector computeDelta( const IngestResult& ing, const Graph& g, const Snapshot& baseline, std::string_view root = {}, const std::vector& excludes = {}, std::size_t maxFileBytes = kDefaultMaxFileBytes, std::size_t* registerMacroExcludedOut = nullptr, // P2.2: honest disclosure count, additive+optional — see isDeadCandidate std::size_t* apiNewSurfaceOut = nullptr, // Q-DIAL-4: the api-surface new-symbol COUNT that replaced N never-gating rows std::vector* cloneIdiomsOut = nullptr, // every CURRENT-tree clone group's (hash, idiom), for the legacy-ack backfill std::size_t* declinedCallExcludedOut = nullptr, // symbols kept out of dead-code ONLY by a declined call (declinedCallMayReach) std::size_t* valueRefExcludedOut = nullptr, // ... ONLY because a table/field/argument holds them as a VALUE const KindScope& scope = {}, // qd-memory-degrade: the kinds to report (see computeSnapshot) HistoryUnread* historyUnreadOut = nullptr, // hwh-fix4 (N1): history a gating kind could not read TreePasses* sharedPasses = nullptr ) // QD-IDENTITY-ONCE: pure passes over `ing` another consumer may already hold { TreePasses ownPasses; TreePasses& passes = sharedPasses != nullptr ? *sharedPasses : ownPasses; HistoryUnread historyUnread; if( declinedCallExcludedOut ) { *declinedCallExcludedOut = 0; } if( valueRefExcludedOut ) { *valueRefExcludedOut = 0; } ASSUME( registerMacroExcludedOut == nullptr || registerMacroExcludedOut != apiNewSurfaceOut, "computeDelta: registerMacroExcludedOut and apiNewSurfaceOut must be distinct" ); // both default to nullptr, so the object form would dereference null std::vector regs; if( registerMacroExcludedOut ) { *registerMacroExcludedOut = 0; } if( apiNewSurfaceOut ) { *apiNewSurfaceOut = 0; } // A4-P10 — HOIST the per-symbol quality key. It materializes a path-qualified string + hashes it; the // passes below (4 metric kinds × 2 loops each, dead, api-surface, error-masking, short-horizon-churn) each // recomputed it per symbol → ~8× redundant string builds per symbol per call. Compute it ONCE here (0 for a // symbol with no canonId — those are skipped by every pass anyway) and let the passes index `keyByNode[i]`. // // qualityKey, NOT fnv1a64(baselineCanonId) — it must be byte-identical to what computeSnapshot stored, and // the two now share one rule so they cannot drift. The canonId presence test below is retained deliberately: // it is the "is this an indexed definition at all" gate every pass depends on, NOT the key derivation. std::vector keyByNode( ing.symbols.size(), 0 ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i < g.canonId.size() && !g.canonId[i].empty() ) { keyByNode[i] = qualityKey( ing, i, root ); } } MoveIdentities nowMove; std::vector nowCodeLoc = codeLocByNode( ing, &nowMove ); // Q-DIAL-3 — the same rule computeSnapshot recorded the baseline with measureCallableNotItsContainer( ing, keyByNode, nowCodeLoc ); // EXTENT-CTOR — and the same container rule // QD-RENAME-IDENTITY — a renamed or moved body keeps its identity: the baseline every kind below reads is re-filed under the new // keys first (a copy, only when something matched; see ContentMoves). const ContentMoves contentMoves( baseline, keyByNode, nowMove.body ); std::optional healedBase; const Snapshot& base = *contentMoves.baseFor( &baseline, healedBase ); // ─── r26 ORIGIN AXIS: preexisting-worse vs new-symbol ────────────────────────────────────────────── // The exit code used to fire on ANY major unacked finding, which meant every large-but-fine NEW symbol // ("was=0" complexity/verbosity/nesting/params rows, and one api-surface row per new export) landed in // the same exit-2 pile as the genuinely-useful "this function that already existed got worse" catch. // A report whose acceptance criterion is negotiated per finding is not an acceptance criterion, so the // two are now separated: only PREEXISTING-worse findings gate; new-symbol findings stay printed. // // THE ORACLE is `base.locBySym` — computeSnapshot populates it for EVERY symbol that has a canonId // (public or not, body or not), so "is this canonId in locBySym" is the one clean, kind-independent // "existed at the baseline" test. It generalizes the api-surface kind's own isNewSymbol tier (B10.2e), // which used exactly this map, to every kind rather than adding a parallel mechanism. // // PER-KIND RULE (the ambiguous kinds decided deliberately, not by default): // complexity / verbosity / nesting / params / api-surface / error-masking — the finding IS a symbol: // classify by that symbol's canonId. Direct. // dead-code — the finding is "this symbol is now dead". A symbol that existed and LOST its last caller // is preexisting-worse; a symbol born uncalled is new-symbol (that is a "you have not wired it up // yet" note about new code, not a regression of anything that worked before). // duplication / new-clone-of-reused-helper — the finding is a RELATION over a member set, not one // symbol, so "the symbol existed" needs a decision: a group counts as preexisting-worse iff AT LEAST // ONE member existed at the baseline — i.e. the new copy eroded code that was already there (the // high-value half of these kinds, and the whole point of the reuse-decline kind: the reused helper is // preexisting — r27 made that an ENFORCED precondition at the reuse kind's own fan-in test, where it // had until then been only an assertion in this comment). A group whose members are ALL new is new code duplicating itself: // real information, still printed, but nothing that existed got worse. A member with no canonId // (key 0) is unclassifiable and is NOT counted as evidence of preexistence. // short-horizon-churn — ALWAYS preexisting by construction: its gate 2 already requires the symbol to // be present in the baseline's bodyHashBySym ("a symbol absent from the baseline is a first write, // never a REwrite"), so this kind can never produce a new-symbol row. Recorded explicitly below // rather than derived, so the invariant is visible at the push site. // placeholder — ALWAYS new-symbol by construction, the mirror image of churn: the finding is the added // stub or TODO comment, which did not exist at the baseline whatever symbol it lands in. A placeholder // is an unfinished statement about new code, never evidence that something that worked got worse, so // it is printed and never gates. // // WHAT "PREEXISTING" CANNOT DETECT (stated in the XML comment + --help too): identity is the // root-relative canonId `path::scope::name`, so a symbol that was RENAMED or MOVED to another file reads // as new on the current side — a regression carried in with a move classifies new-symbol and does not // gate. There is no rename detection here and adding one would make the classification non-deterministic // (a similarity heuristic), which the determinism law forbids. // // DEGRADE, FAIL-CLOSED: a pre-Q1 (v1-format) baseline sidecar carries no `loc ` lines at all, so the // oracle is empty and NOTHING could be classified. Rather than silently disarming the exit code on an // unreadably-old baseline, classify every finding as preexisting-worse (gating) and alert — the honest // outcome is "re-baseline", never "green because I could not tell". // r27 SUSPICION-A FIX — `!base.locBySym.empty()` alone CONFLATED two opposite situations, and got the // second one factually wrong: // (i) a pre-Q1 (v1-format) sidecar, which has ccx/clone/dead/api records but no `loc ` lines → the // oracle really is unavailable → fail closed (gate everything) + alert. Correct, keep. // (ii) a baseline that is legitimately, COMPLETELY empty — a README-only first commit, a docs/JSON-only // HEAD, a root pointed at a non-source subdirectory. HEAD genuinely has no canonId symbols, so the // oracle is PERFECT ("nothing existed; every finding is new"), yet every finding was classified // preexisting-worse and GATED, under an alert that told the user their baseline was in a stale // pre-Q1 format. Wrong answer AND wrong explanation. // The discriminator is exact, not a heuristic: computeSnapshot populates locBySym for EVERY symbol that has // a canonId, so ANY other per-symbol record existing while locBySym is empty is only possible for a v1 // sidecar; a genuinely-empty HEAD leaves every map and vector empty together. const bool baselineIsWhollyEmpty = base.locBySym.empty() && base.ccxBySym.empty() && base.nestBySym.empty() && base.paramsBySym.empty() && base.maskBySym.empty() && base.placeholderBySym.empty() && base.bodyHashBySym.empty() && base.cloneGroups.empty() && base.dead.empty() && base.publicApi.empty(); const bool originOracleOk = !base.locBySym.empty() || baselineIsWhollyEmpty; if( !originOracleOk ) { DISCLOSE( "quality: baseline has no per-symbol loc map (pre-Q1 format) — origin unclassifiable, gating every finding" ); } const auto existedAtBaseline = [ & ]( std::uint64_t symKey ) { if( !originOracleOk ) { return true; // fail closed — see the degrade note above } return base.locBySym.find( symKey ) != base.locBySym.end(); }; // A clone group is new-symbol only when EVERY member is new (see the per-kind rule above). // r27 SUSPICION-B FIX: this loop asked `existedAtBaseline` per member, but a member with key 0 (no // canonId) short-circuits past it, so with the oracle UNAVAILABLE a group of such members still returned // true — "new-symbol", never gates — while every OTHER kind was busy failing CLOSED on the same missing // oracle. One unclassifiable kind silently disarming the exit code is exactly the shape of the bug the // fail-closed rule exists to prevent. Answer the oracle question FIRST, once, for the whole group. const auto cloneGroupIsNew = [ & ]( const CloneGroup& cg ) { if( !originOracleOk ) { return false; // fail closed — preexisting-worse, gates } for( NodeId m : cg.members ) { if( m < keyByNode.size() && keyByNode[m] != 0 && existedAtBaseline( keyByNode[m] ) ) { return false; } } return true; }; // P2.5 (r27) — the LOCATOR stamp. Fill the row's p="path:line" from the symbol that produced it, right // after the push so no call site has to restate the whole aggregate initializer. Root-relative path (the // relForHash spelling every sidecar key already uses) + the symbol's own 1-based start line. const auto stampLoc = [ & ]( NodeId i ) { ASSUME( !regs.empty() ); if( i >= ing.symbols.size() ) { return; // degrade: no locator rather than a wrong one } const Symbol& s = ing.symbols[i]; if( s.fileId >= ing.files.size() ) { return; } regs.back().path = std::string( relForHash( ing.files[ s.fileId ], root ) ); regs.back().line = s.line; }; // The clone kinds' locator: the member whose canonId sorts FIRST, so p= names the same symbol that leads // the emitted members= list rather than an arbitrary NodeId-order pick. const auto stampCloneLoc = [ & ]( const CloneGroup& cg ) { NodeId best = NodeId( -1 ); std::string bestId; for( NodeId m : cg.members ) { if( m >= g.canonId.size() || g.canonId[m].empty() ) { continue; } if( best == NodeId( -1 ) || g.canonId[m] < bestId ) { best = m; bestId = g.canonId[m]; } } if( best != NodeId( -1 ) ) { stampLoc( best ); } regs.back().memberPaths = cloneMemberPaths( cg, ing, root ); // P1 SCOPE — see cloneMemberPaths }; const MovedBodies moved( base, keyByNode, nowMove ); // a current clone group the baseline holds: by its member set or pairs, or (QD-RENAME-IDENTITY) by its members' unchanged bodies const auto isHeld = [ & ]( const CloneGroup& cg, std::uint64_t h ) { return cloneGroupHeldAtBaseline( cg, h, base.cloneGroups, ing, root ) || contentMoves.holdsCloneGroup( cg, base, keyByNode, nowMove.body ) || cloneGroupHeldAcrossRenames( cg, base.cloneGroups, base.renamedFrom, ing, root ); }; // MOVED-BODY — read by perSymbolKind below // One per-symbol metric kind: aggregate the CURRENT side to the same per-canonId MAX the snapshot stores // (overloads share an id), compare per-id MAX vs the baseline's per-id MAX, report each id once at its // first symbol, and flag only when it GREW and now exceeds the bar. `metricOf` reads the metric off a // Symbol; `baseMap` is the matching baseline map. Identical treatment for ccx/loc/nest/params guarantees // the trap is handled the same way for every one of them. // `minorDelta` is the kind's materiality tier: a regression whose growth (now − was) is under it is // reported sev="minor" and does not gate exit 2 (0 = no tier, every regression is major). // // Q-DIAL-3 — `growthTiered` swaps that flat delta tier for the pair of thresholds kMaterialGrowthPct / // kSubBarGrowthPct define, for complexity and verbosity only: // OVER the bar — gate on a bar CROSSING (was <= bar < now) or on growth >= 25%; anything else is a // real row, printed, sev="minor". It names debt the change did not create. // UNDER the bar — a DOUBLING that clears the floor is a minor row instead of silence. Nothing here can // gate: the symbol is still under its bar, and the row exists to be seen, not to stop // a commit. // `metricOf` takes the NodeId rather than the Symbol because verbosity's metric is not on the Symbol any // more (codeLoc is read off the body bytes); the other three still just read a field. const auto perSymbolKind = [ & ]( const MaterialityBar& mb, std::uint32_t ceilingAt, const gtl::btree_map& baseMap, auto metricOf ) { const std::uint32_t bar = mb.bar; ScratchMap nowBySym = metricMaxByKey( ing, g, keyByNode, metricOf ); ScratchMap reported( ing.symbols.size() ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } const std::uint64_t key = keyByNode[i]; if( !insertScratchSeen( reported, key ) ) { continue; // already reported at an earlier overload } const auto nowIt = nowBySym.find( key ); if( nowIt == nowBySym.end() ) { continue; // corrupt/inconsistent ids: degrade by skipping } const std::uint32_t now = nowIt->second.now; const auto it = baseMap.find( key ); const std::uint32_t was = ( it == baseMap.end() ) ? 0u : it->second; if( now <= was ) { continue; // nothing got worse on this axis } const std::uint64_t growthPct = ( std::uint64_t( now - was ) * 100 ) / std::max( was, 1u ); if( now > bar ) { // numericRegressionIsMajor is the SAME formula rescoreNumericMajor calls when a later run // re-scores this row's stored was=/now= off the ack ledger (see AckRecord's doc comment) — // one body, so the live report and a re-score can never silently disagree. const bool material = numericRegressionIsMajor( was, now, mb, bar, mb.minorDelta, growthPct ); const bool isNew = !existedAtBaseline( key ); const bool isMovedB = isNew && moved.isMoved( nowIt->second.at ); // QD-MONSTER-GROWTH — facet "1" is emitted as monster="1" (kFacetAttrs): set whenever the clause // holds, whether or not the 25 % tier would have made the row major on its own. regs.push_back( { std::string( mb.kind ), g.canonId[i], was, now, key, !material, isMonsterGrowth( was, now, bar, mb.monsterGrowth ) ? std::string( kMonsterFacet ) : std::string(), isNew, isMovedB } ); // origin: the finding IS this symbol stampLoc( i ); regs.back().ceiling = newSymbolCeilingGate( regs.back(), ing.symbols[ nowIt->second.at ].kind, ceilingAt ); // QD-ENTRY-CEILING } else if( mb.growthTiered && was > 0 && growthPct >= kSubBarGrowthPct && now >= subBarGrowthFloor( bar ) ) { // Q-DIAL-3 — still UNDER the bar, so this can never gate; it is the row that turns synthetics // S4b (6 → 55 LOC) and S8-sub-bar (ccx 5 → 13) from silence into something a reader can see. // `was > 0` is load-bearing, not defensive: growth is a RATIO and a brand-new symbol has // nothing to double from, so without it every added function of 40 code lines or ccx 10 // reported as "grew 4200%". Measured on the 40-commit ref-pair replay: 38 of the 57 rows this // tier first produced were exactly that (`was="0"`), including every symbol of the vendored // timsort landing at 08416403. regs.push_back( { std::string( mb.kind ), g.canonId[i], was, now, key, /*isMinor=*/true, {}, !existedAtBaseline( key ) } ); stampLoc( i ); } } }; // Each kind's row of the ONE materiality table, so the live decision and rescoreNumericMajor cannot drift. perSymbolKind( kMaterialityBars[0], newSymbolCeiling( kCcxBar ), base.ccxBySym, [ & ]( NodeId i ){ return ing.symbols[i].ccx; } ); perSymbolKind( kMaterialityBars[1], newSymbolCeiling( kLocBar ), base.locBySym, [ & ]( NodeId i ){ return nowCodeLoc[i]; } ); perSymbolKind( kMaterialityBars[2], 0, base.nestBySym, [ & ]( NodeId i ){ return std::uint32_t( ing.symbols[i].maxNest ); } ); perSymbolKind( kMaterialityBars[3], 0, base.paramsBySym, [ & ]( NodeId i ){ return std::uint32_t( ing.symbols[i].params ); } ); // PERF (P5W2) — the working-tree clone pass is the dominant --quality-delta cost: on a large private C++ corpus the // Type-3 pass alone is ~2.7-3.2 s (60 M intra-bucket pair-visits; tokenization is only ~3 %). It is a PURE // function of the working tree (ing), yet BOTH consumers below — the `duplication`/§D#4-3 new-clone report // AND the reuse-connectivity report — used to call findClones/findClonesType3 independently, so each pass // ran TWICE per call (~46 % of the whole verb was redundant recompute). Compute each pass ONCE here and let // both consumers read the same vectors. Byte-identical BY CONSTRUCTION: both functions are deterministic // pure functions, so their single result is field-for-field the value both call sites received before. // qd-memory-degrade: the clone passes feed only the two clone kinds (and the --quality-ack backfill export, which is // never asked with a kind mask) — not run when neither is selected, the largest saving a kind selection buys. const bool wantClones = ( scope.kinds & ( kindBit( "duplication" ) | kindBit( "new-clone-of-reused-helper" ) ) ) != 0 || cloneIdiomsOut != nullptr; // QD-IDENTITY-ONCE carries the same rule one level up: `passes` may already hold them from the identity-basis snapshot. const std::vector noClones; const std::vector& exactClones = wantClones ? passes.exactClones( ing ) : noClones; const std::vector& type3Clones = wantClones ? passes.type3Clones( ing ) : noClones; // duplication: a clone group (exact Type-1/2 OR gapped Type-3) whose member-set is not in the // baseline set. Both passes hash by the same sorted-member-canonId identity, so a change that // introduces a NEW near-clone (Type-3) is flagged exactly like a new exact copy. `now` carries the // group's tokens; the reported set is deduped by the same emitted-hash guard both passes share (an // exact and a near group can never share a member-set hash, so no double-report). // IDIOM CLASS (cloneidiom.h) — an idiom COLLISION is reported minor with its shape NAMED, not gated; a // group that classifies but fails the rest of the conjunction gates as before, name and all. const std::vector exactIdioms = classifyCloneGroupIdioms( ing, exactClones ); const std::vector type3Idioms = classifyCloneGroupIdioms( ing, type3Clones ); // THE BACKFILL EXPORT. Deliberately taken BEFORE either reporting lambda runs, and without any of their // filters: a legacy ack row is healed by matching its member-set hash, and that row was accepted under a // baseline this run knows nothing about, so the group it names is almost never "new" HERE. Filtering by // newness — or by the all-test-script skip, or by the fan-in floor — would hide exactly the rows the // backfill exists to reach. Sorted and deduped by hash so the consumer can binary_search it and so two // runs over the same tree export byte-identical facts (the determinism contract; both clone passes are // themselves deterministic, and a group found by BOTH passes hashes the same and must collapse to one). if( cloneIdiomsOut != nullptr ) { const auto collect = [ & ]( const std::vector& cgs, const std::vector& vx ) { for( std::size_t ci = 0; ci < cgs.size() && ci < vx.size(); ++ci ) { cloneIdiomsOut->push_back( { cloneGroupHash( cgs[ci], ing, root ), std::string( cloneIdiomName( vx[ci].idiom ) ) } ); } }; collect( exactClones, exactIdioms ); collect( type3Clones, type3Idioms ); std::sort( cloneIdiomsOut->begin(), cloneIdiomsOut->end(), []( const CloneIdiomFact& a, const CloneIdiomFact& b ) { return a.hash != b.hash ? a.hash < b.hash : a.idiom < b.idiom; } ); cloneIdiomsOut->erase( std::unique( cloneIdiomsOut->begin(), cloneIdiomsOut->end(), []( const CloneIdiomFact& a, const CloneIdiomFact& b ) { return a.hash == b.hash; } ), cloneIdiomsOut->end() ); } // ── Q-DIAL-5 (2026-09-10) — three shapes that are not THIS CHANGE'S duplication ───────────────────── // Duplication's gating precision over 40 replayed commits was 0%: 11 gating rows, 9 noise and 2 wrong. // Three mechanisms produced them, and each is a property of the GROUP rather than of its text, so each is // decidable here without touching the clone matcher: // (a) ONE OVERLOAD SET — every member shares one canonical id. Overloads of a function are near- // identical by construction (emitTo|emitTo, sort::stable|sort::stable); reporting them as a copy is // reporting the language. // (b) WITHDRAWN — see the note below. // (c) VENDORED — every member sits under a vendored path (see isVendoredPath). Upstream's shape is not // this repo's to fix, and one commit produced 9 such rows. // ONE-FILE IS NOT ON THIS LIST, and the reason is worth more than the rows it would have dropped. The // audit's labelling rule W3b called a group whose members share one file "sibling/alternate // implementations" (mergeHi|mergeLo, gallopLeft|gallopRight) and 13 groups were labelled WRONG by it. The // clause was written, and TWO of this repo's own gates went red on it: test/clonededupcheck.sh's whole // positive case is a copy of a reused helper appended to the SAME file, and test/qualitycheck.sh §3 pins // a dup1/dup2 pair inside one new file as a duplication finding. Both were written deliberately, and both // are right: a copy-pasted body is duplication wherever it lands, and file identity cannot tell a // deliberate specialization from a paste. A hand rule in a labelling script does not outrank two gates // that encode the opposite policy, so the drop is withdrawn rather than argued around. The rows it aimed // at need the discriminator the acks themselves use — no shared domain identifier — which is a // cloneidiom.h round, not a group-shape predicate. // // NOT a token floor either: raising kMinCloneTokens was measured and REFUTED. The canonical true positive // (synthetic S1, a 12-line copy of a reused helper) is 59 tokens, while the idiom collisions in the same // replay run 22, 24, 31, 36, 56, 65, 66, 74, 78, 91, 92, 96, 114 and 127 — a floor above 22 loses true // positives before it clears any noise. Token count is the wrong axis. const std::vector vendoredPrefixes = vendoredPathPrefixes( root ); const auto cloneGroupIsOutOfScope = [ & ]( const CloneGroup& cg ) { if( cg.members.size() < 2 ) { return false; } bool oneId = true; bool allVend = true; std::string_view firstId; bool haveFirst = false; for( NodeId m : cg.members ) { if( m >= ing.symbols.size() || m >= g.canonId.size() ) { return false; // unclassifiable member — never claim a whole-group property } const std::uint32_t f = ing.symbols[m].fileId; if( f >= ing.files.size() ) { return false; } if( !isVendoredPath( relForHash( ing.files[f], root ), vendoredPrefixes ) ) { allVend = false; } if( !haveFirst ) { firstId = g.canonId[m]; haveFirst = true; continue; } if( g.canonId[m] != firstId ) { oneId = false; } } return oneId || allVend; }; gtl::btree_map dupSeen; const auto reportNewClones = [ & ]( const std::vector& cgs, const std::vector& vx ) { for( std::size_t ci = 0; ci < cgs.size(); ++ci ) { const CloneGroup& cg = cgs[ci]; const CloneIdiomVerdict& vd = vx[ci]; const std::uint64_t h = cloneGroupHash( cg, ing, root ); if( isHeld( cg, h ) ) { continue; } // B10.1a: a clone group ENTIRELY composed of test-SCRIPT members is fixture-class noise — sibling // shell test scripts repeat near-identical setup/ok/no boilerplate by convention (see // isTestScriptPath); exempt only when every member is a test script, so a real src/ ↔ test-script // clone (still worth a look) is unaffected. bool allTestScript = !cg.members.empty(); for( NodeId m : cg.members ) { if( m >= ing.symbols.size() || !isTestScriptPath( rootRelPath( ing, ing.symbols[m].fileId ) ) ) { allTestScript = false; break; } } if( allTestScript ) { continue; } if( cloneGroupIsOutOfScope( cg ) ) { continue; // Q-DIAL-5 — an overload set, one file, or vendored upstream (see the block above) } if( !dupSeen.insert( { h, 1 } ).second ) { continue; // same member-set already reported this run } std::vector ids; for( NodeId m : cg.members ) { if( m < g.canonId.size() ) { ids.push_back( g.canonId[m] ); } } std::sort( ids.begin(), ids.end() ); std::string joined; for( std::size_t k = 0; k < ids.size(); ++k ) { joined += ids[k]; if( k + 1 < ids.size() ) { joined += " | "; } } // isMinor = the demotion; facet = the recognized shape, emitted as idiom= (facetAttrName). regs.push_back( { "duplication", joined, 0, cg.tokens, h, vd.demoted, std::string( cloneIdiomName( vd.idiom ) ), cloneGroupIsNew( cg ) } ); // ack identity = the member-set hash; origin = "no member existed" stampCloneLoc( cg ); } }; reportNewClones( exactClones, exactIdioms ); reportNewClones( type3Clones, type3Idioms ); if( kindSelected( scope.kinds, "dead-code" ) ) // qd-memory-degrade: the pass and its four evidence structures, only for its kind { const std::size_t deadFrom = regs.size(); appendDeadCodeRows( regs, ing, g, base, root, keyByNode, existedAtBaseline, stampLoc, DeadExclusionCounts{ registerMacroExcludedOut, declinedCallExcludedOut, valueRefExcludedOut } ); contentMoves.markMovedDeadRows( regs, deadFrom ); // QD-RENAME-IDENTITY markRenamedDeadRows( regs, deadFrom, base.renamedKeys ); // QD-GIT-RENAME-HEAL: the same reading for a file rename git recorded } // api-surface (contract drift) — B10.2e TIERED into two shapes on the PUBLIC/exported surface: // (A) a public canonId not yet in the baseline public set. Tiered by whether the canonId existed in // ANY baseline per-symbol map at all (locBySym is populated for EVERY symbol with a canonId, // public or not — see computeSnapshot — so its absence is a clean, single-map "genuinely new // symbol" test that also covers "its enclosing file is new", since a new file's symbols are // trivially absent from every baseline map too): absent ⇒ additive new-feature surface, not a // contract break → sev=minor, facet surface="new-symbol". Present (existed at baseline in some // form, e.g. a visibility flip from private → public) ⇒ facet surface="contract-change", stays major. // (B) a public canonId ALREADY in the baseline public set whose declared parameter COUNT changed vs // baseline: a genuine signature edit on code external callers may already depend on. ANY delta // counts (not gated by kParamBar/kMinorParamDelta the way the separate `params` kind is — a public // contract's arity moving by even 1 is externally observable regardless of function size) → stays // major, facet surface="contract-change", was/now = the parameter counts. BOTH sides are the // per-canonId MAX over EVERY symbol sharing the key — mirroring computeSnapshot's own paramsBySym // aggregation EXACTLY, public and non-public alike, NOT just the public overload set. Two reasons: // constructors are the common multi-overload case (a default ctor alongside a parameterized one), // and comparing a single arbitrarily-iterated overload's raw count against the baseline's // MAX-aggregated one would manufacture a phantom regression on an UNCHANGED overload set purely // from NodeId iteration order (the exact "overload trap" this file guards against everywhere else). // And §P13.4: canonicalId degrades to the BARE NAME for scope-less free functions, so same-named // symbols COLLIDE across files and languages (a 4-param module-level Python `add` shares its key // with a 2-param C header `add`). The baseline side (computeSnapshot) folds ALL of them into its // MAX; a public-only now-side reads a lower MAX for the same unchanged set → a phantom // contract-change row, and a gating exit, on a CLEAN tree (gate: test/qualitycrosslangcheck.sh). // Same-set aggregation on both sides makes a clean tree vacuously regression-free by construction. // Known, accepted cost: a colliding non-public same-name symbol with a higher arity masks a real // arity change on the public one — inherent to bare-name keying, identical to the `params` kind. // Report each canonId once — overloads collapse to one canonId, so gate on "not already reported this // key" to avoid one per overload. gtl::btree_map nowParamsBySym; for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } std::uint32_t& slot = nowParamsBySym[ keyByNode[i] ]; slot = std::max( slot, std::uint32_t( ing.symbols[i].params ) ); } // Q-DIAL-4 — the two inputs the tiering below reads. `paramsRowKeys` is derived from the rows ALREADY // pushed rather than plumbed out of perSymbolKind: `params` is the only kind that can have reported an // arity change by now, and reading it off `regs` keeps the fold honest even if that kind's own gate moves. std::vector paramsRowKeys; for( const Regression& r : regs ) { if( r.kind == "params" ) { paramsRowKeys.push_back( r.key ); } } std::sort( paramsRowKeys.begin(), paramsRowKeys.end() ); const std::vector trailingDefaults = trailingDefaultByNode( ing ); ScratchMap apiSeen( ing.symbols.size() ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() || !isPublicApi( ing, i ) ) { continue; } const std::uint64_t key = keyByNode[i]; if( !insertScratchSeen( apiSeen, key ) ) { continue; // overload of an already-reported symbol } if( !std::binary_search( base.publicApi.begin(), base.publicApi.end(), key ) ) { const bool isNewSymbol = !existedAtBaseline( key ); // SAME oracle the r26 origin axis uses — one source of truth if( isNewSymbol || contentMoves.isTarget( key ) ) // QD-RENAME-IDENTITY: a matched symbol's export is no body fact; counted as before the match { // Q-DIAL-4 — A COUNT, NOT N ROWS. This row could never gate (the legend says so), it is one // per new export, and it dominated the document: 103 of 119 api-surface rows over 40 replayed // commits, 193 of the 1,177 rows in this repo's own committed ack ledger — acked one at a // time, by hand, for a fact the header can state in one attribute. api-new-surface= on the // root says how much new public surface arrived; nothing is hidden, and nothing about it was // ever actionable per row. if( apiNewSurfaceOut ) { ++( *apiNewSurfaceOut ); } continue; } regs.push_back( { "api-surface", g.canonId[i], 0, 0, key, false, "contract-change", false } ); // a visibility flip: it existed, and it is public now stampLoc( i ); continue; } const auto pit = base.paramsBySym.find( key ); if( pit == base.paramsBySym.end() ) { continue; // no baseline params recorded — nothing to compare } const std::uint32_t nowParams = nowParamsBySym[ key ]; // MAX-aggregated — see the overload-trap note above if( nowParams == pit->second ) { continue; } if( nowParams < pit->second ) { continue; // Q-DIAL-4 — the surface got SMALLER. This document's first sentence is "only what a // change made WORSE"; three rows over 40 commits reported an arity DROP as a // regression (probeBodyCost 7->5, selectMonotoneBodySubset 7->5, // liftPackageDirMention 4->3). Drift is not the contract this verb publishes. } if( std::binary_search( paramsRowKeys.begin(), paramsRowKeys.end(), key ) ) { continue; // Q-DIAL-4 — ONE FACT, ONE ROW. The `params` kind already reported this symbol's arity // change, and it is the highest-precision kind in the table (77% TRUE); a second row // saying the same thing under another kind is what agents ack. Synthetic S3 // (3 -> 7 parameters) produced two rows for one edit. } // Q-DIAL-4 — one ADDED parameter that carries a DEFAULT is source-compatible by construction: every // existing caller still compiles, which is what 113 of this repo's 132 api-surface acks say in those // words. Still a row (the contract moved), reported sev="minor". const bool trailingDefault = nowParams == pit->second + 1 && i < trailingDefaults.size() && trailingDefaults[i] != 0; regs.push_back( { "api-surface", g.canonId[i], pit->second, nowParams, key, trailingDefault, "contract-change", false } ); // origin: reached only for a symbol already in the baseline public set stampLoc( i ); } // ── §D#4-1 error-masking (GitClear +47%) ────────────────────────────────────────────────────────────── // NEW error-masking constructs vs baseline, per symbol: aggregate the current side to a per-canonId COUNT // (SUM over overloads, mirroring computeSnapshot's constructCountsBySym), and flag a symbol whose count // GREW vs the baseline count (was 0 for a symbol/mask absent from the baseline). No bar — any NEW masking // construct is the regression; the count magnitude is the was/now signal. A pre-existing empty catch in an // UNTOUCHED symbol keeps the same count on both sides → not flagged (the quality-delta contract). // // REPORT-ONLY SHAPES (noise control). The widened handler shapes (log-only / rethrow-only) gate only in a // language kHandlerShapeGates lists; elsewhere they are counted in maskReportBySym as well. A row whose // growth is entirely report-only shapes — the GATING part of the count (total minus report-only) did not // grow — is still printed, as sev="minor", so it never fires exit 2. One row per symbol either way, so the // ack identity (kind, key) and the magnitude it ratchets on stay what they were. // // PLACEHOLDER (the eleventh kind) rides the same pass: a stub or TODO the change ADDED, per symbol, the same // grew-vs-baseline count. It is new-symbol BY CONSTRUCTION — the finding is the added placeholder itself, // code that did not exist at the baseline — so it is marked origin="new-symbol" on every row and never // gates, whatever symbol it lands in (the same way short-horizon-churn is preexisting by construction). { // qd-memory-degrade: the construct pass only for its two kinds — without them every count reads 0 and no row is made const ConstructCounts noCounts; const ConstructCounts& nowCounts = ( scope.kinds & ( kindBit( "error-masking" ) | kindBit( "placeholder" ) ) ) != 0 ? passes.constructCounts( ing, root ) : noCounts; const auto countIn = []( const gtl::btree_map& m, std::uint64_t key ) { const auto it = m.find( key ); return ( it == m.end() ) ? 0u : it->second; }; // report each canonId once, at its first defining symbol (a mask count is a per-canonId magnitude). ScratchMap maskSeen( ing.symbols.size() ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } const std::uint64_t key = keyByNode[i]; const std::uint32_t nowMask = countIn( nowCounts.mask, key ); const std::uint32_t nowStub = countIn( nowCounts.placeholder, key ); if( ( nowMask == 0 && nowStub == 0 ) || !insertScratchSeen( maskSeen, key ) ) { continue; // nothing here now, or already reported at an earlier overload of this id } const std::uint32_t wasMask = countIn( base.maskBySym, key ); const std::uint32_t nowGating = nowMask - std::min( nowMask, countIn( nowCounts.maskReport, key ) ); const std::uint32_t wasGating = wasMask - std::min( wasMask, countIn( base.maskReportBySym, key ) ); // a report-only handler turned gating (a failure-default catch made empty) grows the gating count, not the total // (CodeRabbit 4577036262, #662): either growth is a row if( nowMask > wasMask || nowGating > wasGating ) { // facet="failure-default" when that facet's own count grew: the row's growth includes a site it names const bool failureDefault = countIn( nowCounts.failureDefault, key ) > countIn( base.failureDefaultBySym, key ); regs.push_back( { "error-masking", g.canonId[i], wasMask, nowMask, key, nowGating <= wasGating, failureDefault ? std::string( kShapeFailureDefault ) : std::string(), !existedAtBaseline( key ) } ); stampLoc( i ); } const std::uint32_t wasStub = countIn( base.placeholderBySym, key ); if( nowStub > wasStub ) { regs.push_back( { "placeholder", g.canonId[i], wasStub, nowStub, key, false, {}, true } ); // new-symbol by construction (above) stampLoc( i ); } } } if( kindSelected( scope.kinds, "defect-shape" ) ) { appendDefectShapeRows( regs, ing, g, base, root, existedAtBaseline, stampLoc, scope.macroOverride ); // the twelfth kind (see its doc) } if( kindSelected( scope.kinds, "params" ) ) // QD-SWAP-1117 similar=: on by default, report-only (never gating) { appendSimilarArgsRows( regs, { g, base, moved }, similarRunsByKey( ing, g, keyByNode ), existedAtBaseline, stampLoc ); } // ── §D#4-2 short-horizon churn (GitClear +15% "new code rewritten within two weeks") ─────────────────── // A symbol flags iff THREE independent gates all hold (signal-to-noise round, 2026-07-13): // 1. its FILE had ≥ kShortHorizonMinCommits commits in the last kShortHorizonDays (git COMMIT TIMESTAMPS // vs HEAD's epoch — deterministic, NOT wall-clock); // 2. THIS diff rewrites it: the symbol exists in the baseline AND its RAW-body hash differs (a raw-byte // hash, not metrics — `return 2` → `return 3` moves no metric yet IS a rewrite). A symbol ABSENT from // the baseline is a FIRST write, not a REwrite — brand-new symbols never flag (the old behavior fired // on every added symbol in an active file by construction, drowning real thrash); // 3. COMMITTED thrash evidence: the symbol's baseline (HEAD) body differs from its body at the churn- // window reference commit — or it first appeared inside the window — i.e. commits ALREADY rewrote it // recently and the working tree is rewriting it AGAIN. Without this gate the current uncommitted edit // alone counted as churn, flagging every touched symbol in any active file. Markdown Sections and // test-fixture paths are exempt (docs and fixtures churn by design — the noise rules). // All three gates join on pathQualifiedKey, never the bare canonId — see bodyHashesBySym's doc // (W1-S2 cross-file misattribution; gate: test/qualitysignalcheck.sh §1d). // Git access uses computeDelta's own `root` (= cfg.rootPath on the CLI, the real repo root over MCP); // no git / no HEAD / no obtainable window ref → this kind simply reports nothing (degrade, precision-first). { // qd-memory-degrade: no window mining when the kind is not asked for (no count reaches the threshold, so no row) bool walkUnread = false; // hwh-fix4 (N1): the count walk ended before the window floor, so a count can be short const std::vector commitCounts = kindSelected( scope.kinds, "short-horizon-churn" ) ? gitFileCommitCountsInDayWindow( std::string( root ), ing, kShortHorizonDays, &walkUnread ) : std::vector{}; const bool anyChurn = std::any_of( commitCounts.begin(), commitCounts.end(), []( std::uint32_t c ){ return c >= kShortHorizonMinCommits; } ); // Gate 2 and the exemptions first, from the trees in hand: the history reads below (the window ref tree, the blame) // are asked only for a symbol this diff rewrites, so an unread one is named only when it could have held a row // (hwh-fix4, N1: a clean tree or an untouched file never reports history it did not need). struct ChurnCandidate { NodeId node; std::uint64_t key; std::uint64_t baseBody; }; std::vector candidates; if( anyChurn || walkUnread ) { const gtl::btree_map nowBody = bodyHashesBySym( ing, root ); // fixture exemption, hoisted per file (path scan once, not per symbol). std::vector fixtureByFile( ing.files.size(), 0 ); for( std::uint32_t f = 0; f < ing.files.size(); ++f ) { fixtureByFile[f] = isFixturePath( rootRelPath( ing, f ) ) ? 1 : 0; } ScratchMap churnSeen( ing.symbols.size() ); for( NodeId i = 0; i < ing.symbols.size(); ++i ) { if( i >= g.canonId.size() || g.canonId[i].empty() ) { continue; } const Symbol& s = ing.symbols[i]; if( s.kind == SymKind::Section || s.kind == SymKind::ModuleScope ) { continue; // doc sections churn by design; a module scope has no body to churn (exempt) } if( s.fileId >= commitCounts.size() || fixtureByFile[s.fileId] ) { continue; // fixtures churn by design (exempt) } // W1-S2: join on the path-qualified identity, NOT keyByNode — a scope-less symbol's // bare-canonId key folded every same-named symbol in the tree into one identity, so // gates 2+3 judged cross-file FOLDS (see bodyHashesBySym's doc; gate: §1d). const std::uint64_t key = pathQualifiedKey( relForHash( ing.files[ s.fileId ], root ), s ); if( !insertScratchSeen( churnSeen, key ) ) { continue; // one report per (file, scope, name) identity — same-file overloads fold (one key = one file, one gate 1) } const auto nb = nowBody.find( key ); if( nb == nowBody.end() ) { continue; // no hashable body now (decl only) → nothing to rewrite } const auto bb = base.bodyHashBySym.find( key ); if( bb == base.bodyHashBySym.end() || bb->second == nb->second ) { continue; // gate 2: absent from baseline = a first write, never churn; equal = this diff does not rewrite it } if( commitCounts[s.fileId] < kShortHorizonMinCommits ) { historyUnread.churnWindow = historyUnread.churnWindow || walkUnread; // gate 1 not met, or not known to be continue; } candidates.push_back( { i, key, bb->second } ); } } // The window ref tree is read only when a candidate needs it (an empty candidate list reads nothing and loses nothing); // a file reached the window threshold, so history exists: a ref tree that did not load is unread, not absent. using RefBodies = std::pair, bool>; const auto [ refBody, refOk ] = candidates.empty() ? RefBodies{ {}, true } : computeWindowRefBodyHashes( std::string( root ), kShortHorizonDays, excludes, maxFileBytes ); historyUnread.churnTree = !refOk; if( refOk && !candidates.empty() ) { // B10.2d — SELF-vs-AMBIENT window cutoff, same basis as gates 1/3 (HEAD's own committer epoch // minus the window, never wall-clock). A failed lookup leaves churnCutoffEpoch==0, and every // candidate below then reads churn="unknown" (the blame cannot be asked). const std::int64_t churnHeadEpoch = gitHeadCommitEpoch( std::string( root ) ); // the same `log -1 --format=%ct HEAD` read, 0 on failure const std::int64_t churnCutoffEpoch = churnHeadEpoch > 0 ? churnHeadEpoch - std::int64_t( kShortHorizonDays ) * 86400 : 0; // P3 (r27) — ONE `git diff --unified=0 HEAD -- ` spawn per PATH for the whole loop. The // diff is a pure function of (HEAD, working tree), both fixed for this call, yet it used to be // re-spawned per symbol (measured: 8 byte-identical spawns for a single dirty file). DiffHunkMemo churnHunkMemo; for( const ChurnCandidate& c : candidates ) { const Symbol& s = ing.symbols[c.node]; const auto rb = refBody.find( c.key ); // gate 3: rewritten across window commits (ref ≠ baseline body), or first COMMITTED inside the window. if( rb != refBody.end() && rb->second == c.baseBody ) { continue; } // B10.2d: SELF vs AMBIENT — does THIS diff modify a pre-existing line that was itself // last committed inside the window? See the section comment above churnEditWindowCommitCount. // Q-DIAL-1 — ONE blame-derived number decides both the facet and the severity (see // churnEditWindowCommitCount): >=1 in-window commit on the edited lines is SELF, and it // is now INFORMATIONAL exactly as AMBIENT already was; >= kShortHorizonMinCommits is the // rewrite-thrash that gates. Measured on twelve LANDED commits of this repo (audit Q1 // §2b): the old "SELF gates" rule fired 135 of 171 gating rows, 0% of them a finding a // reviewer would act on, because on an active branch the symbol you wrote this week and // are touching again is churn="self" by construction. bool blameUnread = churnCutoffEpoch <= 0; // no HEAD epoch: the blame cannot be asked const std::uint32_t windowCommits = churnCutoffEpoch > 0 ? churnEditWindowCommitCount( churnHunkMemo, std::string( root ), std::string( relForHash( ing.files[ s.fileId ], root ) ), s.line, s.loc, churnCutoffEpoch, blameUnread ) : 0u; const bool gates = windowCommits >= kShortHorizonMinCommits; // a floor at the bar already proves it, read or not // hwh-fix4 (N1): a refused read under the bar is unknown, never ambient (and never a gating claim it cannot prove) const bool unknown = blameUnread && !gates; historyUnread.churnRows += unknown ? 1u : 0u; const bool self = windowCommits > 0; regs.push_back( { "short-horizon-churn", g.canonId[c.node], 0, commitCounts[ s.fileId ], c.key, !gates, unknown ? "unknown" : self ? "self" : "ambient", false } ); // now = window commit count on the file; origin: ALWAYS preexisting (gate 2 above required a baseline body) stampLoc( c.node ); } } } // ── §D#4-3 reuse-connectivity decline: a NEW clone of a REUSED (high-fan-in) helper (GitClear) ────────── // A clone group (exact Type-1/2 OR gapped Type-3) whose member-SET is NOT in the baseline (a copy this diff // just introduced) AND that contains a member with fan-in ≥ kReusedHelperMinFanin — i.e. the new code // duplicates the ROLE of an existing well-reused helper instead of calling it ("cross-file reuse declining"). // Reuses the SAME new-group gate the duplication kind uses, so it can only fire on a freshly-added copy, // never on pre-existing debt. Fan-in = the symbol's in-edge count in the CSR (who depends on it). Reported // once per new qualifying group (its member list); now = the group's max member fan-in (the reuse it eroded). { const auto* ro = g.inEdges.rowOffsets(); gtl::btree_map reuseSeen; // clone-group count is not strictly bounded by symbol count, so keep the unbounded sorted map here // T13/fix2: reportReusedClones read the SAME clone vectors as reportNewClones (duplication, above) // but carried neither of its two demotions — the all-test-script skip and the idiom→minor demotion — // so a clone group entirely composed of test SCRIPTS (sibling shell gates repeating the house // mcp_call()-style boilerplate by convention) fired this kind even though `duplication` exempts the // identical shape. Both demotions now mirror reportNewClones exactly: the skip continues outright // (never a row), and the idiom verdict rides the row the same way (vd.demoted / cloneIdiomName). const auto reportReusedClones = [ & ]( const std::vector& cgs, const std::vector& vx ) { for( std::size_t ci = 0; ci < cgs.size(); ++ci ) { const CloneGroup& cg = cgs[ci]; const CloneIdiomVerdict& vd = vx[ci]; const std::uint64_t h = cloneGroupHash( cg, ing, root ); if( isHeld( cg, h ) ) { continue; // group already existed → not new } // B10.1a (mirrors reportNewClones): a clone group ENTIRELY composed of test-SCRIPT members // is fixture-class noise — sibling shell test scripts repeat near-identical setup/ok/no // boilerplate by convention (see isTestScriptPath). Exempt only when every member is a test // script, so a real src/ ↔ test-script clone (still worth a look) is unaffected. bool allTestScript = !cg.members.empty(); for( NodeId m : cg.members ) { if( m >= ing.symbols.size() || !isTestScriptPath( rootRelPath( ing, ing.symbols[m].fileId ) ) ) { allTestScript = false; break; } } if( allTestScript ) { continue; } // r27 SUSPICION-C FIX — "the reused helper is preexisting BY CONSTRUCTION" was asserted here // (and in fbc527e's commit message) but never ENFORCED: fan-in ≥ 3 is trivially reached by a // brand-new helper that three brand-new call sites use, so an all-new blob of code duplicating // ITSELF was reported under a kind whose entire meaning is "you eroded reuse that already // existed". The claim is now a precondition: the qualifying high-fan-in member must have // EXISTED at the baseline. Nothing is lost — an all-new self-duplication is still reported by // the `duplication` kind, which is where it belongs. std::uint32_t maxFanin = 0; for( NodeId m : cg.members ) { if( m >= ing.symbols.size() ) { continue; } if( m >= keyByNode.size() || keyByNode[m] == 0 ) { continue; // unclassifiable member — never evidence of preexisting reuse } if( !existedAtBaseline( keyByNode[m] ) ) { continue; // a NEW helper's fan-in is not reuse this change eroded } maxFanin = std::max( maxFanin, std::uint32_t( ro[m + 1] - ro[m] ) ); // in-edge count = fan-in } if( maxFanin < kReusedHelperMinFanin ) { continue; // no PREEXISTING reused helper in the group } if( cloneGroupIsOutOfScope( cg ) ) { continue; // Q-DIAL-5 — the same three shapes, on the same groups: a helper cannot have // eroded its own reuse by being overloaded, and an upstream body is not ours. } if( !reuseSeen.insert( { h, 1 } ).second ) { continue; // same member-set already reported } std::vector ids; for( NodeId m : cg.members ) { if( m < g.canonId.size() ) { ids.push_back( g.canonId[m] ); } } std::sort( ids.begin(), ids.end() ); std::string joined; for( std::size_t k = 0; k < ids.size(); ++k ) { joined += ids[k]; if( k + 1 < ids.size() ) { joined += " | "; } } regs.push_back( { "new-clone-of-reused-helper", joined, 0, maxFanin, h, vd.demoted, std::string( cloneIdiomName( vd.idiom ) ), cloneGroupIsNew( cg ) } ); // now = the eroded helper's fan-in; ack identity = the member-set hash stampCloneLoc( cg ); } }; reportReusedClones( exactClones, exactIdioms ); reportReusedClones( type3Clones, type3Idioms ); } // qd-memory-degrade: only the selected kinds' rows. A pass shared by two kinds (error-masking and placeholder, the // two clone kinds) or read by another kind (params, which api-surface's one-fact-one-row rule reads) ran for the // selected one; its other rows are dropped here, so a selected kind's rows are exactly its rows in a full answer. if( scope.kinds != kAllKinds ) { std::erase_if( regs, [ &scope ]( const Regression& r ) { return !kindSelected( scope.kinds, r.kind ); } ); } std::sort( regs.begin(), regs.end(), []( const Regression& a, const Regression& b ) { return a.kind != b.kind ? a.kind < b.kind : a.sym < b.sym; } ); if( historyUnreadOut ) { *historyUnreadOut = historyUnread; } return regs; } // Promoted from main.cpp (2026-08-29 main.cpp split): the --dead-code eligibility trio is asked by TWO verb // families — --dead-code (runQualityViews) and --safe-delete (the navigate family) — and by the communities' // isolate stats, so the shared contract lives in the quality domain header both consult. inline bool isHeaderPath( std::string_view path ) noexcept { const std::size_t dot = path.rfind( '.' ); if( dot == std::string_view::npos ) { return false; } const std::string_view extension = path.substr( dot + 1 ); return extension == "h" || extension == "hpp" || extension == "hh" || extension == "hxx"; } // lane/safe-delete: the whole-word "static" token scan behind the --dead-code high-confidence detector's // internal-linkage check, factored to a PURE function (source text + a signature byte range in, bool out) // so a single-symbol check (--safe-delete's dead_code_candidate=) can ask the identical question without // re-deriving it. The --dead-code block below keeps only what is its own — the per-file sourceFor() cache // that amortizes this scan across every candidate in the tree; a single-symbol check has nothing to // amortize, so it calls this directly on its own one-off read. // // 0.6.6 D4: a `static` inside a COMMENT is not a linkage specifier. A Python def's signature span runs on through the // comment lines that open its body, so `# the static type is unchanged` there made a pytest method a "high-confidence" // internal-linkage row. offsetInComment answers, for a byte of the span, whether a line comment (`//` or `#`) opened // earlier on its line or a `/*` opened earlier in the span is still unclosed — language-agnostic, because a sig span // opens at the def itself, so a `#` or `//` before the token on its line is a comment in every grammar that has one // (a `#` inside a string literal reads as a comment too: the conservative side, one row fewer, never one more). inline bool offsetInComment( std::string_view source, std::size_t spanBegin, std::size_t position ) noexcept { EXPECTS( spanBegin <= position && position <= source.size() ); const std::size_t newline = position == 0 ? std::string_view::npos : source.rfind( '\n', position - 1 ); const std::size_t lineBegin = std::max( spanBegin, newline == std::string_view::npos ? std::size_t( 0 ) : newline + 1 ); const std::string_view head = source.substr( lineBegin, position - lineBegin ); if( head.find( '#' ) != std::string_view::npos || head.find( "//" ) != std::string_view::npos ) { return true; } const std::string_view span = source.substr( spanBegin, position - spanBegin ); const std::size_t open = span.rfind( "/*" ); return open != std::string_view::npos && span.find( "*/", open + 2 ) == std::string_view::npos; } // CR 4396503844: C99 `int api(int values[static 1])` — `static` inside [ ] qualifies the array parameter, it is no storage class. inline bool insideSquareBrackets( std::string_view source, std::size_t begin, std::size_t position ) noexcept { int depth = 0; for( std::size_t at = begin; at < position; ++at ) { depth += source[ at ] == '[' ? 1 : source[ at ] == ']' && depth > 0 ? -1 : 0; } return depth > 0; } inline bool sourceHasStaticToken( std::string_view source, std::size_t sigStartByte, std::size_t sigEndByte ) noexcept { const std::size_t begin = std::min( sigStartByte, source.size() ); const std::size_t end = std::min( sigEndByte, source.size() ); if( begin >= end ) { return false; } constexpr std::string_view token = "static"; std::size_t position = begin; while( ( position = source.find( token, position ) ) != std::string_view::npos && position + token.size() <= end ) { const auto isIdentifier = []( char c ) noexcept { return std::isalnum( static_cast( c ) ) || c == '_'; }; const bool leftBoundary = position == begin || !isIdentifier( source[ position - 1 ] ); const bool rightBoundary = position + token.size() == end || !isIdentifier( source[ position + token.size() ] ); if( leftBoundary && rightBoundary && !offsetInComment( source, begin, position ) && !insideSquareBrackets( source, begin, position ) ) { return true; } position += token.size(); } return false; } // D1 fix round 1: internal linkage of ONE definition. The token is the C-family storage class, so the scan runs only for a // language whose LangFacts row says `staticLinkage` (C, C++, Objective-C). A Python parameter `static=False`, a TypeScript literal // type `'static'` and a Rust `'static` lifetime are the same four letters and no linkage: before this gate they made a public // function an "internal-linkage" row (--dead-code ``: zed listed 67 Rust rows; the test-only `` rows inherited it). inline bool symbolHasStaticLinkage( const Symbol& s, std::string_view source ) noexcept { return langFacts( s.lang ).staticLinkage && sourceHasStaticToken( source, s.sigStartByte, s.sigEndByte ); } // The nearest non-blank, non-comment line above a Python def at `defByte` (or the def's own first byte) opens with '@'. inline bool pythonDefIsDecorated( std::string_view source, std::size_t defByte ) noexcept { EXPECTS( defByte <= source.size() ); const std::size_t own = source.find_first_not_of( " \t", defByte ); if( own != std::string_view::npos && source[ own ] == '@' ) { return true; } std::size_t lineEnd = defByte == 0 ? std::string_view::npos : source.rfind( '\n', defByte - 1 ); // the newline ending the line above while( lineEnd != std::string_view::npos && lineEnd > 0 ) { const std::size_t prevNewline = source.rfind( '\n', lineEnd - 1 ); const std::size_t lineBegin = prevNewline == std::string_view::npos ? 0 : prevNewline + 1; const std::size_t text = source.find_first_not_of( " \t\r", lineBegin ); const bool blankOrNote = text == std::string_view::npos || text >= lineEnd || source[ text ] == '#'; if( !blankOrNote ) { return source[ text ] == '@'; } lineEnd = prevNewline; } return false; } // The nearest `class (…):` header above `beforeByte` names a *TestCase among its OWN bases. inline bool pythonClassBasesNameTestCase( std::string_view source, std::string_view className, std::size_t beforeByte ) { const std::string header = "class " + std::string( className ); for( std::size_t at = source.rfind( header, beforeByte ); at != std::string_view::npos; at = at == 0 ? std::string_view::npos : source.rfind( header, at - 1 ) ) { const std::size_t after = at + header.size(); if( after < source.size() && ( source[ after ] == '(' || source[ after ] == ':' || source[ after ] == ' ' ) ) { const std::size_t colon = source.find( ':', after ); return source.substr( after, colon == std::string_view::npos ? 0 : colon - after ).find( "TestCase" ) != std::string_view::npos; } } return false; } // 0.6.6 D4: a DECORATED Python def. It is not a --dead-code / dead_code_candidate= row, and it is counted apart from the // test-runner roots below (decorated-excluded=), because the reason differs: a decorator MAY register the def (`@app.route`, // `@pytest.fixture`, `@click.command` — the registry's call is invisible to the graph), but a plain wrapper // (`@staticmethod`, `@property`, `@functools.lru_cache`) registers nothing. Such a row's only Python "linkage" evidence is a // non-comment `static` token (a parameter named static), which is never real linkage, so dropping it removes a claim the // detector could not back; the count says how many were dropped for this reason alone. Python only. inline bool pythonDecoratedDef( const Symbol& s, std::string_view source ) noexcept { return s.lang == Lang::Python && s.sigStartByte <= source.size() && pythonDefIsDecorated( source, s.sigStartByte ); } // 0.6.6 D4: a Python def that a TEST RUNNER reaches with no call the index can see — so zero in-edges on it is not // evidence of anything, and --dead-code / --safe-delete's dead_code_candidate= must not name it (runner-root-excluded=): // * pytest discovery in a test_*.py / *_test.py file: a `test*` function or method, and the xunit-style hooks // (setup_module, setup_method, teardown_class …); // * unittest: a `test*` method or a setUp/tearDown/setUpClass/tearDownClass/asyncSetUp/asyncTearDown hook of a class // whose OWN base list names a *TestCase (unittest.TestCase, IsolatedAsyncioTestCase, a framework's TestCase). // Not covered, all on the "still reported" side: a TestCase subclass reached only through an intermediate base class, // and pytest's python_files/python_functions overrides from a config file. Python only; every other language is false. inline bool pythonRunnerRoot( std::string_view path, const Symbol& s, std::string_view source ) noexcept { if( s.lang != Lang::Python || s.sigStartByte > source.size() ) { return false; } const std::size_t slash = path.rfind( '/' ); const std::string_view baseName = slash == std::string_view::npos ? path : path.substr( slash + 1 ); const bool pytestFile = ( baseName.starts_with( "test_" ) || baseName.ends_with( "_test.py" ) ) && baseName.ends_with( ".py" ); const std::string_view name = s.name; if( pytestFile && ( name.starts_with( "test" ) || std::ranges::contains( kXunitHooks, name ) ) ) { return true; } if( s.scope.empty() || !( name.starts_with( "test" ) || std::ranges::contains( kUnittestHooks, name ) ) ) { return false; } const std::size_t scopeSep = s.scope.rfind( "::" ); return pythonClassBasesNameTestCase( source, scopeSep == std::string::npos ? std::string_view( s.scope ) : std::string_view( s.scope ).substr( scopeSep + 2 ), s.sigStartByte ); } // D1 TESTONLY-DEAD: Python's own internal-interface evidence, standing in for the `static` token C/C++ spells — PEP 8's // "internal interfaces" convention: a leading-underscore name, or a def inside a module or package whose path component // starts with one underscore (`_segment_tools.py`, `_internal/x.py`). A dunder component (`__init__.py`, `__main__.py`) // is the language's own spelling, not a privacy mark. `relPath` is ROOT-relative, so a directory above the root never // counts. MODULE-LEVEL defs only (empty scope): a method's reach is its class's, and a class in a private module is often // re-exported as public API (textual's widgets/_data_table.py DataTable), with methods a framework dispatches by name // (action_*, _on_*). Only a language whose LangFacts row sets underscorePrivacy (Python); every other language is false. // Read only by --dead-code's test-only rows (test-only=). inline bool underscorePrivateDef( std::string_view relPath, const Symbol& s ) noexcept { if( !langFacts( s.lang ).underscorePrivacy || !s.scope.empty() ) { return false; } const auto privateMark = []( std::string_view part ) noexcept { return part.size() > 1 && part[ 0 ] == '_' && part[ 1 ] != '_'; }; if( privateMark( s.name ) ) { return true; } std::size_t start = 0; while( start < relPath.size() ) { const std::size_t slash = relPath.find( '/', start ); const std::size_t end = slash == std::string_view::npos ? relPath.size() : slash; if( privateMark( relPath.substr( start, end - start ) ) ) { return true; } start = end + 1; } return false; } // D1 fix round 1 (F4): pytest's own test file. A root `conftest.py` sits outside every test/ directory, so the shared test-path // rule (filter.h isTestPath) reads its helpers as library code; --dead-code's test-only rows must not list them as library // functions. The base name alone decides (any conftest.py, at any depth). inline bool isConftestFile( std::string_view path ) noexcept { return namesplit::afterLast( path, "/" ) == "conftest.py"; } // D1 fix round 1 (F3): the module name a Python file answers to at its tail: the file stem, or the package directory's name for // `__init__.py`. "" for a path that is not a .py file (or an __init__.py with no directory). inline std::string_view pythonModuleTail( std::string_view relPath ) noexcept { if( !relPath.ends_with( ".py" ) ) { return {}; } relPath.remove_suffix( 3 ); if( namesplit::afterLast( relPath, "/" ) != "__init__" ) { return namesplit::afterLast( relPath, "/" ); } relPath.remove_suffix( relPath.size() == 8 ? 8 : 9 ); // "__init__" or "/__init__" return namesplit::afterLast( relPath, "/" ); } // CR 4396503848: the offset of the `import` keyword of a `from import …` line, or npos for any other line. Any run of // spaces or tabs may stand around the keyword (`from ._impl import *`); the keyword is a whole word between two of them. inline std::size_t pythonImportKeywordAt( std::string_view line ) noexcept { const auto blank = [ & ]( std::size_t at ) noexcept { return at < line.size() && ( line[ at ] == ' ' || line[ at ] == '\t' ); }; if( !line.starts_with( "from" ) || !blank( 4 ) ) { return std::string_view::npos; } for( std::size_t imp = line.find( "import" ); imp != std::string_view::npos; imp = line.find( "import", imp + 1 ) ) { if( blank( imp - 1 ) && blank( imp + 6 ) ) { return imp; } } return std::string_view::npos; } // D1 fix round 1 (F3): the tail of every module a `from import *` line in `text` names (`from ._impl import *` and // `from pkg._impl import *` both give "_impl"). A glob re-exports the module's public names through the importing package, so a // def in that module is part of the package's public surface even when no other file spells its name. Line-based text, not // parsed Python: a glob inside a string or a comment reads as one too (a row fewer, never one more). inline std::vector pythonGlobImportTails( std::string_view text ) { std::vector tails; for( std::size_t at = 0; at < text.size(); ) { const std::size_t eol = std::min( text.find( '\n', at ), text.size() ); std::string_view line = text.substr( at, eol - at ); at = eol + 1; line.remove_prefix( std::min( line.find_first_not_of( " \t" ), line.size() ) ); const std::size_t imp = pythonImportKeywordAt( line ); if( imp == std::string_view::npos ) { continue; } std::string_view after = line.substr( imp + 7 ); after.remove_prefix( std::min( after.find_first_not_of( " \t" ), after.size() ) ); if( !after.starts_with( '*' ) ) { continue; } std::string_view module = line.substr( 5, imp - 5 ); module.remove_prefix( std::min( module.find_first_not_of( " \t" ), module.size() ) ); module.remove_suffix( module.size() - std::min( module.find_last_not_of( " \t" ) + 1, module.size() ) ); const std::size_t dot = module.rfind( '.' ); const std::string_view tail = dot == std::string_view::npos ? module : module.substr( dot + 1 ); if( !tail.empty() ) { tails.push_back( tail ); } } return tails; } // lane/safe-delete: the --dead-code high-confidence PRECONDITIONS on symbol KIND/PLACEMENT alone — a // source free function with a body, living outside a header. Deliberately excludes in-degree (the // --dead-code block tests the corpus-wide in-edge CSR; --safe-delete already has its own 1-hop caller // list for one already-resolved definition and reuses that instead of recomputing it here) and internal // linkage (sourceHasStaticToken above — a separate question, needing the file's bytes). inline bool deadCodeEligibleKind( const rw::IngestResult& ing, const rw::Symbol& s ) noexcept { return s.kind == rw::SymKind::Function && s.sigEndByte < s.endByte && !isHeaderPath( ing.files[ s.fileId ] ); } } // namespace quality } // namespace rw