fix(perturbation-sim): degenerate-grid + key-cardinality guards (review #511)

[AdaWorldAPI]

What

Follow-up to merged #511 addressing its open review findings (the PR merged before they were resolved). Scoped to the standalone perturbation-sim crate + one board lint.

Fixed

• CodeRabbit Major — examples/calibrate.rs divide-by-zero on a degenerate grid. k = 24.min(m) is 0 when m == 0, so m / k panics; eigenvector(1) / m - 1 also break for n < 2. Added an up-front guard that exits cleanly with a message.
• CodeRabbit Major — src/hhtl.rs::basin_lambda2 silent corruption. A keys slice whose length ≠ grid.n silently produced wrong basin groupings + λ₂. Added an assert_eq!(keys.len(), grid.n, …) precondition at the API boundary.
• CodeRabbit Minor — TECH_DEBT.md MD018. Reflowed the wrapped #507 so it is no longer parsed as an ATX heading.

Not changed (with reason)

• Codex P2 (infight width) was already fixed before merge — columns.rs has spec("infight", 4, …) (the certified 4-bit width per the §10 note), and the tests assert it. No change needed; the thread was just left open.
• CodeRabbit Major (TECH_DEBT.md append-only) — the 2026-06-16 addendum sits mid-entry instead of as a prepended dated entry. Valid governance observation, but the compliant fix is a 31-line reorganization of board prose that's better done in a focused board-hygiene pass than churned inside a code-fix PR (and moving it separates the addendum from the CI-debuginfo entry it extends). Flagged on the thread; left for the entry owner.

Gates

fmt + clippy -D warnings + test green (75 lib tests) on the standalone perturbation-sim crate.

https://claude.ai/code/session_016b33swuXE23hKtqxsHu9p1

---

Generated by Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Added validation to prevent invalid grid dimensions in simulation calibration.
  • Added runtime precondition checks to ensure input dimensions match expected values.

• Documentation

  • Updated internal development documentation and knowledge base for transcode workflows.

[coderabbitai]

Warning

Review limit reached

@AdaWorldAPI, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 39 minutes and 23 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 12324a03-d7bc-4e0d-9cfd-0966b779d0ac

📥 Commits

Reviewing files that changed from the base of the PR and between b2732db and d1b5477.

📒 Files selected for processing (11)

• .claude/agents/BOOT.md
• .claude/agents/README.md
• .claude/agents/adapter-shaper.md
• .claude/agents/core-first-architect.md
• .claude/agents/core-gap-auditor.md
• .claude/board/EPIPHANIES.md
• .claude/board/TECH_DEBT.md
• .claude/knowledge/core-first-transcode-doctrine.md
• CLAUDE.md
• crates/perturbation-sim/examples/calibrate.rs
• crates/perturbation-sim/src/hhtl.rs

📝 Walkthrough

Walkthrough

Adds three new AI agent specification files (core-first-architect, adapter-shaper, core-gap-auditor) and a supporting knowledge doctrine document (core-first-transcode-doctrine.md) governing C++→Rust transcode/codegen around the OGAR Core; wires them into CLAUDE.md, BOOT.md, and README.md. Separately, adds two runtime precondition guards in the perturbation-sim crate.

Changes

Core-First Transcode Agent System

Layer / File(s)	Summary
Core-First Transcode Doctrine knowledge document .claude/knowledge/core-first-transcode-doctrine.md	Full doctrine doc defining the OGAR Core assume-contract (classid identity, SoA state, EdgeBlock relations, ClassView composition, UnifiedStep invocation), SPO harvest/codegen coupling, scope boundary for leaf vs. hand-port methods, iron guard rule for Core gaps, unicharset falsifier probe, anti-pattern catalogue, cross-references, and provenance.
Three new agent specs .claude/agents/core-first-architect.md, .claude/agents/adapter-shaper.md, .claude/agents/core-gap-auditor.md	core-first-architect enforces doctrine and rejects anti-patterns with a parity-probe gate; adapter-shaper classifies each C++ method as ADAPTER or HAND-PORT and fills the four Core slots (identity, DO-in, DO-out, body); core-gap-auditor identifies Core gaps, rules EXTEND-CORE vs ADAPTER-HACK, and manages the PROBE-OGAR-ADAPTER-UNICHARSET falsifier.
Activation wiring CLAUDE.md, .claude/agents/BOOT.md, .claude/agents/README.md, .claude/board/TECH_DEBT.md	Inserts the doctrine doc into CLAUDE.md's knowledge base list and expands the P0 activation block; adds three Knowledge Activation Protocol trigger rows in BOOT.md; registers agents in README.md (19→22 specialists, new Transcode/Codegen section, updated decision flow); reformats a TECH_DEBT.md cross-reference.

Perturbation-Sim Runtime Guards

Layer / File(s)	Summary
Degenerate-grid and keys-length preconditions crates/perturbation-sim/examples/calibrate.rs, crates/perturbation-sim/src/hhtl.rs	calibrate.rs computes m earlier and exits with code 2 if n < 2 or m == 0; hhtl.rs basin_lambda2 panics with a descriptive message when keys.len() != grid.n.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐇 A rabbit built a doctrine bright,
Three agents woke at transcode's call,
"Shape thin adapters, Core holds tight!"
No parallel models, no fat sprawl—
Just classids, EdgeBlocks, harvest light,
And probes to catch conjecture's flight. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding degenerate-grid and key-cardinality guards to the perturbation-sim crate, with a reference to the related review (#511).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[AdaWorldAPI]

⚠️ Scope note — this branch now carries a second, separable change-set.

Commit b2732db adds the Core-First Transcode doctrine (operator-requested, "capture before it dilutes"): a knowledge doc + a 3-agent ensemble + a CLAUDE.md best-practice link. It is docs-only and disjoint from the perturbation-sim review fixes above (different files entirely):

• + .claude/knowledge/core-first-transcode-doctrine.md — the Core-first inversion (a generated AST/codegen/adapter layer is only as clean as the OGAR Core it targets) + the movable-parts assume-contract + the PROBE-OGAR-ADAPTER-UNICHARSET falsifier (labelled CONJECTURE).
• + .claude/agents/{core-first-architect,adapter-shaper,core-gap-auditor}.md — the ensemble carrying it.
• ~ CLAUDE.md, ~ .claude/agents/README.md, ~ .claude/agents/BOOT.md — knowledge-base link, ensemble registration (19→22 specialists), trigger rows.

It rides here only because both change-sets must live on the one designated session branch while this PR is open (one open PR per head→base). Merging #512 lands both; both are intended. Say the word if you'd prefer the doctrine as a standalone PR and I'll split it (needs a separate branch).

---

Generated by Claude Code

[coderabbitai]

🧹 Nitpick comments (1)

crates/perturbation-sim/src/hhtl.rs (1)

109-115: ⚡ Quick win

Add a focused regression test for the new length precondition.

The new assert is correct, but this contract should be locked with a #[should_panic(expected = "exactly one HHTL key per grid node")] test in the existing #[cfg(test)] module to prevent regressions.

Suggested test addition

 #[cfg(test)]
 mod tests {
     use super::*;
@@
     fn keys_partition_the_nodes() {
         let g = grid_2x2_blocks();
         let k = hhtl_keys(&g);
         // Every node has a key; nodes sharing a full key are in one leaf basin.
         let l2 = basin_lambda2(&g, &k);
         assert!(!l2.is_empty(), "at least one keyed basin");
         assert_eq!(k.len(), g.n);
     }
+
+    #[test]
+    #[should_panic(expected = "exactly one HHTL key per grid node")]
+    fn basin_lambda2_panics_on_key_count_mismatch() {
+        let g = grid_2x2_blocks();
+        let mut k = hhtl_keys(&g);
+        k.pop(); // mismatch: keys.len() == g.n - 1
+        let _ = basin_lambda2(&g, &k);
+    }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/perturbation-sim/src/hhtl.rs` around lines 109 - 115, A regression
test is needed to prevent future violations of the precondition check in the
basin_lambda2 function. Add a new test function to the existing #[cfg(test)]
module that uses the #[should_panic(expected = "exactly one HHTL key per grid
node")] attribute. The test should call basin_lambda2 with mismatched key and
grid node counts (such as fewer keys than grid nodes) to verify that the
assertion triggers the expected panic with the correct error message.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@crates/perturbation-sim/src/hhtl.rs`:
- Around line 109-115: A regression test is needed to prevent future violations
of the precondition check in the basin_lambda2 function. Add a new test function
to the existing #[cfg(test)] module that uses the #[should_panic(expected =
"exactly one HHTL key per grid node")] attribute. The test should call
basin_lambda2 with mismatched key and grid node counts (such as fewer keys than
grid nodes) to verify that the assertion triggers the expected panic with the
correct error message.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d49568b-218e-494e-aee5-aef706e45092

📥 Commits

Reviewing files that changed from the base of the PR and between c3dddfc and b2732db.

📒 Files selected for processing (10)

• .claude/agents/BOOT.md
• .claude/agents/README.md
• .claude/agents/adapter-shaper.md
• .claude/agents/core-first-architect.md
• .claude/agents/core-gap-auditor.md
• .claude/board/TECH_DEBT.md
• .claude/knowledge/core-first-transcode-doctrine.md
• CLAUDE.md
• crates/perturbation-sim/examples/calibrate.rs
• crates/perturbation-sim/src/hhtl.rs