[Shubham-Padkonde]

Description

Counter already computes the upcoming value. summer.sum is exactly what buildFlops registers into count:

count <= flop(clk, summer.sum, reset: reset, resetValue: initialValueLogic, ...);

This exposes it as a nextCount output, so a caller that needs the count a cycle early can read it instead of instantiating a second Sum — which is the "reuse the same Sum hardware" the issue asks for. It is driven in _buildLogic from the same summer, so there is no new arithmetic.

GatedCounter overrides buildFlops to register that same summer.sum through gated clocks, so it inherits the output. That raised the obvious question — whether a gated-off clock makes the prediction wrong, since the flop holds while summer.sum may have moved — so the test below covers GatedCounter explicitly rather than assuming. It does not: the gate enables exactly when the value needs to change.

Related Issue(s)

Fixes #264

Testing

New test/summation/counter_next_count_test.dart. Rather than asserting specific numbers, it checks the property that actually matters — the nextCount visible this cycle is the count visible the next one — over 50 cycles of a randomized enable pattern:

enable.inject(rand.nextBool() ? 1 : 0);
await clk.nextNegedge;

final predicted = counter.nextCount.value;

await clk.nextNegedge;

expect(counter.count.value, predicted,
    reason: 'cycle $i: nextCount did not match the following count');

It runs against both Counter.simple(...) and a GatedCounter, including cycles where the counter is disabled and the value must stay put.

00:00 +2: All tests passed!

Full suite, dart test -j 3, clean main versus this branch:

12:23 +1356 ~1: All tests passed!    <- main
05:56 +1358 ~1: All tests passed!    <- this branch

No failures either way; the +2 is the new tests. dart format --output=none --set-exit-if-changed reports no changes, and dart analyze over the package finds no issues.

Backwards-compatibility

Additive: a new output port on Counter and a new getter. Nothing existing changes behaviour.

The one visible consequence is that Counter (and GatedCounter) now have an extra port in generated SystemVerilog. If you would rather this be opt-in behind a constructor flag so unused instances don't carry the port, say so and I'll rework it that way — I went with always-present because it costs no logic beyond the wire, and an unused output is normally optimized away downstream.

Documentation

The nextCount getter carries a doc comment explaining what it is and that it shares the existing Sum. doc/components/summation.md documents the summation components at a level that doesn't enumerate individual ports, so nothing there needed updating — happy to add a line if you'd like it mentioned.

---

Disclosure: this change was written by Claude Code (Claude Opus 5) working as my agent, at my direction. The test output quoted above comes from real runs in my local environment; I am accountable for the content of this PR and happy to iterate on review feedback.

🤖 Generated with Claude Code