jsonpit 4.4.4__tar.gz → 4.4.6__tar.gz

jsonpit-4.4.6/API.md

@@ -0,0 +1,200 @@
+# jsonpit API Reference (v4.4.6)
+
+This document provides a foldable, searchable reference for the public `jsonpit` Python API. Designed for 100% C# JsonPit parity, zero third-party runtime dependencies, and Smalltalk-grade object-oriented architecture.
+
+---
+
+## Pit Lifecycle & Storage
+
+- <details>
+  <summary><code>Pit</code>: Live eventually consistent distributed JSON store</summary>
+
+  Coordinates one live public instance per canonical pit path, implements `MutableMapping[str, PitItem]` and the `ContextManager` protocol, observes cloud-drive changes, emits sparse delta change files, and coordinates master leases.
+
+  **Key Methods:**
+  - `__enter__()` / `__exit__()`: Context manager for atomic batch sessions and guaranteed flag cleanup.
+  - `add(item: PitItem, refresh_modified: bool = True) -> bool`: Adds or updates a living entity. Validates against prohibited template markers (`{` or `<`) under CR049.
+  - `add_historical(item: PitItem) -> bool`: Replays an immutable historical fragment without modifying timestamps or rejecting legacy IDs.
+  - `get(item_id: str, default: Any = None, at: datetime = None, with_deleted: bool = False) -> PitItem | None`: Retrieves the projected living state of an entity, with optional time-travel projection.
+  - `delete_item(item_id: str, by: str | None = None, backdate_100: bool = False) -> bool`: Tombstones an entity across the distributed cluster.
+  - `rename_id(old_key: str, new_key: str, by: str | None = None) -> bool`: Atomically migrates an entity identity.
+  - `seed_from_file(file_path: Path | str, require_existing: bool = False) -> int`: Ingests an external JSON/JSON5 file (single entity, keyed map, or array) with whole-batch ID preflight and optional CR047 strict patch enforcement.
+  - `maintain(options: PitMaintenanceOptions = None, apply: bool = False) -> PitMaintenanceResult`: Reconciles change files, manages 10-minute receipt grace periods, prunes expired process flags (`--older-than`), and repairs legacy event extensions.
+  - `save(force: bool = False, pretty: bool = False) -> None`: Persists the unified canonical `.pit` file in-place using CR022 sibling writes (`.pit.tmp` followed by atomic rename).
+  </details>
+
+- <details>
+  <summary><code>Pit.maintain(...)</code>, <code>PitMaintenanceOptions</code>, and <code>PitMaintenanceResult</code></summary>
+
+  `maintain()` inventories pending change/receipt cleanup without mutation. It checks the canonical parent first, returning deferred status for missing targets without creating directories. `maintain(apply=True)` applies canonical reconciliation and eligible change-first/receipt-second retirement (10-minute grace period).
+  
+  **Maintenance Options:**
+  - `apply: bool`: Authorizes modifications to disk (default False: report-only preview).
+  - `prune_process_flags: bool`: Authorizes pruning of expired PID-window flag files. Requires `apply=True` and `older_than`.
+  - `older_than: timedelta`: Duration threshold for flag pruning (e.g. `01:00:00`, `7.00:00:00`).
+  - `repair_legacy_extensions: bool`: Migrates legacy `{stem}_{sha256}.event` files to clean `{stem}.event` in `Events/`.
+  - `archive_events: bool`: Compacts event logs into immutable archives.
+
+  **Maintenance Result (`to_dict()` for 100% C# parity):**
+  - Exposes `PitFile`, `Applied`, `Succeeded`, `ChangeFilesObserved/Merged/Removed`, `ReceiptsCreated/Removed`, `ProcessFlagsActive/Expired/Pruned`, `LegacyArtifactsObserved/Repaired`, `Deferred`, and `Failures`.
+  </details>
+
+- <details>
+  <summary><code>JsonPitBase</code>: Shared storage and path foundation</summary>
+
+  Base class providing pit path resolution, cloud drive detection, subscriber identity, process leasing options (`read_only`, `unflagged`, `retain_window`), and canonical serialization.
+  </details>
+
+- <details>
+  <summary><code>PitStore</code>: Thread-safe repository of open Pit instances</summary>
+
+  Factory and cache ensuring only one active `Pit` instance exists per canonical file path within a single process, preventing memory divergence.
+  </details>
+
+---
+
+## Entity Domain Model & History
+
+- <details>
+  <summary><code>PitItem</code>: Polymorphic living entity and sparse delta emitter</summary>
+
+  Represents an individual entity within a Pit. Implements dictionary-like attribute access while protecting immutable engine attributes (`id`, `modified`, `deleted`) from accidental mutation (CR040). When bound to a `Pit`, mutations automatically stream sparse delta change files without triggering read-modify-write anti-patterns.
+
+  **Core Attributes:**
+  - `id`: Non-empty string identifier. Rejects unresolved template markers (`{` or `<`) at write boundaries (CR049).
+  - `modified`: 7-digit UTC timestamp (`datetime`) of the latest fragment.
+  - `deleted`: Boolean tombstone flag.
+  - `note`: Optional human- or agent-readable string note.
+
+  **Sparse Mutation Methods:**
+  - `set_property(patch: dict[str, Any] | str) -> bool`: Atomically applies a property delta and emits a sparse change file.
+  - `delete_property(property_name: str) -> None`: Emits a property-level null tombstone without rewriting living state.
+  - `delete_property_path(property_path: str) -> None`: Traverses dot-delimited paths to tombstone nested properties.
+  - `extend_with(obj: dict[str, Any]) -> bool`: Merges attributes from a dictionary.
+  - `to_dict() -> dict[str, Any]` / `to_json() -> str`: Canonical JSON serialization.
+  </details>
+
+- <details>
+  <summary><code>PitItems</code>: Immutable fragment stack and time-travel projector</summary>
+
+  Maintains an entity's ordered history of timestamped fragments.
+
+  **Key Methods:**
+  - `push(item: PitItem) -> PitItems`: Returns a new `PitItems` stack with the fragment prepended.
+  - `latest_fragment() -> PitItem | None`: Returns the most recently written fragment.
+  - `project_state(at: datetime = None, with_deleted: bool = False) -> PitItem | None`: Merges historical fragments from oldest to newest up to timestamp `at` to compute accurate point-in-time living state.
+  </details>
+
+---
+
+## Distributed Protocol & Cloud Safety
+
+- <details>
+  <summary><code>ChangeFile</code>: Shortened cloud-safe change artifact</summary>
+
+  Writes sparse delta mutations into `Changes/` using the 4-character hex checksum format:
+  `{UtcTicks}_{ExactProcessIdentity}_{4charHex}.json`
+  Guards against partially synchronized cloud writes (e.g. OneDrive) without exceeding path length limits. Validates checksums on read and maintains backwards compatibility with legacy 64-character SHA-suffixed change files.
+  </details>
+
+- <details>
+  <summary><code>ReceiptFile</code>: Durable round-trip confirmation</summary>
+
+  Pairs with change files using the `.receipt` extension. Enforces a 10-minute grace period before allowing retired change files to be compacted or purged.
+  </details>
+
+- <details>
+  <summary><code>MasterFlagFile</code> & <code>ProcessFlagFile</code>: Cloud drive lease coordination</summary>
+
+  - `Master.flag`: 60-second lease renewed every 30 seconds by the active master writer.
+  - `{Machine}-{Process}-{PID}.flag`: Ephemeral process activity flag with heartbeat updates. Enforces deterministic self-cleanup on process exit (CR024).
+  </details>
+
+- <details>
+  <summary><code>EventFile</code>: Clean event compaction naming & migration</summary>
+
+  Emits compacted historical events under clean logical stems (`{LogicalStem}.event`) without SHA-256 hash suffixes. Automatically recognizes legacy 64-char hash filenames and supports in-place migration.
+  </details>
+
+---
+
+## Configuration & Cloud Discovery
+
+- <details>
+  <summary><code>OsConfig</code>: Cross-platform cloud drive discovery</summary>
+
+  Discovers synchronization folders for `Dropbox`, `OneDrive`, `GoogleDrive`, and `ICloudDrive`. Reads primarily from `~/.config/RAIkeep.json5` with fallback to `~/.config/jsonpit.json5` or `$JSONPIT_CONFIG`.
+  </details>
+
+- <details>
+  <summary><code>missing_configuration_diagnostic()</code>: CR044 operator guidance</summary>
+
+  When cloud drives or configuration files are absent, formats clear actionable instructions directing the operator to run `amafu init` to bootstrap configuration.
+  </details>
+
+---
+
+## Audit Engine & Recovery Inspection
+
+- <details>
+  <summary><code>PitAudit</code>: Read-only inspection of durable event logs</summary>
+
+  Provides read-only access to durable JsonPit recovery events under `Events/` without opening a `Pit`, creating process activity flags, acquiring leases, or mutating disk state (CR003, coordinated v3.13.2). Inspects both loose `*.event` files and immutable `Events_*.zip` compaction archives.
+
+  **Key Methods:**
+  - `PitAudit.inspect(pit_directory: Path | str, machine_filter: str = "all", min_level: LogLevel = LogLevel.TRACE) -> PitAuditReadResult`: Reads, validates, deduplicates by `EventId`, filters by machine/severity, and orders events deterministically by machine, UTC time, and event identity.
+  </details>
+
+- <details>
+  <summary><code>PitAuditEvent</code>: Durable recovery event domain model</summary>
+
+  Encapsulates a single durable recovery event:
+  - `file_name: str`: Source file or archive entry name.
+  - `content: dict[str, Any]`: Raw deserialized event JSON object.
+  - `machine: str`: Originating machine hostname.
+  - `utc_time: datetime`: Event occurrence timestamp in UTC.
+  - `level: LogLevel`: Severity level.
+  - `stage: str`: Pit lifecycle stage (e.g. `ChangeFilesPublished`, `CleanupPending`, `Completed`).
+  - `event_id: str`: Unique GUID event identifier used for cross-archive deduplication.
+  - `message: str`: Human-readable summary message.
+  </details>
+
+- <details>
+  <summary><code>LogLevel</code>: Event severity enumeration</summary>
+
+  Matches .NET `LogLevel` integer values and names:
+  - `TRACE = 0` (`Trace`)
+  - `DEBUG = 1` (`Debug`)
+  - `INFORMATION = 2` (`Information` / `info`)
+  - `WARNING = 3` (`Warning` / `warn`)
+  - `ERROR = 4` (`Error` / `err`)
+  - `CRITICAL = 5` (`Critical` / `fatal`)
+  - `from_string(name: str) -> LogLevel`: Case-insensitive parsing supporting names, aliases, and integer strings.
+  - `display_name -> str`: Capitalized canonical name matching C# output formatting.
+  </details>
+
+- <details>
+  <summary><code>PitAuditReadResult</code>: Filtered events and diagnostic issues</summary>
+
+  Contains:
+  - `events: list[PitAuditEvent]`: Filtered and ordinally sorted events.
+  - `issues: list[str]`: Physical corruption, empty file, or conflicting event identity warnings.
+  - `succeeded: bool`: Returns `True` if no diagnostic issues were discovered.
+  </details>
+
+---
+
+## Exception Hierarchy
+
+All `jsonpit` exceptions derive from `JsonPitError`:
+
+```text
+JsonPitError
+├── PitNotFoundError               # Target pit directory or file does not exist
+├── PitCorruptError                # Payload failed checksum or schema validation
+├── PitConcurrencyError            # Conflict acquiring or renewing master lease
+├── PitInstanceConflictError       # Multiple live Pit instances for the same file path
+├── ProtectedAttributeError        # Client attempted to mutate 'id', 'modified', or 'deleted' (CR040)
+├── TombstoneError                 # Attempted to delete protected engine attributes
+└── StrictPatchValidationError     # Missing or tombstoned entity under --require-existing (CR047)
+```

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: jsonpit
-Version: 4.4.4
+Version: 4.4.6
 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.6`)
 
-`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.6`** in direct lockstep with C# `JsonPit` and `pits 4.4.6` 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, CR047 strict patch validation, and [CR049](doc/CR/CR049_AIA_and_jsonpit_to_RAIkeep_Live-ID-Validation_and_Zip-Image-Import.md) live ID validation with 4-character change checksums—are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -54,6 +54,23 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Object-Oriented Architecture
+
+`jsonpit` models distributed state through rich, encapsulated domain classes implementing standard Python protocols (`MutableMapping`, `ContextManager`):
+
+- **`Pit`**: Living collection and coordinator of distributed leases, change files, and storage compaction.
+- **`PitItem`**: Polymorphic living entity. Emits pure sparse deltas without read-modify-write cycles (CR040).
+- **`PitItems`**: Immutable fragment stack managing value history and accurate point-in-time state projection.
+- **`JsonPitBase`**: Shared foundation for storage resolution, subscriber roles, and cloud synchronization.
+
+<p align="center">
+  <img src="doc/uml/jsonpitCD.svg" alt="jsonpit Class Diagram" width="720"/>
+</p>
+
+> 📖 **Full API Reference:** For comprehensive method signatures, exception contracts, and protocol details, see **[API.md](API.md)**.
+
+---
+
 ## Installation & Upgrade
 
 ### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
@@ -65,7 +82,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.6)
 pipx upgrade jsonpit
 # (or)
 pipx upgrade jpit
@@ -180,6 +197,16 @@ echo '{id: "AlanKay", dynabook: true}' | jpit put Person
 # Set individual properties or tombstone an entity:
 jpit set Person AlanKay Status "Visionary"
 jpit del Person ObsoleteEntity
+
+# Automated maintenance and dead flag pruning (100% C# pits maintain parity):
+jpit maintain Activity -c OneDrive -r AIA
+jpit maintain Activity -c OneDrive -r AIA --apply --prune-process-flags --older-than 01:00:00 --json
+jpit maintain --wwwa -c OneDrive -r AIA --apply --prune-process-flags --older-than 7.00:00:00
+
+# Read-only audit of durable recovery events (100% C# pits audit parity):
+jpit audit Activity -c OneDrive -r AIA
+jpit audit Activity -c OneDrive -r AIA --machine local --level Warning
+jpit audit --wwwa -c OneDrive -r AIA --json
 ```
 
 ---

{jsonpit-4.4.4 → jsonpit-4.4.6}/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.6`)
 
-`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.6`** in direct lockstep with C# `JsonPit` and `pits 4.4.6` 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, CR047 strict patch validation, and [CR049](doc/CR/CR049_AIA_and_jsonpit_to_RAIkeep_Live-ID-Validation_and_Zip-Image-Import.md) live ID validation with 4-character change checksums—are certified across both languages under the exact same version milestone before release.
 
 ---
 
@@ -32,6 +32,23 @@ The canonical **reference (lead) implementation** is C# `JsonPit` and the `pits`
 
 ---
 
+## Object-Oriented Architecture
+
+`jsonpit` models distributed state through rich, encapsulated domain classes implementing standard Python protocols (`MutableMapping`, `ContextManager`):
+
+- **`Pit`**: Living collection and coordinator of distributed leases, change files, and storage compaction.
+- **`PitItem`**: Polymorphic living entity. Emits pure sparse deltas without read-modify-write cycles (CR040).
+- **`PitItems`**: Immutable fragment stack managing value history and accurate point-in-time state projection.
+- **`JsonPitBase`**: Shared foundation for storage resolution, subscriber roles, and cloud synchronization.
+
+<p align="center">
+  <img src="doc/uml/jsonpitCD.svg" alt="jsonpit Class Diagram" width="720"/>
+</p>
+
+> 📖 **Full API Reference:** For comprehensive method signatures, exception contracts, and protocol details, see **[API.md](API.md)**.
+
+---
+
 ## Installation & Upgrade
 
 ### As a Global CLI Tool (`jpit`) via `pipx` (Recommended)
@@ -43,7 +60,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.6)
 pipx upgrade jsonpit
 # (or)
 pipx upgrade jpit
@@ -158,6 +175,16 @@ echo '{id: "AlanKay", dynabook: true}' | jpit put Person
 # Set individual properties or tombstone an entity:
 jpit set Person AlanKay Status "Visionary"
 jpit del Person ObsoleteEntity
+
+# Automated maintenance and dead flag pruning (100% C# pits maintain parity):
+jpit maintain Activity -c OneDrive -r AIA
+jpit maintain Activity -c OneDrive -r AIA --apply --prune-process-flags --older-than 01:00:00 --json
+jpit maintain --wwwa -c OneDrive -r AIA --apply --prune-process-flags --older-than 7.00:00:00
+
+# Read-only audit of durable recovery events (100% C# pits audit parity):
+jpit audit Activity -c OneDrive -r AIA
+jpit audit Activity -c OneDrive -r AIA --machine local --level Warning
+jpit audit --wwwa -c OneDrive -r AIA --json
 ```
 
 ---

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

@@ -10,26 +10,41 @@ from .exceptions import (
 	PitInstanceConflictError,
 	PitNotFoundError,
 	ProtectedAttributeError,
+	StrictPatchValidationError,
 	TombstoneError,
 )
+from .audit import (
+	LogLevel,
+	PitAudit,
+	PitAuditEvent,
+	PitAuditReadResult,
+)
 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
+from .store import (
+	Pit,
+	PitMaintenanceOptions,
+	PitMaintenanceResult,
+	PitStore,
+	parse_and_validate_seed_payload,
+)
 
-try:
-	import importlib.metadata
-	__version__ = importlib.metadata.version("jsonpit")
-except Exception:
-	__version__ = "4.4.4"
+__version__ = "4.4.6"
 
 __all__ = [
 	"Pit",
 	"PitStore",
+	"PitMaintenanceOptions",
+	"PitMaintenanceResult",
 	"parse_and_validate_seed_payload",
 	"PitItem",
 	"PitItems",
+	"LogLevel",
+	"PitAuditEvent",
+	"PitAuditReadResult",
+	"PitAudit",
 	"OsConfig",
 	"DEFAULT_CONFIG_FILE_LOCATION",
 	"missing_configuration_diagnostic",
@@ -40,5 +55,6 @@ __all__ = [
 	"PitConcurrencyError",
 	"PitInstanceConflictError",
 	"ProtectedAttributeError",
+	"StrictPatchValidationError",
 	"TombstoneError",
 ]

jsonpit-4.4.6/jsonpit/audit.py

@@ -0,0 +1,209 @@
+"""
+Read-only audit access to durable JsonPit recovery events (CR003, coordinated v3.13.2).
+Inspects immutable event logs and compact archives without opening a Pit,
+creating process activity windows, or mutating storage.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import datetime
+from enum import IntEnum
+import json
+from pathlib import Path
+from typing import Any
+import zipfile
+
+from .canonical import format_iso_timestamp, parse_iso_timestamp, utc_ticks_to_datetime
+from .flags import get_machine_name
+from .fs import safe_read_text
+
+
+class LogLevel(IntEnum):
+	"""Standard severity levels for Pit audit events matching .NET LogLevel."""
+	TRACE = 0
+	DEBUG = 1
+	INFORMATION = 2
+	WARNING = 3
+	ERROR = 4
+	CRITICAL = 5
+
+	@classmethod
+	def from_string(cls, name: str) -> LogLevel:
+		norm = name.strip().lower()
+		if norm in ("trace", "0"):
+			return cls.TRACE
+		if norm in ("debug", "1"):
+			return cls.DEBUG
+		if norm in ("information", "info", "2"):
+			return cls.INFORMATION
+		if norm in ("warning", "warn", "3"):
+			return cls.WARNING
+		if norm in ("error", "err", "4"):
+			return cls.ERROR
+		if norm in ("critical", "crit", "fatal", "5"):
+			return cls.CRITICAL
+		raise ValueError(
+			f"Unknown log level '{name}'. Valid levels: Trace, Debug, Information, Warning, Error, Critical."
+		)
+
+	@property
+	def display_name(self) -> str:
+		if self == LogLevel.INFORMATION:
+			return "Information"
+		return self.name.capitalize()
+
+
+@dataclass
+class PitAuditEvent:
+	"""One durable JsonPit audit event as read back from a pit's Events directory."""
+	file_name: str
+	content: dict[str, Any]
+	machine: str
+	utc_time: datetime.datetime
+	level: LogLevel
+	stage: str
+	event_id: str
+	message: str
+
+	@classmethod
+	def from_dict(cls, file_name: str, content: dict[str, Any]) -> PitAuditEvent:
+		machine = str(content.get("Machine") or "")
+
+		# Parse timestamp from UtcTicks or UtcTime
+		ticks = content.get("UtcTicks")
+		if ticks is not None and isinstance(ticks, (int, float)):
+			utc_time = utc_ticks_to_datetime(int(ticks))
+		elif content.get("UtcTime"):
+			try:
+				utc_time = parse_iso_timestamp(str(content["UtcTime"]))
+			except Exception:
+				utc_time = datetime.datetime.min.replace(tzinfo=datetime.timezone.utc)
+		else:
+			utc_time = datetime.datetime.min.replace(tzinfo=datetime.timezone.utc)
+
+		lvl_raw = str(content.get("Level") or "Trace")
+		try:
+			level = LogLevel.from_string(lvl_raw)
+		except ValueError:
+			level = LogLevel.TRACE
+
+		stage = str(content.get("Stage") or "")
+		event_id = str(content.get("EventId") or "")
+		message = str(content.get("Message") or "")
+
+		return cls(
+			file_name=file_name,
+			content=content,
+			machine=machine,
+			utc_time=utc_time,
+			level=level,
+			stage=stage,
+			event_id=event_id,
+			message=message,
+		)
+
+
+@dataclass
+class PitAuditReadResult:
+	"""Read result containing filtered events and physical diagnostic issues."""
+	events: list[PitAuditEvent] = field(default_factory=list)
+	issues: list[str] = field(default_factory=list)
+
+	@property
+	def succeeded(self) -> bool:
+		return len(self.issues) == 0
+
+
+class PitAudit:
+	"""Read-only audit inspector for durable JsonPit event logs (Events/)."""
+
+	@staticmethod
+	def inspect(
+		pit_directory: Path | str,
+		machine_filter: str = "all",
+		min_level: LogLevel = LogLevel.TRACE,
+	) -> PitAuditReadResult:
+		p_dir = Path(pit_directory)
+		events_dir = p_dir / "Events"
+		issues: list[str] = []
+
+		if not events_dir.is_dir():
+			return PitAuditReadResult(events=[], issues=[])
+
+		raw_events: dict[str, dict[str, Any]] = {}
+
+		# 1. Inspect loose event files (*.event)
+		for ef in sorted(events_dir.glob("*.event"), key=lambda p: p.name):
+			try:
+				text = safe_read_text(ef)
+				if not text or not text.strip():
+					issues.append(f"Empty loose event '{ef.name}'")
+					continue
+				parsed = json.loads(text)
+				if not isinstance(parsed, dict):
+					issues.append(f"Invalid loose event '{ef.name}': content is not a JSON object")
+					continue
+				raw_events[ef.name] = parsed
+			except Exception as ex:
+				issues.append(f"Unreadable loose event '{ef.name}': {ex}")
+
+		# 2. Inspect immutable zip archives (Events_*.zip)
+		for zf_path in sorted(events_dir.glob("Events_*.zip"), key=lambda p: p.name):
+			try:
+				with zipfile.ZipFile(zf_path, "r") as zf:
+					for info in zf.infolist():
+						if info.filename.endswith(".event"):
+							try:
+								with zf.open(info) as z_entry:
+									text = z_entry.read().decode("utf-8")
+									parsed = json.loads(text)
+									if isinstance(parsed, dict):
+										if info.filename in raw_events:
+											if raw_events[info.filename] != parsed:
+												issues.append(
+													f"Conflicting event content for '{info.filename}' in '{zf_path.name}'."
+												)
+										else:
+											raw_events[info.filename] = parsed
+							except Exception as ex:
+								issues.append(f"Invalid event '{info.filename}' in '{zf_path.name}': {ex}")
+			except Exception as ex:
+				issues.append(f"Invalid event archive '{zf_path.name}': {ex}")
+
+		# 3. Deduplicate events by EventId
+		identities: dict[str, PitAuditEvent] = {}
+		distinct: list[PitAuditEvent] = []
+		for file_name in sorted(raw_events.keys()):
+			content = raw_events[file_name]
+			ev = PitAuditEvent.from_dict(file_name, content)
+			if not ev.event_id:
+				distinct.append(ev)
+				continue
+
+			if ev.event_id not in identities:
+				identities[ev.event_id] = ev
+				distinct.append(ev)
+			else:
+				existing = identities[ev.event_id]
+				if existing.content != ev.content:
+					issues.append(
+						f"Conflicting event content for EventId '{ev.event_id}' in "
+						f"'{existing.file_name}' and '{ev.file_name}'."
+					)
+
+		# 4. Filter by machine
+		m_filt = (machine_filter or "all").strip().lower()
+		events = distinct
+		if m_filt != "all":
+			target_machine = get_machine_name().lower() if m_filt == "local" else m_filt
+			events = [e for e in events if e.machine.lower() == target_machine]
+
+		# 5. Filter by severity level
+		if min_level > LogLevel.TRACE:
+			events = [e for e in events if e.level >= min_level]
+
+		# 6. Order deterministically: Machine, UtcTime, EventId
+		events.sort(key=lambda e: (e.machine, e.utc_time, e.event_id))
+
+		return PitAuditReadResult(events=events, issues=issues)