patchground 0.1.0__py3-none-any.whl

patchground/sessions/submission.py

@@ -0,0 +1,344 @@
+"""Private frozen inputs and atomic, independently readable session closure."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import tempfile
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import AwareDatetime, Field, ValidationError
+
+from patchground import sandbox as engine
+from patchground.sandbox import SandboxError
+from patchground.sessions import store
+from patchground.sessions.files import copy_tree, open_directory, open_entry
+from patchground.sessions.models import CheckResult, Event, Model, SessionError, SessionRecord, now
+from patchground.sessions.workflow import Sandbox, _root, _sanitized
+from patchground.spec import ChallengeManifest
+
+
+@dataclass(frozen=True)
+class SubmissionSnapshot:
+    session: Path
+    original: Path
+    final: Path
+    hidden: Path
+    record: SessionRecord
+    manifest: ChallengeManifest
+    events: tuple[Event, ...]
+    requested_at: datetime
+    saved_report: dict[str, object] | None
+
+
+class SubmissionAudit(Model):
+    prefix_size: int = Field(ge=0)
+    prefix_sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+    event: str
+
+
+class Receipt(Model):
+    schema_version: Literal[1]
+    requested_at: AwareDatetime
+    final_check: CheckResult
+    artifacts: dict[str, str]
+    audit: SubmissionAudit
+
+
+def _inventory(path: Path) -> dict[str, str]:
+    result: dict[str, str] = {}
+
+    def visit(parent: int, prefix: str) -> None:
+        for name in sorted(os.listdir(parent)):
+            if not prefix and name == "receipt.json":
+                continue
+            with open_entry(parent, name) as descriptor:
+                info = os.fstat(descriptor)
+                key = prefix + name
+                if stat.S_ISDIR(info.st_mode):
+                    result[key + "/"] = f"directory:{stat.S_IMODE(info.st_mode):o}"
+                    visit(descriptor, key + "/")
+                else:
+                    if info.st_nlink != 1:
+                        raise SessionError("submission artifacts must not have hardlinks")
+                    digest = hashlib.sha256(stat.S_IMODE(info.st_mode).to_bytes(2, "big"))
+                    with os.fdopen(os.dup(descriptor), "rb") as stream:
+                        for block in iter(lambda: stream.read(65536), b""):
+                            digest.update(block)
+                    result[key] = digest.hexdigest()
+
+    with open_directory(path) as parent:
+        visit(parent, "")
+    return result
+
+
+def completed(meta: Path) -> tuple[dict[str, object], Receipt] | None:
+    """Validate committed artifacts without consulting live workspace files."""
+    with open_directory(meta) as parent:
+        if "submission" not in os.listdir(parent):  # noqa: PTH208 -- pinned descriptor
+            return None
+    bundle = meta / "submission"
+    try:
+        with open_directory(bundle) as parent:
+            values: dict[str, str] = {}
+            for name in ("receipt.json", "report.json", "report.md"):
+                with (
+                    store.metadata_file(parent, name) as descriptor,
+                    os.fdopen(os.dup(descriptor), "r", encoding="utf-8") as stream,
+                ):
+                    values[name] = stream.read()
+            if set(os.listdir(parent)) != {  # noqa: PTH208 -- pinned descriptor
+                "receipt.json",
+                "report.json",
+                "report.md",
+                "final",
+            }:
+                raise ValueError("unexpected bundle entry")
+        with open_directory(bundle / "final"):
+            pass
+        receipt = Receipt.model_validate_json(values["receipt.json"])
+        event = Event.model_validate_json(receipt.audit.event)
+        if (
+            not receipt.audit.event.endswith("\n")
+            or len(receipt.audit.event.splitlines()) != 1
+            or event.type != "submitted"
+            or event.data != {"requested_at": receipt.requested_at.isoformat()}
+        ):
+            raise ValueError("inconsistent submission audit receipt")
+        if _inventory(bundle) != receipt.artifacts:
+            raise ValueError("artifact integrity mismatch")
+        report = json.loads(values["report.json"])
+        if not isinstance(report, dict):
+            raise ValueError("invalid report")
+        return report, receipt
+    except (OSError, UnicodeError, ValueError, ValidationError) as exc:
+        raise SessionError("corrupt or unsafe submission bundle") from exc
+
+
+def require_active(meta: Path) -> None:
+    if completed(meta) is not None:
+        raise SessionError("session already submitted: start a new session to practice again")
+
+
+def audit_contents(raw: bytes, receipt: Receipt) -> tuple[bytes, bytes]:
+    """Return parseable audit bytes and a proven missing append suffix; never discard bytes."""
+    audit = receipt.audit
+    prefix = raw[: audit.prefix_size]
+    if (
+        len(prefix) != audit.prefix_size
+        or hashlib.sha256(prefix).hexdigest() != audit.prefix_sha256
+    ):
+        raise SessionError("corrupt submission audit: history does not match receipt")
+    expected = audit.event.encode("utf-8")
+    suffix = raw[audit.prefix_size :]
+    if len(suffix) < len(expected) and expected.startswith(suffix):
+        return prefix, expected[len(suffix) :]
+    if not suffix.startswith(expected):
+        raise SessionError("corrupt submission audit: unexpected submission append")
+    if not raw.endswith(b"\n"):
+        raise SessionError("corrupt submission audit: incomplete unrelated event")
+    return raw, b""
+
+
+def _journal(meta: Path) -> bytes:
+    with (
+        open_directory(meta) as parent,
+        store.metadata_file(parent, "events.jsonl") as descriptor,
+        os.fdopen(os.dup(descriptor), "rb") as stream,
+    ):
+        return stream.read()
+
+
+def _reconcile(meta: Path, receipt: Receipt) -> None:
+    try:
+        raw = _journal(meta)
+        _, missing = audit_contents(raw, receipt)
+        if missing:
+            store.append_bytes(meta, missing)
+    except (OSError, UnicodeError, SessionError) as exc:
+        raise SessionError(
+            "submission bundle may already be published; retry submit to reconcile its audit"
+        ) from exc
+
+
+@contextmanager
+def prepare_submission(
+    session: Path | None = None, *, root: Path | None = None
+) -> Iterator[SubmissionSnapshot]:
+    requested_at = now()
+    try:
+        path = store.resolve(session, _root(root))
+        meta = path / ".session"
+        with store.locked(meta):
+            record, manifest, events = store.load(path)
+            saved = completed(meta)
+            if saved is not None:
+                report, receipt = saved
+                _reconcile(meta, receipt)
+                yield SubmissionSnapshot(
+                    path,
+                    meta / "original",
+                    meta / "submission/final",
+                    meta / "hidden",
+                    record,
+                    manifest,
+                    tuple(events),
+                    receipt.requested_at,
+                    report,
+                )
+                return
+            with tempfile.TemporaryDirectory(
+                prefix="patchground-submit-", dir=Path(tempfile.gettempdir()).resolve(strict=True)
+            ) as temporary:
+                captured = Path(temporary)
+                for name, source in (
+                    ("original", meta / "original"),
+                    ("final", path / "workspace"),
+                    ("hidden", meta / "hidden"),
+                ):
+                    (captured / name).mkdir(mode=0o700)
+                    copy_tree(source, captured / name)
+                yield SubmissionSnapshot(
+                    path,
+                    captured / "original",
+                    captured / "final",
+                    captured / "hidden",
+                    record,
+                    manifest,
+                    tuple(events),
+                    requested_at,
+                    None,
+                )
+    except (OSError, UnicodeError, SandboxError) as exc:
+        raise SessionError("submission unavailable: storage or frozen image unavailable") from exc
+
+
+def check_submission(snapshot: SubmissionSnapshot, *, sandbox: Sandbox = engine) -> CheckResult:
+    if snapshot.saved_report is not None:
+        raise SessionError("session already submitted")
+    started = time.monotonic()
+    try:
+        with tempfile.TemporaryDirectory(
+            prefix="patchground-submit-check-", dir=Path(tempfile.gettempdir()).resolve(strict=True)
+        ) as temporary:
+            clean = Path(temporary)
+            copy_tree(snapshot.final, clean)
+            copy_tree(snapshot.hidden, clean)
+            raw = sandbox.run_check(
+                snapshot.record.image_id, [clean], snapshot.manifest.environment.test_command
+            )
+        return _sanitized(raw, time.monotonic() - started)
+    except (OSError, SandboxError) as exc:
+        raise SessionError(
+            "submission check unavailable: storage or frozen image unavailable"
+        ) from exc
+
+
+def _write(path: Path, text: str) -> None:
+    with open_directory(path.parent) as parent:
+        descriptor = os.open(
+            path.name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=parent
+        )
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+
+
+def _sync_tree(path: Path) -> None:
+    with open_directory(path) as parent:
+        for name in os.listdir(parent):  # noqa: PTH208 -- pinned descriptor
+            with open_entry(parent, name) as descriptor:
+                if stat.S_ISDIR(os.fstat(descriptor).st_mode):
+                    _sync_tree(path / name)
+                else:
+                    os.fsync(descriptor)
+        os.fsync(parent)
+
+
+def commit_submission(
+    snapshot: SubmissionSnapshot, report: dict[str, object], markdown: str, final_check: CheckResult
+) -> None:
+    meta = snapshot.session / ".session"
+    existing = completed(meta)
+    if existing is not None:
+        store.load(snapshot.session)
+        _reconcile(meta, existing[1])
+        return
+    published = False
+    try:
+        # Failed/incomplete staging is deliberately left private and is never treated as closure.
+        # Never clean it via a pathname that an editor may have replaced.
+        name = ".submission-" + uuid4().hex
+        with open_directory(meta) as parent:
+            os.mkdir(name, mode=0o700, dir_fd=parent)
+            stage = meta / name
+            with open_directory(stage) as staged:
+                os.mkdir("final", mode=0o700, dir_fd=staged)
+            copy_tree(snapshot.final, stage / "final")
+            _write(
+                stage / "report.json",
+                json.dumps(report, ensure_ascii=False, allow_nan=False) + "\n",
+            )
+            _write(stage / "report.md", markdown)
+            store.load(snapshot.session)
+            prefix = _journal(meta)
+            if not prefix.endswith(b"\n"):
+                raise SessionError("corrupt session audit before submission")
+            audit_event = (
+                Event(
+                    ts=now(),
+                    type="submitted",
+                    data={"requested_at": snapshot.requested_at.isoformat()},
+                ).model_dump_json()
+                + "\n"
+            )
+            receipt = Receipt(
+                schema_version=1,
+                requested_at=snapshot.requested_at,
+                final_check=final_check,
+                artifacts=_inventory(stage),
+                audit=SubmissionAudit(
+                    prefix_size=len(prefix),
+                    prefix_sha256=hashlib.sha256(prefix).hexdigest(),
+                    event=audit_event,
+                ),
+            )
+            _write(
+                stage / "receipt.json",
+                receipt.model_dump_json(exclude={"final_check": {"passed", "counts"}}) + "\n",
+            )
+            _sync_tree(stage)
+            os.rename(name, "submission", src_dir_fd=parent, dst_dir_fd=parent)
+            published = True
+            # Closure has committed: any subsequent failure must never reopen the session.
+            os.fsync(parent)
+        store.load(snapshot.session)
+        _reconcile(meta, receipt)
+    except (OSError, UnicodeError, SessionError) as exc:
+        if published:
+            raise SessionError(
+                "submission bundle may already be published; retry submit to finish finalization"
+            ) from exc
+        raise
+
+
+def read_submission(session: Path | None = None, *, root: Path | None = None) -> dict[str, object]:
+    try:
+        path = store.resolve(session, _root(root))
+        store.load(path)
+        saved = completed(path / ".session")
+        if saved is None:
+            raise SessionError("session not submitted: no final report exists")
+        return saved[0]
+    except (OSError, UnicodeError) as exc:
+        raise SessionError("submission unavailable: invalid session storage") from exc

patchground/sessions/workflow.py

@@ -0,0 +1,297 @@
+"""Start, check and status; sandbox is injected at the execution boundary."""
+
+from __future__ import annotations
+
+import tempfile
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from patchground import sandbox as engine
+from patchground.packs.models import ConsentRequired, PackError, PreparedChallenge
+from patchground.sandbox import BuildResult, RunOutcome, RunResult, SandboxError, TestStatus
+from patchground.sessions import git, store
+from patchground.sessions.files import copy_tree, readonly, remove_partial, safe_path
+from patchground.sessions.history import capture
+from patchground.sessions.history_ignore import resolve as resolve_history_ignores
+from patchground.sessions.models import (
+    CheckResult,
+    CheckTest,
+    Event,
+    SessionError,
+    SessionRecord,
+    SessionStatus,
+    StartedSession,
+    now,
+)
+from patchground.spec import ManifestError, load_challenge
+
+
+class Sandbox(Protocol):
+    """Only execution capabilities sessions require; no engine SDK leaks upward."""
+
+    def build_image(self, dockerfile: Path, *, name: str) -> BuildResult: ...
+
+    def run_check(self, image_id: str, layers: Sequence[Path], command: str) -> RunResult: ...
+
+
+def _root(root: Path | None) -> Path:
+    return (root if root is not None else store.default_root()).absolute()
+
+
+def start_session(
+    path: Path | str,
+    *,
+    root: Path | None = None,
+    timer: bool = True,
+    history: bool = True,
+    sandbox: Sandbox = engine,
+    yes: bool = False,
+    expected_identity: str | None = None,
+    pack_root: Path | None = None,
+) -> StartedSession:
+    """Resolve and authorize a source before any build or session mutation."""
+    from patchground.packs.registry import prepare_execution
+
+    try:
+        with prepare_execution(
+            path, yes=yes, expected_identity=expected_identity, root=pack_root
+        ) as prepared:
+            return _start_session(
+                prepared.path,
+                root=root,
+                timer=timer,
+                history=history,
+                sandbox=sandbox,
+                prepared=prepared,
+            )
+    except ConsentRequired:
+        raise
+    except PackError as exc:
+        raise SessionError(str(exc)) from exc
+
+
+def _start_session(
+    path: Path,
+    *,
+    root: Path | None = None,
+    timer: bool = True,
+    history: bool = True,
+    sandbox: Sandbox = engine,
+    prepared: PreparedChallenge,
+) -> StartedSession:
+    """Freeze an authorized source into an independent session."""
+    partial: Path | None = None
+    try:
+        try:
+            challenge = load_challenge(path)
+        except ManifestError as exc:
+            # Keep file/line diagnostics, but do not echo arbitrary manifest values.
+            locations = ", ".join(f"{issue.file.name}:{issue.line or 1}" for issue in exc.issues)
+            raise SessionError(f"invalid challenge manifest or unsafe paths ({locations})") from exc
+        manifest = challenge.manifest
+        if manifest.environment.services:
+            raise SessionError("services are not supported by local sessions yet")
+        partial = store.allocate(_root(root), manifest.id)
+        workspace = partial / "workspace"
+        meta = partial / ".session"
+        for folder in (workspace, meta, meta / "hidden", meta / "original"):
+            folder.mkdir(mode=0o700)
+        copy_tree(challenge.root / "workspace", workspace)
+        if manifest.checks.visible is not None:
+            copy_tree(challenge.root / manifest.checks.visible, workspace)
+        copy_tree(workspace, meta / "original")
+        readonly(meta / "original")
+        copy_tree(challenge.root / manifest.checks.hidden, meta / "hidden")
+        safe_path(challenge.root / "TICKET.md", directory=False)
+        ticket = (challenge.root / "TICKET.md").read_text(encoding="utf-8")
+        (meta / "TICKET.md").write_text(ticket, encoding="utf-8")
+        (meta / "TICKET.md").chmod(0o600)
+        store.write_json(meta / "manifest.json", manifest.model_dump(mode="json"))
+        if prepared.pack is None:
+            git.initialize(workspace, source=challenge.root)
+        else:
+            git.initialize(workspace, source=challenge.root, inputs=prepared.input_roots)
+        built = sandbox.build_image(
+            challenge.root / manifest.environment.dockerfile, name=manifest.id
+        )
+        record = SessionRecord(
+            challenge_id=manifest.id,
+            challenge_version=manifest.version,
+            source=str(prepared.source_path if prepared.pack else challenge.root),
+            trust="unofficial" if prepared.pack else "local-authored",
+            pack=prepared.pack,
+            image_id=built.image_id,
+            started_at=now(),
+            timer=timer,
+            history_enabled=history,
+        )
+        store.write_json(meta / "session.json", record.model_dump(mode="json"))
+        event = Event(
+            ts=record.started_at, type="session_started", data={"challenge_id": manifest.id}
+        )
+        (meta / "events.jsonl").write_text(event.model_dump_json() + "\n", encoding="utf-8")
+        (meta / "events.jsonl").chmod(0o600)
+        (meta / "lock").touch(mode=0o600)
+        checkpoint = capture(
+            meta,
+            meta / "original",
+            enabled=history,
+            kind="initial",
+            rules=resolve_history_ignores(
+                workspace, source=challenge.root, inputs=prepared.input_roots
+            )
+            if history
+            else None,
+        )
+        store.append_event(meta, "history_recorded", checkpoint.model_dump(mode="json"))
+        return StartedSession(
+            session=partial,
+            workspace=workspace,
+            challenge_id=manifest.id,
+            timer=timer,
+            ticket=ticket,
+            pack=prepared.pack,
+            history=checkpoint,
+        )
+    except BaseException as exc:
+        if partial is not None:
+            remove_partial(partial)
+        if isinstance(exc, OSError | UnicodeError | SandboxError):
+            raise SessionError(
+                "could not start session: filesystem, Git or image build unavailable"
+            ) from exc
+        raise
+
+
+def _sanitized(result: RunResult, duration: float) -> CheckResult:
+    tests = tuple(
+        CheckTest(id="".join(c for c in test.id if c.isprintable())[:240], status=test.status)
+        for test in result.tests
+    )
+    outcome = result.outcome
+    if outcome == RunOutcome.PASSED:
+        if not tests or any(t.status == TestStatus.ERRORED for t in tests):
+            outcome = RunOutcome.ERRORED
+        elif any(t.status != TestStatus.PASSED for t in tests):
+            outcome = RunOutcome.FAILED
+    return CheckResult(
+        outcome=outcome,
+        tests=tests,
+        duration_seconds=duration,
+        limit=result.limit if result.limit in ("timeout", "memory") else None,
+    )
+
+
+def check_session(
+    session: Path | None = None, *, root: Path | None = None, sandbox: Sandbox = engine
+) -> CheckResult:
+    """Check captured input; checkpoint only editable files in private storage."""
+    try:
+        path = store.resolve(session, _root(root))
+        store.load(path)
+        meta = path / ".session"
+        with store.locked(meta):
+            record, manifest, _events = store.load(path)
+            from patchground.sessions.submission import require_active
+
+            require_active(meta)
+            started = time.monotonic()
+            try:
+                # Canonicalize only the system temp parent (e.g. macOS /var),
+                # before creating our private directory; never resolve user trees.
+                with tempfile.TemporaryDirectory(
+                    prefix="patchground-check-",
+                    dir=Path(tempfile.gettempdir()).resolve(strict=True),
+                ) as temp:
+                    editable = Path(temp) / "editable"
+                    clean = Path(temp) / "check"
+                    editable.mkdir()
+                    clean.mkdir()
+                    rules = (
+                        resolve_history_ignores(
+                            path / "workspace",
+                            source=Path(record.source),
+                            inputs=(Path(record.pack.source),)
+                            if record.pack and record.pack.source_kind == "local"
+                            else (),
+                        )
+                        if record.history_enabled
+                        else None
+                    )
+                    copy_tree(path / "workspace", editable)
+                    copy_tree(editable, clean)
+                    copy_tree(meta / "hidden", clean)
+                    raw = sandbox.run_check(
+                        record.image_id, [clean], manifest.environment.test_command
+                    )
+                    result = _sanitized(raw, time.monotonic() - started)
+                    checkpoint = capture(
+                        meta,
+                        editable,
+                        enabled=record.history_enabled,
+                        kind="check",
+                        check_outcome=result.outcome.value,
+                        rules=rules,
+                    )
+                    result = result.model_copy(update={"history": checkpoint})
+            except (SandboxError, OSError, SessionError, KeyboardInterrupt) as exc:
+                store.append_event(
+                    meta,
+                    "check_run",
+                    {
+                        "outcome": "interrupted"
+                        if isinstance(exc, KeyboardInterrupt)
+                        else "environment_error",
+                        "duration_seconds": time.monotonic() - started,
+                    },
+                )
+                raise
+            store.append_event(meta, "check_run", result.model_dump(mode="json"))
+            return result
+    except (OSError, UnicodeError, SandboxError) as exc:
+        raise SessionError(
+            "check unavailable: session storage or frozen image unavailable"
+        ) from exc
+
+
+def session_status(session: Path | None = None, *, root: Path | None = None) -> SessionStatus:
+    """Read session state without Docker, lock creation or any filesystem writes."""
+    try:
+        path = store.resolve(session, _root(root))
+        record, manifest, events = store.load(path)
+        from patchground.sessions.submission import completed
+
+        saved = completed(path / ".session")
+        receipt = saved[1] if saved else None
+        last = next((event for event in reversed(events) if event.type == "check_run"), None)
+        return SessionStatus(
+            session=path,
+            workspace=path / "workspace",
+            challenge_id=record.challenge_id,
+            timer=record.timer,
+            state="submitted" if receipt else "active",
+            submitted_at=receipt.requested_at if receipt else None,
+            elapsed_seconds=max(
+                0.0,
+                ((receipt.requested_at if receipt else now()) - record.started_at).total_seconds(),
+            )
+            if record.timer
+            else 0,
+            timebox_minutes=manifest.timebox_minutes,
+            last_check=receipt.final_check
+            if receipt
+            else store.check_from_event(last)
+            if last
+            else None,
+            last_outcome=receipt.final_check.outcome.value
+            if receipt
+            else str(last.data["outcome"])
+            if last
+            else None,
+        )
+    except (OSError, UnicodeError) as exc:
+        raise SessionError(
+            "status unavailable: invalid session storage or no session selected"
+        ) from exc

patchground/spec/__init__.py

@@ -0,0 +1,35 @@
+"""patchground.spec — see SPEC.md in this folder."""
+
+from patchground.spec._schema import export_schemas
+from patchground.spec.loader import (
+    Challenge,
+    ManifestError,
+    ManifestIssue,
+    Pack,
+    load_challenge,
+    load_pack,
+)
+from patchground.spec.models import (
+    AIPolicy,
+    ChallengeManifest,
+    ChallengeType,
+    Difficulty,
+    PackManifest,
+    Provenance,
+)
+
+__all__ = [
+    "AIPolicy",
+    "Challenge",
+    "ChallengeManifest",
+    "ChallengeType",
+    "Difficulty",
+    "ManifestError",
+    "ManifestIssue",
+    "Pack",
+    "PackManifest",
+    "Provenance",
+    "export_schemas",
+    "load_challenge",
+    "load_pack",
+]