"""The run ledger: one folder per voyage run, and one per stage inside it (plan ยง4). ///state.json every stage's state, ids, gate decisions; rewritten on each change ////inputs.json the run inputs as sent, uploads shown by name only ////context.yaml the context file as uploaded or sent (with `generated:`) ////status.json, steps.json, evaluation.json No token or secret is ever written here. state.json is what a resumed run reads. """ from __future__ import annotations import json import os from datetime import datetime, timezone from pathlib import Path from typing import Any def utc_stamp(now: float | None = None) -> str: moment = datetime.fromtimestamp(now, timezone.utc) if now is not None else datetime.now(timezone.utc) return moment.strftime("%Y%m%dT%H%M%SZ") def utc_iso(now: float | None = None) -> str: moment = datetime.fromtimestamp(now, timezone.utc) if now is not None else datetime.now(timezone.utc) return moment.strftime("%Y-%m-%dT%H:%M:%SZ") def default_root() -> Path: return Path(os.getenv("SHAKEDOWN_LEDGER") or Path(__file__).resolve().parents[1] / "ledger") class Ledger: def __init__(self, folder: Path) -> None: self.folder = Path(folder) self.folder.mkdir(parents=True, exist_ok=True) @classmethod def new(cls, root: Path, voyage: str, now: float | None = None) -> "Ledger": return cls(Path(root) / voyage / utc_stamp(now)) def path(self, *parts: str) -> Path: target = self.folder.joinpath(*parts) target.parent.mkdir(parents=True, exist_ok=True) return target def write(self, name: str, data: Any, stage: str | None = None) -> Path: target = self.path(*([stage] if stage else []), name) tmp = target.with_suffix(target.suffix + ".tmp") if isinstance(data, (bytes, bytearray)): tmp.write_bytes(data) elif isinstance(data, str): tmp.write_text(data) else: tmp.write_text(json.dumps(data, indent=1, default=str)) tmp.replace(target) return target def load_state(self) -> dict: path = self.folder / "state.json" return json.loads(path.read_text()) if path.is_file() else {} def save_state(self, state: dict) -> None: self.write("state.json", state) def shown_inputs(inputs: dict) -> dict: """The inputs as recorded: uploads by name, long documents by length (their text is kept beside, in the stage).""" out = {} for key, value in inputs.items(): if key == "file" and isinstance(value, list): out[key] = [item.get("name") for item in value if isinstance(item, dict)] elif isinstance(value, str) and len(value) > 200: out[key] = f"<{len(value)} characters>" else: out[key] = value return out