jsonpit 4.4.2__tar.gz → 4.4.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.2
+Version: 4.4.4
 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
@@ -31,14 +31,14 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
-## Cross-Tool & Cross-Language Version Alignment (`v4.4.2`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
 
-`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).
+`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).
 
 ### 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, and CR044 missing configuration diagnostics) 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.4)
+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.2 → jsonpit-4.4.4}/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.2`)
+## Cross-Tool & Cross-Language Version Alignment (`v4.4.4`)
 
-`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).
+`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).
 
 ### 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, and CR044 missing configuration diagnostics) 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.4)
+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.2 → jsonpit-4.4.4}/jsonpit/__init__.py

@@ -12,23 +12,27 @@ from .exceptions import (
 	ProtectedAttributeError,
 	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
+from .store import Pit, PitStore, parse_and_validate_seed_payload
 
 try:
 	import importlib.metadata
 	__version__ = importlib.metadata.version("jsonpit")
 except Exception:
-	__version__ = "4.4.2"
+	__version__ = "4.4.4"
 
 __all__ = [
 	"Pit",
+	"PitStore",
+	"parse_and_validate_seed_payload",
 	"PitItem",
 	"PitItems",
 	"OsConfig",
+	"DEFAULT_CONFIG_FILE_LOCATION",
+	"missing_configuration_diagnostic",
 	"Icons",
 	"JsonPitError",
 	"PitNotFoundError",

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

@@ -19,12 +19,12 @@ 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
+from .config import OsConfig, loads_json5, missing_configuration_diagnostic
+from .exceptions import JsonPitError, PitNotFoundError, ProtectedAttributeError
 from .fs import resolve_pit_target
 from .item import PitItem
 from .icons import Icons
-from .store import Pit
+from .store import Pit, parse_and_validate_seed_payload
 from . import __version__
 
 
@@ -70,21 +70,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 +115,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 +126,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 []
@@ -380,47 +394,37 @@ 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.
 	"""
+	source_path_str = getattr(args, "source", None)
+	if not source_path_str and getattr(args, "source_opt", None):
+		source_path_str = args.source_opt
+	if not source_path_str:
+		source_path_str = "-"
+
 	# Read source content
 	content = ""
-	if args.source and args.source != "-":
-		path = Path(args.source)
+	if source_path_str != "-":
+		path = Path(source_path_str)
 		if not path.is_file():
 			sys.stderr.write(f"[jpit] Source file not found: {path}\n")
 			return 1
 		content = path.read_text(encoding="utf-8")
+		source_name = str(path)
 	else:
 		content = sys.stdin.read()
+		source_name = "<stdin>"
 
-	if not content.strip():
-		sys.stderr.write("[jpit] Error: No input data provided.\n")
+	# CR043 Pre-flight validation strictly before opening target Pit or creating directories
+	try:
+		items_to_add = parse_and_validate_seed_payload(content, source_name)
+	except (ValueError, ProtectedAttributeError) as ex:
+		sys.stderr.write(f"[jpit] Error: {ex}\n")
 		return 1
 
-	data = loads_json5(content)
-	items_to_add: list[dict[str, Any]] = []
-	if isinstance(data, list):
-		items_to_add = [row for row in data if isinstance(row, dict)]
-	elif isinstance(data, dict):
-		if "Id" in data or "id" in data:
-			items_to_add = [data]
-		else:
-			for k, v in data.items():
-				if isinstance(v, dict):
-					v["Id"] = k
-					items_to_add.append(v)
-
 	if not items_to_add:
-		sys.stderr.write("[jpit] Error: Input data contains no valid entity objects.\n")
-		return 1
-
-	for raw_obj in items_to_add:
-		forbidden = [k for k in raw_obj if k.lower() in ("modified", "deleted")]
-		if forbidden:
-			sys.stderr.write(
-				f"[jpit] Error: Cannot manually update protected attribute '{forbidden[0]}'. "
-				"Use 'jpit del' to delete an entity.\n"
-			)
-			return 1
+		print(f"[jpit] Seed source '{source_name}' contained 0 entities.")
+		return 0
 
 	with Pit.open(
 		args.pit,
@@ -430,10 +434,7 @@ def cmd_put(args: argparse.Namespace) -> int:
 	) as pit:
 		count = 0
 		for raw_obj in items_to_add:
-			item_id = raw_obj.get("Id") or raw_obj.get("id") or raw_obj.get("Name")
-			if not item_id:
-				continue
-			item = PitItem(raw_obj, id=str(item_id))
+			item = PitItem(raw_obj)
 			pit.add(item)
 			count += 1
 
@@ -712,7 +713,7 @@ def print_top_help(
 		("get", "<PitName> <ItemId> [--at <ts>] [--jq <expr>] [--with-deleted]"),
 		("history", "<PitName> <ItemId> [--jq <expr>]"),
 		("list", "[<PitName>] [--json] [--jq <expr>] (lists pits if <PitName> omitted)"),
-		("put", "<PitName> [<source>]"),
+		("put", "<PitName> [<source>] [-s <source>] (alias: seed)"),
 		("set", "<PitName> <ItemId> <payload>"),
 		("del", "<PitName> <ItemId> [--by <author>]"),
 		("del-prop", "<PitName> <ItemId> <PropertyPath>"),
@@ -748,7 +749,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):
@@ -774,6 +778,7 @@ def print_command_help(cmd: str, nologo: bool = False, use_color: bool = True) -
 		"delete": "del",
 		"delete-item": "del",
 		"delete-property": "del-prop",
+		"seed": "put",
 	}
 	canonical_cmd = alias_map.get(cmd, cmd)
 
@@ -839,13 +844,16 @@ def print_command_help(cmd: str, nologo: bool = False, use_color: bool = True) -
 			],
 		},
 		"put": {
-			"usage": "jpit put <PitName> [<source>] [options]",
-			"desc": "Ingest JSON5 entities from file or stdin pipe.",
+			"usage": "jpit put <PitName> [<source>] [-s <source>] [options]",
+			"desc": "Ingest JSON5 entities from file or stdin pipe (alias: seed).",
 			"args": [
 				("PitName", "Pit name or file path"),
 				("source", "Source file or '-' for stdin (default: '-')"),
 			],
-			"opts": [],
+			"opts": [
+				("-s, --source <file>", "Source file for import (JSON or JSON5)"),
+			],
+			"aliases": ["seed"],
 		},
 		"set": {
 			"usage": "jpit set <PitName> <ItemId> <payload> [options]",
@@ -1083,10 +1091,16 @@ def build_parser() -> JsonPitArgumentParser:
 	p_pits = subparsers.add_parser("pits", parents=[common_parser], help="Discover available pits under a tenant root (-r is required)")
 	p_pits.add_argument("--json", action="store_true", help="Output JSON array of pit names")
 
-	# put
-	p_put = subparsers.add_parser("put", parents=[common_parser], help="Ingest JSON5 entities from file or stdin pipe")
+	# put / seed
+	p_put = subparsers.add_parser(
+		"put",
+		aliases=["seed"],
+		parents=[common_parser],
+		help="Ingest JSON5 entities from file or stdin pipe (alias: seed)",
+	)
 	p_put.add_argument("pit", help="Pit name")
-	p_put.add_argument("source", nargs="?", default="-", help="Source file or '-' for stdin")
+	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)")
 
 	# set
 	p_set = subparsers.add_parser("set", parents=[common_parser], help="Set or patch entity with JSON5 payload")
@@ -1146,7 +1160,7 @@ def main(argv: list[str] | None = None) -> int:
 	cloud, root = extract_cloud_and_root(argv)
 
 	known_subcommands = {
-		"grep", "get", "history", "list", "put", "set", "del",
+		"grep", "get", "history", "list", "put", "seed", "set", "del",
 		"delete", "delete-item", "del-prop", "delete-property",
 		"rename", "export", "status", "pits",
 	}
@@ -1184,6 +1198,7 @@ def main(argv: list[str] | None = None) -> int:
 		"list": cmd_list,
 		"pits": cmd_pits,
 		"put": cmd_put,
+		"seed": cmd_put,
 		"set": cmd_set,
 		"del": cmd_delete,
 		"delete": cmd_delete,

{jsonpit-4.4.2 → jsonpit-4.4.4}/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.2 → jsonpit-4.4.4}/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.2 → jsonpit-4.4.4}/jsonpit/item.py

@@ -245,6 +245,21 @@ class PitItem(MutableMapping[str, Any]):
 
 		return self.extend_with(patch_dict)
 
+	@staticmethod
+	def validate_client_payload(payload: dict[str, Any]) -> None:
+		"""
+		Validates a client entity payload before live ingestion.
+		CR040: Lifecycle attributes (Modified, Deleted) are reserved for historical replay.
+		"""
+		if not isinstance(payload, dict):
+			raise ValueError("Client payload must evaluate to a dictionary.")
+		for k in payload:
+			if k.lower() in ("modified", "deleted"):
+				raise ProtectedAttributeError(
+					f"Cannot manually update protected attribute '{k}'. "
+					"Use 'jpit del' to delete an entity."
+				)
+
 	def delete_property(self, property_name: str) -> None:
 		"""
 		Appends a property tombstone by setting the top-level property to None (JSON null).

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

@@ -28,6 +28,7 @@ from .exceptions import (
 	PitCorruptError,
 	PitInstanceConflictError,
 	PitNotFoundError,
+	ProtectedAttributeError,
 )
 from .flags import (
 	MasterFlagFile,
@@ -49,6 +50,71 @@ from .history import PitItems
 from .item import PitItem
 
 
+def has_non_empty_string_id(item: Any) -> bool:
+	"""
+	CR043: Checks if an item is a dictionary with an exact non-empty string 'Id'.
+	Lowercase 'id' or non-string/whitespace values are not accepted.
+	"""
+	if not isinstance(item, dict):
+		return False
+	val = item.get("Id")
+	return isinstance(val, str) and bool(val.strip())
+
+
+def parse_and_validate_seed_payload(
+	payload: str | bytes | Any,
+	source_name: str = "source",
+) -> list[dict[str, Any]]:
+	"""
+	CR043: Parses and validates a seed payload strictly BEFORE opening target Pit.
+	Three accepted shapes:
+	  1. Single Entity Object with an exact, non-empty string 'Id'
+	  2. Keyed Entity Map where all values are entity dictionaries
+	  3. Entity Array of dictionaries
+	Every individual entity must have an exact, non-empty string 'Id' and pass client payload validation.
+	"""
+	if isinstance(payload, (str, bytes)):
+		text = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+		if not text.strip():
+			raise ValueError(f"Source '{source_name}' is empty.")
+		try:
+			root = loads_json5(text)
+		except Exception as ex:
+			raise ValueError(f"Source '{source_name}' contains invalid JSON: {ex}") from ex
+	else:
+		root = payload
+
+	shape_diagnostic = (
+		f"Source '{source_name}' must be a JSON array of entities, a single entity object "
+		f"with a non-empty 'Id', or a keyed map of entity objects."
+	)
+
+	items: list[Any]
+	if isinstance(root, list):
+		items = root
+	elif isinstance(root, dict) and has_non_empty_string_id(root):
+		items = [root]
+	elif isinstance(root, dict) and all(isinstance(v, dict) for v in root.values()):
+		items = list(root.values())
+	else:
+		raise ValueError(shape_diagnostic)
+
+	validated: list[dict[str, Any]] = []
+	for item in items:
+		if not isinstance(item, dict):
+			raise ValueError(
+				f"{shape_diagnostic} Arrays and keyed maps may contain only JSON objects."
+			)
+		if not has_non_empty_string_id(item):
+			raise ValueError(
+				f"Source '{source_name}' contains an entity without a non-empty string 'Id'."
+			)
+		PitItem.validate_client_payload(item)
+		validated.append(item)
+
+	return validated
+
+
 class JsonPitBase:
 	"""
 	Common base for pit storage with leasing, identity, and persistence coordination.
@@ -355,35 +421,20 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 		"""
 		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.
 		"""
 		path = Path(file_path)
 		if not path.is_file():
 			raise PitNotFoundError(f"Seed file not found: {path}")
 
 		text = path.read_text(encoding="utf-8")
-		# Human seeder files may use JSON5 syntax (comments, unquoted keys, trailing commas)
-		data = loads_json5(text)
+		items_to_add = parse_and_validate_seed_payload(text, str(path))
 
 		count = 0
-		if isinstance(data, list):
-			for row in data:
-				if isinstance(row, dict):
-					item = PitItem(row)
-					self.add(item)
-					count += 1
-		elif isinstance(data, dict):
-			# Object mapping ID -> entity or single entity
-			if "Id" in data or "id" in data:
-				self.add(PitItem(data))
-				count = 1
-			else:
-				for k, v in data.items():
-					if isinstance(v, dict):
-						row = copy.deepcopy(v)
-						if "Id" not in row and "id" not in row:
-							row["Id"] = k
-						self.add(PitItem(row))
-						count += 1
+		for raw_obj in items_to_add:
+			item = PitItem(raw_obj)
+			self.add(item)
+			count += 1
 		return count
 
 	# --- Entity Addition & Mutation ---
@@ -681,3 +732,7 @@ class Pit(JsonPitBase, MutableMapping[str, PitItem]):
 
 	def __repr__(self) -> str:
 		return f"<Pit '{self.pit_name}' path={self.pit_dir} items={len(self)}>"
+
+
+Pit.parse_and_validate_seed_payload = staticmethod(parse_and_validate_seed_payload)  # type: ignore[attr-defined]
+PitStore = Pit

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

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