simulo-interfaces 0.1.0__py3-none-any.whl

simulo/interfaces/platform/submit.py

@@ -0,0 +1,538 @@
+"""Submit / worker / recordings wire contract (Cloud Submit Wave, PR-0).
+
+This is the **canonical, single source of truth** for the routes that carry a
+package from the laptop client to the cloud, hand it to a worker, and return
+logs/result/recordings to the client. It reconciles the design tracks in the
+cloud-submit plan (`context/decisions.md`, Cloud Submit Wave) and lands
+**before any consumer** — the control plane (client + `/internal/worker/*`
+routes), the thin `simulo` client (`_client/submit_api.py`), and the worker
+loop (`simulo-backend worker`) all implement against this module, not the
+other way around. Implementation-free (Rule #11): route constants, size caps,
+a wire dataclass, reserved-env constants, and semantics docstrings only — no
+HTTP client, no server, no I/O.
+
+**Zero changes to the existing job contract.** The four `GET /v1/jobs*`
+routes and :class:`~simulo.interfaces.platform.runs.JobRecord` in
+``runs.py`` are untouched by this module — ``POST /v1/jobs`` (defined here)
+reuses the *same* route string as ``runs.JOBS_ROUTE`` (``"/v1/jobs"``; POST
+creates, GET lists) and returns the *same* :class:`~simulo.interfaces.platform.runs.JobRecord`
+shape. Scoping (org/project) is server-side and additive, exactly as
+documented in ``runs.py``.
+
+Trust zones (three bearer schemes on the wire; see the Cloud Submit Wave plan
+architecture section for the full picture):
+
+* **Client-facing `/v1/...`** — bearer = the user's Cognito JWT;
+  ``require_active_org`` is enforced server-side. These are the routes a
+  human's ``simulo`` CLI/SDK calls.
+* **Worker-facing `/internal/worker/...`** — bearer = a single static
+  ``WORKER_TOKEN`` (constant-time compare on the server, never logged). Empty
+  server-side config disables every ``/internal/worker/*`` route
+  fail-closed — there is no "auth disabled" state for these routes.
+* **Presigned URLs** (`download_url` / `upload_url` fields below) carry their
+  own auth (S3 SigV4 query params, or a control-plane-served one-time token
+  when running on the local storage backend) — a caller must send the
+  ``Authorization`` bearer header *only* when the URL's host equals the API
+  host. Sending the API bearer to a presigned S3 host is both unnecessary and
+  a credential-leakage risk; this is a client/worker implementation rule, not
+  a wire shape, so it is documented here rather than encoded as a dataclass.
+
+All timestamps are ISO 8601 UTC strings (e.g. ``"2026-07-03T12:00:00Z"``),
+matching ``runs.py`` and the platform NFR contract. Errors use the
+platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id": ...}}``.
+
+---
+
+## Client-facing: package submit + job create
+
+* ``POST /v1/packages`` — register a content-addressed package before
+  uploading its bytes. Request body::
+
+      {"package_id": "...", "source_digest": "sha256:...",
+       "job_name": "train_cartpole", "archive_sha256": "sha256:...",
+       "archive_size": 123456}
+
+  Response ``200``::
+
+      {"package_id": "...", "upload": {"mode": "direct"}}
+
+  The ``upload`` envelope is forward-compatible: today the only mode is
+  ``"direct"`` (the client ``PUT``s the tar to
+  :data:`PACKAGE_ARCHIVE_ROUTE_TEMPLATE` itself). A future ``"presigned"``
+  mode (client ``PUT``s straight to S3) is an **additive** variant of this
+  same envelope — the ``package_id`` field and the ``POST`` request body
+  never change.
+
+* ``PUT /v1/packages/{package_id}/archive`` — the raw tar bytes (request
+  body is the archive, not JSON). Idempotent: if the content-addressed
+  ``package_id`` already has an archive stored, a repeat ``PUT`` is a no-op
+  (``200``, bytes discarded) rather than an error — packaging the same
+  source twice is a client-retry, not a conflict. ``413`` (over
+  :data:`MAX_PACKAGE_BYTES`) and ``422`` (uploaded bytes' digest does not
+  match the registered ``archive_sha256``) are the only failure modes.
+
+* ``POST /v1/jobs`` — reuses ``runs.JOBS_ROUTE`` (``"/v1/jobs"``; see the
+  module docstring above). Request body::
+
+      {"package_id": "...", "job_name": "train_cartpole", "args": {...}}
+
+  Response ``201`` — a :class:`~simulo.interfaces.platform.runs.JobRecord`
+  with ``status`` :attr:`~simulo.interfaces.platform.enums.JobStatus.QUEUED`.
+  **Idempotent replay:** a second ``POST`` with the same ``package_id`` while
+  a job for that package is still ``queued`` or ``running`` returns ``200``
+  with the *existing* record rather than creating a second job — a client
+  retry (e.g. after a dropped response) must not double-submit.
+
+## Client-facing: recordings
+
+* :data:`JOB_RECORDINGS_ROUTE_TEMPLATE` (``GET``) — paginated envelope of
+  :class:`RecordingRecord`, same pagination shape as ``GET /v1/jobs``::
+
+      {"items": [<RecordingRecord>, ...], "total": 2, "page": 1, "limit": 20, "pages": 1}
+
+* :data:`JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE` (``GET``) — resolves one
+  recording to a short-lived download link. Response::
+
+      {"url": "https://...", "expires_at": "2026-07-03T13:00:00Z"}
+
+  Org/project membership is re-checked on **this** request (Data Model §12)
+  — a recording's presence in a prior list response is not itself
+  authorization to download it. On staging this is a presigned S3 GET; on
+  the local storage backend it is a control-plane-served URL with its own
+  short-lived, single-use token.
+
+## Worker-facing (`/internal/worker/*`)
+
+* :data:`WORKER_CLAIM_ROUTE` (``POST``) — request ``{"worker_id": "..."}``.
+  Response ``200``::
+
+      {"job": <JobRecord>,
+       "package": {"download_url": "...", "tar_sha256": "sha256:...", "size_bytes": 123456},
+       "lease_seconds": 300,
+       "lease_id": "5e0c4a4e-..."}
+
+  or ``204`` with an empty body when there is no queued work. A claim is one
+  atomic ``SELECT ... FOR UPDATE SKIP LOCKED`` transition of exactly one
+  ``queued`` job to ``running`` — plus a status event, ``attempts += 1``, and
+  a fresh lease. Two workers racing the same claim never both win.
+
+  ``lease_id`` (lease-reaper wave, additive) is the **per-claim ownership
+  token**: a fresh server-generated opaque id stamped on the job row by this
+  claim. The worker must present it back on every subsequent job-scoped call
+  (heartbeat / logs / complete) in the :data:`WORKER_LEASE_HEADER` request
+  header — it is what distinguishes "the worker holding the CURRENT claim"
+  from "a worker that once held a claim on this job_id". A call whose
+  presented lease does not match the job's current one (the job was reaped
+  after a lease expiry and reclaimed — possibly by another worker) is
+  rejected ``409 lease_lost``; the losing worker must abort its subprocess
+  and stop reporting for that job.
+
+  **Lease expiry / reaper semantics:** the lease is the job's liveness
+  signal. A ``running`` job whose lease has expired is *reaped* by the
+  server (the reap runs inside the claim path, so any worker's next claim
+  heals the queue): while the job has attempts left it transitions back to
+  ``queued`` (status event ``reason_code="lease_expired"``) for retry —
+  the next claim re-runs it with a fresh ``lease_id`` and ``attempts + 1``;
+  once attempts are exhausted it transitions terminally to ``failed``
+  (``reason_code="lease_expired_max_attempts"``). Expiry is enforced at
+  REAP time, not at heartbeat time: a heartbeat/complete presenting the
+  MATCHING lease of an expired-but-not-yet-reaped claim still succeeds
+  (the worker was merely slow — reviving is strictly better than killing
+  a live run), because the atomic ``lease_id`` swap at reclaim is what
+  fences out a stale worker, not the wall clock.
+
+* :data:`WORKER_JOB_LOGS_ROUTE_TEMPLATE` (``POST``, ``?offset=N``) — request
+  body is raw log bytes (not JSON), capped at :data:`MAX_LOG_CHUNK_BYTES` per
+  call. ``offset`` is the byte offset the worker believes the server is at
+  (mirrors the client-side ``GET .../logs?offset=N`` semantics in
+  ``runs.py``, from the writer's side):
+
+  - ``offset == <server's current total>`` — append normally.
+  - ``offset < <server's current total>`` — a duplicate resend (e.g. a
+    retried request whose first attempt actually landed); the server drops
+    the (already-applied) bytes and returns its current total — not an
+    error.
+  - ``offset > <server's current total>`` — a gap (a lost chunk in between);
+    ``409`` ``log_offset_gap`` with the server's actual total so the worker
+    resyncs and resends from the correct offset.
+
+  Total accumulated log bytes for a job are capped at
+  :data:`MAX_LOG_TOTAL_BYTES`; once reached, further chunks are rejected
+  (job output past the cap is truncated, not the job).
+
+  Ownership: the request must carry the claim's ``lease_id`` in
+  :data:`WORKER_LEASE_HEADER` (the body is raw bytes, so the header is the
+  only channel). A stale lease is ``409 lease_lost`` — a reaped worker can
+  never append into the stream a later attempt now owns.
+
+* :data:`WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE` (``POST``) — no request body
+  required; extends the claim lease. The request carries the claim's
+  ``lease_id`` in :data:`WORKER_LEASE_HEADER`; a stale lease is ``409
+  lease_lost`` — the signal the losing worker uses to abort its subprocess
+  (the same abort plumbing the ``cancelled`` seam drives). Response
+  ``{"cancelled": false}`` — the seam a future ``simulo cancel`` uses to
+  signal the worker to stop (always ``false`` today; no cancellation path
+  exists yet).
+
+* :data:`WORKER_JOB_COMPLETE_ROUTE_TEMPLATE` (``POST``) — request::
+
+      {"status": "completed", "exit_code": 0,
+       "reason_code": null, "message": null, "result": {...}}
+
+  ``status`` is :attr:`~simulo.interfaces.platform.enums.JobStatus.COMPLETED`
+  or :attr:`~simulo.interfaces.platform.enums.JobStatus.FAILED` — a terminal
+  status. ``reason_code`` and ``message`` are optional (used on failure);
+  ``result`` is the job's result JSON object (present only on success,
+  capped at :data:`MAX_RESULT_BYTES`). The server validates the job's
+  current status is ``running`` (any other current status is ``409
+  invalid_transition`` — a job cannot complete twice) AND that the request's
+  :data:`WORKER_LEASE_HEADER` matches the job's current ``lease_id``
+  (mismatch is ``409 lease_lost`` — a worker whose lease was reaped cannot
+  complete, or overwrite the result of, a job another worker has since
+  claimed). On success the server best-effort flattens the accumulated log
+  chunks to durable storage; a flatten failure does not fail the
+  ``complete`` call.
+
+* :data:`WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE` (``POST``) — request
+  ``{"size_bytes": 123456}``. Response::
+
+      {"recording_id": "...", "upload_url": "...", "storage_uri": "..."}
+
+  The worker then ``PUT``s the MCAP bytes directly to ``upload_url``.
+
+* :data:`WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE` (``POST``) — finalizes a
+  presigned upload once the worker's ``PUT`` has succeeded. Request is the
+  :class:`RecordingRecord` fields the worker knows about the recording it
+  just uploaded (``recording_id``, ``name``, ``digest_sha256``,
+  ``schema_version``, ``profile``, and the optional episode-summary fields);
+  the server verifies the uploaded object exists (and, where the storage
+  backend supports it, matches ``digest_sha256``) before inserting the
+  ``job_recordings`` row. Response ``201`` — the persisted
+  :class:`RecordingRecord`.
+
+## Client-facing: models (trained-checkpoint retrieval)
+
+The exact analogue of the recordings surface, for the ``.pt`` policy
+checkpoints a training job leaves in its result's ``checkpoint_dir``
+(Data Model §4.6 Model; ``best.pt`` / ``latest.pt`` — see the
+``simulo.checkpoint.v1`` sidecar schema). Non-training jobs simply have no
+models; the list is empty, never an error.
+
+* :data:`JOB_MODELS_ROUTE_TEMPLATE` (``GET``) — paginated envelope of
+  :class:`ModelRecord`, same pagination shape as ``GET /v1/jobs``::
+
+      {"items": [<ModelRecord>, ...], "total": 2, "page": 1, "limit": 20, "pages": 1}
+
+* :data:`JOB_MODEL_ROUTE_TEMPLATE` (``GET``) — one :class:`ModelRecord`
+  (Job.md "Retrieve Model Information Using CLI"). ``404 model_not_found``
+  for an unknown/foreign/malformed id — never 403 (anti-enumeration).
+
+* :data:`JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE` (``GET``) — resolves one model
+  to a short-lived download link, ``{"url": ..., "expires_at": ...}`` —
+  identical semantics to the recording download route, including the
+  membership-recheck-on-THIS-request rule. The client verifies the
+  downloaded bytes against the record's ``digest_sha256`` (which is
+  REQUIRED for models, unlike recordings — the worker always hashes the
+  checkpoint before finalizing).
+
+## Worker-facing: models (upload after ``complete``)
+
+* :data:`WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE` (``POST``) — request
+  ``{"size_bytes": 123456}``. Response::
+
+      {"model_id": "...", "upload_url": "...", "storage_uri": "..."}
+
+  The worker then ``PUT``s the checkpoint bytes directly to ``upload_url``.
+  The stored object key is the Data Model §9 layout
+  (``.../models/{model_id}/model.bin``) — the ORIGINAL filename travels in
+  the finalize body's ``name`` and is what clients save the download as.
+
+* :data:`WORKER_JOB_MODELS_ROUTE_TEMPLATE` (``POST``) — finalizes a
+  presigned model upload. Request: ``{"model_id": ..., "name": "best.pt",
+  "kind": "best", "digest_sha256": "sha256:...", "content_type":
+  "application/octet-stream"}``. ``kind`` is one of :data:`MODEL_KINDS`
+  (an unknown kind is stored as unlabelled, not rejected). The server
+  verifies the uploaded object exists and takes ``size_bytes`` from the
+  STORED object, never from the worker's claim. Response ``201`` — the
+  persisted :class:`ModelRecord`; an idempotent replay answers ``200``.
+
+  Like the recordings pair, presign/finalize are deliberately NOT
+  lease-gated server-side (the worker uploads models AFTER ``complete``,
+  when the lease is moot) — the anti-zombie invariant is worker-side: a
+  worker whose ``complete`` was 409-rejected (or whose heartbeat observed
+  ``lease_lost``) must SKIP the model upload exactly as it skips the
+  recordings upload.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from simulo.interfaces.ids import JobId, RecordingId, TrainedModelId
+
+# --------------------------------------------------------------------------
+# Client-facing routes (bearer = user JWT; require_active_org server-side)
+# --------------------------------------------------------------------------
+
+#: ``POST`` — register a content-addressed package before uploading its archive.
+PACKAGES_ROUTE = "/v1/packages"
+#: ``PUT`` — upload the raw tar bytes for a registered package. ``.format(package_id=...)``.
+PACKAGE_ARCHIVE_ROUTE_TEMPLATE = "/v1/packages/{package_id}/archive"
+
+#: ``GET`` — paginated envelope of :class:`RecordingRecord` for one job. ``.format(job_id=...)``.
+JOB_RECORDINGS_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/recordings"
+#: ``GET`` — resolve one recording to a short-lived download link.
+#: ``.format(job_id=..., recording_id=...)``.
+JOB_RECORDING_DOWNLOAD_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/recordings/{recording_id}/download"
+
+#: ``GET`` — paginated envelope of :class:`ModelRecord` for one job. ``.format(job_id=...)``.
+JOB_MODELS_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/models"
+#: ``GET`` — one :class:`ModelRecord`. ``.format(job_id=..., model_id=...)``.
+JOB_MODEL_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/models/{model_id}"
+#: ``GET`` — resolve one model to a short-lived download link.
+#: ``.format(job_id=..., model_id=...)``.
+JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/models/{model_id}/download"
+
+#: Note: ``POST /v1/jobs`` (create a job from a package) reuses
+#: ``simulo.interfaces.platform.runs.JOBS_ROUTE`` — the *same* route string
+#: as the existing ``GET /v1/jobs`` list endpoint (POST creates, GET lists).
+#: There is deliberately no separate ``*_SUBMIT_ROUTE`` constant here — see
+#: the module docstring's "Client-facing: package submit + job create" section.
+
+# --------------------------------------------------------------------------
+# Worker-facing routes (bearer = static WORKER_TOKEN, constant-time compare;
+# empty server-side config disables every route below, fail-closed)
+# --------------------------------------------------------------------------
+
+#: ``POST`` — atomically claim the next queued job (``FOR UPDATE SKIP LOCKED``).
+WORKER_CLAIM_ROUTE = "/internal/worker/claim"
+#: ``POST`` — append raw log bytes at a byte offset (``?offset=N``). ``.format(job_id=...)``.
+WORKER_JOB_LOGS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/logs"
+#: ``POST`` — extend the claim lease; response carries the ``cancelled`` seam.
+#: ``.format(job_id=...)``.
+WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/heartbeat"
+#: ``POST`` — transition a job to a terminal status with its exit code/result.
+#: ``.format(job_id=...)``.
+WORKER_JOB_COMPLETE_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/complete"
+#: ``POST`` — obtain a presigned upload URL for a new recording. ``.format(job_id=...)``.
+WORKER_JOB_RECORDINGS_PRESIGN_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/recordings/presign"
+#: ``POST`` — finalize a presigned recording upload (inserts ``job_recordings`` row).
+#: ``.format(job_id=...)``.
+WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/recordings"
+#: ``POST`` — obtain a presigned upload URL for a new model checkpoint. ``.format(job_id=...)``.
+WORKER_JOB_MODELS_PRESIGN_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/models/presign"
+#: ``POST`` — finalize a presigned model upload (inserts the ``models`` row).
+#: ``.format(job_id=...)``.
+WORKER_JOB_MODELS_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/models"
+
+#: Request header carrying the claim's ``lease_id`` ownership token on every
+#: job-scoped worker call (heartbeat / logs / complete). A header — not a body
+#: field — because the logs route's body is raw bytes and heartbeat has no
+#: body; one uniform channel for all three. A missing or mismatching value is
+#: ``409 lease_lost`` (see the module docstring's claim section for the full
+#: lease/reaper semantics). Recording presign/finalize are deliberately NOT
+#: lease-gated: the worker uploads recordings AFTER ``complete`` — i.e. after
+#: the job is terminal and the lease is moot.
+WORKER_LEASE_HEADER = "X-Simulo-Lease-Id"
+
+# --------------------------------------------------------------------------
+# Size caps (security NFR — request-size limits per endpoint; see nfr SKILL)
+# --------------------------------------------------------------------------
+
+#: Maximum accepted size of a package archive (``PUT .../archive`` body). 413 over this.
+MAX_PACKAGE_BYTES = 64 * 1024 * 1024  # 64 MiB
+#: Maximum accepted size of a single **worker** log-upload call
+#: (``POST`` :data:`WORKER_JOB_LOGS_ROUTE_TEMPLATE` body) — the write-side cap, 1 MiB.
+#:
+#: **Not the same constant as** ``simulo.interfaces.platform.runs.LOG_CHUNK_MAX_BYTES``
+#: (64 KiB) — that is the pre-existing **client** read-side cap on a single
+#: ``GET .../logs?offset=N`` response (``runs.py``). Both are now re-exported
+#: from ``simulo.interfaces.platform``, so importing the wrong one silently
+#: changes behavior by 16x: a worker that POSTs up to ``runs.LOG_CHUNK_MAX_BYTES``
+#: per call under-uses its allowance; a client GET that budgeted for this
+#: (larger) constant would be surprised the server never returns that much.
+MAX_LOG_CHUNK_BYTES = 1 * 1024 * 1024  # 1 MiB
+#: Maximum accumulated log bytes for one job, across every ``.../logs`` call.
+#: Output past this cap is truncated; the job itself is not failed.
+MAX_LOG_TOTAL_BYTES = 100 * 1024 * 1024  # 100 MiB
+#: Maximum accepted size of a job's ``result`` JSON object
+#: (``POST .../complete`` body's ``result`` field).
+MAX_RESULT_BYTES = 1 * 1024 * 1024  # 1 MiB
+#: Character caps on the ``POST .../complete`` body's human-facing fields —
+#: the control plane's ``WorkerCompleteRequest`` schema enforces exactly these
+#: (Pydantic ``max_length``). A worker MUST clamp before POSTing: an oversized
+#: ``message`` 422-rejects the WHOLE terminal-status call, and a worker that
+#: treats the 422 as best-effort leaves the job stuck ``running`` server-side
+#: forever (found live in the first real-S3 staging run, 2026-07-04 — the
+#: download-failure message embedded a ~1.9 KiB presigned URL).
+MAX_COMPLETE_REASON_CODE_CHARS = 64
+MAX_COMPLETE_MESSAGE_CHARS = 1024
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RecordingRecord:
+    """One MCAP recording produced by a job — the wire schema returned by
+    :data:`JOB_RECORDINGS_ROUTE_TEMPLATE` and by the worker-facing recordings
+    finalize call (:data:`WORKER_JOB_RECORDINGS_ROUTE_TEMPLATE`).
+
+    ``schema_version`` and ``profile`` describe the MCAP file itself (schema
+    versioning is owned by the `mcap-recording` SKILL — this dataclass only
+    carries the value through the wire, it does not define it).
+    The three episode-summary fields are optional because not every
+    recording is episodic (e.g. a raw rollout capture) and because a worker
+    may finalize a recording before its summary stats are computed.
+    """
+
+    recording_id: RecordingId
+    job_id: JobId
+    name: str
+    size_bytes: int
+    digest_sha256: str
+    schema_version: str
+    profile: str
+    created_at: str
+    #: Number of episodes represented in this recording, if episodic.
+    n_episodes: Optional[int] = None
+    #: Mean per-episode return, if episodic and computed.
+    mean_episode_return: Optional[float] = None
+    #: Fraction of episodes that reached a success termination, if computed.
+    success_rate: Optional[float] = None
+
+
+#: The checkpoint kinds a training job produces (``simulo.checkpoint.v1``:
+#: ``best.pt`` = highest-mean-episode-reward snapshot, ``latest.pt`` = most
+#: recent snapshot, kept for resume). The worker labels each uploaded model
+#: with its kind; a kind outside this set is stored unlabelled, not rejected.
+MODEL_KINDS = ("best", "latest")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ModelRecord:
+    """One trained-model artifact produced by a job (Data Model §4.6 Model) —
+    the wire schema returned by :data:`JOB_MODELS_ROUTE_TEMPLATE` /
+    :data:`JOB_MODEL_ROUTE_TEMPLATE` and by the worker-facing models
+    finalize call (:data:`WORKER_JOB_MODELS_ROUTE_TEMPLATE`).
+
+    ``name`` is the artifact's ORIGINAL filename (``best.pt`` /
+    ``latest.pt``) — the name a client saves the download under. The stored
+    object itself lives at the Data Model §9 key
+    (``.../models/{model_id}/model.bin``); the row's name/content_type are
+    what give the opaque object its user-facing identity. ``digest_sha256``
+    is always present (bare 64-hex): the worker hashes the checkpoint before
+    finalizing, and clients MUST verify the downloaded bytes against it.
+    """
+
+    model_id: TrainedModelId
+    job_id: JobId
+    name: str
+    #: One of :data:`MODEL_KINDS`, or ``""`` when the kind is unknown.
+    kind: str
+    size_bytes: int
+    digest_sha256: str
+    content_type: str
+    created_at: str
+
+
+# --------------------------------------------------------------------------
+# Reserved runtime environment keys
+# --------------------------------------------------------------------------
+#
+# The worker spawns the job subprocess (``simulo-backend run-package``) with
+# the user's job ``args`` merged into its environment. This denylist is
+# derived from a single principle — **runner-owned vs. user-tunable** — read
+# directly off what ``simulo-backend``'s ``runner.py`` / ``run_store.py``
+# actually do to ``os.environ`` (not guessed):
+#
+# * **Runner-owned** (reserved here): any ``SIMULO_*`` key the runner or
+#   run-store *sets* to identify the job/worker, resolve a filesystem path it
+#   then trusts, select execution mode, or authenticate outbound calls.
+#   ``runner.py`` sets ``SIMULO_MODE=execution`` unconditionally
+#   (``run_package()``); exports ``SIMULO_VOLUME_<name>`` / ``SIMULO_ASSET_<uri>``
+#   as resolved mount paths (``_volume_env_key`` / ``_asset_env_key`` /
+#   ``_setup_mounts``) — a user-supplied ``SIMULO_VOLUME_data=/etc`` would
+#   redirect a mount, the **sandbox-escape vector** and the highest-priority
+#   reservation here; prints the ``SIMULO_RESULT_JSON=`` stdout sentinel a
+#   parent process trusts as the job's result payload
+#   (``RESULT_SENTINEL_PREFIX``); sets ``SIMULO_RETRY_ATTEMPT`` per subprocess
+#   attempt so a child never starts its own retry loop; and ``run_store.py``
+#   resolves ``SIMULO_RUNS_ROOT`` to decide where run state is durably
+#   recorded. ``SIMULO_CHECKPOINT_DIR`` is the one checkpoint-envelope key
+#   that is also runner-owned (``_setup_checkpointing`` derives it from the
+#   job's *submission* identity — ``package_id`` + job name — so a
+#   user-supplied override would silently point training at another job's
+#   checkpoint state); ``SIMULO_API_TOKEN`` is the worker-bearer credential
+#   the job process would use to call back to the control plane once that
+#   lands (PR-5) — reserved proactively so the contract does not need a
+#   second pass. ``PATH`` / ``PYTHONPATH`` / ``HOME`` are reserved because
+#   the worker's ``pip install --target`` dependency layer depends on
+#   controlling ``PYTHONPATH``, and a job/worker identity key
+#   (``SIMULO_JOB_ID`` / ``SIMULO_PACKAGE_ID`` / ``SIMULO_WORKER_ID`` /
+#   ``SIMULO_WORKER_TOKEN`` / ``SIMULO_API_URL``) must not be spoofable by
+#   job ``args``. ``SIMULO_SHUTDOWN_GRACE_S`` (2026-07-07 shutdown watchdog)
+#   is the ORCHESTRATOR's own post-success grace-period knob — an operator
+#   env var, not a per-job one — so it is reserved defense-in-depth even
+#   though nothing in the current job-``args`` merge path would let a
+#   package set it today; a submitted package's manifest ``args`` must never
+#   be able to widen its own attempt child's kill grace.
+#
+# * **User-tunable** (deliberately NOT reserved): ``_setup_checkpointing``
+#   exports ``SIMULO_CHECKPOINT_EVERY`` / ``SIMULO_CHECKPOINT_KEEP_LAST`` /
+#   ``SIMULO_RESUME`` with ``os.environ.setdefault`` specifically so an
+#   explicit caller/job env value wins — these are job-tunable knobs by
+#   design, not runner secrets. That is why :data:`RESERVED_RUNTIME_ENV_KEYS`
+#   reserves the checkpoint **directory key only**
+#   (``SIMULO_CHECKPOINT_DIR``), never a ``SIMULO_CHECKPOINT_`` *prefix* — a
+#   prefix ban would also catch ``EVERY``/``KEEP_LAST``, the same class of
+#   bug this whole design avoids for ``SIMULO_EVAL_REWARD_TARGET`` (read by
+#   ``examples/cartpole_eval``; still legitimate user-supplied job env, and
+#   still not reserved by any key or prefix here).
+#
+# This is deliberately a **reserved-KEYS list, not a blanket `SIMULO_*` prefix
+# ban.** Banning the whole prefix would make every future user-facing
+# ``SIMULO_*`` job knob (the eval-target case, the checkpoint-tuning case, and
+# whatever comes next) a breaking change to smuggle past this contract.
+# Instead, :data:`RESERVED_RUNTIME_ENV_PREFIXES` reserves only the narrow
+# sub-namespaces the runner/worker fully own — worker-internal identifiers,
+# and the per-mount ``SIMULO_VOLUME_*`` / ``SIMULO_ASSET_*`` families, whose
+# every member is runner-generated (there is no legitimate user-facing key
+# under either prefix; every valid key that starts with them is a mount the
+# runner itself created) — and :data:`RESERVED_RUNTIME_ENV_KEYS` reserves the
+# specific mechanical/identity keys enumerated above. ``run_package()``
+# (``simulo-backend``, PR-5) enforces this by skipping and warning on any
+# user ``args`` key that matches either collection — it never raises, so a
+# job with an (accidentally) colliding env key still runs, just without
+# clobbering the runner's own environment.
+
+#: Exact environment-variable names reserved for the runner/worker's own use
+#: (see the "runner-owned vs. user-tunable" note above for the derivation of
+#: every entry). A user-supplied job arg using one of these keys is skipped
+#: (with a warning), never applied.
+RESERVED_RUNTIME_ENV_KEYS = frozenset(
+    {
+        "PATH",
+        "PYTHONPATH",
+        "HOME",
+        "SIMULO_JOB_ID",
+        "SIMULO_PACKAGE_ID",
+        "SIMULO_API_URL",
+        "SIMULO_WORKER_ID",
+        "SIMULO_WORKER_TOKEN",
+        "SIMULO_RUNS_ROOT",
+        "SIMULO_CHECKPOINT_DIR",
+        "SIMULO_API_TOKEN",
+        "SIMULO_RESULT_JSON",
+        "SIMULO_MODE",
+        "SIMULO_RETRY_ATTEMPT",
+        "SIMULO_SHUTDOWN_GRACE_S",
+    }
+)
+
+#: Environment-variable name prefixes reserved for the runner/worker's own
+#: internal namespaces — narrower than a blanket ``SIMULO_*`` ban (see the
+#: module note above). ``SIMULO_VOLUME_*`` / ``SIMULO_ASSET_*`` are the mount
+#: env keys ``runner._setup_mounts`` exports for every declared volume/asset
+#: (the sandbox-escape vector: an unreserved ``SIMULO_VOLUME_<name>`` would
+#: let a job arg redirect a mount path). ``SIMULO_EVAL_REWARD_TARGET`` (and
+#: any other ``SIMULO_EVAL_*`` / ``SIMULO_CHECKPOINT_EVERY`` /
+#: ``SIMULO_CHECKPOINT_KEEP_LAST`` / ``SIMULO_RESUME``) does not match any of
+#: these prefixes and remains legitimate user-supplied job env.
+RESERVED_RUNTIME_ENV_PREFIXES = ("SIMULO_WORKER_", "SIMULO_INTERNAL_", "SIMULO_VOLUME_", "SIMULO_ASSET_")

simulo/interfaces/platform/volume.py

@@ -0,0 +1,13 @@
+"""``VolumeProtocol`` — named, durable, writable cloud volume (Part B)."""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class VolumeProtocol(Protocol):
+    """Named, durable, writable volume. FORWARD."""
+
+    @classmethod
+    def from_name(cls, name: str, *, create_if_missing: bool = False) -> "VolumeProtocol": ...
+    @property
+    def name(self) -> str: ...

simulo/interfaces/runtime/__init__.py

@@ -0,0 +1,50 @@
+"""Part A — runtime/sim Protocols (torch-free structural mirrors of ``simulo.core``).
+
+Tensor-library-agnostic ``typing.Protocol`` contracts for the SDK runtime
+surface: Task, Policy, Trainer, Player, LearningEnv, Scenario, and the
+observation/reward/termination components. Structural (no inheritance required)
+and ``runtime_checkable`` for ``isinstance`` smoke checks. ``simulo-backend``'s
+``simulo.core`` classes additionally declare *nominal* conformance (they list
+these Protocols as base classes) so mypy drift-checks every implementation at
+its definition site; other implementers remain free to conform structurally.
+``PolicyExporterProtocol`` is the narrow optional export capability — see
+``simulo.interfaces.runtime.trainer``.
+"""
+
+from simulo.interfaces.runtime.anomaly import (
+    AnomalyDebugSessionProtocol,
+    AnomalyKind,
+    AnomalySignal,
+    DebugOnAnomaly,
+)
+from simulo.interfaces.runtime.components import (
+    ObservationComponentProtocol,
+    RewardComponentProtocol,
+    TerminationConditionProtocol,
+)
+from simulo.interfaces.runtime.env import LearningEnvProtocol
+from simulo.interfaces.runtime.player import PlayerProtocol
+from simulo.interfaces.runtime.policy import PolicyProtocol
+from simulo.interfaces.runtime.scenario import ScenarioProtocol
+from simulo.interfaces.runtime.task import TaskProtocol
+from simulo.interfaces.runtime.tensors import TensorLike
+from simulo.interfaces.runtime.trainer import PolicyExporterProtocol, TrainerProtocol
+
+__all__ = [
+    "TensorLike",
+    "TaskProtocol",
+    "PolicyProtocol",
+    "TrainerProtocol",
+    "PolicyExporterProtocol",
+    "PlayerProtocol",
+    "LearningEnvProtocol",
+    "ScenarioProtocol",
+    "ObservationComponentProtocol",
+    "RewardComponentProtocol",
+    "TerminationConditionProtocol",
+    # anomaly capture (DebugOnAnomaly — the local half of Rule #10)
+    "AnomalyKind",
+    "AnomalySignal",
+    "DebugOnAnomaly",
+    "AnomalyDebugSessionProtocol",
+]