From 0283ac81e8c8b73cb797f86c75f2b6c60b54e61f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 21:21:09 +0000 Subject: [PATCH] board: EPIPHANIES entry for the DATAFUSION-PERIMETER proxy-substitution finding E-A-CHEAP-PROXY-GETS-PUBLISHED-AS-THE-QUANTITY-IT-RESEMBLES-1, owed since #871 (merged via GitHub API push while the Bash permission classifier was intermittently unavailable in-session -- a 14,447-line append-only file was not safe to re-transmit whole through that path, so it waited for git). Status updated to SHIPPED: both #870 (first edition) and #871 (correction pass) are on main now. Added the process paragraph the entry was missing -- this is the THIRD occurrence this session of a merge outrunning its review (#866 review-in-flight, #868 merged while DO-NOT-MERGE, #870 merged mid- correction-pass), and a fourth near-miss (#871 itself merged before CodeRabbit's rate-limited review could run). Sharpens E-A-GUARANTEE-WITH-A-RE-EXPORTED-BYPASS-IS-NOT-A-GUARANTEE-1's rule: the reviewable window is "until the operator reads it," which can be zero, so correctness has to be front-loaded into the PR rather than caught after. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01K3RyLEbuNSHxxB3NTTrGki --- .claude/board/EPIPHANIES.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/.claude/board/EPIPHANIES.md b/.claude/board/EPIPHANIES.md index a201fd48..189322d6 100644 --- a/.claude/board/EPIPHANIES.md +++ b/.claude/board/EPIPHANIES.md @@ -1,3 +1,28 @@ +## 2026-07-29 — E-A-CHEAP-PROXY-GETS-PUBLISHED-AS-THE-QUANTITY-IT-RESEMBLES-1 — the doc that named the same-identifier-grep anti-pattern in §9 committed it in §5 + +**Status:** SHIPPED — first edition merged as #870 (`a50299c`); correction pass merged as **#871** (`f91eeb6`), both on `main`. **Confidence:** High — all four corrections re-measured; two changed the document's conclusions, and the `lance-table` number was produced by a probe that had to leave the workspace to be honest. + +**`docs/DATAFUSION-PERIMETER.md` shipped with a §9 "Method note — proxies that lied", listing four proxies caught during research, and closing with the rule *"for dependency questions use `cargo tree`, not `grep`."* Four sections earlier, §5 published a public-surface census built from `grep -c ScanStrategy`.** Those 6 hits were `crate::ir::logical_op::ScanStrategy` in `lance-graph-planner` — a **different type in a different crate** (`Cascade`/`Full`/`Index`/`CamPq`) from `datafusion_planner::cost_estimation::ScanStrategy` (`Cascade`/`FullScan`), which is used in exactly two files, both *inside* the module. It was ranked the widest name on the surface and it was not on the surface at all. A proposal followed from it ("if it is a plain enum describing how to scan, move it to `contract`") — a change that would have been made for a reason that did not exist. + +**The generalization is not "greps are unreliable".** It is: **a proxy that is cheap to compute gets published as the quantity it resembles.** All four first-edition errors have that one shape, and each was one command away from the real measurement: + +| the proxy | what it resembles | what it actually is | +|---|---|---| +| `grep -c ` | a reference census | a name count; names are not identities, only resolved imports are | +| the `lance` façade crate | "Lance storage" the capability | one crate; `lance-table` carries `Manifest`/`Transaction`/`CommitHandler` | +| `cargo tree -p X` **inside** the workspace | crate X's closure | X resolved under workspace **feature unification** | +| `-e normal` | the build's dependency cost | normal edges only; `contract` goes 1 → 16 with build edges | + +**The correction that mattered most inverted a headline.** §1's corollary read *"Lance storage and a Pi-sized binary are mutually exclusive today."* Measured in isolated scratch crates: `lance` = **571 crates / 32 datafusion**; `lance-table` = **280 crates / 1 datafusion** (`datafusion-common`, non-optional, via `lance-file`; `lance-core`'s datafusion deps are behind an optional feature and `lance-table`'s manifest names DataFusion nowhere). Versioned durable storage — the thing the corollary said was unaffordable — costs half the closure and one datafusion crate. **The sentence equated a capability with a crate**, which is the same substitution as the grep, one abstraction level up. + +**Second-order finding: writing an anti-pattern down does not immunise the document against it.** §9 existed, correct and specific, before §5 was written. The defence cannot be vigilance — it has to be mechanical: resolve imports rather than match names; leave the workspace before measuring a closure; count the edge kinds the question is actually about. **A method note is only load-bearing if the method it describes is the one that produced the numbers beside it.** + +**Third: a recipe that does not reproduce its own number is a defect regardless of which end is wrong.** Codex read §2's printed pipeline (`cargo tree -e normal --prefix none | sort -u | wc -l`), correctly observed that `(*)`-marked repeat subtrees survive `sort -u`, and inferred the published 598/70/47 were inflated. They were not — re-derived two ways (strip `(*)`; reduce to `name version` pairs) both give 598. **The counts were right and the recipe was wrong**, which is the worse failure of the two: a wrong number gets challenged, an unreproducible recipe gets trusted and re-run by someone who then disbelieves their own correct result. + +**Process, third occurrence this same session — the merge outran the review AGAIN.** #866 merged with a CodeRabbit review in flight (`E-A-GUARANTEE-WITH-A-RE-EXPORTED-BYPASS-IS-NOT-A-GUARANTEE-1`, which recorded the rule: *when a PR merges with a review in flight, the review must be pulled explicitly*); #868 was merged while marked DO-NOT-MERGE; **#870 merged while this very correction pass was still being written**, so the uncorrected first edition was briefly on `main` and the fixes had to land as a follow-up PR (#871) rather than an edit to #870. #871 then merged again before CodeRabbit's own rate-limit window cleared (a `@coderabbitai review` request came back "review limit reached, next available in 46 minutes" — the review that would have checked the correction pass never ran before merge). Three-then-four instances sharpen the rule past its first statement: **the reviewable window here is not "until merge" but "until the operator reads it," and that window can be zero.** The operational fix is not "wait longer" — it is to make the artifact correct *before* opening the PR wherever the checks are cheap: all four corrections here were four shell commands and one scratch crate, every one of them available before the first edition was ever written. + +Cross-ref: `docs/DATAFUSION-PERIMETER.md` §§1, 2, 2a, 5, 9 (round two), 10; sibling `E-A-COUNT-NEXT-TO-A-CLAIM-IS-READ-AS-BACKING-IT-1` (adjacency sets meaning) and `E-THE-EQUALITY-PASSED-WHILE-AN-AXIS-WAS-CONSTANT-1` (the check that structurally cannot see the defect) — same day, same family: **the artifact was accurate about something other than the question.** + ## 2026-07-29 — E-THE-EQUALITY-PASSED-WHILE-AN-AXIS-WAS-CONSTANT-1 — the anti-vacuity clause found what the equivalence assert structurally could not **Status:** IN PR. **Confidence:** High — the vacuity was caught twice, by the guard, on two different fixtures, and the revert-test proves the equality assert bites when the behaviour actually diverges.