jsonpit 4.4.2__tar.gz → 4.4.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.2
+Version: 4.4.3
 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,9 +31,9 @@ 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.3`)
 
-`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.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` 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.

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

@@ -9,9 +9,9 @@ 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.3`)
 
-`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.3`** in direct lockstep with C# `JsonPit` and `pits 4.4.3` 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.

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

@@ -16,16 +16,18 @@ from .fs import OsConfig
 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.3"
 
 __all__ = [
 	"Pit",
+	"PitStore",
+	"parse_and_validate_seed_payload",
 	"PitItem",
 	"PitItems",
 	"OsConfig",

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

@@ -20,11 +20,11 @@ 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 .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__
 
 
@@ -380,47 +380,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 +420,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 +699,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>"),
@@ -774,6 +761,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 +827,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 +1074,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 +1143,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 +1181,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.3}/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.3}/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.3}/pyproject.toml

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