Skip to content

Commit 745098b

Browse files
coenttbcoenttb
committed
Readiness: flip-ready prep for swift-algebra-primitives
- Doc comments on all public declarations; lint conformance (swiftlint --strict + swift format lint --strict both 0). - Family E README; per-package .swift-format / metadata backfill where missing. Floor: clean-room resolve (deps-public verified) + build + test green.
1 parent c04a4b1 commit 745098b

34 files changed

Lines changed: 195 additions & 31 deletions

‎README.md‎

Lines changed: 111 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,113 @@
11
# Algebra Primitives
22

3-
Swift Embedded compatible.
3+
![Development Status](https://img.shields.io/badge/status-active--development-blue.svg)
4+
5+
Witness value types for the algebraic tower — magma, semigroup, monoid, group, ring, field, module, semilattice, lattice — that carry a structure's operations as stored closures, with the type name asserting the mathematical laws.
6+
7+
---
8+
9+
## Quick Start
10+
11+
`Algebra` types are *witnesses*: each one bundles the operations of an algebraic structure (its identity, its binary operation, its inverse) into a value, and the type name records the laws those operations are required to satisfy. Associativity, commutativity, idempotency, and the rest are documented invariants the constructing code must guarantee — they are not re-checked at every call.
12+
13+
A bounded join-semilattice is the algebraic core of a state-based CRDT: any associative, commutative, *idempotent* merge with an identity converges. The witness makes that structure explicit and reusable.
14+
15+
```swift
16+
import Algebra_Primitives
17+
18+
// A grow-only counter merges by taking the per-replica maximum.
19+
// `max` is associative, commutative, and idempotent — a bounded semilattice with bottom 0.
20+
let merge = Algebra.Semilattice<Int>.maximum(bottom: 0)
21+
22+
let replicaA = 5
23+
let replicaB = 3
24+
merge.combining(replicaA, replicaB) // 5 (least upper bound)
25+
merge.combining(replicaA, replicaA) // 5 (idempotent — re-merging is a no-op)
26+
27+
// The merge induces a partial order: a ≤ b iff a ∨ b == b.
28+
merge.leq(3, 5) // true
29+
```
30+
31+
Stack two semilattices and you get a bounded lattice, with join, meet, and the order they share:
32+
33+
```swift
34+
import Algebra_Primitives
35+
36+
// Any Comparable chain is a distributive bounded lattice: join = max, meet = min.
37+
let lattice = Algebra.Lattice<Int>.minMax(bottom: .min, top: .max)
38+
39+
lattice.join(3, 7) // 7 (∨ = least upper bound)
40+
lattice.meet(3, 7) // 3 (∧ = greatest lower bound)
41+
lattice.leq(3, 7) // true
42+
```
43+
44+
The same vocabulary scales up to rings and fields, where convenience accessors (`zero`, `one`, `adding`, `multiplying`, `reciprocal`) read off the underlying monoids and groups. The `Algebra.Law` harnesses verify a witness's invariants over a finite sample of elements, returning an `Algebra.Law.Violation?` that is `nil` when the law holds — pure functions with no traps, ready to drop into a test.
45+
46+
---
47+
48+
## Installation
49+
50+
```swift
51+
dependencies: [
52+
.package(url: "https://github.com/swift-primitives/swift-algebra-primitives.git", branch: "main")
53+
]
54+
```
55+
56+
```swift
57+
.target(
58+
name: "App",
59+
dependencies: [
60+
.product(name: "Algebra Primitives", package: "swift-algebra-primitives"),
61+
]
62+
)
63+
```
64+
65+
Import `Algebra_Primitives` for the whole tower, or depend on a single rung (e.g. `Algebra Semilattice Primitives`) to pull in only what you use.
66+
67+
---
68+
69+
## Architecture
70+
71+
The package is split along the algebraic tower so each rung is an independent product depending only on the rungs below it. The `Algebra` namespace is shared by all of them.
72+
73+
| Product | Target | Purpose |
74+
|---------|--------|---------|
75+
| `Algebra Primitive` | `Sources/Algebra Primitive/` | The empty `Algebra` namespace enum that every structure extends. |
76+
| `Algebra Magma Primitives` | `Sources/Algebra Magma Primitives/` | `Algebra.Magma` — a set with one binary operation, no laws. |
77+
| `Algebra Semigroup Primitives` | `Sources/Algebra Semigroup Primitives/` | `Algebra.Semigroup` — associative magma. |
78+
| `Algebra Monoid Primitives` | `Sources/Algebra Monoid Primitives/` | `Algebra.Monoid` and `Algebra.Monoid.Commutative` — semigroup with identity. |
79+
| `Algebra Semiring Primitives` | `Sources/Algebra Semiring Primitives/` | `Algebra.Semiring` and its commutative variant — additive and multiplicative monoids with distributivity. |
80+
| `Algebra Semilattice Primitives` | `Sources/Algebra Semilattice Primitives/` | `Algebra.Semilattice` — idempotent commutative monoid (the CRDT merge). |
81+
| `Algebra Lattice Primitives` | `Sources/Algebra Lattice Primitives/` | `Algebra.Lattice` — join and meet semilattices with absorption and bounds. |
82+
| `Algebra Group Primitives` | `Sources/Algebra Group Primitives/` | `Algebra.Group` and `Algebra.Group.Abelian` — monoid with inverses. |
83+
| `Algebra Ring Primitives` | `Sources/Algebra Ring Primitives/` | `Algebra.Ring` and its commutative variant — additive abelian group with multiplicative monoid. |
84+
| `Algebra Field Primitives` | `Sources/Algebra Field Primitives/` | `Algebra.Field` and `Algebra.Field.Unit` — ring with a partial reciprocal. |
85+
| `Algebra Module Primitives` | `Sources/Algebra Module Primitives/` | `Algebra.Module` and `Algebra.VectorSpace` — scalars acting on a vector group. |
86+
| `Algebra Law Primitives` | `Sources/Algebra Law Primitives/` | `Algebra.Law` verification harnesses (associativity, commutativity, identity, inverse, distributivity, annihilation, reciprocal, action, compatibility) returning `Algebra.Law.Violation?`. |
87+
| `Algebra Primitives` | `Sources/Algebra Primitives/` | Umbrella re-exporting every rung above. |
88+
| `Algebra Primitives Test Support` | `Tests/Support/` | Re-exports the umbrella for test consumers. |
89+
90+
Foundation-free.
91+
92+
---
93+
94+
## Platform Support
95+
96+
| Platform | Status |
97+
|----------|--------|
98+
| macOS 26 | Full support |
99+
| Linux | Full support |
100+
| Windows | Full support |
101+
| iOS / tvOS / watchOS / visionOS | Supported |
102+
103+
---
104+
105+
## Community
106+
107+
<!-- BEGIN: discussion -->
108+
<!-- Discussion thread created at publication. -->
109+
<!-- END: discussion -->
110+
111+
## License
112+
113+
Apache 2.0. See [LICENSE.md](LICENSE.md).

‎Sources/Algebra Field Primitives/Algebra.Field+Ring.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ extension Algebra.Field {
1616
}
1717

1818
extension Algebra.Ring.Commutative {
19+
/// Creates the commutative ring underlying a field by forgetting its reciprocal.
1920
public init(
2021
_ field: Algebra.Field<Element>
2122
) {

‎Sources/Algebra Field Primitives/Algebra.Field.Unit.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import Algebra_Ring_Primitives
99
/// element and its precomputed inverse are stored, making all
1010
/// group operations on units total.
1111
extension Algebra.Field {
12+
/// A field element together with its precomputed multiplicative inverse, proving it is a unit.
1213
@frozen
1314
public struct Unit {
1415
/// The element value.

‎Sources/Algebra Field Primitives/Algebra.Field.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import Algebra_Ring_Primitives
2323
/// integration packages such as `swift-parity-algebra-primitives`; this type is
2424
/// the generic structure they instantiate.
2525
extension Algebra {
26+
/// An additive abelian group and a multiplicative commutative monoid with a partial reciprocal that inverts every nonzero element.
2627
@frozen
2728
public struct Field<Element> {
2829
/// Additive structure: abelian group with identity (zero).
@@ -34,6 +35,7 @@ extension Algebra {
3435
/// Multiplicative inverse, throwing for non-invertible elements.
3536
public var reciprocal: (Element) throws(Algebra.Field<Element>.Error) -> Element
3637

38+
/// Creates a field from its additive abelian group, multiplicative commutative monoid, and reciprocal.
3739
@inlinable
3840
public init(
3941
additive: Algebra.Group<Element>.Abelian,

‎Sources/Algebra Group Primitives/Algebra.Group.Abelian.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,13 @@ import Algebra_Monoid_Primitives
1111
/// Used as the additive component of rings and fields, where
1212
/// commutativity of addition is required by definition.
1313
extension Algebra.Group {
14+
/// A group whose binary operation is additionally commutative.
1415
@frozen
1516
public struct Abelian {
1617
/// The underlying group.
1718
public var group: Algebra.Group<Element>
1819

20+
/// Creates an abelian group by asserting commutativity of the given group.
1921
@inlinable
2022
public init(group: Algebra.Group<Element>) {
2123
self.group = group

‎Sources/Algebra Group Primitives/Algebra.Group.swift‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import Algebra_Monoid_Primitives
1919
/// additive.combining(3, additive.inverting(3)) // 0
2020
/// ```
2121
extension Algebra {
22+
/// A monoid in which every element has a two-sided inverse.
2223
@frozen
2324
public struct Group<Element> {
2425
/// The identity element.
@@ -30,6 +31,7 @@ extension Algebra {
3031
/// The inverse operation: combining(a, inverting(a)) = identity.
3132
public var inverting: (Element) -> Element
3233

34+
/// Creates a group from its identity, associative binary operation, and inverse operation.
3335
@inlinable
3436
public init(
3537
identity: Element,

‎Sources/Algebra Lattice Primitives/Algebra.Lattice.swift‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ import Algebra_Semilattice_Primitives
4949
/// | **`Algebra.Lattice`** | **join ∨ + meet ∧ + absorption + bounds** |
5050
/// | Boolean algebra (`Swift.Bool`) | + distributivity + complement (native) |
5151
extension Algebra {
52+
/// A bounded lattice: join and meet semilattices linked by absorption, with a bottom and a top.
5253
@frozen
5354
public struct Lattice<Element> {
5455
/// The join (∨) semilattice — least upper bound; its identity is the
@@ -59,6 +60,7 @@ extension Algebra {
5960
/// lattice top (⊤). `lattice.meet(a, b)` computes a ∧ b.
6061
public var meet: Algebra.Semilattice<Element>
6162

63+
/// Creates a bounded lattice from its join and meet semilattices.
6264
@inlinable
6365
public init(
6466
join: Algebra.Semilattice<Element>,
@@ -89,8 +91,9 @@ extension Algebra.Lattice {
8991
// MARK: - Convenience constructor
9092

9193
extension Algebra.Lattice {
92-
/// Creates a bounded lattice directly from its bounds and operations,
93-
/// bypassing the explicit `Algebra.Semilattice` wrapping. The caller is
94+
/// Creates a bounded lattice directly from its bounds and operations.
95+
///
96+
/// Bypasses the explicit `Algebra.Semilattice` wrapping. The caller is
9497
/// responsible for ensuring join/meet are each associative, commutative,
9598
/// and idempotent, that absorption holds between them, and that `bottom`
9699
/// (⊥) and `top` (⊤) are the respective identities.
@@ -111,9 +114,10 @@ extension Algebra.Lattice {
111114
// MARK: - Partial-order projection
112115

113116
extension Algebra.Lattice {
114-
/// Returns true iff `lhs ≤ rhs` in the induced partial order, defined as
115-
/// `lhs ∨ rhs == rhs` (equivalently `lhs ∧ rhs == lhs`). Requires
116-
/// `Element: Equatable`.
117+
/// Returns true iff `lhs ≤ rhs` in the induced partial order.
118+
///
119+
/// The order is defined as `lhs ∨ rhs == rhs` (equivalently
120+
/// `lhs ∧ rhs == lhs`). Requires `Element: Equatable`.
117121
@inlinable
118122
public func leq(_ lhs: Element, _ rhs: Element) -> Bool where Element: Equatable {
119123
join(lhs, rhs) == rhs

‎Sources/Algebra Law Primitives/Algebra.Law.Action.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import Algebra_Module_Primitives
44

55
/// Identity action law: 1 · m = m.
66
extension Algebra.Law {
7+
/// Harness for the identity action law: 1 · m = m.
78
public enum Action {}
89
}
910

‎Sources/Algebra Law Primitives/Algebra.Law.Annihilation.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import Algebra_Field_Primitives
44

55
/// Annihilation law: 0 · a = 0 and a · 0 = 0.
66
extension Algebra.Law {
7+
/// Harness for the annihilation law: 0 · a = 0 and a · 0 = 0.
78
public enum Annihilation {}
89
}
910

‎Sources/Algebra Law Primitives/Algebra.Law.Associativity.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import Algebra_Field_Primitives
44

55
/// Associativity law: (a ∗ b) ∗ c = a ∗ (b ∗ c).
66
extension Algebra.Law {
7+
/// Harness for the associativity law: (a ∗ b) ∗ c = a ∗ (b ∗ c).
78
public enum Associativity {}
89
}
910

0 commit comments

Comments
 (0)