jsonpit 4.4.3__tar.gz → 4.4.5__tar.gz

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.3
+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.3`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.5`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` 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 and CR041 clean change file formatting) 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.
 
 ---
 
@@ -54,6 +54,69 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Installation & Upgrade
+
+### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
+To run the `jpit` command-line companion anywhere across your machine in an isolated environment without polluting system packages:
+
+```bash
+# Install globally
+pipx install jsonpit
+# (or via companion alias)
+pipx install jpit
+
+# Upgrade to the latest lockstep release (v4.4.5)
+pipx upgrade jsonpit
+# (or)
+pipx upgrade jpit
+```
+
+### In a Project / Virtual Environment via `pip`
+To embed `jsonpit` into your Python applications, data science workflows, or agentic runtimes:
+
+```bash
+# Install
+pip install jsonpit
+
+# Upgrade to the latest release
+pip install --upgrade jsonpit
+```
+
+### Upgrading with Multi-Python / `pyenv` Environments
+If you maintain multiple Python versions on your machine (e.g. 3.12, 3.13, 3.14):
+
+1. **Always anchor `pip` to your active Python interpreter:**
+   ```bash
+   python -m pip install --upgrade jpit
+   ```
+   *(Avoid bare `pip install`: invoking `pip` directly may resolve to an older Python version in `$PATH`, installing the package into the wrong runtime).*
+
+2. **If using `pyenv`, regenerate shims:**
+   ```bash
+   pyenv rehash
+   ```
+   *This ensures `which jpit` resolves to `~/.pyenv/shims/jpit`, which dynamically routes to whichever Python version is currently active in your shell.*
+
+3. **Verify the active executable:**
+   ```bash
+   which jpit
+   jpit --version
+   ```
+
+> [!TIP]
+> **Encountering `error: externally-managed-environment` (Homebrew Python or modern Linux / PEP 668)?**  
+> Modern Homebrew and Linux package managers protect their system Python prefix by default. You have two clean options:
+> - **Option A (Isolated CLI via `pipx`):** Run `brew install pipx && pipx ensurepath`, then `pipx install jpit`.
+> - **Option B (Direct install into Homebrew Python):** Pass `--break-system-packages`:
+>   ```bash
+>   python -m pip install --upgrade --break-system-packages jpit
+>   ```
+>   *(Completely safe: `jsonpit` has zero runtime dependencies and cannot break system packages).*
+
+*(Both the `jsonpit` library package and the `jpit` companion package provide both `jpit` and `jsonpit` command-line executables).*
+
+---
+
 ## Quickstart
 
 ### 1. Cloud-First Triad (The Standard Pattern)

{jsonpit-4.4.3 → 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.3`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.5`)
 
-`jsonpit` and the `jpit` CLI are version-synchronized to **`v4.4.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` 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 and CR041 clean change file formatting) 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.
 
 ---
 
@@ -32,6 +32,69 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Installation & Upgrade
+
+### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
+To run the `jpit` command-line companion anywhere across your machine in an isolated environment without polluting system packages:
+
+```bash
+# Install globally
+pipx install jsonpit
+# (or via companion alias)
+pipx install jpit
+
+# Upgrade to the latest lockstep release (v4.4.5)
+pipx upgrade jsonpit
+# (or)
+pipx upgrade jpit
+```
+
+### In a Project / Virtual Environment via `pip`
+To embed `jsonpit` into your Python applications, data science workflows, or agentic runtimes:
+
+```bash
+# Install
+pip install jsonpit
+
+# Upgrade to the latest release
+pip install --upgrade jsonpit
+```
+
+### Upgrading with Multi-Python / `pyenv` Environments
+If you maintain multiple Python versions on your machine (e.g. 3.12, 3.13, 3.14):
+
+1. **Always anchor `pip` to your active Python interpreter:**
+   ```bash
+   python -m pip install --upgrade jpit
+   ```
+   *(Avoid bare `pip install`: invoking `pip` directly may resolve to an older Python version in `$PATH`, installing the package into the wrong runtime).*
+
+2. **If using `pyenv`, regenerate shims:**
+   ```bash
+   pyenv rehash
+   ```
+   *This ensures `which jpit` resolves to `~/.pyenv/shims/jpit`, which dynamically routes to whichever Python version is currently active in your shell.*
+
+3. **Verify the active executable:**
+   ```bash
+   which jpit
+   jpit --version
+   ```
+
+> [!TIP]
+> **Encountering `error: externally-managed-environment` (Homebrew Python or modern Linux / PEP 668)?**  
+> Modern Homebrew and Linux package managers protect their system Python prefix by default. You have two clean options:
+> - **Option A (Isolated CLI via `pipx`):** Run `brew install pipx && pipx ensurepath`, then `pipx install jpit`.
+> - **Option B (Direct install into Homebrew Python):** Pass `--break-system-packages`:
+>   ```bash
+>   python -m pip install --upgrade --break-system-packages jpit
+>   ```
+>   *(Completely safe: `jsonpit` has zero runtime dependencies and cannot break system packages).*
+
+*(Both the `jsonpit` library package and the `jpit` companion package provide both `jpit` and `jsonpit` command-line executables).*
+
+---
+
 ## Quickstart
 
 ### 1. Cloud-First Triad (The Standard Pattern)

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

@@ -10,19 +10,16 @@ from .exceptions import (
 	PitInstanceConflictError,
 	PitNotFoundError,
 	ProtectedAttributeError,
+	StrictPatchValidationError,
 	TombstoneError,
 )
-from .fs import OsConfig
+from .config import DEFAULT_CONFIG_FILE_LOCATION, OsConfig, missing_configuration_diagnostic
 from .history import PitItems
 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.3"
+__version__ = "4.4.5"
 
 __all__ = [
 	"Pit",
@@ -31,6 +28,8 @@ __all__ = [
 	"PitItem",
 	"PitItems",
 	"OsConfig",
+	"DEFAULT_CONFIG_FILE_LOCATION",
+	"missing_configuration_diagnostic",
 	"Icons",
 	"JsonPitError",
 	"PitNotFoundError",
@@ -38,5 +37,6 @@ __all__ = [
 	"PitConcurrencyError",
 	"PitInstanceConflictError",
 	"ProtectedAttributeError",
+	"StrictPatchValidationError",
 	"TombstoneError",
 ]

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

@@ -19,8 +19,13 @@ import sys
 from typing import Any
 
 from .canonical import canonical_json, format_iso_timestamp, parse_iso_timestamp, utcnow
-from .config import OsConfig, loads_json5
-from .exceptions import JsonPitError, PitNotFoundError, ProtectedAttributeError
+from .config import OsConfig, loads_json5, missing_configuration_diagnostic
+from .exceptions import (
+	JsonPitError,
+	PitNotFoundError,
+	ProtectedAttributeError,
+	StrictPatchValidationError,
+)
 from .fs import resolve_pit_target
 from .item import PitItem
 from .icons import Icons
@@ -70,21 +75,39 @@ def discover_pits(
 			return discovered_cwd
 
 	# Check if target is a single pit or an explicit directory
-	try:
-		p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
-		if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
-			return [(p_dir, p_name)]
-	except Exception:
-		pass
-
-	# Check if target is a tenant/root folder containing multiple pit directories
+	raw_str = str(target).strip()
+	is_explicit_path = (
+		raw_str.startswith(("/", "~", ".", "\\"))
+		or ("/" in raw_str and not raw_str.startswith("-"))
+		or ("\\" in raw_str)
+		or Path(raw_str).exists()
+	)
+	if is_explicit_path:
+		try:
+			p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
+			if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
+				return [(p_dir, p_name)]
+		except Exception:
+			pass
+		if Path(target).is_dir():
+			discovered = []
+			for child in sorted(Path(target).iterdir()):
+				if child.is_dir():
+					pit_file = child / f"{child.name}.pit"
+					if pit_file.is_file():
+						discovered.append((child, child.name))
+			if discovered:
+				return discovered
+
+	# Target requires cloud resolution
 	cfg = OsConfig.load()
+	if not cfg.is_config_loaded and not is_explicit_path:
+		raise PitNotFoundError(missing_configuration_diagnostic())
+
 	cloud_root = cfg.get_cloud_root(cloud)
 	candidates: list[Path] = []
 	if cloud_root and (cloud_root / target).is_dir():
 		candidates.append(cloud_root / target)
-	if Path(target).is_dir():
-		candidates.append(Path(target))
 
 	discovered: list[tuple[Path, str]] = []
 	for candidate_root in candidates:
@@ -97,13 +120,10 @@ def discover_pits(
 	if discovered:
 		return discovered
 
-	# Fallback single pit target (only return if it physically exists)
-	try:
-		p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
-		if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
-			return [(p_dir, p_name)]
-	except Exception:
-		pass
+	# Fallback single pit target
+	p_dir, p_name = resolve_pit_target(target, cloud=cloud, root=root)
+	if (p_dir / f"{p_name}.pit").is_file() or p_dir.is_dir():
+		return [(p_dir, p_name)]
 	return []
 
 
@@ -111,17 +131,16 @@ def discover_root_pits(root: str | None, cloud: str | None = "OneDrive") -> list
 	"""Discovers all pit names under a resolved tenant root directory."""
 	if not root:
 		return []
-	cfg = OsConfig.load()
-	cloud_root = cfg.get_cloud_root(cloud or "OneDrive")
-	candidate: Path | None = None
-	if cloud_root and (cloud_root / root).is_dir():
-		candidate = cloud_root / root
+	raw_str = str(root).strip()
+	p = Path(os.path.expanduser(raw_str))
+	if p.is_dir():
+		candidate: Path | None = p
 	else:
-		p = Path(os.path.expanduser(root))
-		if p.is_dir():
-			candidate = p
-		elif cloud_root:
-			candidate = cloud_root / root
+		cfg = OsConfig.load()
+		if not cfg.is_config_loaded:
+			raise PitNotFoundError(missing_configuration_diagnostic())
+		cloud_root = cfg.get_cloud_root(cloud or "OneDrive")
+		candidate = cloud_root / root if cloud_root else None
 
 	if not candidate or not candidate.is_dir():
 		return []
@@ -381,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
@@ -408,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,
@@ -450,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
@@ -499,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
@@ -735,7 +786,10 @@ def print_top_help(
 	# Dynamic Pits Discovery line
 	pits_title = color(f"{Icons.INFO} PitNames", C_CYAN, use_color)
 	if root:
-		discovered = discover_root_pits(root, cloud)
+		try:
+			discovered = discover_root_pits(root, cloud)
+		except Exception:
+			discovered = []
 		if discovered:
 			formatted_pits = []
 			for idx, p in enumerate(discovered):
@@ -827,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"),
@@ -835,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"],
 		},
@@ -999,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",
@@ -1025,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)
@@ -1084,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.3 → jsonpit-4.4.5}/jsonpit/config.py

@@ -217,6 +217,20 @@ def loads_json5(text: str) -> Any:
 	return parse_value()
 
 
+DEFAULT_CONFIG_FILE_LOCATION: str = "~/.config/RAIkeep.json5"
+
+
+def missing_configuration_diagnostic() -> str:
+	"""
+	CR044 §7.4: Standardized diagnostic when RAIkeep configuration is not found.
+	Directs the operator to 'amafu init'.
+	"""
+	return (
+		f"RAIkeep configuration was not found at '{DEFAULT_CONFIG_FILE_LOCATION}'. "
+		"Run 'amafu init' to detect cloud providers and create it."
+	)
+
+
 class OsConfig:
 	"""
 	System configuration derived from ~/.config/RAIkeep.json5 or fallback files.
@@ -253,6 +267,16 @@ class OsConfig:
 				if path_str:
 					self.clouds[name] = self._normalize_path(str(path_str))
 
+	@property
+	def is_config_loaded(self) -> bool:
+		"""Returns True if configuration was loaded from a file or explicit dictionary."""
+		return self._config_path is not None or bool(self.clouds)
+
+	@classmethod
+	def reset(cls) -> None:
+		"""Resets the singleton instance (used in tests)."""
+		cls._instance = None
+
 	@staticmethod
 	def _normalize_path(p: str) -> Path:
 		expanded = os.path.expanduser(p.strip())

{jsonpit-4.4.3 → 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.3 → jsonpit-4.4.5}/jsonpit/fs.py

@@ -11,7 +11,7 @@ import shutil
 from pathlib import Path
 from typing import Any
 
-from .config import OsConfig
+from .config import DEFAULT_CONFIG_FILE_LOCATION, OsConfig, missing_configuration_diagnostic
 from .exceptions import PitNotFoundError
 
 
@@ -52,12 +52,16 @@ def resolve_pit_target(
 			pit_name = resolved.name
 		return pit_dir, pit_name
 
+	# CR044 §7.4: If attempting cloud triad resolution and no configuration file exists
+	if not cfg.is_config_loaded:
+		raise PitNotFoundError(missing_configuration_diagnostic())
+
 	# Cloud triad resolution (e.g. name="Person", cloud="OneDrive", root="AfricaStage")
 	cloud_root = cfg.get_cloud_root(cloud)
 	if cloud_root is None:
 		raise PitNotFoundError(
 			f"Could not resolve cloud storage root for cloud '{cloud or 'default'}'. "
-			"Ensure ~/.config/RAIkeep.json5 or ~/.config/jsonpit.json5 is configured."
+			f"Ensure {DEFAULT_CONFIG_FILE_LOCATION} or ~/.config/jsonpit.json5 is configured."
 		)
 
 	pit_name = raw_str

{jsonpit-4.4.3 → 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.3 → 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.3 → jsonpit-4.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jsonpit"
-version = "4.4.3"
+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",