simulo-interfaces 0.1.0__py3-none-any.whl

simulo/interfaces/__init__.py

@@ -0,0 +1,65 @@
+"""Simulo Interfaces — implementation-free contract layer for the Simulo platform.
+
+Torch-free, zero-runtime-dependency (Rule #11). Importable on a laptop with no
+torch / numpy / gymnasium / Isaac / AWS / HTTP / DB installed. Two parts:
+
+* **Part A — ``simulo.interfaces.runtime``**: tensor-library-agnostic structural
+  Protocols mirroring the ``simulo.core`` runtime surface (Task, Policy,
+  Trainer, Player, LearningEnv, Scenario, and the observation/reward/termination
+  components).
+* **Part B — ``simulo.interfaces.platform``**: platform/workspace domain
+  contracts — wire-stable enums, frozen domain dataclasses (Project, Package,
+  Job, Resource, Checkpoint, TrainedModel, Tag), and the cloud-execution
+  Protocols (App, Runtime, Asset, Volume, callbacks, and
+  debug/replay/visualization sessions).
+
+This package contributes ``simulo.interfaces.*`` to the shared ``simulo`` PEP 420
+namespace that ``simulo-backend`` also contributes to; it ships NO
+``src/simulo/__init__.py``.
+"""
+
+from simulo.interfaces import platform, runtime
+from simulo.interfaces.exceptions import (
+    ContractViolationError,
+    ImportResolutionError,
+    JobFailedError,
+    ResourceNotFoundError,
+    ResumeIncompatibleError,
+    SimuloError,
+)
+from simulo.interfaces.ids import (
+    CheckpointId,
+    Digest,
+    JobId,
+    OrganizationId,
+    PackageId,
+    ProjectId,
+    ResourceId,
+    ResourceUri,
+    TagId,
+    TrainedModelId,
+)
+
+__all__ = [
+    # subpackages
+    "platform",
+    "runtime",
+    # exception hierarchy
+    "SimuloError",
+    "ContractViolationError",
+    "ImportResolutionError",
+    "ResourceNotFoundError",
+    "ResumeIncompatibleError",
+    "JobFailedError",
+    # identifiers
+    "OrganizationId",
+    "ProjectId",
+    "PackageId",
+    "JobId",
+    "ResourceId",
+    "CheckpointId",
+    "TrainedModelId",
+    "TagId",
+    "ResourceUri",
+    "Digest",
+]

simulo/interfaces/exceptions.py

@@ -0,0 +1,31 @@
+"""Shared Simulo contract exception hierarchy.
+
+Implementation-free (Rule #11): no I/O, no heavy deps. These types are the
+common error vocabulary the thin ``simulo`` client and the ``simulo-backend``
+GPU SDK both raise/catch when a contract is violated.
+"""
+
+
+class SimuloError(Exception):
+    """Root of the shared Simulo contract exception hierarchy."""
+
+
+class ContractViolationError(SimuloError):
+    """An object failed to satisfy a Simulo contract/Protocol."""
+
+
+class ImportResolutionError(SimuloError):
+    """A deferred ``runtime.imports()`` symbol was used in local discovery mode
+    without a resolved cloud import (Rule #3)."""
+
+
+class ResourceNotFoundError(SimuloError):
+    """``from_registry()``/``from_name()`` could not resolve a resource/volume (Rule #6)."""
+
+
+class ResumeIncompatibleError(SimuloError):
+    """A discovered checkpoint is incompatible with the current job (Rule #9)."""
+
+
+class JobFailedError(SimuloError):
+    """A submitted job terminated in ``JobStatus.FAILED``."""

simulo/interfaces/ids.py

@@ -0,0 +1,21 @@
+"""Strongly-typed string identifiers for the platform domain model (Part B).
+
+``NewType`` aliases — zero runtime cost (each is the underlying ``str`` at
+runtime) but distinct to the type checker, so a ``ProjectId`` can never be
+passed where a ``JobId`` is expected.
+"""
+
+from typing import NewType
+
+OrganizationId = NewType("OrganizationId", str)
+ProjectId = NewType("ProjectId", str)
+PackageId = NewType("PackageId", str)
+JobId = NewType("JobId", str)
+ResourceId = NewType("ResourceId", str)
+CheckpointId = NewType("CheckpointId", str)
+TrainedModelId = NewType("TrainedModelId", str)
+TagId = NewType("TagId", str)
+ResourceUri = NewType("ResourceUri", str)  # e.g. "robot/so-arm-100:v3"
+Digest = NewType("Digest", str)  # content-addressed package source digest
+RecordingId = NewType("RecordingId", str)  # a job-produced MCAP recording (PR-0 wire contract)
+WorkerId = NewType("WorkerId", str)  # a claiming worker process (PR-0 wire contract)

simulo/interfaces/platform/__init__.py

@@ -0,0 +1,120 @@
+"""Part B — platform/workspace domain contracts.
+
+Wire-stable enums, frozen domain dataclasses (Project, Package, Job, Resource,
+Checkpoint, TrainedModel, Tag), and the cloud-execution Protocols (App, Runtime,
+Asset, Volume, job callbacks, and debug/replay/visualization sessions). All
+implementation-free (Rule #11) — concrete behaviour lives in the future
+``simulo`` client and the ``simulo-backend`` SDK.
+"""
+
+from simulo.interfaces.platform.app import AppProtocol, JobFunctionProtocol, Mount
+from simulo.interfaces.platform.asset import AssetProtocol
+from simulo.interfaces.platform.callbacks import JobCallbackProtocol
+from simulo.interfaces.platform.debug import DebugSessionProtocol, ReplaySessionProtocol, VisualizationSessionProtocol
+from simulo.interfaces.platform.domain import Checkpoint, Job, Package, Project, Resource, Tag, TrainedModel
+from simulo.interfaces.platform.enums import ArtifactKind, JobStatus, ResourceKind, ResumePolicy
+from simulo.interfaces.platform.runs import (
+    JOB_LOGS_ROUTE_TEMPLATE,
+    JOB_RESULT_ROUTE_TEMPLATE,
+    JOB_ROUTE_TEMPLATE,
+    JOBS_API_DEFAULT_PORT,
+    JOBS_ROUTE,
+    LOG_CHUNK_MAX_BYTES,
+    TERMINAL_JOB_STATUSES,
+    JobRecord,
+)
+from simulo.interfaces.platform.runtime import RuntimeProtocol
+from simulo.interfaces.platform.submit import (
+    JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_MODEL_ROUTE_TEMPLATE,
+    JOB_MODELS_ROUTE_TEMPLATE,
+    JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE,
+    JOB_RECORDINGS_ROUTE_TEMPLATE,
+    MAX_COMPLETE_MESSAGE_CHARS,
+    MAX_COMPLETE_REASON_CODE_CHARS,
+    MAX_LOG_CHUNK_BYTES,
+    MAX_LOG_TOTAL_BYTES,
+    MAX_PACKAGE_BYTES,
+    MAX_RESULT_BYTES,
+    MODEL_KINDS,
+    PACKAGE_ARCHIVE_ROUTE_TEMPLATE,
+    PACKAGES_ROUTE,
+    RESERVED_RUNTIME_ENV_KEYS,
+    RESERVED_RUNTIME_ENV_PREFIXES,
+    WORKER_CLAIM_ROUTE,
+    WORKER_JOB_COMPLETE_ROUTE_TEMPLATE,
+    WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE,
+    WORKER_JOB_LOGS_ROUTE_TEMPLATE,
+    WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_MODELS_ROUTE_TEMPLATE,
+    WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE,
+    WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE,
+    WORKER_LEASE_HEADER,
+    ModelRecord,
+    RecordingRecord,
+)
+from simulo.interfaces.platform.volume import VolumeProtocol
+
+__all__ = [
+    # enums
+    "JobStatus",
+    "ResumePolicy",
+    "ResourceKind",
+    "ArtifactKind",
+    # domain dataclasses
+    "Tag",
+    "Project",
+    "Package",
+    "Resource",
+    "Job",
+    "Checkpoint",
+    "TrainedModel",
+    # job-run contract (run record schema + jobs HTTP API shape)
+    "JobRecord",
+    "TERMINAL_JOB_STATUSES",
+    "JOBS_API_DEFAULT_PORT",
+    "JOBS_ROUTE",
+    "JOB_ROUTE_TEMPLATE",
+    "JOB_LOGS_ROUTE_TEMPLATE",
+    "JOB_RESULT_ROUTE_TEMPLATE",
+    "LOG_CHUNK_MAX_BYTES",
+    # submit / worker / recordings wire contract (PR-0)
+    "PACKAGES_ROUTE",
+    "PACKAGE_ARCHIVE_ROUTE_TEMPLATE",
+    "JOB_RECORDINGS_ROUTE_TEMPLATE",
+    "JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE",
+    "JOB_MODELS_ROUTE_TEMPLATE",
+    "JOB_MODEL_ROUTE_TEMPLATE",
+    "JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE",
+    "WORKER_CLAIM_ROUTE",
+    "WORKER_JOB_LOGS_ROUTE_TEMPLATE",
+    "WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE",
+    "WORKER_JOB_COMPLETE_ROUTE_TEMPLATE",
+    "WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE",
+    "WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE",
+    "WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE",
+    "WORKER_JOB_MODELS_ROUTE_TEMPLATE",
+    "WORKER_LEASE_HEADER",
+    "MAX_PACKAGE_BYTES",
+    "MAX_LOG_CHUNK_BYTES",
+    "MAX_LOG_TOTAL_BYTES",
+    "MAX_RESULT_BYTES",
+    "MAX_COMPLETE_MESSAGE_CHARS",
+    "MAX_COMPLETE_REASON_CODE_CHARS",
+    "MODEL_KINDS",
+    "ModelRecord",
+    "RecordingRecord",
+    "RESERVED_RUNTIME_ENV_KEYS",
+    "RESERVED_RUNTIME_ENV_PREFIXES",
+    # protocols
+    "RuntimeProtocol",
+    "AssetProtocol",
+    "VolumeProtocol",
+    "JobCallbackProtocol",
+    "JobFunctionProtocol",
+    "AppProtocol",
+    "Mount",
+    "DebugSessionProtocol",
+    "ReplaySessionProtocol",
+    "VisualizationSessionProtocol",
+]

simulo/interfaces/platform/app.py

@@ -0,0 +1,47 @@
+"""User-facing job-container Protocols (Part B) — ``App`` / ``@app.job`` surface."""
+
+from typing import Callable, Mapping, Optional, Protocol, Sequence, TypeVar, Union, overload, runtime_checkable
+
+from simulo.interfaces.ids import JobId
+from simulo.interfaces.platform.asset import AssetProtocol
+from simulo.interfaces.platform.callbacks import JobCallbackProtocol
+from simulo.interfaces.platform.enums import ResumePolicy
+from simulo.interfaces.platform.runtime import RuntimeProtocol
+from simulo.interfaces.platform.volume import VolumeProtocol
+
+F = TypeVar("F", bound=Callable[..., object])
+Mount = Union[AssetProtocol, VolumeProtocol]
+
+
+@runtime_checkable
+class JobFunctionProtocol(Protocol):
+    """What ``@app.job`` returns: the user's original function, wrapped (Rule #1 — source-preserving). FORWARD."""
+
+    def __call__(self, *args: object, **kwargs: object) -> object: ...
+    def submit(self, *args: object, **kwargs: object) -> JobId: ...
+
+
+@runtime_checkable
+class AppProtocol(Protocol):
+    """User-facing job container: ``app = simulo.App(name, runtime=, mounts={...})``. FORWARD."""
+
+    @property
+    def name(self) -> str: ...
+    @property
+    def runtime(self) -> RuntimeProtocol: ...
+    @property
+    def mounts(self) -> Mapping[str, Mount]: ...
+    @overload
+    def job(self, fn: F) -> JobFunctionProtocol: ...
+    @overload
+    def job(
+        self, *, callbacks: Sequence[JobCallbackProtocol] = ..., resume: ResumePolicy = ...
+    ) -> Callable[[F], JobFunctionProtocol]: ...
+    def job(
+        self,
+        fn: Optional[F] = None,
+        *,
+        callbacks: Sequence[JobCallbackProtocol] = (),
+        resume: ResumePolicy = ResumePolicy.AUTO,
+    ) -> Union[JobFunctionProtocol, Callable[[F], JobFunctionProtocol]]: ...
+    def local_entrypoint(self, fn: F) -> F: ...

simulo/interfaces/platform/asset.py

@@ -0,0 +1,15 @@
+"""``AssetProtocol`` — read-only mounted cloud resource handle (Part B, Rule #6)."""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AssetProtocol(Protocol):
+    """Read-only mounted cloud resource handle (Rule #6). FORWARD.
+
+    Distinct from ``simulo.core.asset.Asset`` (a USD/URDF simulation asset).
+    """
+
+    @classmethod
+    def from_registry(cls, uri: str) -> "AssetProtocol": ...
+    def read_only(self) -> "AssetProtocol": ...

simulo/interfaces/platform/callbacks.py

@@ -0,0 +1,17 @@
+"""Job lifecycle callback marker contract (Part B)."""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class JobCallbackProtocol(Protocol):
+    """Marker contract for job lifecycle callbacks passed to ``@app.job(callbacks=...)``.
+
+    Concrete callbacks (ResumableCheckpoint, CommitVolume, DebugOnAnomaly) are
+    implemented in the future ``simulo`` package. FORWARD. All hooks optional.
+    """
+
+    def on_job_start(self, job_id: str) -> None: ...
+    def on_checkpoint(self, checkpoint_uri: str, step: int) -> None: ...
+    def on_anomaly(self, detail: str) -> None: ...
+    def on_job_end(self, job_id: str, status: str) -> None: ...

simulo/interfaces/platform/debug.py

@@ -0,0 +1,31 @@
+"""Remote debug / replay / visualization session Protocols (Part B, Rule #10)."""
+
+from contextlib import AbstractContextManager
+from typing import Protocol, runtime_checkable
+
+from simulo.interfaces.ids import JobId
+
+
+@runtime_checkable
+class DebugSessionProtocol(Protocol):
+    """Remote attach/breakpoint/shell session (Rule #10). FORWARD."""
+
+    @property
+    def job_id(self) -> JobId: ...
+    def attach(self) -> AbstractContextManager[None]: ...
+
+
+@runtime_checkable
+class ReplaySessionProtocol(Protocol):
+    """Replay of a recorded run (Rule #10). FORWARD."""
+
+    @property
+    def job_id(self) -> JobId: ...
+
+
+@runtime_checkable
+class VisualizationSessionProtocol(Protocol):
+    """Cloud visualization runtime session (Rule #10). FORWARD."""
+
+    @property
+    def job_id(self) -> JobId: ...

simulo/interfaces/platform/domain.py

@@ -0,0 +1,118 @@
+"""Platform domain dataclasses — the workspace object model (Part B).
+
+Frozen, slotted, keyword-only value objects shared by the thin ``simulo`` client
+and the ``simulo-backend`` SDK. Implementation-free (Rule #11): no behaviour, no
+I/O, no persistence — these mirror the records the control plane owns.
+
+Domain invariants encoded here:
+
+* **Rule #5** — ``Package`` (immutable, content-addressed source archive) and
+  ``Job`` (one execution of a package) are distinct; a ``Job`` references its
+  ``Package`` by id, never the other way around.
+* **Rule #6** — ``Resource`` is a read-only, versioned, registry-resolved mount
+  (robot / environment / dataset / …); it is NOT a package.
+* **Rule #7** — ``Project`` is the workspace anchor every other object hangs off.
+* **Rule #8** — ``Checkpoint`` (intermediate training artifact) and
+  ``TrainedModel`` (final, deployable model) are separate types — never collapse.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, Tuple
+
+from simulo.interfaces.ids import (
+    CheckpointId,
+    Digest,
+    JobId,
+    OrganizationId,
+    PackageId,
+    ProjectId,
+    ResourceId,
+    ResourceUri,
+    TagId,
+    TrainedModelId,
+)
+from simulo.interfaces.platform.enums import JobStatus, ResourceKind, ResumePolicy
+
+# Shared dataclass options: immutable value objects (frozen), memory-lean
+# (slots), and keyword-only construction (kw_only) so positional drift across
+# the client/SDK boundary is impossible.
+_DC = {"frozen": True, "slots": True, "kw_only": True}
+
+
+@dataclass(**_DC)
+class Tag:
+    """A key/value (value optional) label attachable to workspace objects."""
+
+    id: TagId
+    key: str
+    value: Optional[str] = None
+
+
+@dataclass(**_DC)
+class Project:
+    """Workspace anchor (Rule #7) — every other domain object hangs off a project."""
+
+    id: ProjectId
+    organization_id: OrganizationId
+    name: str
+    slug: str
+    created_at: datetime
+    tags: Tuple[TagId, ...] = field(default_factory=tuple)
+
+
+@dataclass(**_DC)
+class Package:
+    """Immutable, content-addressed source archive (Rule #5)."""
+
+    id: PackageId
+    project_id: ProjectId
+    digest: Digest
+    created_at: datetime
+
+
+@dataclass(**_DC)
+class Resource:
+    """Read-only, versioned, registry-resolved mount (Rule #6) — not a package."""
+
+    id: ResourceId
+    project_id: ProjectId
+    uri: ResourceUri
+    kind: ResourceKind
+    version: str
+    read_only: bool = True
+
+
+@dataclass(**_DC)
+class Job:
+    """One execution of a package (Rule #5 lineage) — references its package by id."""
+
+    id: JobId
+    project_id: ProjectId
+    package_id: PackageId
+    status: JobStatus
+    resume_policy: ResumePolicy = ResumePolicy.AUTO
+    created_at: Optional[datetime] = None
+
+
+@dataclass(**_DC)
+class Checkpoint:
+    """Intermediate training artifact (Rule #8) — distinct from a TrainedModel."""
+
+    id: CheckpointId
+    job_id: JobId
+    step: int
+    uri: ResourceUri
+    created_at: Optional[datetime] = None
+
+
+@dataclass(**_DC)
+class TrainedModel:
+    """Final, deployable model artifact (Rule #8) — distinct from a Checkpoint."""
+
+    id: TrainedModelId
+    project_id: ProjectId
+    job_id: JobId
+    uri: ResourceUri
+    format: str
+    created_at: Optional[datetime] = None

simulo/interfaces/platform/enums.py

@@ -0,0 +1,49 @@
+"""Wire-stable platform enums (Part B).
+
+Enum *values* are a stable wire ABI: append-only, never renumber or rename. The
+thin client and the SDK both serialize/deserialize against these strings.
+"""
+
+from enum import StrEnum
+
+
+class JobStatus(StrEnum):
+    """Lifecycle state of a submitted job."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class ResumePolicy(StrEnum):
+    """How a job resumes from a discovered checkpoint (Rule #9)."""
+
+    AUTO = "auto"
+    NEVER = "never"
+    MANUAL = "manual"
+
+
+class ResourceKind(StrEnum):
+    """Kind of a registry-resolved, read-only resource mount (Rule #6)."""
+
+    ROBOT = "robot"
+    ENVIRONMENT = "environment"
+    DATASET = "dataset"
+    REPLAY_INPUT = "replay_input"
+    EVAL_ASSET = "eval_asset"
+    CHECKPOINT = "checkpoint"
+    TRAINED_MODEL = "trained_model"
+    CONFIG = "config"
+
+
+class ArtifactKind(StrEnum):
+    """Kind of a job-produced artifact. Rule #8 — a checkpoint is NOT a trained model."""
+
+    MODEL_CHECKPOINT = "model_checkpoint"
+    TRAINED_MODEL = "trained_model"
+    LOG = "log"
+    METRIC = "metric"
+    REPLAY_OUTPUT = "replay_output"
+    EVALUATION_OUTPUT = "evaluation_output"

simulo/interfaces/platform/runs.py

@@ -0,0 +1,112 @@
+"""Job-run contract — the run-record schema and the jobs HTTP API shape (Part B).
+
+This module is the DURABLE contract between the executor side (which records runs
+and serves them — today ``simulo-backend run-package`` + ``simulo-backend serve``,
+the local stand-ins; eventually the cloud worker + control plane) and the thin
+``simulo`` client (``simulo jobs`` / ``simulo logs`` / ``simulo result``, which
+talk HTTP only — never the run store on disk). Implementation-free (Rule #11):
+schema, enum reuse, endpoint constants, and semantics docstrings only.
+
+Field names and lifecycle align with ``context/use-cases/Job.md``: a job is one
+managed execution of exactly one package, with lifecycle states drawn from
+:class:`~simulo.interfaces.platform.enums.JobStatus` (``queued``/``running``/
+``completed``/``failed``/``cancelled`` — Job.md's wording; the local executor
+uses the ``running`` → ``completed``|``failed`` subset, the cloud adds
+``queued``/``cancelled``).
+
+HTTP API shape (all responses JSON; all timestamps ISO 8601 UTC, e.g.
+``2026-07-03T12:00:00Z``):
+
+* ``GET /v1/jobs?page=1&limit=20`` — list job records, most recent first
+  (``created_at`` descending). Paginated envelope::
+
+      {"items": [<JobRecord>, ...], "total": 3, "page": 1, "limit": 20, "pages": 1}
+
+  ``limit`` defaults to 20, maximum 100; out-of-range ``page``/``limit`` → 422.
+* ``GET /v1/jobs/{job_id}`` — one job record (the :class:`JobRecord` fields).
+* ``GET /v1/jobs/{job_id}/logs?offset=N`` — one log chunk::
+
+      {"chunk": "<text>", "next_offset": 4096, "status": "running"}
+
+  **Offset semantics:** ``offset`` is a BYTE offset into the job's log stream
+  (``offset=0`` is the start). The server returns at most
+  :data:`LOG_CHUNK_MAX_BYTES` bytes per request (it may return fewer, e.g. to
+  avoid splitting a multi-byte UTF-8 character); the client resumes from the
+  returned ``next_offset``. A reconnect is just "resume from your offset". An
+  offset at or beyond end-of-log yields an empty ``chunk`` with
+  ``next_offset == offset``; the accompanying ``status`` tells the client
+  whether more output may still arrive (poll while the status is
+  non-terminal, stop once it is in :data:`TERMINAL_JOB_STATUSES`).
+* ``GET /v1/jobs/{job_id}/result`` — the job's result JSON object. 404 (code
+  ``result_not_available``) until the job has completed successfully.
+
+**Scoping (evolves toward the cloud):** every route above is UNSCOPED locally
+— there is no project/org filter because the local stand-in has exactly one
+run store and one caller. The real control plane scopes ``GET /v1/jobs`` (and
+the per-job routes) to the caller's authenticated organization/project, via
+query parameters (e.g. ``?project_id=...``) and/or the auth context resolved
+from the request's bearer token — never a client-supplied trust boundary.
+That scoping is additive at the transport layer: the :class:`JobRecord`
+fields and route shapes defined here do not change, only the server-side
+filtering they are evaluated under.
+
+Errors use the platform-standard shape (NFR contract)::
+
+    {"error": {"code": "job_not_found", "message": "...", "request_id": "req_..."}}
+
+Unknown ``job_id`` → 404 ``job_not_found``.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from simulo.interfaces.ids import JobId, PackageId
+from simulo.interfaces.platform.enums import JobStatus
+
+#: Default TCP port for the jobs API. Locally this is where ``simulo-backend
+#: serve`` listens (127.0.0.1 only) and where the thin client points when
+#: ``SIMULO_API_URL`` is unset (``http://127.0.0.1:8765``).
+JOBS_API_DEFAULT_PORT = 8765
+
+#: ``GET`` — list job records (paginated, most recent first).
+JOBS_ROUTE = "/v1/jobs"
+#: ``GET`` — one job record. ``.format(job_id=...)``.
+JOB_ROUTE_TEMPLATE = "/v1/jobs/{job_id}"
+#: ``GET`` — one log chunk by byte offset (``?offset=N``). ``.format(job_id=...)``.
+JOB_LOGS_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/logs"
+#: ``GET`` — the result JSON of a successfully completed job. ``.format(job_id=...)``.
+JOB_RESULT_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/result"
+
+#: Upper bound on the log bytes a single ``/logs`` response carries. The server
+#: may return fewer bytes (never more); clients keep reading from ``next_offset``.
+LOG_CHUNK_MAX_BYTES = 64 * 1024
+
+#: Statuses after which a job's log stream and record no longer change. A log
+#: follower drains the remaining bytes and stops once the status is terminal.
+TERMINAL_JOB_STATUSES = frozenset({JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class JobRecord:
+    """One recorded run of a packaged job — the wire schema of a job record.
+
+    This is the JSON object stored per run and returned by ``GET /v1/jobs`` /
+    ``GET /v1/jobs/{job_id}``. Timestamps are ISO 8601 UTC strings (wire-shaped
+    by construction so ``dataclasses.asdict`` serializes directly; ``status`` is
+    a :class:`~simulo.interfaces.platform.enums.JobStatus` ``StrEnum`` and
+    JSON-encodes as its string value).
+    """
+
+    job_id: JobId
+    package_id: PackageId
+    job_name: str
+    status: JobStatus
+    created_at: str
+    args: Mapping[str, Any] = field(default_factory=dict)
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+    #: Process exit code of the run (0 on success). ``None`` while running.
+    exit_code: Optional[int] = None
+    #: Number of execution attempts started so far (retries make this > 1).
+    attempts: int = 0

simulo/interfaces/platform/runtime.py

@@ -0,0 +1,19 @@
+"""``RuntimeProtocol`` — cloud runtime envelope contract (Part B, Rule #4)."""
+
+from contextlib import AbstractContextManager
+from typing import Mapping, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RuntimeProtocol(Protocol):
+    """Cloud runtime envelope (Rule #4). FORWARD.
+
+    ``imports()`` is the real remote-only-import boundary (Rule #3): locally it
+    records deferred import intent; in the cloud it resolves the real imports.
+    Heavy imports (torch / Isaac / …) live ONLY inside this context manager.
+    """
+
+    @classmethod
+    def from_registry(cls, image: str) -> "RuntimeProtocol": ...
+    def env(self, variables: Mapping[str, str]) -> "RuntimeProtocol": ...
+    def imports(self) -> AbstractContextManager[None]: ...