simulo-interfaces 0.12.0__tar.gz → 0.13.0__tar.gz

{simulo_interfaces-0.12.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.12.0
+Version: 0.13.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.12.0 → simulo_interfaces-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.12.0"
+version = "0.13.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.12.0 → simulo_interfaces-0.13.0}/src/simulo/interfaces/authoring/record.py

@@ -88,10 +88,10 @@ ProfileName = Literal["core", "standard", "full"]
 VALID_PROFILES: Tuple[str, ...] = ("core", "standard", "full")
 
 # Profile defaults table. Each profile lists ONLY the fields it turns on; any
-# field absent from a profile's dict defaults to False. SRD §10.1 mandates
+# field absent from a profile's dict defaults to False. MCAP recording mandates
 # Phase 1 robot/contact/sensor/video stay off; the `full` row below holds the
 # line by not enabling those streams in Phase 1. Wave 2 may flip them on
-# (plan §6 Wave 2 task F) — that edit is intentionally scoped to this table.
+# when enabled — that edit is intentionally scoped to this table.
 #
 # Wave Policy-Eval-Completeness (2026-06-21) — three changes to defaults:
 #
@@ -161,7 +161,7 @@ _PROFILE_DEFAULTS: Dict[str, Dict[str, bool]] = {
         "include_terminations": True,
         "include_events": True,
         # Wave 2 — Phase 2 streams enabled in the `full` profile per plan
-        # §6 Wave 2 task F + SRD §7 line 409. Phase 3 streams (video, depth,
+        # The full profile includes Phase 2 streams. Phase 3 streams (video, depth,
         # lidar) and `include_collisions` stay opt-in even under `full` to
         # avoid surprising users with high-volume captures.
         "include_robot_state": True,

{simulo_interfaces-0.12.0 → simulo_interfaces-0.13.0}/src/simulo/interfaces/platform/artifacts.py

@@ -133,7 +133,9 @@ and the narrow ``job_artifacts`` table (everything registered via
 appears in the union **exactly once**. The projection reuses the
 platform-standard paginated envelope (``items``/``total``/``page``/``limit``/
 ``pages``; default ``limit=20``, max 100, out-of-range → 422) and the standard
-error shape.
+error shape — see :mod:`simulo.interfaces.platform.runs` for the full
+contract, including the ``pages >= 1`` invariant that holds even for
+``total == 0``.
 """
 
 from collections.abc import Mapping

{simulo_interfaces-0.12.0 → simulo_interfaces-0.13.0}/src/simulo/interfaces/platform/asset_catalog.py

@@ -1,8 +1,8 @@
-"""USD Asset Catalogs wire contract (USD Asset Catalogs Wave, PR-1).
+"""USD asset-catalog wire contract.
 
 This is the **canonical, single source of truth** for the reference grammar, the
 route constants, the size caps, the wire dataclasses, and the reserved-word /
-role / verdict enumerations that carry a USD *asset* (a versioned robot or world
+role / verdict enumerations that carry a USD *asset* (a versioned robot, world, or prop
 package) from the laptop client to the cloud catalog and back into a job. It
 lands **before any consumer** — the control plane (customer, ``/admin/*`` and
 ``/internal/worker/*`` routes), the thin ``simulo`` client (``simulo asset ...``
@@ -28,8 +28,8 @@ stay decoupled (no import cycle). When you want the ref grammar, routes, or a
 wire record, reach here; when you want the mounted-handle protocol, reach
 ``simulo.interfaces.platform.asset``.
 
-The design intent behind every shape below follows the USD Asset Catalogs UX
-proposal; the frozen wire specifics are transcribed from the API contract-freeze doc.
+The constants, parsers, dataclasses, and tests in this module own the exact
+cross-package wire shape.
 
 ## Two catalogs, one grammar
 
@@ -37,15 +37,15 @@ proposal; the frozen wire specifics are transcribed from the API contract-freeze
 
 * **publisher** — omitted means *the caller's own organization catalog*.
   ``simulo`` is the reserved publisher for the read-only **global** catalog.
-  Publishers are organization slugs, so a future org-to-org share is a
-  *permissions* change, not a grammar change — this module therefore accepts
+  Publishers are organization slugs. Sharing is an authorization concern, not
+  a grammar concern, so this module accepts
   any syntactically valid org slug in the publisher position (server-side
   permission checks decide what is actually *usable*), and rejects only the
   reserved segments that can never be org slugs (``builtin``/``nucleus``/
   ``local``/``platform``; ``simulo`` is allowed because it names the global
   catalog). See :data:`RESERVED_ASSET_PUBLISHERS` / :data:`GLOBAL_ASSET_PUBLISHER`.
 * **kind** — :data:`ASSET_KINDS` = ``("robot", "world", "prop")``. ``prop``
-  joined the grammar in W7 — furniture/mount/fixture assets that are neither
+  covers furniture/mount/fixture assets that are neither
   a robot nor a full environment (e.g. ``prop/table:v1``).
 * **name** — an org/project **slug** (:data:`ASSET_SLUG_PATTERN`), unique per
   ``(publisher, kind)``. A reserved-publisher word (:data:`RESERVED_ASSET_PUBLISHERS`)
@@ -121,7 +121,10 @@ opaque asset-version id (:data:`ASSET_VERSION_ROUTE_TEMPLATE` subtree, whose
   latest is hidden by default, and additionally surfaced (with its
   ``deprecated`` :attr:`AssetRecord.latest_version_status`) when
   ``include_deprecated=true`` (``simulo asset list --deprecated``). Global rows
-  are visible to any authenticated user.
+  are visible to any authenticated user. Returns the platform-standard
+  paginated envelope (``items``/``total``/``page``/``limit``/``pages``) — see
+  :mod:`simulo.interfaces.platform.runs` for the full contract, including the
+  ``pages >= 1`` invariant that holds even for ``total == 0``.
 * :data:`ASSET_ROUTE_TEMPLATE` (``GET`` ``?publisher=``) — one asset with
   description/tags + version history; (``PATCH``) — description/tags, the only
   mutable metadata.
@@ -215,17 +218,17 @@ from simulo.interfaces.ids import AssetId, AssetVersionId, Digest, ResourceUri
 # Reference grammar — kinds, reserved words, slug rule
 # --------------------------------------------------------------------------
 
-#: The asset kinds valid in the ref grammar today (§2). ``robot`` is an
+#: The asset kinds valid in the ref grammar today. ``robot`` is an
 #: articulated system instantiated through the Simulo robot APIs; ``world`` is
 #: an environment / facility / terrain / scene robots operate in ("world", not
 #: "environment", because "environment" is overloaded — ``LearningEnv``, Python
 #: envs, deploy envs); ``prop`` (W7) is a furniture/mount/fixture asset that is
 #: neither a robot nor a full environment (e.g. a lab table or camera stand) —
-#: the additive kind §13 anticipated. Adding a further kind later is an
+#: the additive kind added most recently. Adding a further kind later is an
 #: additive change to this constant.
 ASSET_KINDS = ("robot", "world", "prop")
 
-#: Publisher segments that can never be organization slugs (§2). All are rejected
+#: Publisher segments that can never be organization slugs. All are rejected
 #: in the publisher position **except** :data:`GLOBAL_ASSET_PUBLISHER`
 #: (``"simulo"``), which names the read-only global catalog. They are also
 #: rejected as asset *names*, so no ref segment reads ambiguously as a catalog
@@ -234,8 +237,8 @@ ASSET_KINDS = ("robot", "world", "prop")
 #: catalog-grammar reservation.)
 RESERVED_ASSET_PUBLISHERS = frozenset({"simulo", "builtin", "nucleus", "local", "platform"})
 
-#: The one reserved publisher that IS a valid publisher: the global catalog
-#: (§2, §11). Omitting the publisher means the caller's own org; ``simulo`` means
+#: The one reserved publisher that IS a valid publisher: the global catalog.
+#: Omitting the publisher means the caller's own org; ``simulo`` means
 #: the global catalog; nothing else is a reserved-but-valid publisher.
 GLOBAL_ASSET_PUBLISHER = "simulo"
 
@@ -252,8 +255,8 @@ GLOBAL_ASSET_PUBLISHER = "simulo"
 #: inner-group bound verbatim, which has a length-2 hole: 1 char matches via the
 #: optional group being absent, 3+ chars matches via the group, but exactly 2
 #: chars can match neither — incoherent for users. Fixed here to ``{0,61}``,
-#: which accepts every length 1–63 contiguously; see the PR-1 resolutions in
-#: ``context/implementation-plans/archive/usd-asset-catalogs/api-contract-freeze.md``.)
+#: which accepts every length 1–63 contiguously; see
+#: ``context/reference/asset-catalog-contract.md`` "Reference parsing".)
 #: Pinned here (rather than imported) because ``simulo-interfaces`` has zero
 #: dependencies on the control plane — the value is copied deliberately and this
 #: docstring is the drift anchor.
@@ -452,7 +455,7 @@ def format_asset_ref(
 
 #: ``GET`` — list/search assets (``?scope=&kind=&q=&tag=``); labeled scopes.
 ASSETS_ROUTE = "/v1/assets"
-#: ``POST`` — batch submit-time pin resolver (``{refs, runtime}``); §6.
+#: ``POST`` — batch submit-time pin resolver (``{refs, runtime}``).
 ASSETS_RESOLVE_ROUTE = "/v1/assets/resolve"
 #: ``GET`` — the org storage meter (per-asset bytes, org total, quota).
 ASSETS_USAGE_ROUTE = "/v1/assets/usage"
@@ -462,7 +465,7 @@ ASSETS_USAGE_ROUTE = "/v1/assets/usage"
 ASSET_ROUTE_TEMPLATE = "/v1/assets/{kind}/{name}"
 #: ``POST`` — initiate a publish (create a new version). ``.format(kind=..., name=...)``.
 ASSET_VERSIONS_ROUTE_TEMPLATE = "/v1/assets/{kind}/{name}/versions"
-#: ``POST`` — new version from stored source with the current converter (§9.5).
+#: ``POST`` — new version from stored source with the current converter.
 #: ``.format(kind=..., name=...)``.
 ASSET_RECONVERT_ROUTE_TEMPLATE = "/v1/assets/{kind}/{name}/reconvert"
 #: ``POST`` — deprecate one version by its ``vN`` number.
@@ -558,18 +561,18 @@ WORKER_JOB_ASSET_VALIDATION_ROUTE_TEMPLATE = "/internal/worker/jobs/{job_id}/ass
 #: into the ``args`` mapping that gets hashed. An old client that omits it submits
 #: a job with no pinned assets — the additive default. The control plane
 #: re-verifies every pin in the submit transaction and records the ``job_assets``
-#: rows (§6).
+#: rows.
 ASSETS_FIELD = "assets"
 
 # --------------------------------------------------------------------------
 # Authorization roles, status / verdict / format enumerations
 # --------------------------------------------------------------------------
 
-#: Roles allowed to publish / reconvert an org asset (§3). Missing role → one line
+#: Roles allowed to publish / reconvert an org asset. Missing role → one line
 #: naming the role and who can grant it.
 ASSET_PUBLISH_ROLES = frozenset({"owner", "admin", "member"})
-#: Roles allowed to deprecate / delete / edit metadata (§3). Identical value to
-#: :data:`ASSET_PUBLISH_ROLES` today — proposal §3 groups publish/deprecate/delete
+#: Roles allowed to deprecate / delete / edit metadata. Identical value to
+#: :data:`ASSET_PUBLISH_ROLES` today: publish/deprecate/delete
 #: under one publish capability (plan critic review, 2026-07-17 realignment) — kept
 #: as a separate constant so a future, narrower publish role can diverge from
 #: lifecycle without an API change.
@@ -592,22 +595,22 @@ ASSET_LIFECYCLE_ROLES = frozenset({"owner", "admin", "member"})
 ASSET_VERSION_STATUSES = ("uploading", "validating", "published", "failed", "deprecated", "deleted")
 #: The ``asset_validations.verdict`` domain — ``passed`` / ``failed`` are asset
 #: verdicts; ``error`` is an *infrastructure* failure (validator crash), rendered
-#: distinctly so it never reads as "your USD is broken" (§5.1, §8.2).
+#: distinctly so it never reads as "your USD is broken".
 ASSET_VALIDATION_VERDICTS = ("passed", "failed", "error")
 #: The ``asset_versions.source_format`` domain — the two ingest formats of the
-#: first release (§9; MJCF and others extend the same machinery later).
+#: first release; MJCF and others can extend the same machinery later.
 ASSET_SOURCE_FORMATS = ("usd", "urdf")
 #: The base-mode domain — whether a robot is bolted down (``fixed``, manipulators)
 #: or free (``floating``, mobile/legged). Inexpressible in URDF, so declared at
-#: publish (§9.1); ``None`` for worlds and where unset.
+#: publish; ``None`` for worlds and where unset.
 ASSET_BASE_MODES = ("fixed", "floating")
-#: The ``asset_versions.origin_type`` domain (§11.2) — **admin-surface only**.
+#: The ``asset_versions.origin_type`` domain — **admin-surface only**.
 #: ``customer_upload`` is recorded for org publishes (schema symmetry);
 #: ``simulo_authored`` / ``third_party_import`` are the global-catalog origins.
 #: These values NEVER appear in a customer-facing serializer (see
 #: :class:`AssetRecord` / :class:`AssetVersionRecord`, which carry no origin field).
 ASSET_ORIGIN_TYPES = ("customer_upload", "simulo_authored", "third_party_import")
-#: The ``?scope=`` list/search filter values (§5.3). ``org`` = the caller's org
+#: The ``?scope=`` list/search filter values. ``org`` = the caller's org
 #: catalog, ``global`` = the ``simulo`` catalog, ``all`` = both (labeled rows).
 ASSET_LIST_SCOPES = ("org", "global", "all")
 
@@ -615,13 +618,13 @@ ASSET_LIST_SCOPES = ("org", "global", "all")
 # Size caps (security NFR — request-size limits; see nfr SKILL)
 # --------------------------------------------------------------------------
 
-#: Maximum total archive size of one published asset version (§10, §14). 413/422
+#: Maximum total archive size of one published asset version. 413/422
 #: over this. Settings key: ``max_asset_version_bytes``.
 MAX_ASSET_VERSION_BYTES = 10 * 1024 * 1024 * 1024  # 10 GiB
-#: Maximum number of files in one asset package (§10, §14). Settings key:
+#: Maximum number of files in one asset package. Settings key:
 #: ``max_asset_files``.
 MAX_ASSET_FILES = 2000
-#: Multipart upload part size (§10, §14). Settings key: ``asset_upload_part_bytes``.
+#: Multipart upload part size. Settings key: ``asset_upload_part_bytes``.
 ASSET_UPLOAD_PART_BYTES = 64 * 1024 * 1024  # 64 MiB
 
 #: Maximum character length of an asset reference (security NFR — bounds an
@@ -637,22 +640,21 @@ MAX_ASSET_REF_CHARS = 256
 
 #: Maximum number of refs in one :data:`ASSETS_RESOLVE_ROUTE` batch (security NFR
 #: — bounds an otherwise-unbounded request array; over this ⇒ 422). Pinned as the
-#: frozen contract value (freeze doc "## PR-6 amendments": ``{refs: [<=64 strings],
-#: runtime}``). The client de-duplicates before counting, so this bounds the number
+#: request-schema value: ``{refs: [<=64 strings], runtime}``. The client
+#: de-duplicates before counting, so this bounds the number
 #: of *distinct* refs, not the raw authored occurrences.
 MAX_ASSETS_RESOLVE_BATCH = 64
 
 #: The runtime alias :data:`ASSETS_RESOLVE_ROUTE` / :class:`AssetsResolveRequest.runtime`
-#: uses when a caller has no other runtime to name (§6, §14 — one runtime today, no
-#: runtime registry yet; a future registry replaces this constant, proposal §11.3
-#: task-shaped aliases). Hoisted here (rather than left as a client-only constant) because
+#: uses when a caller has no other runtime to name. Hoisted here rather than
+#: left as a client-only constant because
 #: the ``validated_on_runtime`` match requires the CLIENT's resolve request and the
 #: VALIDATOR's finalize call to send the IDENTICAL string — one shared constant is the
-#: only way that can never drift (freeze doc "Runtime-string seam", 2026-07-17).
+#: only way to prevent string drift.
 DEFAULT_ASSET_RUNTIME = "isaac"
 
 # --------------------------------------------------------------------------
-# Publish options envelope (PR-12 — freeze doc "## PR-7 amendments": --scale)
+# Publish options envelope
 # --------------------------------------------------------------------------
 
 #: Bounds on :attr:`AssetPublishOptions.scale` (security NFR — a
@@ -668,20 +670,20 @@ MAX_ASSET_SCALE = 1e6
 # Facts envelope + wire error codes
 # --------------------------------------------------------------------------
 
-#: The schema version stamped on the asset-facts document (§8.2). **Additive-only**
+#: The schema version stamped on the asset-facts document. **Additive-only**
 #: — new facts fields may be added under this version; a breaking change would mint
 #: ``simulo.asset_facts.v2``. Carried opaquely as ``Mapping[str, Any]`` on the wire
-#: (the exact field list is settling, §15.4).
+#: (the exact field list is settling).
 ASSET_FACTS_SCHEMA_VERSION = "simulo.asset_facts.v1"
 
 #: Error code (``GET`` :data:`ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE`, ``403``) when
 #: a **global** asset download is refused — global assets are referenceable and
-#: usable in jobs, never exportable (§5.4). Pinned as a constant (like
+#: usable in jobs, never exportable. Pinned as a constant (like
 #: ``submit.SEED_SOURCE_CONFLICT_CODE``) because both the control plane raising it
 #: and the CLI mapping it to friendly copy switch on this exact string.
 ASSET_NOT_EXPORTABLE_CODE = "not_exportable"
 #: Error/verdict code the worker uses to **fail a job in place** when a claimed
-#: asset's archive is missing at mount time (§14 security posture; the worker
+#: asset's archive is missing at mount time (the security posture; the worker
 #: verifies digests at mount). Pinned for the same reason as above.
 ASSET_MISSING_CODE = "asset_missing"
 #: The ``jobs.job_type`` value of a platform-internal asset-validation job
@@ -716,7 +718,7 @@ ASSET_CORRUPT_CODE = "asset_corrupt"
 #: The uniform per-ref miss code the batch resolver (:data:`ASSETS_RESOLVE_ROUTE`)
 #: and the job-submit pin re-verify both answer for a ref that does not resolve —
 #: unknown, cross-org, deleted, or malformed, **all reported identically**
-#: (anti-enumeration; freeze doc "## PR-6 amendments"). Carried on
+#: (anti-enumeration; batch-resolve schema and tests). Carried on
 #: :class:`ResolveMiss.code`; the submit-pin path raises the same code as its
 #: ``404`` error ``code``. Pinned as a constant because the control plane raising
 #: it and the CLI mapping it to friendly copy switch on this exact string.
@@ -728,21 +730,21 @@ ASSET_NOT_FOUND_CODE = "asset_not_found"
 #
 # Hoisted here per the freeze's "## PR-7 amendments" ("CP friendly-error
 # codes used by the CLI hoist into interfaces/platform/asset_catalog.py —
-# single source; a CP rename can no longer silently degrade §5.1 copy").
+# single source; a control-plane rename can no longer silently degrade CLI copy).
 # These mirror the control plane's OWN local constants
 # (`simulo_control_plane.assets.constants` / `assets/quota.py`) by VALUE —
 # the same "pinned here, not imported" discipline :data:`ASSET_SLUG_PATTERN`
 # documents above (simulo-interfaces has zero dependency on the control
 # plane); this docstring is the drift anchor for a future reconciliation
 # where the control plane imports these directly instead of re-declaring
-# them. The thin client's `simulo asset publish`/`validate` §5.1 error
+# them. The thin client's `simulo asset publish`/`validate` error
 # rendering (`_client/cli.py::_friendly_asset_error`) matches these exact
 # strings, never a hand-typed literal.
 # --------------------------------------------------------------------------
 
 #: 403 — publishing this archive would exceed the org's storage quota
-#: (`assets/quota.py::check_asset_storage_quota`). The CLI appends the §5.1
-#: "two ways out" (delete or upgrade) to the server's own message.
+#: (`assets/quota.py::check_asset_storage_quota`). The CLI appends two remedies
+#: (delete assets or upgrade storage) to the server's own message.
 ASSET_STORAGE_QUOTA_EXCEEDED_CODE = "asset_storage_quota_exceeded"
 #: 422 — the archive exceeds :data:`MAX_ASSET_VERSION_BYTES`.
 ASSET_ARCHIVE_TOO_LARGE_CODE = "asset_archive_too_large"
@@ -767,14 +769,14 @@ ASSET_UPLOAD_INCOMPLETE_CODE = "asset_upload_incomplete"
 # this package (self-contained build discipline, see this module's own
 # "mirrored, not imported" precedent above), so this is a value-only
 # duplication, drift-anchored by this docstring. The thin client's
-# `simulo asset get`/`deprecate`/`delete` §5.4/§5.5 error rendering
+# `simulo asset get`/`deprecate`/`delete` error rendering
 # (`_client/cli.py::_friendly_asset_error`) matches these exact strings so
 # the server's already user-language message renders verbatim, never a
 # code-prefixed wire dump.
 # --------------------------------------------------------------------------
 
 #: 409 — ``simulo asset delete`` refused because at least one non-validation
-#: job still references the version (§5.5's delete guard). The server's
+#: job still references the version (the job-reference delete guard). The server's
 #: message already names the job count and the first job id, proposal-
 #: verbatim, and now also points to the ``--force`` override; the CLI renders
 #: it as-is.
@@ -943,6 +945,13 @@ class AssetVersionRecord:
     validation_attempts: int = 0
     """Number of validation attempts made for this version."""
 
+    validation_job_id: Optional[str] = None
+    """Exact id of the newest system validation attempt for an organization-owned
+    version, or ``None`` when unavailable. Additive and diagnostic-only: callers
+    may surface it as a support/correlation reference, but system validation jobs
+    are not part of the ordinary Jobs catalog, their runtime logs and free-form
+    results are not public surfaces, and global asset reads never expose the id."""
+
     published_by: Optional[str] = None
     """Display identity of the publishing user, or ``None`` while unpublished."""
 
@@ -1134,8 +1143,7 @@ class WorkerAssetInfo:
 
 @dataclass(**_DC)
 class AssetPublishOptions:
-    """The optional ``options`` envelope of a publish initiate (PR-12 —
-    freeze doc "## PR-7 amendments" executed at Wave 3).
+    """The optional ``options`` envelope of a publish-initiate request.
 
     Carried on the initiate body (customer AND admin) as ``options:
     {scale?: float}``; persisted with the version; threaded verbatim into the

{simulo_interfaces-0.12.0 → simulo_interfaces-0.13.0}/src/simulo/interfaces/platform/runs.py

@@ -10,7 +10,7 @@ schema, enum reuse, endpoint constants, and semantics docstrings only.
 Field names and lifecycle align with the platform's Job use case: 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
+``completed``/``failed``/``cancelled`` — job API's wording; the local executor
 uses the ``running`` → ``completed``|``failed`` subset, the cloud adds
 ``queued``/``cancelled``).
 
@@ -23,6 +23,23 @@ HTTP API shape (all responses JSON; all timestamps ISO 8601 UTC, e.g.
       {"items": [<JobRecord>, ...], "total": 3, "page": 1, "limit": 20, "pages": 1}
 
   ``limit`` defaults to 20, maximum 100; out-of-range ``page``/``limit`` → 422.
+
+  **``pages`` is always >= 1**, including for an empty list (``total: 0`` →
+  ``pages: 1``, not ``0``). Clients treat ``page > pages`` as "this page is out
+  of range" and recover by clamping to ``pages``; a ``pages: 0`` would make
+  ``page: 1`` permanently out of range and the clamp non-terminating. Both
+  producers of this envelope (the control plane and the local
+  ``simulo-backend serve`` stand-in) enforce the floor. This platform-standard
+  paginated envelope shape (``items``/``total``/``page``/``limit``/``pages``)
+  is reused verbatim by every other list endpoint in this package — recordings
+  and models in :mod:`simulo.interfaces.platform.submit`, the artifacts
+  projection in :mod:`simulo.interfaces.platform.artifacts`, and the asset
+  list/search route (``ASSETS_ROUTE``) in
+  :mod:`simulo.interfaces.platform.asset_catalog` — and the ``pages >= 1``
+  floor applies identically to all of them. That list is the complete set:
+  adding a paginated route means adding it here too, so a reader learning
+  which endpoints this invariant governs is never told a smaller number than
+  the truth.
 * ``GET /v1/jobs/{job_id}`` — one job record (the :class:`JobRecord` fields).
 * ``GET /v1/jobs/{job_id}/logs?offset=N`` — one log chunk::
 
@@ -105,8 +122,7 @@ routes documented in ``submit.py``) additionally accept an optional
   never the default, and available to any active member (no additional role
   beyond org membership — the platform's existing flat-permission model for
   jobs, ``JOB_CREATE_ROLES``/``JOB_CANCEL_ROLES``).
-* any other value → 422 (Job.md "List All Jobs Using CLI" AF-3, invalid
-  filter option).
+* any other value → 422 as an invalid filter option.
 
 ``POST /v1/jobs/{job_id}/cancel`` is a deliberate exception: it is NOT scope-
 gated and keeps resolving org-wide regardless of ``?scope=`` — any active
@@ -160,8 +176,7 @@ JOB_SCOPE_QUERY_PARAM = "scope"
 #: Default / explicit-opt-in-only values for :data:`JOB_SCOPE_QUERY_PARAM`.
 JOB_SCOPE_MINE = "mine"
 JOB_SCOPE_ORG = "org"
-#: The closed domain of ``?scope=`` — any other value is a 422 (Job.md "List
-#: All Jobs Using CLI" AF-3).
+#: The closed domain of ``?scope=`` — any other value is a 422.
 JOB_LIST_SCOPES = (JOB_SCOPE_MINE, JOB_SCOPE_ORG)
 
 #: Upper bound on the log bytes a single ``/logs`` response carries. The server
@@ -245,6 +260,19 @@ class JobRecord:
     attempts: int = 0
     """Number of execution attempts started so far (retries make this > 1)."""
 
+    viewstream: bool = False
+    """Whether this run requested an interactive live view. Additive and
+    tolerant: older producers omit it and consumers see ``False``."""
+
+    seed: Optional[Mapping[str, Any]] = None
+    """Resolved seed provenance (``job_id``, ``model_id``, ``kind``, and
+    ``name``), or ``None`` for a fresh run. Kept mapping-shaped so a real JSON
+    response can be passed directly to ``JobRecord(**payload)``."""
+
+    job_type: str = "other"
+    """Producer-defined run category. ``"other"`` is an ordinary user job;
+    additive producer categories remain readable by older consumers."""
+
     assets: tuple[str, ...] = ()
     """Human-readable ref of every asset this run pinned, oldest first (the
     ``job_assets`` denormalized canonical ref, e.g. ``myorg/robot/tiny-arm:v1``).
@@ -295,6 +323,12 @@ class JobRecord:
     scoping" section): a shared view of everyone's jobs must say whose job
     each row is, not just that it exists."""
 
+    submitted_by_display: Optional[str] = None
+    """Human-readable identity for :attr:`submitted_by_user_id`, currently the
+    submitter's email. ``None`` covers system-owned runs, deleted accounts,
+    and producers predating the additive field; clients must never fall back
+    to displaying the raw user id."""
+
     outputs: Optional[JobOutputsSummary] = None
     """Typed outputs summary of the run — a **rendering input,
     never a status**: ``completed ⚠ 1 anomaly`` is drawn from here while

{simulo_interfaces-0.12.0 → simulo_interfaces-0.13.0}/src/simulo/interfaces/platform/submit.py

@@ -105,6 +105,16 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   set directly on the top-level body dict — and MUST NOT fold them into the
   ``args`` mapping that gets hashed.
 
+  **App name (live-view wave, additive):** the request body
+  optionally carries ``app_name`` (``str``) — the submitting ``App``'s
+  declared name, display context the platform's live viewer shows next to
+  ``job_name``. The SAME top-level sibling-of-``args`` placement rule as
+  ``viewstream`` and the seed fields (a display property must never perturb
+  the content-addressed ``package_id``). Optional end to end: every client
+  published before the field omits it, an older control plane ignores the
+  extra key, and a job without one renders by ``job_name`` alone — never an
+  error in either direction.
+
   :data:`SEED_SOURCE_FIELDS` pins the two field names:
 
   - ``seed_from_job_id`` (``str``) — continue training from another job's
@@ -129,7 +139,10 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
 ## Client-facing: recordings
 
 * :data:`JOB_RECORDINGS_ROUTE_TEMPLATE` (``GET``) — paginated envelope of
-  :class:`RecordingRecord`, same pagination shape as ``GET /v1/jobs``::
+  :class:`RecordingRecord`, same pagination shape as ``GET /v1/jobs``
+  (see :mod:`simulo.interfaces.platform.runs` for the full contract,
+  including the ``pages >= 1`` invariant that holds even for
+  ``total == 0``)::
 
       {"items": [<RecordingRecord>, ...], "total": 2, "page": 1, "limit": 20, "pages": 1}
 
@@ -218,7 +231,14 @@ platform-standard shape: ``{"error": {"code": ..., "message": ..., "request_id":
   exists yet).
 
 * :data:`WORKER_JOB_STREAM_READY_ROUTE_TEMPLATE` (``POST``) — request
-  ``{"stream_host": "10.0.1.7", "stream_port": 49100}``. Registers the
+  ``{"stream_host": "10.0.1.7", "stream_port": 49100}``, optionally plus
+  ``"num_envs"`` (``int`` ≥ 1 — live-view wave): the run's actual
+  parallel-environment count, read by the worker from the SDK-written
+  runtime-facts sidecar and served to the viewer as display context only.
+  Optional end to end — an older worker omits it, an older control plane
+  ignores the extra key, and the worker DROPS (never sends) a value it
+  cannot validate as a sane positive int, so a garbage sidecar can never
+  fail the endpoint registration itself. Registers the
   claiming worker's Kit signaling endpoint ONCE, the moment Kit is actually
   listening — NOT at claim (Tier-1 1.1). Reporting at claim registered the
   endpoint minutes before Kit's signaling port opened during a cold Isaac
@@ -280,12 +300,15 @@ checkpoints a training job leaves in its result's ``checkpoint_dir``
 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``::
+  :class:`ModelRecord`, same pagination shape as ``GET /v1/jobs``
+  (see :mod:`simulo.interfaces.platform.runs` for the full contract,
+  including the ``pages >= 1`` invariant that holds even for
+  ``total == 0``)::
 
       {"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 model metadata. ``404 model_not_found``
   for an unknown/foreign/malformed id — never 403 (anti-enumeration).
 
 * :data:`JOB_MODEL_DOWNLOAD_ROUTE_TEMPLATE` (``GET``) — resolves one model
@@ -671,6 +694,15 @@ class ModelRecord:
 #   `--viewstream` CLI flag at submit time, never from a package manifest) —
 #   so a manifest-borne override could otherwise force streaming on/off
 #   against the job's actual (server-recorded) submission intent.
+#   ``SIMULO_RUNTIME_FACTS_PATH`` (live-view wave) is its sidecar sibling:
+#   the worker mints a per-attempt runtime-facts path (``worker.py``,
+#   ``tempfile.mkstemp``) and exports it via ``_child_env`` so the SDK
+#   inside the job subprocess can record display facts (e.g. the
+#   parallel-environment count) the worker reads back and reports on
+#   ``stream-ready``. It is a resolved filesystem path the platform then
+#   TRUSTS AND READS — the same runner-owned class as
+#   ``SIMULO_CHECKPOINT_DIR`` / ``SIMULO_ANOMALY_DEBUG_DIR`` — so nothing
+#   user-authored may ever aim it elsewhere.
 #
 # * **User-tunable** (deliberately NOT reserved): ``_setup_checkpointing``
 #   exports ``SIMULO_CHECKPOINT_EVERY`` / ``SIMULO_CHECKPOINT_KEEP_LAST`` /
@@ -728,6 +760,7 @@ RESERVED_RUNTIME_ENV_KEYS = frozenset(
         "SIMULO_SHUTDOWN_GRACE_S",
         "SIMULO_FAST_EXIT_AFTER_RESULT",
         "SIMULO_VIEWSTREAM_ENABLED",
+        "SIMULO_RUNTIME_FACTS_PATH",
         "MAX_JOB_TIMEOUT_S",
     }
 )

{simulo_interfaces-0.12.0 → simulo_interfaces-0.13.0/src/simulo_interfaces.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.12.0
+Version: 0.13.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