Skip to content

Add CappedCountStore: a Go multiset core with 0/1/MANY counts - #469

Merged
jp-fizzbee merged 5 commits into
mainfrom
claude/project-thread-kfg6jh
Nov 10, 2026
Merged

jp-fizzbee merged 5 commits into
mainfrom
claude/project-thread-kfg6jh

Conversation

@jp-fizzbee

@jp-fizzbee jp-fizzbee commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by JP · project thread

Summary

Adds lib.CappedCountStore[T], a plain Go multiset. Each entry's count is a CardinalityCounter: ONE or MANY, with an absent element reading as ZERO. This PR doesn't use Starlark, doesn't change the language and doesn't change any existing behaviour.

  • Canonical by construction. Entries are sorted by key and ZERO is never stored, so the same contents give the same entries whatever order the operations ran in.
  • The key is the element's identity. It must be either a complete canonical encoding of the value or a collision-resistant hash of one. That is the same assumption the checker already makes for state hashes. The store never compares values: Add under an existing key keeps the first value and counts one more copy, and Equal compares keys and counts only.
  • Counter arithmetic.
    • Add is the counter's Inc.
    • RemoveOutcomes is its Dec: removing from ONE leaves ZERO; removing from MANY leaves ONE or MANY.
    • The store never picks an outcome itself. The caller takes one with Remove(key, outcome), typically once in each fork. A nil or invalid outcome is an error.
    • Rekey merges entries that end up with the same key using the new CardinalityCounter.Plus, the abstract sum.
  • API: Add, RemoveOutcomes, Remove, Count, Get, Has, Len (distinct elements), Total (a counter), Entries, Equal, Clone(fn) and Rekey(fn).
    • Entries returns a copy of the entries, so callers can't break the invariants. Values are shared, not copied.
    • Clone(nil) is shallow.
    • Rekey builds the new store before replacing the old one, so a key function that panics leaves the store unchanged.

Intended use. The planned consumer is the capped abstraction of process threads, where an action can have any number of concurrent copies. Advancing one copy of a thread whose count is MANY forks into ONE or MANY for the copies left behind. That scheduler design will come in its own PR. This store is not meant for exact deduplication of identical threads, because it can't represent exact multiplicity. If exact counts are ever needed, they would be a separate type.

Tests

This is a data structure, not a stateful protocol, so it gets property tests instead of a FizzBee spec: lib/countstore_test.go and lib/cardinality_test.go.

  • Random add and remove sequences against exact concrete counts. Each removal must offer the outcome that matches the concrete count. Counts, Has, Len and Total must equal the abstraction of the exact counts. Entries must stay sorted with no ZERO.
  • Canonical equality regardless of insertion order. Removing the last copy must give the same state as never adding it.
  • Outcomes and errors: removing an absent key, a nil outcome, and an outcome that is not a valid result of the removal.
  • API contracts: mutating the slice Entries returns doesn't change the store; Add with a different value under the same key keeps the first; a clone stays independent of later changes; the empty store.
  • Rekey: MANY + MANY and ONE + ONE merge to MANY, a lone ONE stays ONE, Rekey is idempotent, and a panicking key leaves the store unchanged. Clone copies values deeply when given a clone function.
  • CardinalityCounter.Plus matches the abstraction of concrete sums for 0 to 3.

go test ./lib -run 'CountStore|Cardinality' passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_013eDw2fcqNcKpnpHXHYFi7n

CountStore keeps, per canonical key, a value and a count, sorted by key
with no zero entries, so equal contents give equal entries whatever the
order of operations. The count policy is per store: exact, or capped at
Many (0, 1, MANY), where removing from Many has two outcomes and the
caller picks one.

It is plain Go with no Starlark and no language change, meant as the
shared core for later users: the checker's own state (such as threads)
and a spec-visible multiset.

Tests: lib/countstore_test.go, random add/remove sequences against
exact counts for both policies, canonical equality, outcomes and errors,
clone and rekey.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The capped policy's increment, removal outcomes and capping now go
through CardinalityCounter (Inc, Dec, NewCardinalityCounter), so the
0/1/MANY rules live in one place. A capped count is the counter's
ValueCode. New test checks the two agree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drop the count policy and the exact counts. Each entry's count is a
CardinalityCounter (ONE or MANY; absent is ZERO), so Add is the
counter's Inc, RemoveOutcomes is its Dec, and there are no branches on
a policy. Exact counts can come later as a separate type if needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jp-fizzbee jp-fizzbee changed the title Add CountStore: a Go multiset core with exact or capped counts Add CappedCountStore: a Go multiset core with 0/1/MANY counts Nov 10, 2026
- Remove returns an error for a nil outcome instead of panicking.
- Entries returns a copy, so callers cannot break the sort order or the
  no-ZERO invariant.
- Document the key contract: the key is the element's identity, a
  complete canonical encoding or a collision-resistant hash; Add keeps
  the first value and Equal compares keys and counts.
- Rekey merges with CardinalityCounter.Plus (new: the abstract sum) and
  builds into a temporary store, so a panicking key leaves it unchanged.
- Total returns a shared MANY counter instead of allocating one.
- Tests for each, plus Rekey MANY+MANY, idempotence, clone independence
  and the empty store; Plus is tested against concrete sums.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jp-fizzbee
jp-fizzbee merged commit add6f4f into main Nov 10, 2026
1 check passed
@jp-fizzbee
jp-fizzbee deleted the claude/project-thread-kfg6jh branch November 10, 2026 08:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants