aether-lang-runtime 0.1.0__py3-none-any.whl

aether_lang_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,457 @@
+Metadata-Version: 2.5
+Name: aether-lang-runtime
+Version: 0.1.0
+Summary: AI-Safe Execution Infrastructure: structured, sandboxed, reversible AI code modification
+License: MIT
+Keywords: agents,ai,execution,patch,safe,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.22
+Requires-Dist: libcst>=1.1.0
+Requires-Dist: pathspec>=0.12
+Requires-Dist: zstandard>=0.23; sys_platform != 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: wasm
+Requires-Dist: wasmtime>=23.0; extra == 'wasm'
+Description-Content-Type: text/markdown
+
+# AI-Safe Execution Infrastructure
+
+> **A structured, sandboxed, and reversible execution layer for AI-driven code modification.**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-94%20passed-brightgreen.svg)](#testing)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](#requirements)
+
+---
+
+## The Problem
+
+When AI agents generate code and apply it directly to a codebase, several fundamental failure modes emerge:
+
+| Failure | Impact |
+|:--------|:-------|
+| **Syntax errors** | File is broken, app crashes |
+| **Semantic errors** | Logic is wrong, tests fail silently |
+| **Uncontrolled execution** | Changes applied directly against live state |
+| **No rollback path** | Recovery requires manual `git reset` or worse |
+| **Ambiguous intent** | Agent emits free-form diffs, no structured contract |
+
+`aether-lang-runtime` reframes the problem: instead of agents generating raw source code, they emit **structured patch instructions** — a typed JSON contract — that the runtime validates, sandboxes, and commits or rolls back automatically.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        AI Agent                                  │
+│              (LLM, Copilot, AutoGPT, etc.)                       │
+└────────────────────────┬────────────────────────────────────────┘
+                         │  Structured Patch (JSON)
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Validation Layer                               │
+│                                                                  │
+│   Gate 1 ──── JSON Schema (Draft 2020-12)                        │
+│               • Action type enforcement                          │
+│               • UUID patch_id required                           │
+│               • Payload size ceiling (64 KB)                     │
+│               • Timeout bounds [100ms – 30s]                     │
+│                                                                  │
+│   Gate 2 ──── Allow-list & Security Rules                        │
+│               • (action, operation) allow-list                   │
+│               • No absolute paths / path traversal               │
+│               • No os.system / subprocess / eval in payload      │
+│               • run_script requires explicit trust elevation      │
+└────────────────────────┬────────────────────────────────────────┘
+                         │  Valid patch only
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Snapshot System                                │
+│                                                                  │
+│   • Captures project state → .tar.gz archive                    │
+│   • .gitignore + .ai_runtimeignore aware                        │
+│   • Always skips: node_modules / venv / __pycache__ / .git      │
+│   • SQLite WAL index (concurrent-reader safe)                    │
+│   • Cross-platform write lock (fcntl / msvcrt)                  │
+│   • Atomic rename: no partial archives ever on disk             │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                 Sandbox Execution                                │
+│                                                                  │
+│   Tier 1 ── Cranelift JIT  (zero-syscall, v1.2+)                │
+│   Tier 2 ── Wasmtime/WASM  (hardware boundary, v1.1+)           │
+│   Tier 3 ── Subprocess     (OS process isolation, v1.0 ✅)       │
+│             • Windows: Win32 Job Objects (memory limit)          │
+│             • Linux:   resource.setrlimit (RLIMIT_AS + CPU)      │
+│             • Timeout enforced via communicate(timeout=)         │
+│             • CREATE_NEW_PROCESS_GROUP (Windows signal safety)   │
+│             • setsid() + preexec_fn (Unix process group)         │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+              ┌──────────┴──────────┐
+              │                     │
+           Success               Failure
+              │                     │
+              ▼                     ▼
+        ┌──────────┐         ┌──────────────┐
+        │  Commit  │         │   Rollback   │
+        │ snapshot │         │ from archive │
+        └──────────┘         └──────────────┘
+```
+
+---
+
+## Project Layout
+
+```
+aether-lang/
+├── sdk/
+│   └── python/
+│       ├── ai_runtime/
+│       │   ├── __init__.py          # Public API: PatchEngine, Sandbox, etc.
+│       │   ├── _types.py            # Shared dataclasses (ExecutionResult, SnapshotHandle)
+│       │   ├── patch_engine.py      # PatchEngine — validate() + apply() orchestrator
+│       │   ├── sandbox.py           # Sandbox — tier-dispatching execution environment
+│       │   ├── sandbox_t3.py        # T3 subprocess backend (Windows + Unix)
+│       │   ├── sandbox_runner.py    # Worker script run inside child process
+│       │   ├── validation/
+│       │   │   ├── patch_schema.json  # JSON Schema Draft 2020-12 contract
+│       │   │   ├── schema.py          # Gate 1: schema validator
+│       │   │   └── rules.py           # Gate 2: allow-list + security rules
+│       │   └── snapshot/
+│       │       ├── __init__.py
+│       │       ├── store.py           # SnapshotStore — capture/restore/commit/prune
+│       │       ├── gitignore.py       # .gitignore-aware file collector
+│       │       └── lock.py            # Cross-platform advisory file lock
+│       └── tests/
+│           ├── test_validation.py     # Phase 1: 34 tests
+│           ├── test_sandbox.py        # Phase 2: 26 tests (cross-platform)
+│           ├── test_sandbox_t3_windows.py  # Phase 2: 3 tests (Windows-only)
+│           └── test_snapshot.py       # Phase 3: 31 tests
+├── architecture doc/
+│   └── AI-Safe-Execution-Infrastructure-Documentation.md
+└── crates/                           # Legacy Aether language compiler (Cranelift/Rust)
+```
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+pip install aether-lang-runtime
+```
+
+### Basic usage
+
+```python
+import uuid
+from ai_runtime import PatchEngine
+
+engine = PatchEngine()
+
+patch = {
+    "schema_version": "1.0",
+    "patch_id": str(uuid.uuid4()),       # must be valid UUID v4
+    "action": "modify_function",
+    "target": {
+        "file": "src/app.py",            # relative path only
+        "symbol": "calculate_total",
+        "symbol_type": "function",
+    },
+    "changes": {
+        "operation": "replace_body",
+        "payload": "    return sum(items)",
+    },
+}
+
+report = engine.validate(patch)
+if report.ok:
+    engine.apply(patch)
+    print(f"✅ Applied in {report.elapsed_ms:.1f}ms")
+else:
+    print(f"❌ Rejected: {report.first_error}")
+```
+
+### Agent CLI
+
+After installation, agents can use Aether without writing Python glue:
+
+```bash
+aether validate patch.json
+aether apply patch.json
+aether rollback <snapshot-id>
+```
+
+`aether apply` runs validation through `PatchOrchestrator`, captures a snapshot,
+applies the patch, and rolls back if application fails. `ae-safe` is kept as a
+backwards-compatible alias for the same CLI.
+
+### With snapshot + auto-rollback
+
+```python
+from ai_runtime import PatchEngine, Sandbox
+
+sandbox = Sandbox(project_root=".")
+engine  = PatchEngine(sandbox=sandbox)
+
+# Capture state before any change
+handle = sandbox.snapshot(patch_id=patch["patch_id"])
+
+report = engine.validate(patch)
+if report.ok:
+    result = engine.apply(patch)
+    if result and result.failed:
+        # Execution failed — restore immediately
+        sandbox.restore(handle)
+        print(f"⚠️  Rolled back: {result.error}")
+    else:
+        sandbox.commit_snapshot(handle)
+        print("✅ Committed")
+else:
+    print(f"❌ Rejected at gate {report.first_error}")
+```
+
+### Execute a sandboxed script
+
+```python
+from ai_runtime import Sandbox
+
+with Sandbox(project_root=".") as sb:
+    result = sb.execute(
+        payload="print('hello from sandbox')",
+        timeout_ms=5000,
+        memory_limit_mb=128,
+    )
+
+print(result.stdout)    # "hello from sandbox"
+print(result.tier)      # "t3_subprocess"
+print(result.succeeded) # True
+```
+
+---
+
+## Patch Schema
+
+Every patch must be a JSON object conforming to [patch_schema.json](ai_runtime/validation/patch_schema.json) (JSON Schema Draft 2020-12).
+
+### Required fields
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `schema_version` | `"1.0"` | Schema version — must be exactly `"1.0"` |
+| `patch_id` | UUID v4 string | Unique identifier for idempotency tracking |
+| `action` | enum | One of the 7 supported actions below |
+| `target.file` | string | **Relative** path to the target file |
+| `changes.operation` | string | Operation type (must be in allow-list for action) |
+| `changes.payload` | string | Code content, max 64 KB |
+
+### Supported actions
+
+| Action | Operations | Description |
+|:-------|:-----------|:------------|
+| `modify_function` | `replace_body`, `insert_before`, `insert_after`, `update_logic` | Modify an existing function |
+| `add_function` | `replace_body` | Insert a new function |
+| `remove_function` | `replace_body` | Delete a function |
+| `modify_class` | `replace_body`, `insert_before`, `insert_after` | Modify a class |
+| `update_import` | `add_import`, `remove_import` | Add or remove imports |
+| `replace_block` | `context_replace` | Context-based block replacement |
+| `run_script` | `run` | Execute a script (requires `trust_level='elevated'`) |
+
+### Optional fields
+
+```json
+{
+  "constraints": {
+    "timeout_ms":       5000,
+    "memory_limit_mb":  128,
+    "allow_network":    false,
+    "allow_filesystem": false
+  },
+  "metadata": {
+    "generated_by":  "my-agent-v1",
+    "model":         "gemini-2.0-flash",
+    "confidence":    0.95
+  }
+}
+```
+
+---
+
+## Security Model
+
+### Two-gate validation
+
+```
+Patch JSON
+    │
+    ▼
+Gate 1: JSON Schema ─── rejects malformed structure
+    │
+    ▼ (valid)
+Gate 2: Security Rules
+    ├── Operation allow-list ────── unknown (action, operation) pairs rejected
+    ├── Path safety ─────────────── absolute paths, ../ traversal blocked
+    ├── Payload patterns ────────── os.system / subprocess / eval blocked
+    └── Trust elevation ─────────── run_script requires explicit elevated trust
+    │
+    ▼ (valid)
+Execution
+```
+
+### What is NOT protected by this layer
+
+- **AI model hallucination**: The runtime validates structure and security, not semantic correctness. A syntactically valid patch can still produce wrong program behaviour.
+- **Supply chain attacks**: Malicious packages in the project's dependencies are not audited.
+- **Persistent rootkits**: A sufficiently clever payload could attempt to escape the T3 subprocess sandbox. T1 (Cranelift) and T2 (WASM) are the hardened tiers for untrusted code.
+
+---
+
+## Sandbox Tiers
+
+| Tier | Technology | Memory Limit | Syscall Restriction | Status |
+|:-----|:-----------|:-------------|:--------------------|:-------|
+| **T3** | OS subprocess | Win32 Job Objects / `RLIMIT_AS` | None (process boundary only) | ✅ v1.0 |
+| **T2** | Wasmtime/WASI | WASM linear memory | WASI capabilities | 🔜 v1.1 |
+| **T1** | Cranelift JIT | Custom memory allocator | Zero syscall surface | 🔜 v1.2 |
+
+Tier selection is automatic (`preferred_tier="auto"`). T3 is always available; T1/T2 are used when their respective runtimes are detected.
+
+---
+
+## Snapshot System
+
+### Storage layout
+
+```
+<project_root>/
+└── .ai_runtime/
+    ├── snapshot.lock        ← Advisory write lock (fcntl / msvcrt)
+    ├── snapshots.db         ← SQLite index (WAL mode)
+    └── snapshots/
+        ├── <uuid>.tar.gz    ← Compressed project archive
+        └── ...
+```
+
+### What gets snapshotted
+
+The file collector applies a layered exclusion strategy:
+
+```
+All files in project_root
+        │
+        ▼  Tier 1: O(1) frozenset fast-skip
+        │  (node_modules, .git, venv, __pycache__, dist, target, ...)
+        │
+        ▼  Tier 2: pathspec regex
+        │  (*.pyc, *.egg-info/, *.so, ...)
+        │
+        ▼  Tier 3: .gitignore patterns
+        │
+        ▼  Tier 4: .ai_runtimeignore patterns
+        │
+        ▼  Tier 5: Size ceiling (> 5 MB per file → skip)
+        │
+        ▼
+   Source files to archive
+```
+
+### Snapshot lifecycle
+
+```
+capture("patch-123")              status = 'pending'
+        │
+        ├── patch applied OK ──▶  commit(handle)   status = 'committed'
+        │
+        └── execution failed ──▶  restore(handle)  status = 'rolled_back'
+
+prune(keep=10)  ──▶  deletes oldest committed/rolled_back archives
+```
+
+### Concurrency
+
+Multiple agents can operate on the same project simultaneously:
+- `validate()` — fully parallel (read-only, no locking)
+- `capture()` / `restore()` — serialized via advisory write lock per project root
+- SQLite WAL mode — concurrent readers never block during write
+
+---
+
+## Performance SLOs
+
+| Operation | Target | Measured (this machine) |
+|:----------|:-------|:------------------------|
+| `validate()` | < 20 ms | **0.12 ms** |
+| `capture()` (< 50 MB project) | < 100 ms | passes ✅ |
+| `restore()` | < 500 ms | passes ✅ |
+| T3 sandbox overhead | < 500 ms | < 200 ms |
+| T3 timeout enforcement | within 2× budget | ✅ |
+
+---
+
+## Testing
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run full suite
+pytest tests/ -v
+
+# Phase-by-phase
+pytest tests/test_validation.py      # Phase 1 — 34 tests
+pytest tests/test_sandbox.py         # Phase 2 — 26 tests
+pytest tests/test_snapshot.py        # Phase 3 — 31 tests
+pytest tests/test_sandbox_t3_windows.py  # Windows-only — 3 tests
+```
+
+Current suite: **94 tests, 94 passed** (Python 3.14 / Windows 11)
+
+---
+
+## Roadmap
+
+| Phase | Status | Description |
+|:------|:-------|:------------|
+| 1 — Validation Layer | ✅ Done | JSON Schema Gate + security rule allow-list |
+| 2 — Sandbox (T3) | ✅ Done | Subprocess isolation, Windows Job Objects, Unix rlimit |
+| 3 — Snapshot System | ✅ Done | `.tar.gz` archives, SQLite WAL, gitignore-aware, cross-platform locks |
+| 4 — Observability | ✅ Done | Structured diffs, audit log, `aether status` CLI |
+| 5 — AST Apply Engine | 🔄 Next | Real `modify_function` / `add_function` via `ast` + `libcst` |
+| 6 — Node.js SDK | 🔜 Planned | `sdk/node/` TypeScript port |
+| 7 — T2 Sandbox (WASM) | 🔜 Planned | Wasmtime WASI integration |
+| 8 — T1 Sandbox (JIT) | 🔜 Planned | Cranelift FFI from existing `crates/ae-codegen` |
+
+---
+
+## Requirements
+
+- Python ≥ 3.11
+- `jsonschema >= 4.22`
+- `pathspec >= 0.12`
+- No Docker, no external daemons, no root required
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aether_lang_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+ai_runtime/__init__.py,sha256=KsWuqEL2rNZImhJ_ApeiAzW5V_sV7u_PEAcvdcDOvSs,896
+ai_runtime/_types.py,sha256=Rq-NCr9UdRMuZt8Cmj-mAW4sjQjEMXELNu19R8WcRgI,2333
+ai_runtime/cli.py,sha256=_6YUWibr1mYQSUhSVCrZ_raCFa3ivGtR8QELNfMwYCY,8320
+ai_runtime/orchestrator.py,sha256=tWEkO7ufvpx6gdUr9dX4Ij53auQDZgDD_e6_PLM_Pdc,13857
+ai_runtime/patch_engine.py,sha256=Oj4RNs364hcSBzIfl1orLCVegvo0slFHcfc_b1AJQpQ,8654
+ai_runtime/sandbox.py,sha256=l7Hzv80MvFW6ZjwYQ7hHD7hOHaoNYMevLLMGAXpNWxE,10359
+ai_runtime/sandbox_runner.py,sha256=GxlomublWBXnBVZDFZyxIpEHg93CN9zRQTCGTRunELI,5494
+ai_runtime/sandbox_t1.py,sha256=Ixt-DH7ZzIBK5q2kfd-neocD_alnDy9Xcvspx9CwxWM,12583
+ai_runtime/sandbox_t2.py,sha256=bIISJZWcpp0USmWJNDokYnffXd9XeuyWuJvpXksPr1M,7575
+ai_runtime/sandbox_t3.py,sha256=fZb4FKuOViZcepLmTuW7wNPzqR0d_B9v-j6PoIvgRVE,14957
+ai_runtime/ast/engine.py,sha256=mYcVaIaL6GX9iZ2iTraq6TdGIASy7sJOr_Gxnv04sY4,11217
+ai_runtime/observability/__init__.py,sha256=WLRRSBStKrJVJMUsS19ZxWjr5WKBUxaJS6KPKe5g3-w,421
+ai_runtime/observability/audit_log.py,sha256=06kGe-XVTWbEOqXdWQ4MLYMQ0v50P40su_u2s8MGRIQ,7410
+ai_runtime/observability/diff.py,sha256=MwI3Zr4dlEC7EubMBo-7pnWB6BVTkYnhz2x3kw3faig,10288
+ai_runtime/observability/events.py,sha256=zUW_3c32kl0VK0YD3YKb4sNpXZHNrSj5UiUHZRSPOgc,2643
+ai_runtime/snapshot/__init__.py,sha256=DeftVT4a9Ym_s3tpYX7vFfYq83i0L1LvECAxPl_xc8M,210
+ai_runtime/snapshot/gitignore.py,sha256=xzF1UOhuDiBU8wKZ9cxErDkXs7HHOSr_kTNFSGcio-8,5903
+ai_runtime/snapshot/lock.py,sha256=CBMcbzO1_VSzKKjoIwkjyGbRO5zYiYbTr6_DDKegO_Q,4139
+ai_runtime/snapshot/store.py,sha256=xaPrhUnUlJk2XIr_Rs926aZsCIrbpy-KNSrAqt_1Z2M,16917
+ai_runtime/validation/__init__.py,sha256=zapdN2L_XaRc9ZCoFBFmqlswGecHEnsMEAJ61g7a4Cw,692
+ai_runtime/validation/ae_bridge.py,sha256=20p1r1vl4PwQHsxe_70Z_7kNSZXxrhjmw2tu_1rUAjE,12758
+ai_runtime/validation/patch_schema.json,sha256=8Pqxj00L5PAdCFgFshFU2T5KPfvSSwiqwPbwqRNVbrI,7648
+ai_runtime/validation/rules.py,sha256=mJ41KaMC9jK-vUKK9KBznL6cd8AZtbc9vLOZT4d2MDg,7952
+ai_runtime/validation/schema.py,sha256=lX9zZ9CLCcdveftTGPEMkiXtE7wCALNj3O-5LdJ0UTA,3399
+aether_lang_runtime-0.1.0.dist-info/METADATA,sha256=yiadBvHmw6EQvRHyXipjYqGU3v584UparxpjMX3ckmA,18077
+aether_lang_runtime-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+aether_lang_runtime-0.1.0.dist-info/entry_points.txt,sha256=y4Z4L0w16GG2781mGkPXZKnzusU2bvW4_nB-1aRXWaM,77
+aether_lang_runtime-0.1.0.dist-info/RECORD,,

aether_lang_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aether_lang_runtime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ae-safe = ai_runtime.cli:main
+aether = ai_runtime.cli:main

ai_runtime/__init__.py

@@ -0,0 +1,31 @@
+"""
+ai_runtime
+~~~~~~~~~~~
+AI-Safe Execution Infrastructure — Python SDK
+
+Provides a safe, reversible, auditable execution layer for AI-driven code
+modification. AI agents emit structured patches; this runtime validates,
+sandboxes, and commits or rolls back the resulting changes.
+
+Quick start:
+    from ai_runtime import PatchEngine, Sandbox
+
+    engine = PatchEngine()
+    report = engine.validate(my_patch_dict)
+    if report.ok:
+        engine.apply(my_patch_dict)
+    else:
+        print(report.first_error)
+"""
+
+from .patch_engine import PatchEngine, ValidationReport
+from .sandbox import Sandbox
+from ._types import ExecutionResult, SnapshotHandle
+from .orchestrator import PatchOrchestrator, OrchestratorResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "PatchEngine", "ValidationReport", "Sandbox",
+    "ExecutionResult", "SnapshotHandle",
+    "PatchOrchestrator", "OrchestratorResult",
+]

ai_runtime/_types.py

@@ -0,0 +1,66 @@
+"""
+ai_runtime._types
+~~~~~~~~~~~~~~~~~
+Shared data-only types for the sandbox subsystem.
+Kept in a separate module to eliminate circular imports between
+sandbox.py and sandbox_t3.py.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ExecutionResult:
+    """Result of a sandboxed code execution."""
+    failed:          bool
+    exit_code:       int
+    stdout:          str
+    stderr:          str
+    elapsed_ms:      float
+    tier:            str        # "t1_cranelift" | "t2_wasm" | "t3_subprocess"
+    error:           Optional[str] = None
+    isolation_level: str = "unknown"
+    """
+    Isolation mechanism actually applied:
+      "audit_hook"    — Python sys.addaudithook (T3). Bypassable by indirect imports.
+                        See SECURITY.md for the full threat model.
+      "wasm_sandbox"  — Wasmtime WASI sandbox (T2). Hardware-level memory isolation.
+      "cranelift_jit" — Cranelift JIT inside process via catch_unwind guard (T1).
+                        No OS-level isolation; only safe for trusted Aether payloads.
+    """
+
+    @property
+    def succeeded(self) -> bool:
+        return not self.failed
+
+    def __bool__(self) -> bool:
+        return self.succeeded
+
+
+@dataclass
+class SnapshotHandle:
+    """
+    Reference to a pre-modification snapshot captured by SnapshotStore.
+
+    Fields:
+        snapshot_id:       UUID identifying this snapshot in snapshots.db.
+        project_root:      Absolute path to the captured project root.
+        patch_id:          ID of the patch this snapshot was taken for.
+        path:              Filesystem path to the .tar.gz archive.
+        status:            'pending' | 'committed' | 'rolled_back'
+        created_at:        Unix timestamp of capture.
+        archive_size_bytes: Compressed archive size in bytes (0 if unknown).
+        file_count:        Number of files in the snapshot (0 if unknown).
+    """
+    snapshot_id:        str
+    project_root:       str
+    patch_id:           str           = ""
+    path:               Optional[str] = None
+    status:             str           = "pending"
+    created_at:         float         = field(default_factory=time.time)
+    archive_size_bytes: int           = 0
+    file_count:         int           = 0