simjecture 0.1.0__py3-none-any.whl

conjecture_solver/mvp_control.py

@@ -0,0 +1,322 @@
+"""Operator control channel and run clock for MVP campaigns.
+
+These files live under operator_input/ and are not scientific evidence. The
+runner consults them only at action boundaries. They never use SIGSTOP.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field
+
+from .models import StrictModel
+
+CONTROL_RELATIVE = Path("operator_input") / "control.json"
+CLOCK_RELATIVE = Path("operator_input") / "run_clock.json"
+PAUSE_STATE_RELATIVE = Path("operator_input") / "pause_state.json"
+
+
+class ControlCommand(StrEnum):
+    NONE = "none"
+    PAUSE = "pause"
+    CANCEL = "cancel"
+
+
+class CampaignPaused(Exception):
+    """Raised when the runner honors an action-boundary pause.
+
+    No terminal report is written. Repeating the original contract resumes.
+    """
+
+    def __init__(self, run_directory: str | Path, *, iterations: int) -> None:
+        self.run_directory = Path(run_directory)
+        self.iterations = iterations
+        super().__init__(
+            f"campaign paused at an action boundary after {iterations} iteration(s)"
+        )
+
+
+class OperatorControl(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    command: ControlCommand = ControlCommand.NONE
+    requested_at: datetime | None = None
+    source: str = "operator"
+
+
+class RunClock(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    started_at: datetime
+    session_started_at: datetime
+    last_tick_at: datetime
+    accumulated_active_seconds: float = Field(default=0.0, ge=0)
+    state: Literal["running", "paused", "finished"] = "running"
+
+
+class PauseState(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    paused_at: datetime
+    iterations: int = Field(ge=0)
+    reason: str = "operator requested pause at the next action boundary"
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def read_control(run_directory: str | Path) -> OperatorControl:
+    path = Path(run_directory) / CONTROL_RELATIVE
+    payload = _read_json(path)
+    if payload is None:
+        return OperatorControl()
+    try:
+        return OperatorControl.model_validate(payload)
+    except Exception:
+        return OperatorControl()
+
+
+def write_control(
+    run_directory: str | Path,
+    command: ControlCommand,
+    *,
+    source: str = "operator",
+    now: datetime | None = None,
+) -> OperatorControl:
+    control = OperatorControl(
+        command=command,
+        requested_at=now or utc_now(),
+        source=source,
+    )
+    _write_json(Path(run_directory) / CONTROL_RELATIVE, control.model_dump(mode="json"))
+    return control
+
+
+def clear_control(run_directory: str | Path, *, source: str = "runner") -> None:
+    write_control(run_directory, ControlCommand.NONE, source=source)
+
+
+def poll_control(run_directory: str | Path) -> ControlCommand:
+    return read_control(run_directory).command
+
+
+def read_clock(run_directory: str | Path) -> RunClock | None:
+    payload = _read_json(Path(run_directory) / CLOCK_RELATIVE)
+    if payload is None:
+        return None
+    try:
+        return RunClock.model_validate(payload)
+    except Exception:
+        return None
+
+
+def read_pause_state(run_directory: str | Path) -> PauseState | None:
+    payload = _read_json(Path(run_directory) / PAUSE_STATE_RELATIVE)
+    if payload is None:
+        return None
+    try:
+        return PauseState.model_validate(payload)
+    except Exception:
+        return None
+
+
+def begin_or_resume_clock(
+    run_directory: str | Path,
+    *,
+    now: datetime | None = None,
+) -> RunClock:
+    """Start or continue the operator clock and clear a prior pause request."""
+
+    moment = now or utc_now()
+    existing = read_clock(run_directory)
+    if existing is None:
+        clock = RunClock(
+            started_at=moment,
+            session_started_at=moment,
+            last_tick_at=moment,
+            accumulated_active_seconds=0.0,
+            state="running",
+        )
+    else:
+        orphan = 0.0
+        if existing.state == "running":
+            orphan = max(
+                0.0,
+                (existing.last_tick_at - existing.session_started_at).total_seconds(),
+            )
+        clock = RunClock(
+            started_at=existing.started_at,
+            session_started_at=moment,
+            last_tick_at=moment,
+            accumulated_active_seconds=existing.accumulated_active_seconds + orphan,
+            state="running",
+        )
+    _write_clock(run_directory, clock)
+    clear_control(run_directory, source="runner")
+    pause_path = Path(run_directory) / PAUSE_STATE_RELATIVE
+    if pause_path.exists():
+        pause_path.unlink()
+    return clock
+
+
+def tick_clock(run_directory: str | Path, *, now: datetime | None = None) -> RunClock:
+    moment = now or utc_now()
+    clock = read_clock(run_directory)
+    if clock is None:
+        return begin_or_resume_clock(run_directory, now=moment)
+    if clock.state != "running":
+        return clock
+    updated = clock.model_copy(update={"last_tick_at": moment})
+    _write_clock(run_directory, updated)
+    return updated
+
+
+def pause_at_boundary(
+    run_directory: str | Path,
+    *,
+    iterations: int,
+    now: datetime | None = None,
+) -> PauseState:
+    moment = now or utc_now()
+    clock = read_clock(run_directory)
+    if clock is not None and clock.state == "running":
+        session = max(0.0, (moment - clock.session_started_at).total_seconds())
+        paused_clock = RunClock(
+            started_at=clock.started_at,
+            session_started_at=clock.session_started_at,
+            last_tick_at=moment,
+            accumulated_active_seconds=clock.accumulated_active_seconds + session,
+            state="paused",
+        )
+        _write_clock(run_directory, paused_clock)
+    state = PauseState(paused_at=moment, iterations=iterations)
+    _write_json(Path(run_directory) / PAUSE_STATE_RELATIVE, state.model_dump(mode="json"))
+    clear_control(run_directory, source="runner")
+    return state
+
+
+def finalize_clock(run_directory: str | Path, *, now: datetime | None = None) -> RunClock | None:
+    moment = now or utc_now()
+    clock = read_clock(run_directory)
+    if clock is None:
+        return None
+    extra = 0.0
+    if clock.state == "running":
+        extra = max(0.0, (moment - clock.session_started_at).total_seconds())
+    finished = RunClock(
+        started_at=clock.started_at,
+        session_started_at=clock.session_started_at,
+        last_tick_at=moment,
+        accumulated_active_seconds=clock.accumulated_active_seconds + extra,
+        state="finished",
+    )
+    _write_clock(run_directory, finished)
+    return finished
+
+
+def elapsed_from_clock(clock: RunClock, *, now: datetime | None = None) -> float:
+    moment = now or utc_now()
+    if clock.state == "running":
+        session = max(0.0, (moment - clock.session_started_at).total_seconds())
+        return clock.accumulated_active_seconds + session
+    return clock.accumulated_active_seconds
+
+
+def parse_usage_payload(usage: Any) -> dict[str, int]:
+    """Normalize provider usage objects without treating them as scientific status."""
+
+    empty = {
+        "prompt_tokens": 0,
+        "completion_tokens": 0,
+        "total_tokens": 0,
+        "cached_tokens": 0,
+        "reasoning_tokens": 0,
+    }
+    if not isinstance(usage, dict):
+        return empty
+    prompt = _as_int(usage.get("prompt_tokens"))
+    if prompt is None:
+        prompt = _as_int(usage.get("input_tokens")) or 0
+    completion = _as_int(usage.get("completion_tokens"))
+    if completion is None:
+        completion = _as_int(usage.get("output_tokens")) or 0
+    total = _as_int(usage.get("total_tokens"))
+    if total is None:
+        total = prompt + completion
+    cached = 0
+    details = usage.get("prompt_tokens_details")
+    if isinstance(details, dict):
+        cached = _as_int(details.get("cached_tokens")) or 0
+    cached = (
+        _as_int(usage.get("prompt_cache_hit_tokens"))
+        or _as_int(usage.get("cached_tokens"))
+        or cached
+    )
+    reasoning = 0
+    out_details = usage.get("completion_tokens_details")
+    if isinstance(out_details, dict):
+        reasoning = _as_int(out_details.get("reasoning_tokens")) or 0
+    return {
+        "prompt_tokens": max(0, prompt),
+        "completion_tokens": max(0, completion),
+        "total_tokens": max(0, total),
+        "cached_tokens": max(0, cached),
+        "reasoning_tokens": max(0, reasoning),
+    }
+
+
+def format_token_counts(
+    *,
+    prompt_tokens: int,
+    completion_tokens: int,
+    total_tokens: int,
+    turns: int,
+    missing_turns: int = 0,
+    cached_tokens: int = 0,
+) -> str:
+    parts = [
+        f"tokens: {_comma(prompt_tokens)} in / {_comma(completion_tokens)} out / "
+        f"{_comma(total_tokens)} total"
+    ]
+    extras: list[str] = [f"{turns} turn" + ("s" if turns != 1 else "")]
+    if missing_turns:
+        extras.append(f"{missing_turns} without usage")
+    if cached_tokens:
+        extras.append(f"{_comma(cached_tokens)} cached")
+    parts.append("(" + ", ".join(extras) + ")")
+    return " ".join(parts)
+
+
+def _comma(value: int) -> str:
+    return f"{value:,}"
+
+
+def _as_int(value: Any) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return int(value)
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _write_clock(run_directory: str | Path, clock: RunClock) -> None:
+    _write_json(Path(run_directory) / CLOCK_RELATIVE, clock.model_dump(mode="json"))
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+    os.replace(temporary, path)

conjecture_solver/mvp_guidance.py

@@ -0,0 +1,172 @@
+"""Validated starting points for guided MVP commissioning campaigns."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+from pydantic import Field, model_validator
+
+from .models import StrictModel
+
+
+def _workspace_relative_path(value: str) -> str:
+    path = PurePosixPath(value)
+    if (
+        not value
+        or path.is_absolute()
+        or "\\" in value
+        or any(part in {"", ".", ".."} for part in path.parts)
+    ):
+        raise ValueError(f"guided commissioning path must be workspace-relative: {value!r}")
+    if path.as_posix() != value:
+        raise ValueError(f"guided commissioning path must be canonical: {value!r}")
+    return path.as_posix()
+
+
+class MVPGuidedCommissioningSpec(StrictModel):
+    """Operator-authored manifest for one known-runnable starting point.
+
+    The package deliberately says only what was run and where its compact validation
+    record lives. It does not qualify the supplied output as campaign evidence.
+    """
+
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    name: str = Field(min_length=1, pattern=r"^[a-z0-9][a-z0-9._-]*$")
+    description: str = Field(min_length=1)
+    capability: str = Field(min_length=1)
+    program_path: str = Field(min_length=1)
+    validated_argv: tuple[str, ...] = Field(min_length=1)
+    validation_summary_path: str = Field(min_length=1)
+    operator_validation: str = Field(min_length=1)
+    limitations: tuple[str, ...] = ()
+    files: tuple[str, ...] = Field(min_length=2)
+
+    @model_validator(mode="after")
+    def paths_and_command_are_self_contained(self) -> MVPGuidedCommissioningSpec:
+        normalized_files = tuple(_workspace_relative_path(path) for path in self.files)
+        if len(set(normalized_files)) != len(normalized_files):
+            raise ValueError("guided commissioning files must be unique")
+        program_path = _workspace_relative_path(self.program_path)
+        summary_path = _workspace_relative_path(self.validation_summary_path)
+        if program_path not in normalized_files:
+            raise ValueError("program_path must be listed in files")
+        if summary_path not in normalized_files:
+            raise ValueError("validation_summary_path must be listed in files")
+        if self.validated_argv[0] != program_path:
+            raise ValueError("validated_argv[0] must equal program_path")
+        if any(not argument for argument in self.validated_argv):
+            raise ValueError("validated_argv arguments cannot be empty")
+        return self
+
+
+class MVPGuidedCommissioningFile(StrictModel):
+    path: str = Field(min_length=1)
+    bytes: int = Field(ge=0)
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True)
+class MVPGuidedCommissioningPackage:
+    """Loaded, content-addressed guided commissioning package."""
+
+    manifest_path: Path
+    spec: MVPGuidedCommissioningSpec
+    file_records: tuple[MVPGuidedCommissioningFile, ...]
+    package_sha256: str
+
+    @classmethod
+    def read(cls, manifest_path: str | Path) -> MVPGuidedCommissioningPackage:
+        requested_manifest = Path(manifest_path)
+        if requested_manifest.is_symlink():
+            raise ValueError("guided commissioning manifest must be a regular file")
+        manifest = requested_manifest.resolve()
+        if not manifest.is_file():
+            raise ValueError("guided commissioning manifest must be a regular file")
+        spec = MVPGuidedCommissioningSpec.model_validate_json(manifest.read_text())
+        root = manifest.parent
+        digest = hashlib.sha256()
+        canonical_spec = json.dumps(
+            spec.model_dump(mode="json"),
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        digest.update(len(canonical_spec).to_bytes(8, "big"))
+        digest.update(canonical_spec)
+        records: list[MVPGuidedCommissioningFile] = []
+        for relative in sorted(spec.files):
+            normalized = _workspace_relative_path(relative)
+            requested = root / normalized
+            path = requested.resolve()
+            if requested.is_symlink() or not path.is_relative_to(root) or not path.is_file():
+                raise ValueError(
+                    f"guided commissioning file is missing, irregular, or escapes package: "
+                    f"{relative!r}"
+                )
+            encoded = path.read_bytes()
+            sha256 = hashlib.sha256(encoded).hexdigest()
+            records.append(
+                MVPGuidedCommissioningFile(
+                    path=normalized,
+                    bytes=len(encoded),
+                    sha256=sha256,
+                )
+            )
+            name = normalized.encode()
+            digest.update(len(name).to_bytes(8, "big"))
+            digest.update(name)
+            digest.update(len(encoded).to_bytes(8, "big"))
+            digest.update(encoded)
+        return cls(
+            manifest_path=manifest,
+            spec=spec,
+            file_records=tuple(records),
+            package_sha256=digest.hexdigest(),
+        )
+
+    @property
+    def root(self) -> Path:
+        return self.manifest_path.parent
+
+    def read_file(self, relative: str) -> bytes:
+        normalized = _workspace_relative_path(relative)
+        record = next(
+            (item for item in self.file_records if item.path == normalized),
+            None,
+        )
+        if record is None:
+            raise ValueError(f"file is not declared by guided commissioning: {relative!r}")
+        requested = self.root / normalized
+        path = requested.resolve()
+        if requested.is_symlink() or not path.is_relative_to(self.root) or not path.is_file():
+            raise ValueError(f"guided commissioning file identity changed: {relative!r}")
+        encoded = path.read_bytes()
+        if len(encoded) != record.bytes or hashlib.sha256(encoded).hexdigest() != record.sha256:
+            raise ValueError(f"guided commissioning file identity changed: {relative!r}")
+        return encoded
+
+    def assert_identity(self) -> None:
+        current = self.read(self.manifest_path)
+        if current.package_sha256 != self.package_sha256:
+            raise ValueError("guided commissioning package identity changed")
+
+    def descriptor(self) -> dict[str, Any]:
+        return {
+            "available": True,
+            "schema_version": self.spec.schema_version,
+            "name": self.spec.name,
+            "description": self.spec.description,
+            "capability": self.spec.capability,
+            "program_path": self.spec.program_path,
+            "validated_argv": list(self.spec.validated_argv),
+            "validation_summary_path": self.spec.validation_summary_path,
+            "operator_validation": self.spec.operator_validation,
+            "limitations": list(self.spec.limitations),
+            "files": [item.model_dump(mode="json") for item in self.file_records],
+            "package_sha256": self.package_sha256,
+            "scientific_evidence_eligible": False,
+            "policy": "operator_validated_starting_point_not_campaign_evidence",
+        }