kb+docs: an injection that does not fail names an untested path

Five facts from Wave J. The one worth reading is the first: check_the_checker
is written as "inject the fault and watch it fail", and the case where it
PASSES is the more informative result, because it is evidence about the test
rather than about the code. On improvise-sihr, forcing
ReturnToNormalUnlessMoved alone back to Normal left the characterization test
green — which is how the untested path was found. An empty colon line takes
ExecuteCommand's is_empty branch and settles through ChangeMode, so the effect
settling every colon line that actually runs had no test. There are two tests
rather than one because of it.

Also records why ChangeMode could hide the bug at all: it was a simple_effect!,
which declares a one-field newtype writing one place, so there was nowhere for
a rule to live and the exit mode had to be a constant in the keymap and in
each commit command. Gotcha 16 already warns the macro's kind argument must be
mandatory; this is a second cost of the same shape.

And that improvise-9c9o's ticket pre-diagnosed its own fix as a protocol
change, and was wrong — the basis is App's own bookkeeping, so it was achieved
by moving where the re-base happens. A pre-diagnosis is a hypothesis wearing
the authority of a decision.

Inventory: three protocol files were absent entirely — help.rs (925),
client.rs (255) and resolve.rs, which at 2477 lines and 46 tests is the
largest file in the crate.

Filed improvise-e5pf: Command::ChangeMode(Normal) is on the wire and
reduce_view folds it without the records resolution. Latent — keys.rs emits no
ChangeMode and a view-half command never reaches the host's slice, both
verified rather than assumed — and closeable only by enriching the projection.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH

.beads/issues.jsonl

@@ -194,6 +194,8 @@
 {"_type":"issue","id":"improvise-pby","title":"2.2 Write the README","description":"Replace existing README.md with new one under 250 lines. Sections in order: Title, one-sentence pitch, inline demo GIF, why this exists (Lotus Improv reference), quick start, key bindings, installation (Nix/crates.io/prebuilt - no Homebrew), codebase overview, expectations disclaimer, license. No badges, TOC, or contributing guide.","status":"closed","priority":2,"issue_type":"task","assignee":"Edward Langley","owner":"el-github@elangley.org","created_at":"2026-04-09T04:07:32Z","created_by":"Edward Langley","updated_at":"2026-07-30T23:06:31Z","closed_at":"2026-04-09T07:02:52Z","close_reason":"README written with all 10 required sections, committed. License updated to Apache-2.0 per user request.","dependency_count":0,"dependent_count":2,"comment_count":0}
 {"_type":"issue","id":"improvise-ihv","title":"2.1 Add Nix tooling for asciinema, VHS, and cargo-dist","description":"Modify flake.nix to add pkgs.asciinema and pkgs.vhs to dev shell nativeBuildInputs. Add cargo-dist if packaged in nixpkgs. Add runtime deps for VHS (ttyd, ffmpeg) if needed. Verify tools work via nix develop --command. Add nix run app or shell script for demo recording workflow.","status":"closed","priority":2,"issue_type":"task","assignee":"Edward Langley","owner":"el-github@elangley.org","created_at":"2026-04-09T04:07:30Z","created_by":"Edward Langley","updated_at":"2026-07-30T23:06:31Z","closed_at":"2026-04-09T07:30:19Z","close_reason":"asciinema, vhs, cargo-dist added to flake.nix dev shell and verified. cargo-dist wrapper enables 'cargo dist' subcommand. scripts/record-demo.sh added.","dependency_count":0,"dependent_count":3,"comment_count":0}
 {"_type":"issue","id":"improvise-yk4","title":"Phase 2: README and demo artifacts","description":"The main launch work. README is 80% of the launch, demo artifacts are 20%. Covers Nix tooling for asciinema/VHS, writing the README, creating demo GIF and asciinema casts, and verifying all artifacts.","status":"closed","priority":2,"issue_type":"feature","assignee":"spot","owner":"el-github@elangley.org","created_at":"2026-04-09T04:05:49Z","created_by":"Edward Langley","updated_at":"2026-04-14T07:47:43Z","closed_at":"2026-04-14T07:47:43Z","close_reason":"All 5 subtasks closed; artifacts verified present and tracked in git (README.md, docs/demo.gif, docs/demo.tape, docs/casts/*.cast).","dependencies":[{"issue_id":"improvise-yk4","depends_on_id":"improvise-abz","type":"blocks","created_at":"2026-04-08T23:37:37Z","created_by":"Edward Langley","metadata":"{}"},{"issue_id":"improvise-yk4","depends_on_id":"improvise-d4w","type":"blocks","created_at":"2026-04-08T23:37:36Z","created_by":"Edward Langley","metadata":"{}"},{"issue_id":"improvise-yk4","depends_on_id":"improvise-ihv","type":"blocks","created_at":"2026-04-08T23:37:34Z","created_by":"Edward Langley","metadata":"{}"},{"issue_id":"improvise-yk4","depends_on_id":"improvise-odx","type":"blocks","created_at":"2026-04-08T23:37:35Z","created_by":"Edward Langley","metadata":"{}"},{"issue_id":"improvise-yk4","depends_on_id":"improvise-pby","type":"blocks","created_at":"2026-04-08T23:37:36Z","created_by":"Edward Langley","metadata":"{}"}],"dependency_count":5,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"improvise-e5pf","title":"Command::ChangeMode(Normal) is on the wire and reduce_view folds it without the records resolution","description":"Found by the /code-review pass on PR #91 (improvise-sihr), and checked rather than assumed.\n\nimprovise-sihr made AppMode::Normal resolve through App::normal_mode(), so a minibuffer opened over a records grid returns to RecordsNormal. That resolution lives on the App. Command::ChangeMode(AppMode::Normal) is also on the WIRE, and reduce_view folds it into a client's ViewState WITHOUT the resolution, so a thin client would settle into plain Normal while its layout is still records.\n\n## Why it is latent rather than live\n- keys.rs emits no ChangeMode at all; the only wasm-client occurrences are its own tests.\n- apply_command's catch-all arm returns Dirty::NOTHING, so a view-half command never reaches the host's own slice (gotcha 36).\n\nBoth were verified, not assumed.\n\n## Why it cannot be closed the obvious way\nA client holds a GridCache, not a GridLayout, so \"is this grid records-shaped\" is not a fact it has. Moving the resolution client-side would be a SECOND DERIVATION of records-ness, which is improvise-edp's disease.\n\n## Acceptance Criteria\n- The projection carries what the client needs to settle the mode correctly. Gotcha 47's shape: where a client cannot compose the answer, ENRICH THE PROJECTION rather than moving resolution back to the host.\n- Or: a written argument that ChangeMode(Normal) should not be on the wire at all, plus its removal.\n\nDo NOT close this by having the client re-derive records-ness from the axes.\n","status":"open","priority":3,"issue_type":"bug","owner":"el-github@elangley.org","created_at":"2026-09-21T11:04:35Z","created_by":"Edward Langley","updated_at":"2026-09-21T11:04:48Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"improvise-e8no","title":"A wide numeric category now refuses a fit that used to ignore it","description":"improvise-zv8t forces every document category to `Forced::Categorical`, which is\nright (a `Year` category with items 2024/2025 is a coordinate, not a number).\nThe cost: a WIDE numeric category one-hots past `MAX_FEATURES` and refuses the\nwhole fit, where before it encoded as one numeric feature and a fit that never\nsplit on it succeeded.\n\nMeasured on 100 records with a 100-item numeric `Year` beside a `Cost` that\npredicts `Score` on its own:\n- pre-zv8t: fit lands on `IF(Cost \u003c 48.015...)`; `Year` never appears.\n- post-zv8t: preflight refuses at 101 features.\n\nPinned by `a_wide_numeric_category_now_refuses_a_fit_that_used_to_ignore_it`\nin crates/improvise-gp/src/fit.rs, and argued in context/code/gp.md section 11.\n\nThe workaround the refusal names works: mark the category a Label and the\npre-zv8t feature set is restored exactly. What is lost is the case where the\nuser wants neither -- a wide numeric category left alone while the fit uses the\nmeasures.\n\n## Steps to Reproduce\n\nBuild a model with a Regular category `Year` holding 100 numeric items\n(1900..1999), a Label category for record identity, and two measures `Cost` and\n`Score` where Score = 4000 if Cost \u003e 50 else 1000. Put `Year` on Axis::Row and\n_Measure on Axis::Page. Run `fit_measure(.., \"Score\", ..)`.\n\nPre-zv8t it lands on `IF(Cost \u003c 48.015..)`. Post-zv8t it is refused with\n\"would encode 101 features from 100 records\". The fixture is\n`wide_category_beside_a_good_measure()` in crates/improvise-gp/src/fit.rs.\n\n## Acceptance Criteria\n\nThe honest fix is a budget that can decline A COLUMN rather than the whole\ntable: `encoded_width` (and the exact check beside it) would drop the widest\ncategory and report it as a `Dataset::warnings` notice -- gotcha 37(a), it comes\nback as DATA and nothing prints. That keeps the zv8t decision intact (a category\nis still never inferred numeric) and changes only what the budget does when it\ncannot afford one.\n\nDo NOT close this by making the forcing conditional on cardinality: that is\ninference by another name, and makes the ENCODING depend on a budget rather than\non what the document says.\n","status":"open","priority":3,"issue_type":"bug","owner":"el-github@elangley.org","created_at":"2026-09-21T10:55:32Z","created_by":"Edward Langley","updated_at":"2026-09-21T10:55:39Z","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"improvise-sxsf","title":"cargo test -- --list cannot name the binary, so two crates could share a full test path","description":"MEASURED 2026-09-21 (PR #88). Re-verified latent: 1444 names, zero duplicate full paths, zero duplicate (crate, path) pairs.\n\nTHE PROPOSED FIX IS DECLINED ON TWO INDEPENDENT GROUNDS, and the second is the interesting one:\n\n1. COST: 45.2s against 2.4s for the one workspace call (11 members, warm) — 18x. And --check-evidence needs the --ignored twin, so the honest figure is 22 cargo invocations.\n\n2. IT DOES NOT CLOSE THE CLASS IT NAMES. A package is not a binary. The improvise crate alone has FIVE integration test binaries beside its lib, and an integration test's top-level fn lists with NO MODULE PATH AT ALL — 60 of 1444 names are bare. So '-p improvise' prefixes all six identically and tests/a.rs::foo still cannot be told from tests/b.rs::foo.\n\nAny real fix is per-TARGET (--lib, --test \u003cname\u003e), not per-package. Whoever takes this should start there.\n\nWorth noting how this was found: the agent set out to time the per-package fix and discovered it does not work while reading the target list. The cost measurement was the excuse for reading it; the correctness finding was the payoff — an argument for measuring declines rather than asserting them.","status":"open","priority":3,"issue_type":"bug","owner":"el-github@elangley.org","created_at":"2026-09-21T04:49:16Z","created_by":"Edward Langley","updated_at":"2026-09-21T05:23:48Z","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"improvise-8shu","title":"Constrain the .improv grammar generator's strategy; improvise-io's lib binary is the run's outlier","description":"Split out of improvise-8ec3, whose second half (stop pinning one machine's number) is done. This is the first half, left open.\n\nimprovise-io's lib binary is an order of magnitude above every other binary in the run on every machine it has been measured on: 1.40-1.45s over three runs here (vs a ~0.06s median), 3.70-5.24s on the machine that filed 8ec3. The ratio is the portable signal; the seconds are not.\n\nIts slow half is the grammar-walking generator in persistence/parse.rs plus the .improv roundtrip proptests at the default 256 cases. A grammar walk with no size bound generates deeply nested documents whose cost is not uniform across cases, so a few cases dominate.\n\ndoctrine(proptest_cases) rules out the cheap fix: constrain the strategy, do NOT lower the count below 256.\n\nAcceptance: improvise-io's lib binary is no longer an order of magnitude above the run's median, with the case count still 256 and the properties still covering groups, formulas, views, hidden items and pipe-quoting edges. Report the before/after ratio, not seconds.","status":"closed","priority":3,"issue_type":"task","owner":"el-github@elangley.org","created_at":"2026-09-21T04:14:01Z","created_by":"Edward Langley","updated_at":"2026-09-21T05:15:42Z","closed_at":"2026-09-21T05:15:42Z","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"improvise-9v0j","title":"view_frame and view_shape are separated by example, not by property","description":"Found by the adversarial review of PR #78.\n\nimprovise-ni6k introduced view_frame (the drawn frame, drives the cursor) beside view_shape (the configuration, drives layout_version). They answer different questions -- AddCategory of an empty category moves view_shape and not view_frame -- and context/code/command.md section 'Two observations, not one' now records the argument.\n\nTHE GUARD IS ONE-DIRECTIONAL. Tests assert specific commands move specific counters. Nothing asserts the general relation, in either direction:\n\n- Is every reframe also a reshape? (Probably yes: a drawn-frame change should always be a config change. If so it is a property worth pinning, and its failure would mean layout_version under-reports, which per gotcha 35's asymmetry leaves a client wrong FOREVER.)\n- Is every reshape a reframe? (Definitely not -- that is the AddCategory case, and it is the whole reason there are two.)\n\nSo the first is a candidate property test and the second is a documented asymmetry. Today a change that accidentally made view_frame a superset of view_shape, or vice versa, would pass the suite.\n\nWorth doing as a proptest over a generated workbook plus a generated model command, comparing the two differing-key sets. Note the fixture trap improvise-gfvj's investigation turned up: pressing R to enter records mode fires effect::SortData first, so a records-mode fixture built through the key path has an already-sorted store and cannot demonstrate order-sensitive behaviour.","status":"open","priority":3,"issue_type":"task","owner":"el-github@elangley.org","created_at":"2026-09-21T04:01:34Z","created_by":"claude-agent-protocol","updated_at":"2026-09-21T04:01:34Z","dependency_count":0,"dependent_count":0,"comment_count":0}

context/repo-map.md

@@ -342,6 +342,14 @@ frame.rs                 330 /  3t  ClientFrame/ServerFrame — the ONE envelope
                                     ClientFrame::Save is a request, not a Command (gotcha 45)
 basis.rs                 332 /  5t  Basis (the three tiers), Rejection, BasisCache — ADR 001
                                     layer 1. Basis has no Default and no public constructor
+help.rs                  925 /  7t  HelpPage content and Hint { keys: Vec<(KeyCode, KeyModifiers)>,
+                                    command, caption }. `compact` drops a chord by its MODIFIERS
+                                    (anything beyond shift), never by parsing a label it just
+                                    formatted (improvise-thpe) — the guard is the signature
+resolve.rs              2477 / 46t  the browser's key resolvers: a BrowserKey to the Commands it
+                                    composes, mirroring each Cmd line for line INCLUDING where
+                                    siblings disagree (gotcha 47). The largest file in the crate
+client.rs                255 /  5t  ClientState: ViewState + one cache per widget, and the fold
 ```
 
 ### `gp-tree` / `improvise-gp` (`crates/gp-tree/`, `crates/improvise-gp/`)

prolog-sessions/kb.pl

@@ -120,6 +120,8 @@ invariant(key_matching_is_variant_equality_never_unification,'scripts/kb-merge.p
 invariant(duplicate_category_sections_merge_in_pass_one,'Two ## Category: sections naming one category are ONE category, concatenated by ParsedFile::push_category in pass 1 (improvise-349m). Merging in pass 2 was not idempotent: build_category creates its own section item-groups before its own > lines, while format_md writes every item before every > line, so the reparse built the other order. push_category destructures PCategory so a fourth field cannot be silently dropped on the duplicate path. No grammar change was needed -- this is the tree-walker, not the format, and duplicate headers stay legal.').
 invariant(where_and_is_share_a_word_boundary,'where_clause, inline_where and is_expr are all compound-atomic with sp+ after the keyword (improvise-r08u). Non-atomic, pest auto-inserts WHITESPACE and SUM(Rev WHEREAS x = y) reads as a WHERE on a category AS. Note compound-atomicity ALONE refuses that input, since AS x cannot be one identifier, so the residue sp+ actually closes is WHEREAS=y -- a negative test needs both shapes.').
 invariant(evaluate_aggregated_takes_a_named_state,'Model::evaluate_aggregated takes Aggregation::{Exact, OverHidden}, not none_cats: &[String] (improvise-5jm5). The list was consulted once, for emptiness, in every revision since Axis::None was introduced -- the aggregation runs over key.0 via matching_values. Aggregation::of reduces at the boundary and the regression guard is the SIGNATURE. recompute_formulas and aggregate_raw keep &[String] because they walk the elements.').
+invariant(normal_mode_is_resolved_not_carried,'AppMode::Normal is resolved through App::normal_mode() when the mode is SET -- ChangeMode and ReturnToNormalUnlessMoved are the only two places a batch sets it, and CloseWizard reads the same function -- so no keymap binding and no commit command carries an exit mode, and none can forget one (improvise-sihr). It reads the batch OPENING layout (gotcha 23), which is the property rather than a defect: that is the grid the user was looking at, and toggle-records-mode works in both directions because of the staleness rather than despite it. Carrying the entry mode on MinibufferConfig was the ticket proposal and was declined -- carried generically it also returns CategoryAdd to CategoryPanel. Known gap, filed as improvise-e5pf: Command::ChangeMode(Normal) is on the wire and reduce_view folds it without the resolution.').
+invariant(the_frame_basis_follows_active_view,'The cursor frame basis re-bases AT THE SWITCH, in the loop, as soon as active_view moves -- not at the next geometry effect. Guarding the COMPARISON on the two names agreeing (PR #78 round 2) exempted the first geometry effect after a mid-batch SwitchView from the check altogether, which is under-reporting and gotcha 35 expensive side. SwitchView stays ViewOnly: the basis is App own bookkeeping and none of it crosses the wire, so this needed no protocol change. Costs one extra view_frame per batch that both switches and moves geometry, DrillIntoCell paying most.').
 doctrine(bug_first,'write a failing test demonstrating the bug before fixing it').
 doctrine(unit_over_e2e,'prefer small unit tests over integration/e2e').
 doctrine(suite_speed,'Two numbers, because the ambiguity between them is what let this drift: NO SINGLE TEST BINARY may exceed 2 seconds, and the WORKSPACE WALL CLOCK is the sum of them. Measured at 22d43b2: 1309 tests over 33 binaries, ~2.2s wall, longest single binary 1.42s -- so the workspace is already past 2s and the rule that bites is the per-binary one. Re-MEASURE rather than re-assert: cargo test --workspace prints a \"finished in\" per binary. Excludes compilation, and excludes harness/ (Playwright, minutes, its own CI job).').
@@ -267,6 +269,9 @@ doctrine(a_gate_that_can_exit_zero_answers_every_question_it_gates,'A flag ADDS
 doctrine(a_dispatch_bug_is_invisible_to_unit_self_tests,'When every unit in a file is correct and the defect is in main() argument dispatch, no fixture-level table can reach the wiring -- the guard must INVOKE THE PROGRAM, as a subprocess over a temporary tree. improvise-ijql was exactly that shape: every function in check-comment-runs.py was right, and the early return in main() was the bug. Its guard needs both arms: restore the early return and the clean-tree case must fail, AND force the cap to always report a violation, or an always-failing cap satisfies the first arm.').
 doctrine(job_metadata_outlives_the_artifacts_it_describes,'An artifact-lifetime incident is still diagnosable after the artifacts 404: run, job, step and log APIs retain about 90 days where artifacts here retain 1. So a post-hoc artifact COUNT is not evidence about the incident, it is a reading of retention -- improvise-864a 0/1/0 table could not have been produced by expiry at all, since the newest-finalized expires LAST and expiry can only yield 0/1/1 or 0/0/1. Corollary that did the real work: widen the sample before theorising. The ticket framing of \"two of three artifacts\" was a SAMPLING ARTEFACT that made a two-day, sixteen-failure pattern look like a three-run concurrency race, which is the wrong shape entirely.').
 doctrine(a_control_you_already_have_is_cheaper_than_the_hypothesis_you_were_about_to_test,'Diagnosing improvise-864a, the single observation that eliminated five competing explanations at once was a NEGATIVE one already sitting in a log: a run lookup reporting \"Found 2 artifact(s)\" -- its own harness-serve and wasm-bundles present, its own github-pages absent. Same run, same token, same call, same retention, so service flakiness, eventual consistency, retention, token scope and a v3/v4 backend mismatch all die together, since any of them would have taken the siblings too. The agent nearly did not fetch that log, having already established the timeline. Before testing the next hypothesis, ask what is already in hand that would discriminate.').
+doctrine(an_injection_that_does_not_fail_names_an_untested_path,'check_the_checker is written as \"inject the fault and watch it fail\" -- and the case where it PASSES is the more informative result, because it is evidence about the TEST rather than about the code. On improvise-sihr, forcing ReturnToNormalUnlessMoved alone back to AppMode::Normal left the three-mode characterization test GREEN. That is how the untested path was found: an empty colon line takes ExecuteCommand is_empty branch and settles through ChangeMode, so the effect that settles every colon line which actually RUNS had no test at all. Two tests exist rather than one because of it. When an injection passes, do not move on -- ask which path the test never reached.').
+doctrine(a_macro_effect_cannot_carry_a_derivation,'ChangeMode was a simple_effect!, which declares a one-field newtype writing one place -- so there was NOWHERE for a rule to live, and the exit mode had to be a constant in the keymap and in each commit command instead. That is why improvise-sihr could hide: every minibuffer mode returned to a hard-coded Normal and nothing owned the question. Gotcha 16 already warns the macro kind argument must be mandatory; this is a second cost of the same shape. Reaching for simple_effect! forecloses any answer that needs a derivation, so if an effect ever might have to RESOLVE what it writes rather than copy it, write it out.').
+doctrine(a_ticket_that_pre_diagnoses_its_fix_as_a_protocol_change_deserves_checking,'improvise-9c9o was filed saying the honest fix needs the basis to follow active_view, which SwitchView being ViewOnly prevents -- i.e. a protocol change, not a one-liner. It was neither. The basis is App own bookkeeping and none of it is on the wire, so \"the basis follows active_view\" was achieved by moving WHERE the re-base happens -- into the loop, at the switch -- and SwitchView stayed ViewOnly. A pre-diagnosis in a ticket is a hypothesis wearing the authority of a decision, and the author of the ticket is usually the person with the least time to check it.').
 work_done('improvise-8tk',bug_fix,'ZZ/:wq quit even when the save failed, silently discarding the model. Save now aborts the effect batch on failure; save_to_current_path/1 returns Result<String,String>; three tests in ui/effect.rs.').
 work_done('improvise-907',bug_fix,'Import wizard step machine redesign: validation_error() gate at ReviewProposals (no-category and over-limit), history-stack previous() bound to Left on every step, and Done made a real confirmation step holding the built workbook. Superseded improvise-gfq, improvise-o1c, improvise-c6j.').
 work_done('improvise-6sq',wont_do,'Merging EditOrDrill and EnterEditAtCursorCmd into one EnterEdit{mode} is not safe: they differ in WHEN the cell value is read, not in a mode parameter. Added ui/app.rs::tests::i_and_o_diverge_on_an_empty_records_grid as executable evidence.').