simulo-interfaces 0.19.0__tar.gz → 0.20.0__tar.gz

{simulo_interfaces-0.19.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.19.0
+Version: 0.20.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.19.0"
+version = "0.20.0"
 description = "Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/__init__.py

@@ -228,6 +228,7 @@ from simulo.interfaces.platform.submit import (
     SEED_JOB_REF_GRAMMAR,
     SEED_SOURCE_CONFLICT_CODE,
     SEED_SOURCE_FIELDS,
+    WORKER_BOOTSTRAP_ROUTE,
     WORKER_CLAIM_ROUTE,
     WORKER_JOB_COMPLETE_ROUTE_TEMPLATE,
     WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE,
@@ -351,6 +352,7 @@ __all__ = [
     "JOB_MODELS_ROUTE_TEMPLATE",
     "JOB_MODEL_ROUTE_TEMPLATE",
     "JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE",
+    "WORKER_BOOTSTRAP_ROUTE",
     "WORKER_CLAIM_ROUTE",
     "WORKER_JOB_LOGS_ROUTE_TEMPLATE",
     "WORKER_JOB_HEARTBEAT_ROUTE_TEMPLATE",

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/asset_catalog.py

@@ -493,7 +493,7 @@ ASSET_VERSION_REPORT_ROUTE_TEMPLATE = "/v1/asset-versions/{version_id}/report"
 ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE = "/v1/asset-versions/{version_id}/download"
 
 # --------------------------------------------------------------------------
-# Worker routes  (bearer = static WORKER_TOKEN; + lease header, see submit.py)
+# Worker routes  (bearer = per-worker identity JWT; + lease header, see submit.py)
 # --------------------------------------------------------------------------
 #
 # The claim response (submit.WORKER_CLAIM_ROUTE) additionally carries an

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/enums.py

@@ -11,8 +11,9 @@ class JobStatus(StrEnum):
     """Lifecycle state of a submitted job.
 
     A job moves ``QUEUED`` → ``RUNNING`` → one terminal state
-    (``COMPLETED`` / ``FAILED`` / ``CANCELLED``). Terminal states never change
-    again — logs and results are final once a job reaches one.
+    (``COMPLETED`` / ``FAILED`` / ``CANCELLED`` / ``TIMED_OUT``). Terminal
+    states never change again — logs and results are final once a job
+    reaches one.
     """
 
     QUEUED = "queued"
@@ -30,6 +31,23 @@ class JobStatus(StrEnum):
     CANCELLED = "cancelled"
     """Stopped on request (``simulo cancel``) before completing."""
 
+    TIMED_OUT = "timed_out"
+    """Stopped for exceeding its organization's configured runtime limit —
+    distinct from :attr:`FAILED`: the job did not crash, it ran past its
+    organization's configured runtime limit and was stopped by the platform
+    (the supervisor's own kill, or a backstop reaper after the deadline plus
+    a grace period). Any checkpoint the run had produced by then is salvaged
+    the same way a cancelled run's is.
+
+    Appended, never inserted: this member was added after the first five and
+    keeps its place at the end of the wire enum per this module's own
+    append-only rule. A client should treat this value as
+    terminal-and-distinct wherever it reaches one directly (e.g. a
+    worker-authored `complete` body); the control plane's own public read
+    routes may still project it as `FAILED` for compatibility with clients
+    published before this member existed — see that rollout's own record for
+    when the projection lifts."""
+
 
 class ResumePolicy(StrEnum):
     """How a job resumes from a discovered checkpoint."""

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/manifest.py

@@ -164,9 +164,9 @@ class Manifest:
 #: this endpoint must not break a newer client.
 META_ROUTE = "/v1/meta"
 
-#: ``POST`` — the worker's runtime-manifest self-report (bearer = static
-#: ``WORKER_TOKEN``, same trust zone as every ``/internal/worker/*`` route —
-#: see :mod:`simulo.interfaces.platform.submit`). The worker introspects its
+#: ``POST`` — the worker's runtime-manifest self-report (bearer = the
+#: per-worker identity JWT, same trust zone as every ``/internal/worker/*``
+#: route — see :mod:`simulo.interfaces.platform.submit`). The worker introspects its
 #: own interpreter (``importlib.metadata.distributions()``) on startup and
 #: POSTs a :class:`RuntimeManifest` — the reporter *is* the runtime.
 #: **Best-effort by contract:** a failed report must never stop a worker from

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/outputs.py

@@ -196,8 +196,9 @@ JOB_OUTPUTS_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/outputs"
 JOB_OUTPUT_DOWNLOAD_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/outputs/{output_id}/download"
 
 # --------------------------------------------------------------------------
-# Worker-facing routes (bearer = static WORKER_TOKEN, constant-time compare;
-# same auth surface as the recordings/models worker routes in submit.py)
+# Worker-facing routes (bearer = the per-worker identity JWT
+# `WORKER_BOOTSTRAP_ROUTE` mints, verified server-side per call; same auth
+# surface as the recordings/models worker routes in submit.py)
 # --------------------------------------------------------------------------
 
 #: ``POST`` — obtain a presigned upload URL for a new general output (a

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/runs.py

@@ -302,7 +302,16 @@ LOG_ARCHIVE_READ_FAILED_CODE = "log_archive_read_failed"
 
 #: 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})
+#:
+#: ``TIMED_OUT`` joined this set in `M55-org-runtime-policy` (issue #1537).
+#: The control plane's public read routes do not emit it yet (they project a
+#: `timed_out` job as `FAILED` with `status_reason="timeout"` until a
+#: tolerant-client floor is recorded — see :class:`~simulo.interfaces.
+#: platform.enums.JobStatus`'s own docstring), so this set already carrying
+#: it is what makes a client that widens itself ahead of that projection
+#: lift (per this contract's own unknown-status-is-terminal guidance) treat
+#: the value correctly the moment it does appear on the wire.
+TERMINAL_JOB_STATUSES = frozenset({JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED, JobStatus.TIMED_OUT})
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
@@ -334,7 +343,14 @@ class JobRecord:
     """When the job was created (ISO 8601 UTC, e.g. ``2026-07-03T12:00:00Z``)."""
 
     args: Mapping[str, Any] = field(default_factory=dict)
-    """The keyword arguments the job body was invoked with."""
+    """The keyword arguments the job body was invoked with, AS SERVED ON
+    THIS RECORD — not necessarily what the job actually ran with. The
+    control plane redacts any credential-shaped key or value (replacing it
+    with the literal string ``"<redacted>"``) when building this public
+    record; the job itself executed with the real, unredacted values. A
+    client reading this field to display a job's history sees the redacted
+    view; nothing about a redacted entry here implies the run itself saw
+    ``"<redacted>"``."""
 
     started_at: Optional[str] = None
     """When execution began (ISO 8601 UTC). ``None`` while queued."""

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/submit.py

@@ -25,10 +25,16 @@ 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.
+* **Worker-facing `/internal/worker/...`** — bearer = a short-lived,
+  per-worker identity JWT (see :data:`WORKER_BOOTSTRAP_ROUTE` below). The worker obtains it from an
+  IAM-signed bootstrap call, unique per EC2 instance identity; the server
+  verifies it (audience, issuer, expiry, and — live, on every call — the
+  issuing worker row's revocation status) rather than comparing against a
+  single shared secret. Empty server-side signing-secret config disables
+  every ``/internal/worker/*`` route fail-closed — there is no "auth
+  disabled" state for these routes. (Before this cutover the bearer was a
+  single static ``WORKER_TOKEN`` shared by the whole fleet; that scheme is
+  retired.)
 * **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
@@ -159,8 +165,28 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
 
 ## Worker-facing (`/internal/worker/*`)
 
-* :data:`WORKER_CLAIM_ROUTE` (``POST``) — request ``{"worker_id": "..."}``.
-  Response ``200``::
+* :data:`WORKER_BOOTSTRAP_ROUTE` (``POST``) — request
+  ``{"signature_b64": "..."}``, the caller's own IAM-signed EC2 instance
+  identity document exactly as ``dynamic/instance-identity/rsa2048``
+  returns it (base64, no armor). Carries NO shared secret of its own — the
+  signed document IS the credential. Response ``200``::
+
+      {"worker_id": "wkr_...", "tier": "tier1", "pinned_organization_id": null,
+       "status": "active", "token": "<jwt>", "token_expires_at": "2026-07-03T13:00:00Z"}
+
+  Idempotent per EC2 instance identity: a repeat call from an instance that
+  already holds a worker identity returns that SAME identity (still pinned,
+  if pinned) with a freshly-issued ``token`` — the recommended renewal
+  cadence is half of the deployment's configured token TTL. ``token`` is
+  the bearer every OTHER ``/internal/worker/*`` route now requires (below);
+  nothing on the wire ever carries the ``WORKER_TOKEN`` shared bearer this
+  route's own token retired.
+
+* :data:`WORKER_CLAIM_ROUTE` (``POST``) — request body carries no worker
+  identity field: the claiming worker is whoever the ``Authorization``
+  bearer (above) verifies to, never a caller-asserted value — a
+  pre-cutover claim body's ``{"worker_id": "..."}`` was trusted outright,
+  the actual gap this contract change closed. Response ``200``::
 
       {"job": <JobRecord>,
        "package": {"download_url": "...", "tar_sha256": "sha256:...", "size_bytes": 123456},
@@ -495,10 +521,19 @@ MAX_SEED_REF_CHARS = 80
 SEED_SOURCE_CONFLICT_CODE = "seed_source_conflict"
 
 # --------------------------------------------------------------------------
-# Worker-facing routes (bearer = static WORKER_TOKEN, constant-time compare;
-# empty server-side config disables every route below, fail-closed)
+# Worker-facing routes (bearer = a per-worker identity JWT this bootstrap
+# route mints; empty server-side signing-secret config disables every
+# OTHER route below, fail-closed — see the module docstring's trust zones)
 # --------------------------------------------------------------------------
 
+#: ``POST`` — bind (or re-bind) a worker identity to the calling EC2 instance
+#: via an IAM-signed instance identity document. Body
+#: ``{"signature_b64": "..."}``. Carries NO shared secret of its own — the
+#: signed document IS this route's authentication, which is the whole point
+#: of it existing: it is the ONE route that MINTS the token every OTHER
+#: ``/internal/worker/*`` route now requires, so it cannot itself require
+#: that token without a chicken-and-egg cycle.
+WORKER_BOOTSTRAP_ROUTE = "/internal/worker/bootstrap"
 #: ``POST`` — atomically claim the next queued job (``FOR UPDATE SKIP LOCKED``).
 WORKER_CLAIM_ROUTE = "/internal/worker/claim"
 #: ``POST`` — append ordinary-job raw log bytes at a byte offset
@@ -850,6 +885,31 @@ RESERVED_RUNTIME_ENV_KEYS = frozenset(
         "SIMULO_VIEWSTREAM_ENABLED",
         "SIMULO_RUNTIME_FACTS_PATH",
         "MAX_JOB_TIMEOUT_S",
+        # M40-job-sandbox (issue #527): the container launcher sets this to
+        # advertise the job container's publicly reachable stream endpoint
+        # (`--/app/livestream/publicEndpointAddress=<instance IP>`) to Kit —
+        # a bridge-networked job container needs this because its own
+        # address is NAT'd, unlike the pre-M40 host-networking deployment
+        # where Kit's default self-detected address was already correct.
+        # `simulo/backend/isaaclab/stream_adapter.py`'s `get_launch_args`
+        # merges this env var in LAST, so an unreserved key would let a
+        # manifest's own `runtime_env` override the launcher's own address
+        # and redirect where the job's live-view media is advertised
+        # (ADR-0016's threat table: "Job redirects the stream endpoint via a
+        # job-controllable env key"). Reserving it here is the
+        # denylist-enforcement half of the fix; `worker._child_env` is the
+        # other half, unconditionally scrubbing any ambient value before the
+        # launcher re-sets it from the resolved instance address.
+        "SIMULO_KIT_EXTRA_ARGS",
+        # M40-job-sandbox (issue #527): the same "worker mount wins" seam as
+        # SIMULO_CHECKPOINT_DIR / SIMULO_ANOMALY_DEBUG_DIR — the worker
+        # pre-resolves and bind-mounts the validation run-dir output
+        # contract (verdict/report/facts/runtime-findings) at this path
+        # before an asset-validation job's container starts, because that
+        # container's own `~` is ephemeral tmpfs the worker could never
+        # read back. A manifest-borne override would point the worker's own
+        # later read at a job-chosen path instead.
+        "SIMULO_VALIDATION_OUTPUT_DIR",
     }
 )
 

{simulo_interfaces-0.19.0 → simulo_interfaces-0.20.0/src/simulo_interfaces.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.19.0
+Version: 0.20.0
 Summary: Type contracts for the Simulo SDK. Installed automatically as a dependency of the simulo package.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause