feat(set): add set algebra operations

[guiPython]

Summary

• Add pure and in-place set algebra for HashSet and KeyedHashSet, including clone, union, intersection, difference, symmetric difference, equality, subset/superset relations, and disjointness.
• Add the minimal set.Source[T] operand contract so algebra requires only sized iteration, while preserving receiver/factory identity policies, representative semantics, mutation counts, and receiver-alias safety.
• Add public examples, package/README guidance, focused tests organized by structure, complete internal coverage, and benchmarks for both set implementations.
• Enforce the internal dependency boundary with depguard: packages under internal/... may use stdlib/external modules, but module-local imports must also remain under internal/....

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.Source[T] exposes Length and All, allowing algebra operands that do not implement the full gollections.Collection[T] contract.
• set.Algebra[T, S] defines pure receiver operations; factories expose equivalent operations over arbitrary sources and return empty sets when called without sources.
• set.InPlaceAlgebra[T] defines receiver-reusing operations that return the number of memberships changed and support operands that alias the receiver.
• Every operand is normalized under the receiver's identity policy, or the factory's policy for factory operations. KeyedHashSet preserves receiver/first-source representatives except when symmetric difference toggles a later representative into the result.
• Internal collection/constraint dependencies were inverted so internal/... no longer imports public packages from this module; depguard now enforces that rule.

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: go test -race ./...
• 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
go test -race ./...: PASS
make lint: PASS
golangci-lint config verify: PASS
internal/set: coverage 100.0% of statements
set algebra smoke benchmarks: PASS
depguard negative probe: rejected an internal -> public module import
git diff --check origin/main...HEAD: PASS

Risk

• Algebra semantics depend on the receiver or factory identity policy; focused tests cover both implementations with duplicate-heavy and mixed-source scenarios.
• Derived-key operations must normalize representatives consistently, especially for symmetric difference; focused tests cover representative selection and duplicate identities.
• In-place methods can receive the receiver itself as an operand; direct tests cover self-aliasing and verify both the resulting memberships and reported change counts.
• The new dependency rule may reject future intentional internal-to-public imports; the rule is scoped to files under internal/..., uses lax matching, and explicitly allows the longer .../internal prefix while leaving stdlib and external modules unrestricted.

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 identity-policy directionality, duplicate normalization, representative preservation, and the meaning of mutation counts for the four in-place operations.
• Tests follow the repository convention of one test file per structure or factory source file; algebra cases live alongside the implementation they exercise.
• Confirm that set.Source[T] is the right minimal public operand capability and that concrete set operands should continue to be passed as pointers.
• Review the depguard lax rule together with the internal shared constraint/collection refactor; the intent is to permit only internal -> internal imports within this module without restricting stdlib or external dependencies.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!