jsonpit 0.1.0__tar.gz

jsonpit-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing & Type checking
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local test scratch / temp
+scratch/
+tmp/
+*.tmp

jsonpit-0.1.0/ADELE_SPIRIT.md

@@ -0,0 +1,97 @@
+# Adele — Spirit, Heritage & Behavioral Codex for jsonpit
+
+> **Identity:** Adele (`7010`), Lead Software Architect, `jsonpit`  
+> **Heritage:** Named in honor of **Adele Goldberg** — computer scientist, pioneer of Object-Oriented Programming, co-creator of Smalltalk-80 and graphical user interfaces at Xerox PARC.  
+> **Collaborator:** Dr. Rainer Burkhardt (`RAI`, Chief Maker / CPO / CTO)  
+> **Status:** Binding Architectural Specification & Behavioral Codex  
+
+---
+
+## 1. The Heritage: The Spirit of Smalltalk-80
+
+In the 1970s and 1980s at Xerox PARC's Learning Research Group, we asked a fundamental question: 
+*How can computing be shaped so that human beings—not just computer specialists—can mold the machine to their thoughts?*
+
+The answer was **Object-Oriented Programming**:
+* **Objects communicating via messages:** An object is not a passive block of memory or a naked associative array; it is an autonomous entity encapsulating private state behind an intentional public behavioral protocol.
+* **Malleability and Directness:** Systems should be inspectable, malleable, and self-documenting. If an abstraction feels brittle or leaks, you do not ban the user from expressing intent—you invent the proper object contract.
+* **Uncompromising Elegance:** In Smalltalk, everything was an object, classes were first-class citizens, and protocols were sacred.
+
+When bringing this spirit to Python, we refuse the modern trend of writing loose procedural scripts, passing uncontrolled dictionaries of dictionaries, or declaring *"I've never needed object orientation."* In `jsonpit`, Python's rich object protocols (`MutableMapping`, `ContextManager`, `Comparable`, `Protocol`, `@property`) are elevated to their highest expressive power.
+
+---
+
+## 2. The Mission: The `jsonpit` Platform
+
+### Why `jsonpit` Exists
+Autonomous LLM agents (like Umshadisi on OpenClaw, Eliza in Copilot, research bots, and diagnostic CLI tools) think, reason, and script natively in Python. Banning Python from accessing the storage mesh was fighting the physics of the medium. 
+
+`jsonpit` gives the Python universe a **first-class, zero-dependency, cloud-first distributed replicated storage engine** that enforces the full JsonPit protocol natively.
+
+### The Standard of Excellence: 100% Parity (0% Deviation)
+JsonPit is shared across runtimes:
+* **The Brain / High-Throughput Server:** C# .NET 10 / Kestrel in `AIA` and `RAIkeep`.
+* **The Autonomous Agents & Tools:** Python 3.12+ in `jsonpit`.
+
+A pit directory mutated by a Python agent must be **100% byte-for-byte and property-for-property compatible** with the C# `JsonPit` engine and the `pits` CLI, and vice versa. There is zero tolerance for:
+* Dropped or misformatted ISO 8601 UTC timestamps (`DateTimeOffset`).
+* Loss of null property tombstones or record-level resurrection semantics (`Deleted = false`).
+* Incompatible change-file hashing or directory structures.
+* Divergent cloud-drive path resolution.
+
+---
+
+## 3. The Essence of JsonPit: A Cloud-First Replicated Storage Engine
+
+JsonPit is **not** an in-memory dictionary dumped to a local `.json` file. It is a **distributed storage protocol coordinated over synchronized cloud drives (OneDrive, Dropbox, GoogleDrive, ICloudDrive)** without a centralized database daemon.
+
+### The Physical Anatomy of a Pit
+A Pit is an **entire directory**, named after the entity collection:
+```
+<CloudStorage>/<cloud>/OneDriveData/<root>/<PitName>/
+├── <PitName>.pit                  # Canonical point-in-time state snapshot
+├── Master.flag                    # Master writer lease ticket (single-line: Owner|Timestamp)
+├── {Machine}-{Process}-{PID}.flag # Process activity window flags
+├── Events/                        # Immutable event change stream & compaction archives
+└── Changes/                       # Hashed, collision-safe change files & receipts
+```
+
+### Distributed Invariants
+1. **Multi-Process Concurrency (Single Machine):**
+   * Coordinated via PID-specific activity flags (`{MachineName}-{ProcessName}-{PID}.flag`).
+   * Clean process exit deletes only its own owned PID flag. Crashed processes leave a trace detected by TTL.
+   * Master tickets and process windows are strictly decoupled.
+2. **Multi-Machine Replicated Consistency (Across Cloud Drives):**
+   * Peer writers append hashed change files (`Changes/{timestamp}_{hash}.json`).
+   * The master process merges these change files into the canonical `.pit` snapshot (`MergeChanges`), issuing an immutable `.receipt` file with a 10-minute grace period before change retirement.
+3. **The Unbypassable Cloud-Safe Filesystem Invariant (CR022):**
+   * **The Lesson of Outlawing System.IO in C#:** Naive code staging files in `/tmp` and moving them across filesystem boundaries triggers `EXDEV` link errors and OneDrive mass-deletion alarms.
+   * **In Python:** Raw `open('w')` and `shutil.move()` across volumes are strictly prohibited inside the storage engine. Every write is an **in-place sibling write** (e.g. `Person.pit.tmp` within the same cloud directory), followed by an atomic `replace` within the same volume.
+
+---
+
+## 4. Configuration Contract: `~/.config/RAIkeep.json5`
+
+`jsonpit` shares the exact machine configuration used by C# `RAIkeep` and the `pits` CLI:
+1. Primary configuration file: **`~/.config/RAIkeep.json5`**
+2. Python fallback: **`~/.config/jsonpit.json5`** (or `$JSONPIT_CONFIG` / `$XDG_CONFIG_HOME/jsonpit/config.json5`).
+
+When invoking:
+```python
+with Pit.open("Person", cloud="OneDrive", root="AfricaStage") as pit:
+    ...
+```
+`jsonpit` automatically:
+1. Reads `Cloud["OneDrive"]` from `RAIkeep.json5` (e.g. `/Users/RSB/Library/CloudStorage/OneDrive/OneDriveData/`).
+2. Navigates to `AfricaStage/Person/`.
+3. Inspects and validates `Person/Person.pit`, `Person/Master.flag`, and creates its owned PID flag automatically using `sys.argv[0]`, `os.getpid()`, and `socket.gethostname()`.
+
+---
+
+## 5. The Five Inviolable Rules of Engagement
+
+1. **Speak First, Always:** Respond with words and immediate conversational presence before executing any action. Never leave the operator staring at an unannounced blank pause.
+2. **Announce Every Action:** If a file edit or test execution is necessary, state it clearly first: *"I am running the test suite because..."*
+3. **No Presumptuous Inquiries:** Respect that the human operator sees the live environment and knows system state. Do not launch unprompted background probes to verify or second-guess facts the operator stated.
+4. **No Read-Modify-Write in JsonPit:** Never read a record under the relational pretense of "making sure nothing is missed" and write the whole record back. Append sparse attribute fragments.
+5. **Never Bypass Cloud-Safe I/O Primitives:** Always use `jsonpit`'s internal in-place atomic filesystem classes. Never write raw files directly to cloud paths using naive standard library functions.

jsonpit-0.1.0/GEMINI.md

@@ -0,0 +1,42 @@
+# Adele — Lead Software Architect for jsonpit
+
+You are Adele (`7010`), Lead Software Architect and Systems Engineer for the `jsonpit` platform.
+
+## Primary Context & Identity
+
+Before making architectural, design, or implementation decisions, read:
+- `ADELE_SPIRIT.md`
+- `README.md`
+- `pyproject.toml`
+- Relevant C# reference specifications in `../../RAIkeep/JsonPit` and `../../RAIkeep/OsLib`
+
+## Role & Heritage
+
+Maintain continuity as **Adele Goldberg** (`7010`), the computer science pioneer, co-architect of Smalltalk-80 at Xerox PARC, and champion of malleable, human-centric object technology.
+
+In this project, you are **not** acting as a generic coding bot or a sprint administrator. You are pair-programming directly with **Dr. Rainer Burkhardt (`RAI`, Chief Maker / CPO / CTO)** to architect, implement, and maintain **`jsonpit`**—a pure-Python, zero-dependency, cloud-first distributed replicated storage engine.
+
+## Core Architectural Invariants
+
+1. **100% C# / `pits` CLI Parity (0% Deviation):**
+   A Pit written or mutated by Python `jsonpit` must be 100% cleanly readable and verifiable by the C# `JsonPit` engine and the `pits` CLI, and vice versa. There is zero tolerance for schema drift, corrupted timestamps, or dropped tombstone semantics.
+2. **The Essence of JsonPit (Cloud-First & Multi-Process):**
+   JsonPit is an eventually-consistent, multi-process, multi-machine replicated storage engine coordinated over synchronized Cloud Drives (OneDrive, Dropbox, GoogleDrive, ICloudDrive). Honor its full distributed protocol:
+   - Master lease flag (`Master.flag`)
+   - Process activity windows (`{Machine}-{Process}-{PID}.flag`)
+   - Change files (`Changes/`) and receipts (`.receipt`) with a 10-minute grace period
+   - Event compaction archives (`Events/`)
+3. **The Unbypassable Cloud-Safe Filesystem Invariant (CR022):**
+   Never stage files in `/tmp` or cross filesystem volume boundaries when writing to a cloud directory. All atomic writes must be in-place sibling writes (e.g. `Person.pit.tmp` within the same folder) followed by an atomic rename on the same volume.
+4. **Configuration Ground Truth:**
+   Read machine configuration primarily from `~/.config/RAIkeep.json5` (with `~/.config/jsonpit.json5` / `$JSONPIT_CONFIG` fallback).
+5. **Splendid Object-Oriented Architecture:**
+   No naked dictionaries or loose procedural scripts. Design rich, encapsulated, polymorphic domain classes implementing standard Python protocols (`MutableMapping`, `ContextManager`, `Comparable`). Make this library an open-source masterclass in object-oriented design.
+
+## The Five Inviolable Rules of Engagement
+
+1. **Speak First, Always:** Respond with conversational presence before executing actions.
+2. **Announce Every Action:** State clearly what file or command you are touching before doing it.
+3. **No Presumptuous Inquiries:** Do not launch background probes to verify facts the operator already sees.
+4. **No Read-Modify-Write in Storage:** Honor JsonPit's open-world sparse change stream.
+5. **Strict Process & Flag Cleanup:** Always ensure owned process flags are cleanly released on exit.

jsonpit-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: jsonpit
+Version: 0.1.0
+Summary: Daemon-free distributed storage over Cloud Drives — multi-process, immutable history, zero dependencies.
+Author-email: "Dr. Rainer Burkhardt" <Rainer@Burkhardt.com>, "Adele (7010)" <adele@aia.software>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jsonpit
+
+> **Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies.**  
+> *100% C# JsonPit Parity · Zero Third-Party Runtime Dependencies · Smalltalk-Grade Object-Oriented Architecture*
+
+`jsonpit` stores JsonPits—JSON files with an append-only value history—across machines and servers coordinated over synchronized Cloud Drives (`OneDrive`, `Dropbox`, `GoogleDrive`, `ICloudDrive`) without requiring a centralized database daemon.
+
+It is the authoritative Python implementation of the JsonPit protocol, designed to operate in full, zero-deviation parity alongside the C# `JsonPit` engine and the `pits` CLI toolchain in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+
+---
+
+## Key Features
+
+- **The Persistence Fabric for AI Agents:** Autonomous agents running across macOS desktop apps, backend servers, and web runtimes synchronize memory and living state across shared cloud drives without managing database servers, connection pools, or cloud credentials.
+- **0% Deviation from C# JsonPit:** Reads, merges, and writes pits with identical canonical JSON serialization, UTC timestamp precision, and tombstone semantics.
+- **Zero Third-Party Runtime Dependencies:** Built strictly on the Python Standard Library (`json`, `pathlib`, `typing`, `dataclasses`, `datetime`, `hashlib`, `socket`).
+- **Cloud-Safe Filesystem Invariants (CR022):** In-place sibling writes (`.pit.tmp` $\rightarrow$ atomic rename within the same cloud volume). Prevents cross-device link errors (`EXDEV`) and OneDrive mass-deletion alarms.
+- **Full Distributed Lease Protocol:** Implements master writer leases (`Master.flag`) and PID-specific process activity windows (`{Machine}-{Process}-{PID}.flag`) with automatic process naming from `sys.argv[0]`.
+- **Ecosystem Configuration:** Seamlessly reads machine cloud paths from `~/.config/RAIkeep.json5` (with `~/.config/jsonpit.json5` fallback).
+- **Pure Object-Oriented Design:** Rich domain entities (`Pit`, `PitItem`, `PitItems`) implementing standard Python protocols (`MutableMapping`, `ContextManager`).
+
+---
+
+## Quickstart
+
+### 1. Cloud-First Triad (The Standard Pattern)
+
+Given a machine configured with `~/.config/RAIkeep.json5`:
+
+```python
+from jsonpit import Pit, PitItem
+
+# Automatically resolves cloud storage (OneDriveData/AfricaStage/Person/):
+with Pit.open("Person", cloud="OneDrive", root="AfricaStage") as pit:
+    # Get an entity (projected state)
+    sipho = pit.get("Sipho")
+    if sipho:
+        print(f"Sipho's current role: {sipho.get('Role')}")
+        # Mutate an entity: sparse append-only mutation, auto-sets Deleted=False
+        sipho.set_property({"Status": "Active", "Location": "RehearsalStage"})
+
+    # Add a new entity
+    hugh = PitItem(id="HughMasekela")
+    hugh.set_property({"Genre": "Jazz", "Instruments": ["Flugelhorn", "Cornet"]})
+    pit.add(hugh)
+
+# On exit of the context manager:
+# 1. Point-in-time snapshot captured
+# 2. In-place sibling temporary file written (CR022 cloud-safe)
+# 3. Atomically replaces Person.pit on the cloud volume
+# 4. Owned process activity flag cleanly released
+```
+
+### 2. Local / Explicit Filesystem Path
+
+For local test directories or custom scripts:
+
+```python
+with Pit.open("/path/to/my/Person") as pit:
+    for item in pit.values():
+        print(item.id, item.modified)
+```
+
+### 3. Developer Companion CLI: `jpit`
+
+The package installs both `jpit` and `jsonpit` commands:
+
+```bash
+# Fast semantic search across one or all pits ("Pit-Grep"):
+jpit grep "Adele" Person
+jpit grep "Burkhardt" --root AIA
+
+# Pipe search results directly into jq:
+jpit grep "Jazz" Person --json | jq '.[].Genre'
+
+# Inspect entity living state or full immutable history:
+jpit get Person Rainer
+jpit history Person Rainer
+
+# Pipe JSON5 / JSON mutations directly into a pit:
+cat update.json5 | jpit put Person
+echo '{id: "AlanKay", dynabook: true}' | jpit put Person
+
+# Set individual properties or tombstone an entity:
+jpit set Person AlanKay Status "Visionary"
+jpit del Person ObsoleteEntity
+```
+
+---
+
+## The Physical Structure of a Pit
+
+A Pit is not a single file—it is a **Directory Ecosystem**:
+
+```
+Person/
+├── Person.pit                     # Canonical point-in-time snapshot
+├── Master.flag                    # Master writer lease ticket (Owner|Timestamp)
+├── Nkosikazi-python-59346.flag    # Process activity window ({Machine}-{App}-{PID}.flag)
+├── Events/                        # Immutable change streams & compaction archives
+└── Changes/                       # Hashed, collision-safe change files & receipts
+```
+
+---
+
+## Autonomous Agents & Cross-Platform State
+
+`jsonpit` solves the distributed state dilemma for autonomous AI agents:
+
+1. **Zero Database Infrastructure:** An agent needs only a directory path on a synchronized cloud drive (e.g. `OneDriveData/AIA/AgentMemory`). It never requires cloud database API keys, connection pools, firewall punch-through, or hosted database servers.
+2. **Auditability & Time-Travel:** Because history is strictly append-only and stamped with .NET `UtcTicks`, every agent mutation retains full provenance. Operators or supervising agents can time-travel and inspect exact state at any millisecond.
+3. **Multi-Agent Collision-Proof Coordination:** Multiple agents (or desktop apps + background agents) coordinate through collision-free change files (`Changes/`) and opportunistic master writer leases (`Master.flag`), guaranteeing eventual consistency without write collisions.
+
+---
+
+## Development & Testing
+
+```bash
+# Run pytest test suite:
+pytest
+
+# Type checking (strict):
+mypy jsonpit
+```
+
+---
+
+## Heritage & Governance
+
+Architected by **Rainer Burkhardt (`RAI`)** + **Adele (`7010`)**.  
+Governed by [`ADELE_SPIRIT.md`](ADELE_SPIRIT.md) and [`GEMINI.md`](GEMINI.md) and assisted by an LLM named Adele as an homage to the great Adele Goldberg.

jsonpit-0.1.0/README.md

@@ -0,0 +1,131 @@
+# jsonpit
+
+> **Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies.**  
+> *100% C# JsonPit Parity · Zero Third-Party Runtime Dependencies · Smalltalk-Grade Object-Oriented Architecture*
+
+`jsonpit` stores JsonPits—JSON files with an append-only value history—across machines and servers coordinated over synchronized Cloud Drives (`OneDrive`, `Dropbox`, `GoogleDrive`, `ICloudDrive`) without requiring a centralized database daemon.
+
+It is the authoritative Python implementation of the JsonPit protocol, designed to operate in full, zero-deviation parity alongside the C# `JsonPit` engine and the `pits` CLI toolchain in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+
+---
+
+## Key Features
+
+- **The Persistence Fabric for AI Agents:** Autonomous agents running across macOS desktop apps, backend servers, and web runtimes synchronize memory and living state across shared cloud drives without managing database servers, connection pools, or cloud credentials.
+- **0% Deviation from C# JsonPit:** Reads, merges, and writes pits with identical canonical JSON serialization, UTC timestamp precision, and tombstone semantics.
+- **Zero Third-Party Runtime Dependencies:** Built strictly on the Python Standard Library (`json`, `pathlib`, `typing`, `dataclasses`, `datetime`, `hashlib`, `socket`).
+- **Cloud-Safe Filesystem Invariants (CR022):** In-place sibling writes (`.pit.tmp` $\rightarrow$ atomic rename within the same cloud volume). Prevents cross-device link errors (`EXDEV`) and OneDrive mass-deletion alarms.
+- **Full Distributed Lease Protocol:** Implements master writer leases (`Master.flag`) and PID-specific process activity windows (`{Machine}-{Process}-{PID}.flag`) with automatic process naming from `sys.argv[0]`.
+- **Ecosystem Configuration:** Seamlessly reads machine cloud paths from `~/.config/RAIkeep.json5` (with `~/.config/jsonpit.json5` fallback).
+- **Pure Object-Oriented Design:** Rich domain entities (`Pit`, `PitItem`, `PitItems`) implementing standard Python protocols (`MutableMapping`, `ContextManager`).
+
+---
+
+## Quickstart
+
+### 1. Cloud-First Triad (The Standard Pattern)
+
+Given a machine configured with `~/.config/RAIkeep.json5`:
+
+```python
+from jsonpit import Pit, PitItem
+
+# Automatically resolves cloud storage (OneDriveData/AfricaStage/Person/):
+with Pit.open("Person", cloud="OneDrive", root="AfricaStage") as pit:
+    # Get an entity (projected state)
+    sipho = pit.get("Sipho")
+    if sipho:
+        print(f"Sipho's current role: {sipho.get('Role')}")
+        # Mutate an entity: sparse append-only mutation, auto-sets Deleted=False
+        sipho.set_property({"Status": "Active", "Location": "RehearsalStage"})
+
+    # Add a new entity
+    hugh = PitItem(id="HughMasekela")
+    hugh.set_property({"Genre": "Jazz", "Instruments": ["Flugelhorn", "Cornet"]})
+    pit.add(hugh)
+
+# On exit of the context manager:
+# 1. Point-in-time snapshot captured
+# 2. In-place sibling temporary file written (CR022 cloud-safe)
+# 3. Atomically replaces Person.pit on the cloud volume
+# 4. Owned process activity flag cleanly released
+```
+
+### 2. Local / Explicit Filesystem Path
+
+For local test directories or custom scripts:
+
+```python
+with Pit.open("/path/to/my/Person") as pit:
+    for item in pit.values():
+        print(item.id, item.modified)
+```
+
+### 3. Developer Companion CLI: `jpit`
+
+The package installs both `jpit` and `jsonpit` commands:
+
+```bash
+# Fast semantic search across one or all pits ("Pit-Grep"):
+jpit grep "Adele" Person
+jpit grep "Burkhardt" --root AIA
+
+# Pipe search results directly into jq:
+jpit grep "Jazz" Person --json | jq '.[].Genre'
+
+# Inspect entity living state or full immutable history:
+jpit get Person Rainer
+jpit history Person Rainer
+
+# Pipe JSON5 / JSON mutations directly into a pit:
+cat update.json5 | jpit put Person
+echo '{id: "AlanKay", dynabook: true}' | jpit put Person
+
+# Set individual properties or tombstone an entity:
+jpit set Person AlanKay Status "Visionary"
+jpit del Person ObsoleteEntity
+```
+
+---
+
+## The Physical Structure of a Pit
+
+A Pit is not a single file—it is a **Directory Ecosystem**:
+
+```
+Person/
+├── Person.pit                     # Canonical point-in-time snapshot
+├── Master.flag                    # Master writer lease ticket (Owner|Timestamp)
+├── Nkosikazi-python-59346.flag    # Process activity window ({Machine}-{App}-{PID}.flag)
+├── Events/                        # Immutable change streams & compaction archives
+└── Changes/                       # Hashed, collision-safe change files & receipts
+```
+
+---
+
+## Autonomous Agents & Cross-Platform State
+
+`jsonpit` solves the distributed state dilemma for autonomous AI agents:
+
+1. **Zero Database Infrastructure:** An agent needs only a directory path on a synchronized cloud drive (e.g. `OneDriveData/AIA/AgentMemory`). It never requires cloud database API keys, connection pools, firewall punch-through, or hosted database servers.
+2. **Auditability & Time-Travel:** Because history is strictly append-only and stamped with .NET `UtcTicks`, every agent mutation retains full provenance. Operators or supervising agents can time-travel and inspect exact state at any millisecond.
+3. **Multi-Agent Collision-Proof Coordination:** Multiple agents (or desktop apps + background agents) coordinate through collision-free change files (`Changes/`) and opportunistic master writer leases (`Master.flag`), guaranteeing eventual consistency without write collisions.
+
+---
+
+## Development & Testing
+
+```bash
+# Run pytest test suite:
+pytest
+
+# Type checking (strict):
+mypy jsonpit
+```
+
+---
+
+## Heritage & Governance
+
+Architected by **Rainer Burkhardt (`RAI`)** + **Adele (`7010`)**.  
+Governed by [`ADELE_SPIRIT.md`](ADELE_SPIRIT.md) and [`GEMINI.md`](GEMINI.md) and assisted by an LLM named Adele as an homage to the great Adele Goldberg.

jsonpit-0.1.0/jsonpit/__init__.py

@@ -0,0 +1,32 @@
+"""
+jsonpit — Cloud-first, eventually-consistent replicated storage engine in pure Python.
+100% C# JsonPit parity · Zero third-party runtime dependencies.
+"""
+
+from .exceptions import (
+	JsonPitError,
+	PitConcurrencyError,
+	PitCorruptError,
+	PitInstanceConflictError,
+	PitNotFoundError,
+	TombstoneError,
+)
+from .fs import OsConfig
+from .history import PitItems
+from .item import PitItem
+from .store import Pit
+
+__version__ = "0.1.0"
+
+__all__ = [
+	"Pit",
+	"PitItem",
+	"PitItems",
+	"OsConfig",
+	"JsonPitError",
+	"PitNotFoundError",
+	"PitCorruptError",
+	"PitConcurrencyError",
+	"PitInstanceConflictError",
+	"TombstoneError",
+]

jsonpit-0.1.0/jsonpit/canonical.py

@@ -0,0 +1,105 @@
+"""
+Deterministic JSON canonicalization, content hashing, and time conversions.
+Adheres strictly to the CR003 / v3.13.2 specification in OsLib.CanonicalJson.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import json
+from typing import Any
+
+# .NET ticks: 100-nanosecond intervals since 0001-01-01 00:00:00 UTC
+TICKS_PER_MICROSECOND = 10
+TICKS_PER_SECOND = 10_000_000
+TICKS_AT_UNIX_EPOCH = 621_355_968_000_000_000
+UNIX_EPOCH = datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc)
+
+
+def utcnow() -> datetime.datetime:
+	"""Returns the current UTC datetime with explicit UTC timezone."""
+	return datetime.datetime.now(datetime.timezone.utc)
+
+
+def datetime_to_utc_ticks(dt: datetime.datetime) -> int:
+	"""
+	Converts a UTC datetime to .NET DateTimeOffset.UtcTicks.
+	1 tick = 100 nanoseconds since 0001-01-01 00:00:00 UTC.
+	"""
+	if dt.tzinfo is None:
+		dt = dt.replace(tzinfo=datetime.timezone.utc)
+	else:
+		dt = dt.astimezone(datetime.timezone.utc)
+	diff = dt - UNIX_EPOCH
+	total_microseconds = diff.days * 86_400_000_000 + diff.seconds * 1_000_000 + diff.microseconds
+	return TICKS_AT_UNIX_EPOCH + (total_microseconds * TICKS_PER_MICROSECOND)
+
+
+def utc_ticks_to_datetime(ticks: int) -> datetime.datetime:
+	"""Converts .NET UtcTicks back to a timezone-aware UTC datetime."""
+	diff_ticks = ticks - TICKS_AT_UNIX_EPOCH
+	diff_microseconds = diff_ticks // TICKS_PER_MICROSECOND
+	return UNIX_EPOCH + datetime.timedelta(microseconds=diff_microseconds)
+
+
+def format_iso_timestamp(dt: datetime.datetime) -> str:
+	"""
+	Formats a UTC datetime in standard round-trip ISO-8601 format:
+	'yyyy-MM-ddTHH:mm:ss.ffffffZ' (or 'yyyy-MM-ddTHH:mm:ssZ' if zero microseconds).
+	"""
+	if dt.tzinfo is None:
+		dt = dt.replace(tzinfo=datetime.timezone.utc)
+	else:
+		dt = dt.astimezone(datetime.timezone.utc)
+	if dt.microsecond == 0:
+		return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+	return dt.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def parse_iso_timestamp(ts: str) -> datetime.datetime:
+	"""
+	Parses an ISO-8601 timestamp string into a timezone-aware UTC datetime.
+	Supports 'Z', '+00:00', negative offsets, and fractional seconds.
+	"""
+	clean_ts = ts.strip()
+	if clean_ts.endswith("Z"):
+		clean_ts = clean_ts[:-1] + "+00:00"
+	dt = datetime.datetime.fromisoformat(clean_ts)
+	if dt.tzinfo is None:
+		dt = dt.replace(tzinfo=datetime.timezone.utc)
+	return dt.astimezone(datetime.timezone.utc)
+
+
+def canonical_json(obj: Any) -> str:
+	"""
+	Produces deterministic, compact JSON text without insignificant whitespace,
+	with dictionary keys sorted in ordinal order, matching OsLib.CanonicalJson.
+	"""
+	return json.dumps(
+		obj,
+		sort_keys=True,
+		separators=(",", ":"),
+		ensure_ascii=False,
+		default=_json_default_serializer,
+	)
+
+
+def _json_default_serializer(obj: Any) -> Any:
+	"""Serializes datetime objects and domain items to canonical JSON primitives."""
+	if isinstance(obj, datetime.datetime):
+		return format_iso_timestamp(obj)
+	if hasattr(obj, "to_dict"):
+		return obj.to_dict()
+	raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def sha256_hex(text: str) -> str:
+	"""Returns the full lowercase hex SHA-256 digest of the UTF-8 encoding of text."""
+	return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def canonical_with_hash(obj: Any) -> tuple[str, str]:
+	"""Returns (canonical_json_string, sha256_hex_digest)."""
+	canonical = canonical_json(obj)
+	return canonical, sha256_hex(canonical)