jsonpit 4.4.4__tar.gz → 4.4.5__tar.gz

{jsonpit-4.4.4 → jsonpit-4.4.5}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.4
+Version: 4.4.5
 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
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -31,14 +31,14 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
-## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.5`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.4`** in direct lockstep with C# `JsonPit` and `pits 4.4.4` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.5`** in direct lockstep with C# `JsonPit` and `pits 4.4.5` 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, CR041 clean change file formatting, and CR044 missing configuration diagnostics) are certified across both languages under the exact same version milestone before release.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules, CR041 clean change file formatting, CR044 missing configuration diagnostics, and CR047 strict patch validation) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -65,7 +65,7 @@ pipx install jsonpit
 # (or via companion alias)
 pipx install jpit
 
-# Upgrade to the latest lockstep release (v4.4.4)
+# Upgrade to the latest lockstep release (v4.4.5)
 pipx upgrade jsonpit
 # (or)
 pipx upgrade jpit

{jsonpit-4.4.4 → jsonpit-4.4.5}/README.md

@@ -9,14 +9,14 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
-## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.5`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.4`** in direct lockstep with C# `JsonPit` and `pits 4.4.4` in [RAIkeep](https://github.com/Burkhardt/RAIkeep).
+`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.5`** in direct lockstep with C# `JsonPit` and `pits 4.4.5` 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, CR041 clean change file formatting, and CR044 missing configuration diagnostics) are certified across both languages under the exact same version milestone before release.
+- **Joint Protocol Governance:** Architectural changes (such as CR040 anti-Read-Modify-Write rules, CR041 clean change file formatting, CR044 missing configuration diagnostics, and CR047 strict patch validation) are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -43,7 +43,7 @@ pipx install jsonpit
 # (or via companion alias)
 pipx install jpit
 
-# Upgrade to the latest lockstep release (v4.4.4)
+# Upgrade to the latest lockstep release (v4.4.5)
 pipx upgrade jsonpit
 # (or)
 pipx upgrade jpit

{jsonpit-4.4.4 → jsonpit-4.4.5}/jsonpit/__init__.py

@@ -10,6 +10,7 @@ from .exceptions import (
 	PitInstanceConflictError,
 	PitNotFoundError,
 	ProtectedAttributeError,
+	StrictPatchValidationError,
 	TombstoneError,
 )
 from .config import DEFAULT_CONFIG_FILE_LOCATION, OsConfig, missing_configuration_diagnostic
@@ -18,11 +19,7 @@ from .icons import Icons
 from .item import PitItem
 from .store import Pit, PitStore, parse_and_validate_seed_payload
 
-try:
-	import importlib.metadata
-	__version__ = importlib.metadata.version("jsonpit")
-except Exception:
-	__version__ = "4.4.4"
+__version__ = "4.4.5"
 
 __all__ = [
 	"Pit",
@@ -40,5 +37,6 @@ __all__ = [
 	"PitConcurrencyError",
 	"PitInstanceConflictError",
 	"ProtectedAttributeError",
+	"StrictPatchValidationError",
 	"TombstoneError",
 ]

{jsonpit-4.4.4 → jsonpit-4.4.5}/jsonpit/cli.py

@@ -20,7 +20,12 @@ from typing import Any
 
 from .canonical import canonical_json, format_iso_timestamp, parse_iso_timestamp, utcnow
 from .config import OsConfig, loads_json5, missing_configuration_diagnostic
-from .exceptions import JsonPitError, PitNotFoundError, ProtectedAttributeError
+from .exceptions import (
+	JsonPitError,
+	PitNotFoundError,
+	ProtectedAttributeError,
+	StrictPatchValidationError,
+)
 from .fs import resolve_pit_target
 from .item import PitItem
 from .icons import Icons
@@ -395,7 +400,9 @@ def cmd_put(args: argparse.Namespace) -> int:
 	Ingests entities from stdin, piped jq output, or a JSON5 file.
 	Adds entities cloud-safely with leasing.
 	CR043: Supports single root entity, keyed entity map, or entity array.
+	CR047: Strict patch mode via --require-existing or --patch.
 	"""
+	require_existing = bool(getattr(args, "require_existing", False) or getattr(args, "patch", False))
 	source_path_str = getattr(args, "source", None)
 	if not source_path_str and getattr(args, "source_opt", None):
 		source_path_str = args.source_opt
@@ -422,10 +429,42 @@ def cmd_put(args: argparse.Namespace) -> int:
 		sys.stderr.write(f"[jpit] Error: {ex}\n")
 		return 1
 
+	if require_existing and not items_to_add:
+		sys.stderr.write("error: Patch source contained 0 entities.\n")
+		return 1
+
 	if not items_to_add:
 		print(f"[jpit] Seed source '{source_name}' contained 0 entities.")
 		return 0
 
+	# CR047: Strict patch mode pre-validation before opening target Pit for writing or creating flags
+	if require_existing:
+		try:
+			with Pit.open(
+				args.pit,
+				cloud=args.cloud,
+				root=args.root,
+				read_only=True,
+				unflagged=True,
+			) as living_state:
+				for raw_obj in items_to_add:
+					item_id = raw_obj["Id"]
+					if not living_state.contains(item_id, with_deleted=False):
+						sys.stderr.write(
+							f"error: Entity '{item_id}' does not exist in Pit '{living_state.pit_name}'. "
+							"Use without --require-existing / --patch to allow creating new entities.\n"
+						)
+						return 1
+		except PitNotFoundError:
+			sys.stderr.write(
+				f"error: Entity '{items_to_add[0]['Id']}' does not exist in Pit '{args.pit}'. "
+				"Use without --require-existing / --patch to allow creating new entities.\n"
+			)
+			return 1
+		except Exception as ex:
+			sys.stderr.write(f"[jpit] Error: {ex}\n")
+			return 1
+
 	with Pit.open(
 		args.pit,
 		cloud=args.cloud,
@@ -464,13 +503,12 @@ def cmd_set(args: argparse.Namespace) -> int:
 		retain_window=getattr(args, "retain_window", False),
 	) as pit:
 		existing = pit.get(args.id)
-		if existing:
+		if existing is not None:
 			existing.set_property(payload)
-			pit.add(existing)
 		else:
-			payload["Id"] = args.id
-			new_item = PitItem(payload)
-			pit.add(new_item)
+			delta = dict(payload)
+			delta["Id"] = args.id
+			pit.add(PitItem(delta))
 
 	print(f"[jpit] Updated entity '{args.id}' in Pit '{args.pit}'.")
 	return 0
@@ -513,7 +551,6 @@ def cmd_delete_prop(args: argparse.Namespace) -> int:
 			sys.stderr.write(f"[jpit] Entity '{args.id}' not found.\n")
 			return 1
 		item.delete_property_path(args.property_path)
-		pit.add(item)
 
 	print(f"[jpit] Tombstoned property '{args.property_path}' on entity '{args.id}'.")
 	return 0
@@ -844,7 +881,7 @@ def print_command_help(cmd: str, nologo: bool = False, use_color: bool = True) -
 			],
 		},
 		"put": {
-			"usage": "jpit put <PitName> [<source>] [-s <source>] [options]",
+			"usage": "jpit put <PitName> [<source>] [-s <source>] [--require-existing] [--patch] [options]",
 			"desc": "Ingest JSON5 entities from file or stdin pipe (alias: seed).",
 			"args": [
 				("PitName", "Pit name or file path"),
@@ -852,6 +889,8 @@ def print_command_help(cmd: str, nologo: bool = False, use_color: bool = True) -
 			],
 			"opts": [
 				("-s, --source <file>", "Source file for import (JSON or JSON5)"),
+				("--require-existing", "Reject batch if any entity does not already exist"),
+				("--patch", "Alias for --require-existing"),
 			],
 			"aliases": ["seed"],
 		},
@@ -1016,7 +1055,22 @@ class JsonPitArgumentParser(argparse.ArgumentParser):
 		sys.exit(2)
 
 
-def build_parser() -> JsonPitArgumentParser:
+def get_cli_prog_name(argv0: str | None = None) -> str:
+	"""Determines whether CLI is invoked as 'jsonpit' or 'jpit'."""
+	if argv0 is None:
+		argv0 = sys.argv[0] if sys.argv and sys.argv[0] else "jpit"
+	base = Path(argv0).name.lower()
+	if base == "jsonpit" or base.startswith("jsonpit"):
+		return "jsonpit"
+	if "jsonpit" in str(argv0).lower() and "jpit" not in base:
+		return "jsonpit"
+	return "jpit"
+
+
+def build_parser(prog: str | None = None) -> JsonPitArgumentParser:
+	if prog is None:
+		prog = get_cli_prog_name()
+
 	common_parser = JsonPitArgumentParser(add_help=False)
 	common_parser.add_argument(
 		"-c", "--cloud",
@@ -1042,15 +1096,15 @@ def build_parser() -> JsonPitArgumentParser:
 	)
 
 	parser = JsonPitArgumentParser(
-		prog="jpit",
-		description="jpit — Cloud-first distributed replicated storage CLI and Pit-Grep.",
+		prog=prog,
+		description=f"{prog} — Cloud-first distributed replicated storage CLI and Pit-Grep.",
 		parents=[common_parser],
 	)
 	parser.add_argument(
 		"-v",
 		"--version",
 		action="version",
-		version=f"%(prog)s {__version__}",
+		version=f"%(prog)s v{__version__}",
 	)
 
 	subparsers = parser.add_subparsers(dest="command", required=True, parser_class=JsonPitArgumentParser)
@@ -1101,6 +1155,18 @@ def build_parser() -> JsonPitArgumentParser:
 	p_put.add_argument("pit", help="Pit name")
 	p_put.add_argument("source", nargs="?", default=None, help="Source file or '-' for stdin")
 	p_put.add_argument("-s", "--source", dest="source_opt", help="Source file for import (JSON or JSON5)")
+	p_put.add_argument(
+		"--require-existing",
+		action="store_true",
+		default=False,
+		help="CR047: Strictly require all incoming entity IDs to exist in the Pit",
+	)
+	p_put.add_argument(
+		"--patch",
+		action="store_true",
+		default=False,
+		help="CR047: Alias for --require-existing",
+	)
 
 	# set
 	p_set = subparsers.add_parser("set", parents=[common_parser], help="Set or patch entity with JSON5 payload")

{jsonpit-4.4.4 → jsonpit-4.4.5}/jsonpit/exceptions.py

@@ -29,3 +29,7 @@ class TombstoneError(JsonPitError):
 
 class ProtectedAttributeError(JsonPitError, ValueError):
 	"""Raised when attempting to manually mutate or inject protected lifecycle attributes (Modified, Deleted, Id)."""
+
+
+class StrictPatchValidationError(JsonPitError, ValueError):
+	"""CR047: Raised when --require-existing / --patch validation fails."""

{jsonpit-4.4.4 → jsonpit-4.4.5}/jsonpit/item.py

@@ -11,6 +11,7 @@ import datetime
 import json
 from collections.abc import Iterator, MutableMapping
 from typing import Any
+import weakref
 
 from .canonical import (
 	canonical_json,
@@ -84,13 +85,17 @@ class PitItem(MutableMapping[str, Any]):
 		deleted: bool = False,
 		modified: datetime.datetime | None = None,
 		invalidate: bool = True,
+		pit: Any | None = None,
 	) -> None:
 		self._data: dict[str, Any] = {}
 		self._dirty: bool = False
+		self._pit_ref: weakref.ref[Any] | None = weakref.ref(pit) if pit is not None else None
 
 		if isinstance(initial, PitItem):
 			self._data = copy.deepcopy(initial._data)
 			self._dirty = initial._dirty
+			if pit is not None:
+				self._pit_ref = weakref.ref(pit)
 			if id is not None:
 				self._data["Id"] = id
 			if note:
@@ -153,6 +158,16 @@ class PitItem(MutableMapping[str, Any]):
 		else:
 			self.validate()
 
+	def bind(self, pit: Any) -> PitItem:
+		"""Binds this living entity to its parent Pit container."""
+		self._pit_ref = weakref.ref(pit) if pit is not None else None
+		return self
+
+	@property
+	def pit(self) -> Any | None:
+		"""Returns the parent Pit if bound and alive, else None."""
+		return self._pit_ref() if self._pit_ref is not None else None
+
 	# --- Property Accessors ---
 
 	@property
@@ -264,15 +279,22 @@ class PitItem(MutableMapping[str, Any]):
 		"""
 		Appends a property tombstone by setting the top-level property to None (JSON null).
 		Resets Deleted to False and marks the entity dirty.
+		If bound to a Pit, automatically dispatches a sparse tombstone delta.
 		"""
 		self.deleted = False
 		self.invalidate()
 		self._data[property_name] = None
+		p = self.pit
+		if p is not None:
+			mutation = PitItem(id=self.id)
+			mutation.delete_property(property_name)
+			p.add(mutation)
 
 	def delete_property_path(self, property_path: str) -> None:
 		"""
 		Appends a property tombstone at a dot-delimited nested JSON path (e.g. 'Address.City').
 		Sets the leaf property to None (JSON null), resets Deleted to False, and marks dirty.
+		If bound to a Pit, automatically dispatches a sparse tombstone delta.
 		"""
 		if not property_path or not property_path.strip():
 			raise TombstoneError("A property path is required.")
@@ -304,11 +326,17 @@ class PitItem(MutableMapping[str, Any]):
 		container[segments[-1]] = None
 		self.deleted = False
 		self.invalidate()
+		p = self.pit
+		if p is not None:
+			mutation = PitItem(id=self.id)
+			mutation.delete_property_path(property_path)
+			p.add(mutation)
 
 	def delete(self, by: str | None = None, backdate_100: bool = True) -> bool:
 		"""
 		Tombstones this item. Appends an audit trail to Note.
 		If backdate_100 is True, preserves precedence by backdating Modified by 100 seconds.
+		If bound to a Pit, dispatches the tombstone to the Pit.
 		Returns True if newly deleted, False if already deleted.
 		"""
 		if self.deleted:
@@ -325,14 +353,13 @@ class PitItem(MutableMapping[str, Any]):
 		if by:
 			audit_entry += f" by {by}"
 		self.note = f"{audit_entry};\n{self.note}" if self.note else f"{audit_entry};"
+		p = self.pit
+		if p is not None:
+			p.delete_item(self.id, by=by, backdate_100=backdate_100)
 		return True
 
-	def extend_with(self, obj: dict[str, Any]) -> bool:
-		"""
-		Deep merges a dictionary into this entity.
-		Arrays are replaced; objects are recursively merged; nulls (tombstones) are preserved.
-		Returns True if any value was modified.
-		"""
+	def _apply_extend(self, obj: dict[str, Any]) -> bool:
+		"""In-memory deep merge without dispatching to parent Pit."""
 		original_canonical = canonical_json(self.to_dict())
 
 		def _deep_merge(target: dict[str, Any], source: dict[str, Any]) -> None:
@@ -349,6 +376,21 @@ class PitItem(MutableMapping[str, Any]):
 			self.invalidate()
 		return changed
 
+	def extend_with(self, obj: dict[str, Any]) -> bool:
+		"""
+		Deep merges a dictionary into this entity.
+		Arrays are replaced; objects are recursively merged; nulls (tombstones) are preserved.
+		If bound to a Pit, automatically dispatches a sparse delta fragment.
+		Returns True if any value was modified.
+		"""
+		changed = self._apply_extend(obj)
+		p = self.pit
+		if changed and p is not None:
+			delta = copy.deepcopy(obj)
+			delta["Id"] = self.id
+			p.add(PitItem(delta))
+		return changed
+
 	def extend(self, json_string: str) -> bool:
 		"""Parses JSON text and merges it into this entity."""
 		parsed = json.loads(json_string)
@@ -418,10 +460,19 @@ class PitItem(MutableMapping[str, Any]):
 		else:
 			self._data[key] = value
 			self.invalidate()
+			p = self.pit
+			if p is not None:
+				p.add(PitItem({"Id": self.id, key: value}))
 
 	def __delitem__(self, key: str) -> None:
-		del self._data[key]
+		if key in self._data:
+			del self._data[key]
 		self.invalidate()
+		p = self.pit
+		if p is not None:
+			mutation = PitItem(id=self.id)
+			mutation.delete_property(key)
+			p.add(mutation)
 
 	def __iter__(self) -> Iterator[str]:
 		# Ensure Id, Modified, Deleted are always visible in key enumeration

{jsonpit-4.4.4 → jsonpit-4.4.5}/jsonpit/store.py

@@ -29,6 +29,7 @@ from .exceptions import (
 	PitInstanceConflictError,
 	PitNotFoundError,
 	ProtectedAttributeError,
+	StrictPatchValidationError,
 )
 from .flags import (
 	MasterFlagFile,
@@ -417,11 +418,12 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 				raise
 			raise PitCorruptError(f"Failed to parse pit file {self.canonical_file}: {ex}") from ex
 
-	def seed_from_file(self, file_path: Path | str) -> int:
+	def seed_from_file(self, file_path: Path | str, require_existing: bool = False) -> int:
 		"""
 		Ingests a seed file (JSON or JSON5) and adds all entities to the pit.
 		Returns count of imported entities.
 		CR043: Validates payload shape and entities strictly before mutation.
+		CR047: If require_existing is True, validates that all IDs exist in living state.
 		"""
 		path = Path(file_path)
 		if not path.is_file():
@@ -430,6 +432,17 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 		text = path.read_text(encoding="utf-8")
 		items_to_add = parse_and_validate_seed_payload(text, str(path))
 
+		if require_existing:
+			if not items_to_add:
+				raise StrictPatchValidationError("Patch source contained 0 entities.")
+			for raw_obj in items_to_add:
+				item_id = raw_obj["Id"]
+				if not self.contains(item_id, with_deleted=False):
+					raise StrictPatchValidationError(
+						f"Entity '{item_id}' does not exist in Pit '{self.pit_name}'. "
+						"Use without --require-existing / --patch to allow creating new entities."
+					)
+
 		count = 0
 		for raw_obj in items_to_add:
 			item = PitItem(raw_obj)
@@ -647,6 +660,8 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 		if pit_items is None:
 			return default
 		projected = pit_items.project_state(at=at, with_deleted=with_deleted)
+		if projected is not None and at is None and not self.read_only:
+			projected.bind(self)
 		return projected if projected is not None else default
 
 	def get_at(
@@ -658,6 +673,12 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 		"""Point-in-time historical projection of an entity."""
 		return self.get(item_id, at=at, with_deleted=with_deleted)
 
+	def contains(self, item_id: str, with_deleted: bool = False) -> bool:
+		"""100% C# parity: checks if an entity exists in living state."""
+		if not item_id:
+			return False
+		return self.get(item_id, with_deleted=with_deleted) is not None
+
 	def all_undeleted(self) -> list[PitItem]:
 		"""Returns all active, non-deleted entities in this pit."""
 		results: list[PitItem] = []

{jsonpit-4.4.4 → jsonpit-4.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jsonpit"
-version = "4.4.4"
+version = "4.4.5"
 description = "Daemon-free distributed storage over Cloud Drives for developers and AI agents — multi-process, immutable history, zero dependencies."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -13,7 +13,7 @@ authors = [
 	{ name = "Dr. Rainer Burkhardt" },
 ]
 classifiers = [
-	"Development Status :: 4 - Beta",
+	"Development Status :: 5 - Production/Stable",
 	"Intended Audience :: Developers",
 	"Operating System :: OS Independent",
 	"Programming Language :: Python :: 3",