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

{simulo_interfaces-0.18.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.18.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.18.0 → simulo_interfaces-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.18.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.18.0 → simulo_interfaces-0.20.0}/src/simulo/interfaces/platform/__init__.py

@@ -70,7 +70,7 @@ from simulo.interfaces.platform.asset_catalog import (
 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 OutputKind
+from simulo.interfaces.platform.enums import OutputKind, SystemType
 from simulo.interfaces.platform.job_events import (
     MAX_PUBLIC_ASSET_FINDING_COUNT,
     MAX_PUBLIC_JOB_EVENT_ATTEMPT,
@@ -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,
@@ -240,11 +241,16 @@ from simulo.interfaces.platform.submit import (
     canonical_pypi_name,
     is_platform_pinned,
 )
+from simulo.interfaces.platform.systems import SYSTEM_SPECS, SystemSpec
 from simulo.interfaces.platform.volume import VolumeProtocol
 
 __all__ = [
     # enums
     "OutputKind",
+    "SystemType",
+    # systems (GPU system-tier catalog, issue #1362)
+    "SystemSpec",
+    "SYSTEM_SPECS",
     # closed public job-event contract (#656)
     "PUBLIC_JOB_EVENT_SCHEMA_VERSION",
     "WORKER_JOB_EVENTS_ROUTE_TEMPLATE",
@@ -346,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.18.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.18.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."""
@@ -44,6 +62,28 @@ class ResumePolicy(StrEnum):
     """Resume only on explicit request. Reserved: currently behaves like ``NEVER``."""
 
 
+class SystemType(StrEnum):
+    """An abstract GPU system tier.
+
+    Each tier's hardware profile and fleet-provisioning state lives in
+    :data:`simulo.interfaces.platform.systems.SYSTEM_SPECS`, keyed by these
+    members. The AWS instance type behind a tier is never part of this name —
+    see :class:`simulo.interfaces.platform.systems.SystemSpec`'s own docstring.
+    """
+
+    TIER_1 = "tier1"
+    """Entry tier — always available."""
+
+    TIER_2 = "tier2"
+    """Mid tier — always available."""
+
+    TIER_3 = "tier3"
+    """High tier — not yet available on the deployable fleet."""
+
+    TIER_4 = "tier4"
+    """Top tier — not yet available on the deployable fleet."""
+
+
 class ResourceKind(StrEnum):
     """Kind of a registry-resolved, read-only resource mount."""
 

{simulo_interfaces-0.18.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.18.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.18.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.18.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.20.0/src/simulo/interfaces/platform/systems.py

@@ -0,0 +1,106 @@
+"""GPU system-tier catalog — the closed hardware contract behind `SystemType`.
+
+`SYSTEM_SPECS` is the single published source of truth for what each tier
+means: the marketing GPU name, its VRAM, the host's vCPU/memory, whether the
+tier is provisionable on the deployable fleet today, and (internal-only) the
+AWS instance type behind it. Nothing here schedules a job against real
+hardware — selection stays record-only until a later milestone adds live
+enforcement.
+
+Stdlib-only (`dataclasses` plus the sibling `enums` module): this file must
+import nothing else, so the package's zero-runtime-dependency guarantee
+(`test_no_heavy_deps.py`) holds.
+"""
+
+from dataclasses import dataclass
+
+from simulo.interfaces.platform.enums import SystemType
+
+# Shared dataclass options: immutable value objects (frozen), memory-lean
+# (slots), and keyword-only construction (kw_only) — see `platform/domain.py`'s
+# identical `_DC` for the full rationale.
+_DC = {"frozen": True, "slots": True, "kw_only": True}
+
+
+@dataclass(**_DC)
+class SystemSpec:
+    """One GPU tier's hardware profile and fleet-provisioning state.
+
+    `gpu_model` (e.g. `"T4"`) is the user-facing marketing name — the only
+    hardware identity a CLI table, `--json` output, or documentation page may
+    ever show. `instance_type` is the AWS EC2 instance type behind the tier,
+    kept here ONLY for an offline fleet crosscheck against the deployable
+    CloudFormation allowlist and the control plane's own bookkeeping — it
+    must never reach a user-facing surface. Hiding it is deliberate: a future
+    author copying an AWS SKU into an example is exactly how `gpu="L4"`
+    (actually Tier 3, not provisionable) ended up in 40 tracked files before
+    this catalog existed.
+    """
+
+    system: SystemType
+    gpu_model: str
+    vram_gb: int
+    vcpu: int
+    memory_gb: int
+    max_parallel_envs: int | None
+    available: bool
+    instance_type: str
+
+
+# vcpu/memory_gb: AWS's published instance-type specifications
+# (https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html, confirmed at
+# M20-system-catalog implementation time, 2026-09-07) for
+# g4dn.xlarge/g5.xlarge/g6.xlarge/g6e.xlarge. vram_gb: each GPU model's
+# published VRAM capacity (NVIDIA product specifications) — deliberately NOT
+# the ~22/44 GiB AWS's own instance-type page reports as *usable* GPU memory
+# on g5/g6/g6e after ECC/hypervisor reservation, since `vram_gb` documents the
+# hardware users are told they are getting (`gpu_model`), not a fleet
+# provisioning detail.
+SYSTEM_SPECS: dict[SystemType, SystemSpec] = {
+    SystemType.TIER_1: SystemSpec(
+        system=SystemType.TIER_1,
+        gpu_model="T4",
+        vram_gb=16,
+        vcpu=4,
+        memory_gb=16,
+        # Measured ceiling for g4dn.xlarge's default workload (`.claude/skills/isaaclab/SKILL.md`,
+        # `.claude/skills/aws-infra/SKILL.md`, `cloud-infra/gpu-worker/gpu-worker.yaml`): 16
+        # parallel environments; a 4096-environment run exhausted GPU memory and made the
+        # instance unrecoverable. `aws-infra/SKILL.md` is explicit that this is
+        # workload/instance evidence for the template's default workload, not a universal
+        # constant — re-benchmark before relying on it for a different workload shape.
+        max_parallel_envs=16,
+        available=True,
+        instance_type="g4dn.xlarge",
+    ),
+    SystemType.TIER_2: SystemSpec(
+        system=SystemType.TIER_2,
+        gpu_model="A10G",
+        vram_gb=24,
+        vcpu=4,
+        memory_gb=16,
+        max_parallel_envs=None,
+        available=True,
+        instance_type="g5.xlarge",
+    ),
+    SystemType.TIER_3: SystemSpec(
+        system=SystemType.TIER_3,
+        gpu_model="L4",
+        vram_gb=24,
+        vcpu=4,
+        memory_gb=16,
+        max_parallel_envs=None,
+        available=False,
+        instance_type="g6.xlarge",
+    ),
+    SystemType.TIER_4: SystemSpec(
+        system=SystemType.TIER_4,
+        gpu_model="L40S",
+        vram_gb=48,
+        vcpu=4,
+        memory_gb=32,
+        max_parallel_envs=None,
+        available=False,
+        instance_type="g6e.xlarge",
+    ),
+}

{simulo_interfaces-0.18.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.18.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.18.0 → simulo_interfaces-0.20.0}/src/simulo_interfaces.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ src/simulo/interfaces/platform/policy_bundle.py
 src/simulo/interfaces/platform/runs.py
 src/simulo/interfaces/platform/runtime.py
 src/simulo/interfaces/platform/submit.py
+src/simulo/interfaces/platform/systems.py
 src/simulo/interfaces/platform/volume.py
 src/simulo/interfaces/runtime/__init__.py
 src/simulo/interfaces/runtime/anomaly.py