feat(set): add hash set collections

[guiPython]

Summary

• Add package-local set.Readonly[T] and set.Set[T] contracts while keeping the root package limited to the shared Collection and Map capabilities.
• Add map-backed HashSet[T comparable] and KeyedHashSet[T, K] implementations, including typed factories, readonly views, iteration, JSON marshaling, singular/batch mutations, tests, and local benchmarks.
• Document direct Go equality, derived-key identity, first-representative preservation, zero-value behavior, NaN and comparability constraints, and package selection guidance.
• Keep set algebra out of this initial PR so its API and identity-policy semantics can be reviewed separately.

Issue: N/A

Type Of Change

• Bug fix
• Feature
• Documentation
• Tests
• Benchmarks or performance
• Refactor or maintenance

API And Behavior

• No public API or documented behavior changed.
• Public API or documented behavior changed, and docs/examples were updated.
• This is a breaking change and the migration impact is explained below.

Details:

• set.Readonly[T] embeds gollections.Collection[T] and adds identity-aware membership checks without introducing a global set interface.
• set.Set[T] adds Add/Adds, Remove/Removes, and Clear; singular mutations report whether membership changed and batch mutations report how many memberships changed.
• HashSetOf[T] constructs reusable factories for HashSet[T], which uses Go equality and has a usable zero value.
• KeyedHashSet[T, K] accepts arbitrary values and derives comparable identity keys through HashSetBy; the first value inserted for a key remains its representative, and construction through the factory is required.
• Iteration and JSON array order are unspecified. Sets intentionally do not implement JSON unmarshaling because the identity policy is external construction state.

Testing

• go test ./...
• Targeted tests: go test ./internal/set ./set
• Coverage check, if applicable: internal/set has 100.0% statement coverage.
• Race test, if applicable: not run because the package is explicitly unsynchronized and this change does not introduce concurrent behavior.
• make lint, if public APIs/docs/broad behavior changed:

Paste relevant output or explain why a check was not run:

go test ./internal/set ./set: PASS
go test ./...: PASS
make lint: PASS
internal/set: coverage 100.0% of statements
focused HashSet/KeyedHashSet benchmarks: 0 allocs/op
git diff --check: PASS

Risk

• A mutable value whose derived key changes while stored can no longer be found under its original identity; package and factory documentation make key stability an explicit caller invariant.
• Native Go equality is not reflexive for NaN, and interface-backed HashSet values must have comparable dynamic types; the public docs explain both constraints and direct callers to HashSetBy when canonical identity is required.
• Map iteration and JSON output order are nondeterministic; examples and tests compare contents without depending on order.
• Removal paths use native map deletion and Clear uses clear, so removed representatives are no longer retained by the set.

Checklist

• I followed CONTRIBUTING.md and checked the relevant project standards when applicable.
• The diff is focused and excludes unrelated local edits.
• Behavior changes include tests.
• Public behavior changes include docs, examples, or README guidance.
• Performance-sensitive changes include benchmarks or an explanation.
• Removal paths clear discarded references where relevant.

Notes For Reviewers

• Please focus on the split between direct Go equality (HashSetOf) and derived identity (HashSetBy), including the first-representative rule.
• Confirm that the package-local contracts, public aliases, factory requirements, and zero-value behavior match the conventions used by the other collection packages.
• Set algebra, representative lookup/replacement, and additional set families are intentionally deferred to follow-up work.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!