docs(h-element): reconcile with bert-lenses #86, and correct a stale status

[rsthornton]

Doc-only. No code touched.

Two problems, in opposite directions.

The status line was stale. It said H is "not yet implemented — currently a string field, never read during _act()". True when written; _condition_T() now exists (python/agents.py:333, called at :304) and reads self.history.

And the key formula contradicts an ADOPTED position in the other repo. T(t+1) = f(T(t), H(t), Input(t)) versus bert-lenses #86 (2026-07-18): H is a record, never an input to T — if T reads H the Mesarovic–Takahara semigroup axiom fails, with history-dependence to be folded into the carrier instead. That document is later and normative for the kernel and SL; this one predates it and had never been reconciled with it. Since this repo is public, the contradiction was visible externally.

Being fair to the implementation: Option C picked Buffering precisely because the stock is the history, and storage genuinely is a carrier variable — that already satisfies the rule's own escape clause. What does not is narrower: _release_factor comes from an exponentially-smoothed 10-snapshot window including a second derivative (agents.py:346), and neither the smoothed trend nor the acceleration is in the carrier. Same for the agent-level _prediction_factor / _effort_factor.

The fix is documented, not made: promote smoothed trend and acceleration to carrier variables so node state becomes (storage, trend, accel). Adaptive behaviour unchanged, transition Markovian again, axiom holds. Fold into the carrier, not abandon adaptation.

Surfaced while consolidating the life-cycle thread (bert-lenses #144), where the same trap appears one order up: stage-transition predicates designed as "read H, detect decline" would be the identical violation.

[claude]

Review: PR #112

Scope mismatch: this diffs far more than "doc-only"

The PR description says "Doc-only. No code touched.", but gh pr diff 112 (base 617c8aab -> head 4a2ecc6) shows 16 commits, +2437/-101 across 16 files, including substantial new Rust functionality: per-wire source rates (bert-compose/src/circuit.rs), series forcing / multi-timescale dt_stride, a weighted-splitter mode, a new bert-core/src/transition.rs (1000+ lines implementing mode downgrade/upgrade with a LossWitness), the AgentModel.primitives -> primitive collapse, and TypeDB/Python-bridge updates.

Only the last commit (4a2ecc6, "reconcile with bert-lenses #86") is actually doc-only — it touches docs/h-element-theory.md and docs/system-language-spec-v2-addendum.md and matches the description exactly. Everything else appears to be prior commits on this branch that haven't landed on main yet (a stacked-branch situation), so they're being swept into this PR's diff.

Suggestion: rebase this branch onto a main that already contains commits 135a61c...40de7a7, so PR #112's diff is scoped to just the reconciliation doc change it claims to be. As-is, a reviewer approving "the docs PR" is implicitly also approving a large kernel/engine feature set that hasn't had its own review pass. Both parts are reviewed below, but splitting them would give a cleaner approval trail.

---

1. The actual doc change (4a2ecc6) — looks good

• docs/h-element-theory.md: corrects a stale "not yet implemented" status against the real code (python/agents.py:333/:304), and adds a clearly-marked reconciliation callout against the later, normative bert-lenses#86 position (H must not be read by T; the semigroup axiom argument). Good practice: it names exactly why the current implementation is only partially compliant (_release_factor's smoothed trend/second derivative in agents.py:346 isn't in the carrier yet) and states the fix ("fold into carrier: (storage, trend, accel)") without pretending it's done. Flagging the same trap for the life-cycle/stage-transition work one level up is a nice bit of forward-looking documentation hygiene.
• docs/system-language-spec-v2-addendum.md: clarifies that Full mode has two realizations (authored vs. executable) and that the run trace is an observer artifact distinct from the tuple's H. Consistent with the new run.rs/transition.rs grounding added earlier in the branch.
• No code changes in this commit; nothing to test here beyond doc review.

Minor nit: the callout blocks are long relative to the surrounding prose — consider collapsing to a single reconciliation note per file once _condition_T() is actually fixed, so the doc doesn't accumulate multiple superseded-in-part warnings over time.

---

2. The bundled code changes (prior commits in the stack)

Reviewed for correctness/style even though out of this PR's stated scope:

bert-compose/src/circuit.rs — per-wire rates, series forcing, dt_stride, weighted split (bert#111 / bert-lenses#16)

• Wire losing Copy (now holds Option<Vec<f32>>) is called out explicitly in a doc comment explaining the one merge site affected — good, since this is exactly the kind of change that silently breaks callers relying on implicit copies.
• wire_declared_rate's stride math (idx = (tick / stride).min(len-1)) guards stride against 0 via .max(1), avoiding a divide-by-zero/panic.
• Back-compat is carefully preserved: source_emission/source_wire_rate fall back to the old uniform param split when nothing is declared, asserted by undeclared_fanout_still_splits_param_uniformly.
• Test coverage here is notably thorough — dedicated fixtures per capability (per-wire rate, series forcing with a non-monotonic "spike then crash" shape specifically chosen to catch a mean-collapse bug, stride/hold semantics, splitter weight statics and dynamics, conservation checks via balance()). A good pattern worth reusing elsewhere.
• predator_prey_alpha_growth gaining #[cfg(test)] — worth confirming this function isn't referenced from any non-test code path (e.g. examples.rs/ladder.rs consumers or docs) before merging, since it silently becomes dead code outside cfg(test) builds.

bert-core/src/operational.rs / AgentModel.primitives -> primitive collapse

• The primitive_compat deserializer (untagged enum reading either scalar or legacy array) is a clean migration path: refuses multi-entry legacy arrays with an actionable "decompose" error rather than silently dropping data.
• content_hash() uses DefaultHasher (SipHash, not guaranteed stable across Rust versions/platforms) as the key for RecordedRun. Fine for the stated use (an in-session cache-invalidation key, never persisted) — worth a one-line comment reiterating it must never be persisted or compared cross-process.
• rate_series/dt_stride parsing from Parameter.value (comma-separated string -> Vec<f64>) silently drops unparseable entries via filter_map(...ok()). Consider surfacing a validation error/warning for a malformed series (e.g. "1,two,3") rather than silently truncating it to [1.0, 3.0] with no signal to the modeler that part of the input was ignored.

bert-core/src/transition.rs (new, ~1000 lines) — a substantial addition (mode downgrade/upgrade over the Mode meet-semilattice with a LossWitness round-trip). The design doc comment and Lean/Rust correspondence table are a nice touch for auditability. Given its size and non-trivial lattice logic (meet, ascent_chain, per-field shearing/restore), this alone would benefit from its own PR with focused review — flagged as the highest-risk single file in this diff by surface area, not because of anything specifically wrong found in the portion reviewed.

python/json_bridge.py, tools/bert-typedb/src/insert.rs — both correctly updated for the scalar primitive field with backward-compatible reads; small, consistent changes.

---

Security

Nothing concerning — no new I/O, network, or unsanitized external input paths. The Parameter.value string parsing (series/dt_stride) is the only "external-ish" input surface touched, and it fails closed (falls back to None/no series) rather than panicking on bad input.

Test coverage

Strong for the bundled feature work (circuit/export have dedicated tests per behavior, including explicit back-compat regression tests). The doc-only commit itself needs no tests. transition.rs's round-trip tests weren't fully reviewed given size but appear to cover full/operational/structural transitions with dedicated fixtures.

Overall

The documentation reconciliation itself is a good, honest piece of writing — it surfaces a real design tension instead of quietly picking a side. The main actionable ask is scoping: please confirm whether the other 15 commits are meant to ride along in #112, or whether main needs to catch up first so this PR's diff matches its description.