jsonpit 0.1.4__tar.gz → 4.4.2__tar.gz

{jsonpit-0.1.4 → jsonpit-4.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 0.1.4
+Version: 4.4.2
 Summary: Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies.
 Author: Dr. Rainer Burkhardt
 License-Expression: Apache-2.0
@@ -27,7 +27,18 @@ Description-Content-Type: text/markdown
 
 `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).
+The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits` CLI in [RAIkeep](https://github.com/Burkhardt/RAIkeep). `jsonpit` is the pure-Python implementation engineered for 100% behavioral and physical storage parity with zero deviation.
+
+---
+
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.2`)
+
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.2`** in direct lockstep with C# `JsonPit` and `pits 4.4.2` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+
+### Why Harmonized Versioning is Essential:
+- **Instant Compatibility Clarity:** Operators, DevOps pipelines, and autonomous AI agents immediately know whether `jpit` and `pits` share the exact same distributed protocol revision. If both tools report `4.4.x`, they guarantee identical master leasing rules, receipt mechanisms, 7-digit UTC timestamp parsing, and CR041 clean change file conventions.
+- **Elimination of Multi-Language Matrix Confusion:** In heterogeneous environments (e.g. C# backend daemons paired with Python agent orchestrators and data science tooling), unified SemVer tags eliminate complex cross-compatibility lookup tables.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules and CR041 clean change file formatting) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -137,12 +148,23 @@ Person/
 
 ## Development & Testing
 
+### Cross-Library Differential Parity Battery
+
+To ensure 100% interoperability with C# `JsonPit`, this repository includes a dedicated **Differential Cross-Testing Suite** (`tests/suites/*.json5` & `tests/sequence_runner.py`). The test harness orchestrates bidirectional interaction between the Python runtime (`jpit`) and the C# CLI binary (`pits`):
+
+- **Python Writes $\rightarrow$ C# Validates:** Python writes `.pit` snapshots and sparse changes; C# `pits export` and `pits verify` assert physical byte formatting, timestamp precision, and schema invariants.
+- **C# Writes $\rightarrow$ Python Validates:** C# `pits seed`, `delete-property`, and `maintain` mutate state; Python `jpit get`, `history`, and `PitStore` verify projections and receipt mechanics.
+- **7 Parity Suites (41 Cross-Engine Steps):** Covers persistence CRUD, CR041 clean change files, receipt grace periods, nested property tombstones, compaction/events archiving, process flag lifecycles, and split-master partition recovery.
+
+For full suite descriptions, architecture diagrams, and certification tables, see:  
+👉 **[`doc/CROSS_ENGINE_PARITY_SPECIFICATION.md`](doc/CROSS_ENGINE_PARITY_SPECIFICATION.md)**
+
 ```bash
-# Run pytest test suite:
-pytest
+# Run the full test battery (Unit Tests + 7 Cross-Engine Parity Suites):
+python3 tests/run_all.py
 
-# Type checking (strict):
-mypy jsonpit
+# Run a specific declarative parity suite directly:
+python3 -m tests.sequence_runner tests/suites/01_persistence_and_crud.json5
 ```
 
 ---

{jsonpit-0.1.4 → jsonpit-4.4.2}/README.md

@@ -5,7 +5,18 @@
 
 `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).
+The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits` CLI in [RAIkeep](https://github.com/Burkhardt/RAIkeep). `jsonpit` is the pure-Python implementation engineered for 100% behavioral and physical storage parity with zero deviation.
+
+---
+
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.2`)
+
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.2`** in direct lockstep with C# `JsonPit` and `pits 4.4.2` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+
+### Why Harmonized Versioning is Essential:
+- **Instant Compatibility Clarity:** Operators, DevOps pipelines, and autonomous AI agents immediately know whether `jpit` and `pits` share the exact same distributed protocol revision. If both tools report `4.4.x`, they guarantee identical master leasing rules, receipt mechanisms, 7-digit UTC timestamp parsing, and CR041 clean change file conventions.
+- **Elimination of Multi-Language Matrix Confusion:** In heterogeneous environments (e.g. C# backend daemons paired with Python agent orchestrators and data science tooling), unified SemVer tags eliminate complex cross-compatibility lookup tables.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules and CR041 clean change file formatting) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -115,12 +126,23 @@ Person/
 
 ## Development & Testing
 
+### Cross-Library Differential Parity Battery
+
+To ensure 100% interoperability with C# `JsonPit`, this repository includes a dedicated **Differential Cross-Testing Suite** (`tests/suites/*.json5` & `tests/sequence_runner.py`). The test harness orchestrates bidirectional interaction between the Python runtime (`jpit`) and the C# CLI binary (`pits`):
+
+- **Python Writes $\rightarrow$ C# Validates:** Python writes `.pit` snapshots and sparse changes; C# `pits export` and `pits verify` assert physical byte formatting, timestamp precision, and schema invariants.
+- **C# Writes $\rightarrow$ Python Validates:** C# `pits seed`, `delete-property`, and `maintain` mutate state; Python `jpit get`, `history`, and `PitStore` verify projections and receipt mechanics.
+- **7 Parity Suites (41 Cross-Engine Steps):** Covers persistence CRUD, CR041 clean change files, receipt grace periods, nested property tombstones, compaction/events archiving, process flag lifecycles, and split-master partition recovery.
+
+For full suite descriptions, architecture diagrams, and certification tables, see:  
+👉 **[`doc/CROSS_ENGINE_PARITY_SPECIFICATION.md`](doc/CROSS_ENGINE_PARITY_SPECIFICATION.md)**
+
 ```bash
-# Run pytest test suite:
-pytest
+# Run the full test battery (Unit Tests + 7 Cross-Engine Parity Suites):
+python3 tests/run_all.py
 
-# Type checking (strict):
-mypy jsonpit
+# Run a specific declarative parity suite directly:
+python3 -m tests.sequence_runner tests/suites/01_persistence_and_crud.json5
 ```
 
 ---

{jsonpit-0.1.4 → jsonpit-4.4.2}/jsonpit/__init__.py

@@ -9,26 +9,32 @@ from .exceptions import (
 	PitCorruptError,
 	PitInstanceConflictError,
 	PitNotFoundError,
+	ProtectedAttributeError,
 	TombstoneError,
 )
 from .fs import OsConfig
 from .history import PitItems
+from .icons import Icons
 from .item import PitItem
+from .store import Pit
+
 try:
 	import importlib.metadata
 	__version__ = importlib.metadata.version("jsonpit")
 except Exception:
-	__version__ = "0.1.4"
+	__version__ = "4.4.2"
 
 __all__ = [
 	"Pit",
 	"PitItem",
 	"PitItems",
 	"OsConfig",
+	"Icons",
 	"JsonPitError",
 	"PitNotFoundError",
 	"PitCorruptError",
 	"PitConcurrencyError",
 	"PitInstanceConflictError",
+	"ProtectedAttributeError",
 	"TombstoneError",
 ]

{jsonpit-0.1.4 → jsonpit-4.4.2}/jsonpit/canonical.py

@@ -45,16 +45,16 @@ def utc_ticks_to_datetime(ticks: int) -> datetime.datetime:
 
 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).
+	Formats a UTC datetime in exact .NET 'o' round-trip ISO-8601 format:
+	'yyyy-MM-ddTHH:mm:ss.fffffffZ' (7 fractional digits).
+	Guarantees 100% parity with .NET DateTimeOffset.ParseExact(..., "o", ...).
 	"""
 	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")
+	base = dt.strftime("%Y-%m-%dT%H:%M:%S")
+	return f"{base}.{dt.microsecond:06d}0Z"
 
 
 def parse_iso_timestamp(ts: str) -> datetime.datetime:

{jsonpit-0.1.4 → jsonpit-4.4.2}/jsonpit/changes.py

@@ -42,29 +42,44 @@ class ChangeFile:
 	def compose_name(
 		modified: datetime.datetime,
 		exact_process_identity: str,
-		sha256: str,
+		sha256: str | None = None,
 	) -> str:
-		"""Composes the change-file stem: {UtcTicks}_{ExactProcessIdentity}_{Sha256}."""
+		"""
+		Composes the change-file stem.
+		CR041 clean format: {UtcTicks}_{ExactProcessIdentity}.
+		CR003 legacy format: {UtcTicks}_{ExactProcessIdentity}_{Sha256}.
+		"""
 		ticks = datetime_to_utc_ticks(modified)
-		return f"{ticks}_{exact_process_identity}_{sha256}"
+		if sha256:
+			return f"{ticks}_{exact_process_identity}_{sha256}"
+		return f"{ticks}_{exact_process_identity}"
 
 	@classmethod
-	def compose_name_for(cls, fragment: PitItem, exact_process_identity: str) -> str:
+	def compose_name_for(
+		cls,
+		fragment: PitItem,
+		exact_process_identity: str,
+		include_sha: bool = False,
+	) -> str:
 		"""Composes the change-file stem directly from a PitItem fragment."""
-		_, sha = cls.canonical_payload_for(fragment)
-		return cls.compose_name(fragment.modified, exact_process_identity, sha)
+		if include_sha:
+			_, sha = cls.canonical_payload_for(fragment)
+			return cls.compose_name(fragment.modified, exact_process_identity, sha)
+		return cls.compose_name(fragment.modified, exact_process_identity)
 
 	@staticmethod
-	def try_parse_name(name_without_extension: str) -> tuple[int, str, str] | None:
+	def try_parse_name(name_without_extension: str) -> tuple[int, str, str | None] | None:
 		"""
 		Parses a change-file name without extension.
-		Returns (utc_ticks, exact_process_identity, sha256) or None if invalid.
+		Supports both CR041 clean format ({ticks}_{identity}) and
+		CR003 legacy format ({ticks}_{identity}_{sha256}).
+		Returns (utc_ticks, exact_process_identity, sha256_or_none) or None if invalid.
 		"""
 		if not name_without_extension:
 			return None
+
 		first_sep = name_without_extension.find("_")
-		last_sep = name_without_extension.rfind("_")
-		if first_sep <= 0 or last_sep <= first_sep:
+		if first_sep <= 0 or first_sep == len(name_without_extension) - 1:
 			return None
 
 		ticks_str = name_without_extension[:first_sep]
@@ -73,15 +88,22 @@ class ChangeFile:
 		except ValueError:
 			return None
 
-		sha = name_without_extension[last_sep + 1 :]
-		if len(sha) != 64 or not all(c in "0123456789abcdef" for c in sha.lower()):
-			return None
+		remainder = name_without_extension[first_sep + 1 :]
+		last_sep = remainder.rfind("_")
 
-		identity = name_without_extension[first_sep + 1 : last_sep]
-		if not identity:
-			return None
+		# Check if remainder has a trailing 64-char hex SHA (CR003 legacy format)
+		if last_sep > 0:
+			sha_candidate = remainder[last_sep + 1 :]
+			if len(sha_candidate) == 64 and all(c in "0123456789abcdef" for c in sha_candidate.lower()):
+				identity = remainder[:last_sep]
+				if identity:
+					return ticks, identity, sha_candidate.lower()
+
+		# CR041 clean format: {ticks}_{identity}
+		if remainder:
+			return ticks, remainder, None
 
-		return ticks, identity, sha.lower()
+		return None
 
 	@classmethod
 	def identity_of(cls, name_without_extension: str) -> str | None:
@@ -89,21 +111,14 @@ class ChangeFile:
 		parsed = cls.try_parse_name(name_without_extension)
 		if parsed:
 			return parsed[1]
-		# Legacy format fallback: {ticks}_{identity}
-		sep = name_without_extension.find("_")
-		if sep > 0 and sep < len(name_without_extension) - 1:
-			try:
-				int(name_without_extension[:sep])
-				return name_without_extension[sep + 1 :]
-			except ValueError:
-				pass
 		return None
 
 	@classmethod
 	def read_validated(cls, file_path: Path) -> list[list[dict[str, Any]]] | None:
 		"""
 		Reads and validates a change file.
-		Verifies the file content matches the embedded SHA-256 hash.
+		For legacy files with embedded SHA-256, verifies content matches hash.
+		For clean CR041 files, verifies valid JSON structure.
 		Returns parsed JSON payload or None if invalid or corrupt.
 		"""
 		content = safe_read_text(file_path)
@@ -113,9 +128,10 @@ class ChangeFile:
 		parsed_meta = cls.try_parse_name(file_path.stem)
 		if parsed_meta:
 			_, _, expected_sha = parsed_meta
-			actual_sha = sha256_hex(content)
-			if actual_sha != expected_sha:
-				return None
+			if expected_sha is not None:
+				actual_sha = sha256_hex(content)
+				if actual_sha != expected_sha:
+					return None
 
 		try:
 			data = json.loads(content)
@@ -133,14 +149,17 @@ class ChangeFile:
 		exact_process_identity: str,
 	) -> Path:
 		"""
-		Writes a fragment as an ordinary collision-safe change file in pit_dir.
-		Filename: {Modified.UtcTicks}_{ExactProcessIdentity}_{Sha256}.json.
+		Writes a fragment as an ordinary collision-safe clean change file in pit_dir (CR041).
+		Filename: {Modified.UtcTicks}_{ExactProcessIdentity}.json.
 		Exact byte contract: canonical UTF-8 JSON without trailing newline.
 		"""
-		payload, sha = cls.canonical_payload_for(fragment)
-		stem = cls.compose_name(fragment.modified, exact_process_identity, sha)
+		payload, _ = cls.canonical_payload_for(fragment)
+		stem = cls.compose_name(fragment.modified, exact_process_identity)
 		target_path = pit_dir / f"{stem}.json"
 
+		if not target_path.is_file():
+			safe_write_in_place(target_path, payload)
+
 		if not target_path.is_file():
 			safe_write_in_place(target_path, payload)