atomik-core 0.2.0__tar.gz

atomik_core-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: atomik-core
+Version: 0.2.0
+Summary: ATOMiK delta-state algebra — O(1) state reconstruction for any processor
+Author-email: ATOMiK Project <matt@atomik.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://atomik.tech
+Project-URL: Documentation, https://atomik.tech/docs
+Project-URL: Repository, https://github.com/MatthewHRockwell/ATOMiK
+Project-URL: Changelog, https://github.com/MatthewHRockwell/ATOMiK/releases
+Project-URL: Issues, https://github.com/MatthewHRockwell/ATOMiK/issues
+Keywords: state-management,delta-state,xor-algebra,lock-free,distributed-systems,fingerprinting,change-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# atomik-core
+
+**O(1) state reconstruction. 99% less bandwidth. Formally proven.**
+
+ATOMiK is a delta-state algebra that replaces snapshots, event replay, and full-state replication with four operations. Works on any processor — no FPGA required.
+
+## Install
+
+```bash
+pip install atomik-core
+```
+
+**Zero dependencies.** Python 3.9+.
+
+## Quick Start
+
+```python
+from atomik_core import AtomikContext
+
+# Create a context and set initial state
+ctx = AtomikContext()
+ctx.load(0xDEADBEEF)
+
+# Accumulate deltas (XOR — order doesn't matter)
+ctx.accum(0x000000FF)
+print(f"State: 0x{ctx.read():08x}")  # 0xdeadbe10
+
+# Undo any delta by re-applying it (self-inverse)
+ctx.rollback(0x000000FF)
+assert ctx.read() == 0xDEADBEEF
+```
+
+## The 4 Operations
+
+| Operation | What it does | Complexity |
+|-----------|-------------|------------|
+| `load(value)` | Set reference state, clear accumulator | O(1) |
+| `accum(delta)` | XOR delta into accumulator | O(1) |
+| `read()` | Reconstruct state: reference ^ accumulator | O(1) |
+| `swap()` | Atomic snapshot + new epoch | O(1) |
+
+Everything else — rollback, merge, fingerprinting, streaming — is built on these four.
+
+## Why ATOMiK?
+
+### 99% Less Network Traffic
+
+Send 8-byte deltas instead of full state copies.
+
+```python
+from atomik_core import DeltaStream
+
+# Sender and receiver start with same reference
+sender = DeltaStream()
+receiver = DeltaStream()
+sender.load(0, initial_state=0xCAFE)
+receiver.load(0, initial_state=0xCAFE)
+
+# Sender produces a delta (8 bytes, not full state)
+msg = sender.accum(0, delta=0x00FF)
+
+# Receiver applies it — converges to same state
+receiver.apply(msg)
+assert sender.read(0) == receiver.read(0)
+```
+
+| State Size | Full Replication (10K updates) | ATOMiK Deltas | Reduction |
+|-----------|-------------------------------|---------------|-----------|
+| 1 KB | 10.2 MB | 80 KB | **99.2%** |
+| 64 KB | 655 MB | 80 KB | **99.99%** |
+
+### 333,333x Less Memory for Rollback
+
+ATOMiK uses 24 bytes regardless of history length. No snapshot stack.
+
+```python
+ctx = AtomikContext()
+ctx.load(0xAAAA)
+
+# Apply 1 million deltas...
+for i in range(1_000_000):
+    ctx.accum(i)
+
+# Undo all of them (XOR self-inverse)
+for i in range(1_000_000):
+    ctx.rollback(i)
+
+assert ctx.read() == 0xAAAA  # Back to original
+# Memory used: 24 bytes. Snapshot approach: 8 MB.
+```
+
+### 1,291x Faster Change Detection
+
+Track changes incrementally in O(1), not O(n).
+
+```python
+from atomik_core import Fingerprint
+
+fp = Fingerprint(width=64)
+fp.load(reference_data)     # Set reference fingerprint
+
+# When a field changes, update in O(1):
+fp.accumulate_delta(old_value, new_value)
+
+if fp.changed:
+    print("Data modified!")
+```
+
+### No Consensus Protocol
+
+XOR is commutative — deltas can arrive in any order. All nodes converge.
+
+```python
+# Three nodes, each produces deltas independently
+nodes = [DeltaStream() for _ in range(3)]
+for n in nodes:
+    n.load(0, 0xAAAA)
+
+m0 = nodes[0].accum(0, 0x0001)
+m1 = nodes[1].accum(0, 0x0010)
+m2 = nodes[2].accum(0, 0x0100)
+
+# Broadcast all-to-all (any order)
+for i, node in enumerate(nodes):
+    for j, msg in enumerate([m0, m1, m2]):
+        if i != j:
+            node.apply(msg)
+
+# All converge — no Raft, no Paxos, no leader election
+assert nodes[0].read(0) == nodes[1].read(0) == nodes[2].read(0)
+```
+
+## Multi-Context Table
+
+Track state across 256 independent addresses:
+
+```python
+from atomik_core import AtomikTable
+
+table = AtomikTable(num_contexts=256)
+table.load(addr=0, initial_state=0x1000)
+table.load(addr=1, initial_state=0x2000)
+
+table.accum(addr=0, delta=0x0001)
+assert table.read(0) == 0x1001
+assert table.read(1) == 0x2000  # Independent
+
+# Batch update multiple addresses at once
+table.batch_accum({0: 0x0010, 1: 0x0020, 2: 0x0030})
+
+# Snapshot all non-zero contexts
+active = table.snapshot()
+```
+
+## Formally Proven
+
+Every algebraic property is proven in Lean4 — not tested, proven:
+
+- **Commutativity**: `accum(a); accum(b) == accum(b); accum(a)`
+- **Associativity**: `(a ^ b) ^ c == a ^ (b ^ c)`
+- **Self-inverse**: `accum(d); accum(d) == identity`
+- **Identity**: `accum(0) == identity`
+
+92 theorems total. [See proofs →](https://github.com/MatthewHRockwell/ATOMiK/tree/main/math/proofs)
+
+## C Library
+
+Single-header C99 library with the same API:
+
+```c
+#define ATOMIK_IMPLEMENTATION
+#include "atomik_core.h"
+
+atomik_ctx_t ctx;
+atomik_init(&ctx);
+atomik_load(&ctx, 0xDEADBEEFCAFEBABEULL);
+atomik_accum(&ctx, 0x00000000000000FFULL);
+uint64_t state = atomik_read(&ctx);
+```
+
+## Hardware Upgrade Path
+
+When software performance isn't enough:
+
+| Implementation | Throughput | Latency |
+|---------------|-----------|---------|
+| Python (`atomik-core`) | 5M ops/sec | ~200 ns |
+| C (`atomik_core.h`) | 500M ops/sec | ~2 ns |
+| FPGA (ATOMiK hardware) | 69.7 Gops/sec | 10.6 ns/op |
+
+Same API. Same algebra. Same proofs. Just faster.
+
+## Examples
+
+- [Distributed Cache Sync](examples/distributed_cache.py) — 3-node convergence without consensus
+- [IoT Sensor Fusion](examples/iot_sensor_fusion.py) — 99.2% bandwidth reduction
+- [Real-Time Analytics](examples/realtime_analytics.py) — Trading P&L tracking at 2.5M ops/sec
+
+## License
+
+Apache 2.0 for evaluation and non-commercial use. [Commercial license](https://github.com/MatthewHRockwell/ATOMiK) required for production deployment. Patent pending.

atomik_core-0.2.0/README.md

@@ -0,0 +1,201 @@
+# atomik-core
+
+**O(1) state reconstruction. 99% less bandwidth. Formally proven.**
+
+ATOMiK is a delta-state algebra that replaces snapshots, event replay, and full-state replication with four operations. Works on any processor — no FPGA required.
+
+## Install
+
+```bash
+pip install atomik-core
+```
+
+**Zero dependencies.** Python 3.9+.
+
+## Quick Start
+
+```python
+from atomik_core import AtomikContext
+
+# Create a context and set initial state
+ctx = AtomikContext()
+ctx.load(0xDEADBEEF)
+
+# Accumulate deltas (XOR — order doesn't matter)
+ctx.accum(0x000000FF)
+print(f"State: 0x{ctx.read():08x}")  # 0xdeadbe10
+
+# Undo any delta by re-applying it (self-inverse)
+ctx.rollback(0x000000FF)
+assert ctx.read() == 0xDEADBEEF
+```
+
+## The 4 Operations
+
+| Operation | What it does | Complexity |
+|-----------|-------------|------------|
+| `load(value)` | Set reference state, clear accumulator | O(1) |
+| `accum(delta)` | XOR delta into accumulator | O(1) |
+| `read()` | Reconstruct state: reference ^ accumulator | O(1) |
+| `swap()` | Atomic snapshot + new epoch | O(1) |
+
+Everything else — rollback, merge, fingerprinting, streaming — is built on these four.
+
+## Why ATOMiK?
+
+### 99% Less Network Traffic
+
+Send 8-byte deltas instead of full state copies.
+
+```python
+from atomik_core import DeltaStream
+
+# Sender and receiver start with same reference
+sender = DeltaStream()
+receiver = DeltaStream()
+sender.load(0, initial_state=0xCAFE)
+receiver.load(0, initial_state=0xCAFE)
+
+# Sender produces a delta (8 bytes, not full state)
+msg = sender.accum(0, delta=0x00FF)
+
+# Receiver applies it — converges to same state
+receiver.apply(msg)
+assert sender.read(0) == receiver.read(0)
+```
+
+| State Size | Full Replication (10K updates) | ATOMiK Deltas | Reduction |
+|-----------|-------------------------------|---------------|-----------|
+| 1 KB | 10.2 MB | 80 KB | **99.2%** |
+| 64 KB | 655 MB | 80 KB | **99.99%** |
+
+### 333,333x Less Memory for Rollback
+
+ATOMiK uses 24 bytes regardless of history length. No snapshot stack.
+
+```python
+ctx = AtomikContext()
+ctx.load(0xAAAA)
+
+# Apply 1 million deltas...
+for i in range(1_000_000):
+    ctx.accum(i)
+
+# Undo all of them (XOR self-inverse)
+for i in range(1_000_000):
+    ctx.rollback(i)
+
+assert ctx.read() == 0xAAAA  # Back to original
+# Memory used: 24 bytes. Snapshot approach: 8 MB.
+```
+
+### 1,291x Faster Change Detection
+
+Track changes incrementally in O(1), not O(n).
+
+```python
+from atomik_core import Fingerprint
+
+fp = Fingerprint(width=64)
+fp.load(reference_data)     # Set reference fingerprint
+
+# When a field changes, update in O(1):
+fp.accumulate_delta(old_value, new_value)
+
+if fp.changed:
+    print("Data modified!")
+```
+
+### No Consensus Protocol
+
+XOR is commutative — deltas can arrive in any order. All nodes converge.
+
+```python
+# Three nodes, each produces deltas independently
+nodes = [DeltaStream() for _ in range(3)]
+for n in nodes:
+    n.load(0, 0xAAAA)
+
+m0 = nodes[0].accum(0, 0x0001)
+m1 = nodes[1].accum(0, 0x0010)
+m2 = nodes[2].accum(0, 0x0100)
+
+# Broadcast all-to-all (any order)
+for i, node in enumerate(nodes):
+    for j, msg in enumerate([m0, m1, m2]):
+        if i != j:
+            node.apply(msg)
+
+# All converge — no Raft, no Paxos, no leader election
+assert nodes[0].read(0) == nodes[1].read(0) == nodes[2].read(0)
+```
+
+## Multi-Context Table
+
+Track state across 256 independent addresses:
+
+```python
+from atomik_core import AtomikTable
+
+table = AtomikTable(num_contexts=256)
+table.load(addr=0, initial_state=0x1000)
+table.load(addr=1, initial_state=0x2000)
+
+table.accum(addr=0, delta=0x0001)
+assert table.read(0) == 0x1001
+assert table.read(1) == 0x2000  # Independent
+
+# Batch update multiple addresses at once
+table.batch_accum({0: 0x0010, 1: 0x0020, 2: 0x0030})
+
+# Snapshot all non-zero contexts
+active = table.snapshot()
+```
+
+## Formally Proven
+
+Every algebraic property is proven in Lean4 — not tested, proven:
+
+- **Commutativity**: `accum(a); accum(b) == accum(b); accum(a)`
+- **Associativity**: `(a ^ b) ^ c == a ^ (b ^ c)`
+- **Self-inverse**: `accum(d); accum(d) == identity`
+- **Identity**: `accum(0) == identity`
+
+92 theorems total. [See proofs →](https://github.com/MatthewHRockwell/ATOMiK/tree/main/math/proofs)
+
+## C Library
+
+Single-header C99 library with the same API:
+
+```c
+#define ATOMIK_IMPLEMENTATION
+#include "atomik_core.h"
+
+atomik_ctx_t ctx;
+atomik_init(&ctx);
+atomik_load(&ctx, 0xDEADBEEFCAFEBABEULL);
+atomik_accum(&ctx, 0x00000000000000FFULL);
+uint64_t state = atomik_read(&ctx);
+```
+
+## Hardware Upgrade Path
+
+When software performance isn't enough:
+
+| Implementation | Throughput | Latency |
+|---------------|-----------|---------|
+| Python (`atomik-core`) | 5M ops/sec | ~200 ns |
+| C (`atomik_core.h`) | 500M ops/sec | ~2 ns |
+| FPGA (ATOMiK hardware) | 69.7 Gops/sec | 10.6 ns/op |
+
+Same API. Same algebra. Same proofs. Just faster.
+
+## Examples
+
+- [Distributed Cache Sync](examples/distributed_cache.py) — 3-node convergence without consensus
+- [IoT Sensor Fusion](examples/iot_sensor_fusion.py) — 99.2% bandwidth reduction
+- [Real-Time Analytics](examples/realtime_analytics.py) — Trading P&L tracking at 2.5M ops/sec
+
+## License
+
+Apache 2.0 for evaluation and non-commercial use. [Commercial license](https://github.com/MatthewHRockwell/ATOMiK) required for production deployment. Patent pending.

atomik_core-0.2.0/atomik_core/__init__.py

@@ -0,0 +1,61 @@
+"""ATOMiK Core — Delta-state algebra for any processor.
+
+Pure-software implementation of the ATOMiK instruction set:
+  LOAD  — Set initial reference state
+  ACCUM — XOR delta into accumulator
+  READ  — Reconstruct current state (reference XOR accumulator)
+  SWAP  — Atomic read-and-reset (snapshot + new epoch)
+
+Zero dependencies. Works on any Python 3.9+ interpreter.
+
+Backed by 92 Lean4 theorems proving:
+  - Commutativity:  accum(a); accum(b) == accum(b); accum(a)
+  - Associativity:  (a ^ b) ^ c == a ^ (b ^ c)
+  - Self-inverse:   accum(d); accum(d) == identity
+  - Identity:       accum(0) == identity
+
+Quick start:
+    from atomik_core import AtomikContext
+
+    ctx = AtomikContext()
+    ctx.load(0xDEADBEEF)
+    ctx.accum(0x000000FF)
+    assert ctx.read() == 0xDEADBE10
+
+Multi-context table:
+    from atomik_core import AtomikTable
+
+    table = AtomikTable(num_contexts=256)
+    table.load(addr=0, initial_state=0xCAFEBABE)
+    table.accum(addr=0, delta=0x00000001)
+    assert table.read(addr=0) == 0xCAFEBABF
+
+SPDX-License-Identifier: Apache-2.0
+"""
+
+__version__ = "0.2.0"
+
+from atomik_core.context import AtomikContext
+from atomik_core.table import AtomikTable
+from atomik_core.stream import DeltaStream, DeltaMessage
+from atomik_core.fingerprint import Fingerprint
+from atomik_core.benchmark import (
+    bench_rollback,
+    bench_change_detection,
+    bench_convergence,
+    bench_bandwidth,
+    bench_throughput,
+)
+
+__all__ = [
+    "AtomikContext",
+    "AtomikTable",
+    "DeltaStream",
+    "DeltaMessage",
+    "Fingerprint",
+    "bench_rollback",
+    "bench_change_detection",
+    "bench_convergence",
+    "bench_bandwidth",
+    "bench_throughput",
+]