feat(python): durable transaction subsystem and Kiro IDE 1.0 adapter

Land the crash-recoverable managed-file transaction engine (journal,
staging, commit, restart recovery, opaque snapshots, private artifacts,
Windows DACL hardening) and the Kiro IDE 1.0 workspace hook plugin with
legacy migration.

Repair five defects that kept the suite red (426 failures to zero):

- Anchor the transaction state directory at ~/.elydora/transactions
  instead of the shared system temp directory. The recovery journal now
  shares fate with the runtimes it repairs, survives temp cleaners, and
  isolates naturally under per-test fake homes.
- Skip pending-transaction recovery when no state directory exists so
  rejected installs never create runtime directories.
- Create the runtime root's parent before hardening it, matching the Go
  SDK's expand behavior for fresh homes.
- Stop using file timestamps as identity evidence: Windows exposes
  mtime/ctime with delayed cross-handle visibility. Reads now prove
  stability through a verification re-read; snapshots compare device,
  inode, size, and SHA-256.
- Stop comparing synthetic Windows permission bits across stat
  boundaries: path stats derive execute bits from file extensions while
  handle stats do not, which falsely flagged every managed .cmd wrapper.
  Snapshots store raw modes for restoration and compare portable bits.

Reservation cleanup now verifies content before discarding so a
concurrent writer's file at a rollback path is preserved, and the
install-failure tests assert the precise contract: no agent runtime
residue, with the durable state directory allowed to remain.

Gates: pytest 807 passed, mypy clean, pip check clean, wheel builds.
This commit is contained in:
ZacharyZhang-NY committed 2026-07-21 18:53:06 -04:00
1 parent dce7d1288a
commit e37418c489
53 files changed
+11855 -531

No files matched your search

+99 -5
View File
@@ -5,7 +5,7 @@ from __future__ import annotations
from dataclasses import dataclass
import os
import stat
from typing import Optional
from typing import Callable, Optional
MAX_SECRET_BYTES = 64 * 1024
@@ -21,6 +21,83 @@ class FileSnapshot:
mode: int
@dataclass(frozen=True)
class DirectorySnapshot:
device: int
inode: int
def identity_mode_bits(mode: int) -> int:
"""Collapse permission bits that are not identity evidence on Windows.
Windows synthesizes POSIX modes and derives execute bits from the file
extension for path stats but not for handle stats, so the synthetic value
cannot serve as identity there. Windows permissions are enforced through
DACLs in _windows_security instead. Captured snapshots still store the
raw bits because restoration re-applies them.
"""
return mode if os.name != "nt" else 0
def portable_file_mode(metadata: os.stat_result) -> int:
"""Return the identity-relevant permission bits for one stat result."""
return identity_mode_bits(stat.S_IMODE(metadata.st_mode))
def _stable_file_metadata(
metadata: os.stat_result,
) -> tuple[int, int, int, int]:
# Timestamps are excluded deliberately: Windows exposes file times with
# delayed cross-handle visibility, so they are unsound identity evidence.
# Content changes are caught by the verification re-read instead.
return (
metadata.st_dev,
metadata.st_ino,
portable_file_mode(metadata),
metadata.st_size,
)
def _same_file_metadata(
first: os.stat_result,
second: os.stat_result,
) -> bool:
return _stable_file_metadata(first) == _stable_file_metadata(second)
def assert_content_stable(
opener: Callable[[], int],
file_path: str,
label: str,
expected: os.stat_result,
raw: bytes,
maximum_bytes: int,
) -> None:
"""Re-read a just-read file and require identical identity and bytes.
This is the deterministic replacement for timestamp comparisons: a
concurrent in-place rewrite is proven by content divergence between the
two reads, independent of filesystem timer visibility.
"""
descriptor = opener()
try:
current = os.fstat(descriptor)
if (
not stat.S_ISREG(current.st_mode)
or current.st_dev != expected.st_dev
or current.st_ino != expected.st_ino
):
raise OSError(f"{label} changed while reading: {file_path}")
with os.fdopen(descriptor, "rb") as file:
descriptor = -1
reread = file.read(maximum_bytes + 1)
finally:
if descriptor >= 0:
os.close(descriptor)
if reread != raw:
raise OSError(f"{label} changed while reading: {file_path}")
def _inspect_regular_file(file_path: str, label: str) -> Optional[os.stat_result]:
try:
metadata = os.lstat(file_path)
@@ -52,13 +129,24 @@ def read_physical_file(
after = os.fstat(descriptor)
if not stat.S_ISREG(after.st_mode):
raise OSError(f"{label} path is not a physical file: {file_path}")
if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
if not _same_file_metadata(before, after):
raise OSError(f"{label} changed while opening: {file_path}")
if after.st_size > maximum_bytes:
raise ValueError(f"{label} exceeds {maximum_bytes} bytes: {file_path}")
with os.fdopen(descriptor, "rb") as file:
descriptor = -1
raw = file.read(maximum_bytes + 1)
finished = os.fstat(file.fileno())
if not _same_file_metadata(finished, after):
raise OSError(f"{label} changed while reading: {file_path}")
assert_content_stable(
lambda: os.open(file_path, flags),
file_path,
label,
after,
raw,
maximum_bytes,
)
except OSError as error:
raise OSError(f"Read {label} at {file_path}: {error}") from error
finally:
@@ -83,16 +171,22 @@ def physical_file_exists(file_path: str, label: str) -> bool:
return _inspect_regular_file(file_path, label) is not None
def physical_directory_exists(directory: str, label: str) -> bool:
def read_physical_directory(
directory: str, label: str
) -> Optional[DirectorySnapshot]:
try:
metadata = os.lstat(directory)
except FileNotFoundError:
return False
return None
except OSError as error:
raise OSError(f"Inspect {label} at {directory}: {error}") from error
if not stat.S_ISDIR(metadata.st_mode) or stat.S_ISLNK(metadata.st_mode):
raise OSError(f"{label} is not a physical directory: {directory}")
return True
return DirectorySnapshot(metadata.st_dev, metadata.st_ino)
def physical_directory_exists(directory: str, label: str) -> bool:
return read_physical_directory(directory, label) is not None
def ensure_physical_directory(directory: str, label: str) -> None: