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

{simulo_interfaces-0.16.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.16.0
+Version: 0.18.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.16.0 → simulo_interfaces-0.18.0}/pyproject.toml

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

@@ -9,14 +9,6 @@ implementation-free — concrete behaviour lives in the future
 
 from simulo.interfaces.platform.asset import AssetProtocol
 from simulo.interfaces.platform.asset_catalog import (
-    ADMIN_ASSET_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE,
-    ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE,
     ASSET_BASE_MODES,
     ASSET_CORRUPT_CODE,
     ASSET_DIGEST_MISMATCH_CODE,
@@ -205,6 +197,10 @@ from simulo.interfaces.platform.runs import (
     JOB_SCOPE_QUERY_PARAM,
     JOBS_API_DEFAULT_PORT,
     JOBS_ROUTE,
+    LOG_ARCHIVE_EXPIRED_CODE,
+    LOG_ARCHIVE_LOST_CODE,
+    LOG_ARCHIVE_READ_FAILED_CODE,
+    LOG_ARCHIVE_UNAVAILABLE_CODES,
     LOG_CHUNK_MAX_BYTES,
     LOG_TAIL_MAX_BYTES,
     TERMINAL_JOB_STATUSES,
@@ -327,6 +323,16 @@ __all__ = [
     "JOB_RESULT_ROUTE_TEMPLATE",
     "LOG_CHUNK_MAX_BYTES",
     "LOG_TAIL_MAX_BYTES",
+    # unavailable-log contract (issue #1052) — 410 Gone, TERMINAL: the bytes
+    # are gone and retrying cannot succeed
+    "LOG_ARCHIVE_EXPIRED_CODE",
+    "LOG_ARCHIVE_LOST_CODE",
+    "LOG_ARCHIVE_UNAVAILABLE_CODES",
+    # ...and its RETRYABLE counterpart, deliberately NOT one of the above:
+    # 503, the stored log could not be read right now. A client that folds it
+    # into the terminal set tells the user their logs are gone because S3 was
+    # briefly slow.
+    "LOG_ARCHIVE_READ_FAILED_CODE",
     # user scoping (issue #651)
     "JOB_SCOPE_QUERY_PARAM",
     "JOB_SCOPE_MINE",
@@ -390,15 +396,7 @@ __all__ = [
     "ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE",
     "ASSET_VERSION_REPORT_ROUTE_TEMPLATE",
     "ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE",
-    # asset catalog — admin routes
-    "ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_ROUTE_TEMPLATE",
-    "ADMIN_ASSET_VERSION_ROUTE_TEMPLATE",
+    # asset catalog — staff routes
     # asset catalog — worker routes
     "WORKER_JOB_ASSET_VALIDATION_PRESIGN_ROUTE_TEMPLATE",
     "WORKER_JOB_ASSET_VALIDATION_ROUTE_TEMPLATE",

{simulo_interfaces-0.16.0 → simulo_interfaces-0.18.0}/src/simulo/interfaces/platform/asset_catalog.py

@@ -4,7 +4,7 @@ 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, 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
+lands **before any consumer** — the control plane (customer, ``/staff/*`` and
 ``/internal/worker/*`` routes), the thin ``simulo`` client (``simulo asset ...``
 + the ``simulo run`` submit-time pin resolver), the ``simulo-backend`` worker
 (claim → download → validate), and the ``simulo-console`` catalog browser all
@@ -155,18 +155,6 @@ the two frozensets stay separate constants (identical value today) so a future r
 publish role can split them without an API change. A missing role answers one line
 naming the role and who can grant it.
 
-## Admin endpoints (``require_admin_key`` — the ONLY producers of global rows)
-
-The ``/admin`` mirrors of initiate / parts / complete / validate / deprecate /
-reactivate / delete, plus reads that **include the origin block**. Admin *initiate*
-(:data:`ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE`) REQUIRES origin:
-``{origin_type, origin_ref, origin_url?, origin_digest?}`` where ``origin_type``
-is one of :data:`ASSET_ORIGIN_TYPES`. Customer serializers exclude origin **by
-construction** — :class:`AssetRecord` / :class:`AssetVersionRecord` carry no
-origin field at all, so ``show --json`` and console payloads can never contain
-it. An org publish records ``origin_type="customer_upload"`` for schema
-symmetry.
-
 ## Worker endpoints (``require_worker`` + lease header)
 
 * The existing claim response
@@ -504,33 +492,6 @@ ASSET_VERSION_REPORT_ROUTE_TEMPLATE = "/v1/asset-versions/{version_id}/report"
 #: :data:`ASSET_NOT_EXPORTABLE_CODE`. ``.format(version_id=...)``.
 ASSET_VERSION_DOWNLOAD_ROUTE_TEMPLATE = "/v1/asset-versions/{version_id}/download"
 
-# --------------------------------------------------------------------------
-# Admin routes  (require_admin_key; the ONLY producers of global rows)
-# --------------------------------------------------------------------------
-#
-# Mirrors of initiate/parts/complete/validate/deprecate/delete, plus reads that
-# INCLUDE the origin block. Same two path families under /admin.
-
-#: ``POST`` — admin initiate (REQUIRES origin). ``.format(kind=..., name=...)``.
-ADMIN_ASSET_VERSIONS_ROUTE_TEMPLATE = "/admin/assets/{kind}/{name}/versions"
-#: ``POST`` — admin batch part presigns. ``.format(version_id=...)``.
-ADMIN_ASSET_VERSION_UPLOAD_PARTS_ROUTE_TEMPLATE = "/admin/asset-versions/{version_id}/upload/parts"
-#: ``POST`` — admin complete multipart upload. ``.format(version_id=...)``.
-ADMIN_ASSET_VERSION_UPLOAD_COMPLETE_ROUTE_TEMPLATE = "/admin/asset-versions/{version_id}/upload/complete"
-#: ``POST`` — admin revalidate. ``.format(version_id=...)``.
-ADMIN_ASSET_VERSION_VALIDATE_ROUTE_TEMPLATE = "/admin/asset-versions/{version_id}/validate"
-#: ``POST`` — admin deprecate by ``vN``. ``.format(kind=..., name=..., version=<int>)``.
-ADMIN_ASSET_VERSION_DEPRECATE_ROUTE_TEMPLATE = "/admin/assets/{kind}/{name}/versions/v{version}/deprecate"
-#: ``POST`` — admin reactivate (un-deprecate) by ``vN`` (global catalog, admin-only).
-#: ``.format(kind=..., name=..., version=<int>)``.
-ADMIN_ASSET_VERSION_REACTIVATE_ROUTE_TEMPLATE = "/admin/assets/{kind}/{name}/versions/v{version}/reactivate"
-#: ``DELETE`` — admin delete by ``vN``. ``.format(kind=..., name=..., version=<int>)``.
-ADMIN_ASSET_VERSION_BY_NUMBER_ROUTE_TEMPLATE = "/admin/assets/{kind}/{name}/versions/v{version}"
-#: ``GET`` — admin asset read (INCLUDES origin). ``.format(kind=..., name=...)``.
-ADMIN_ASSET_ROUTE_TEMPLATE = "/admin/assets/{kind}/{name}"
-#: ``GET`` — admin version read (INCLUDES origin). ``.format(version_id=...)``.
-ADMIN_ASSET_VERSION_ROUTE_TEMPLATE = "/admin/asset-versions/{version_id}"
-
 # --------------------------------------------------------------------------
 # Worker routes  (bearer = static WORKER_TOKEN; + lease header, see submit.py)
 # --------------------------------------------------------------------------

{simulo_interfaces-0.16.0 → simulo_interfaces-0.18.0}/src/simulo/interfaces/platform/runs.py

@@ -74,6 +74,44 @@ HTTP API shape (all responses JSON; all timestamps ISO 8601 UTC, e.g.
   sequence; a line-oriented client trims its first partial line client-side
   (``simulo logs --follow`` requests a generous byte window for its line
   count and does exactly that).
+
+  **Log retention, and the ``410 Gone`` outcome it produces.** A job's logs
+  live in the platform's live-tail store while the job runs, and are archived
+  to object storage once it reaches a terminal status. That archive is kept
+  for a BOUNDED time, and once it is gone the log is gone — there is no
+  second copy and no retry brings it back.
+
+  **The window's LENGTH is deliberately not stated here.** It is a
+  per-environment deployment value — an object-store lifecycle rule, mirrored
+  by the platform's own retention ceiling — and it differs between production,
+  staging, and a local development stack, which a client cannot reliably tell
+  apart. Restating a number in this module would publish a copy to PyPI that
+  no guard covers and that nobody would update the first time the window
+  moved, so a released client would go on stating a figure that had stopped
+  being true. Simulo's product documentation (docs.simulo.ai) carries the
+  single user-facing statement of the current windows, and the ``simulo``
+  CLI's own message names the behaviour rather than the number for exactly
+  this reason.
+
+  What IS contractual here, and does not vary by environment: reading a job's
+  logs after that point answers **410 Gone** in the usual
+  error envelope, with a machine-readable code naming WHICH of the two
+  terminal conditions occurred:
+
+  * :data:`LOG_ARCHIVE_EXPIRED_CODE` — the archive aged out under the
+    retention policy above;
+  * :data:`LOG_ARCHIVE_LOST_CODE` — the platform could not archive the bytes
+    and, rather than retain them indefinitely, accounted for the loss and
+    released them.
+
+  Both are TERMINAL: retrying the same request cannot succeed, so a client
+  must present them as "these logs are no longer available" rather than as an
+  empty log or a generic failure. Neither is ``404`` — ``404 job_not_found``
+  is this API's deliberately indistinguishable answer for a job the caller
+  may not see, so reusing it here could not tell "no such job" apart from
+  "your logs expired". A transient storage failure is a separate, RETRYABLE
+  ``503`` carrying :data:`LOG_ARCHIVE_READ_FAILED_CODE`, and is never one of
+  these codes.
 * ``GET /v1/jobs/{job_id}/result`` — the job's result JSON object. 404 (code
   ``result_not_available``) until the run stores one. A run stores its result
   when it completes successfully, and in ONE failure case: a run reported
@@ -222,6 +260,46 @@ LOG_CHUNK_MAX_BYTES = 256 * 1024
 #: server's tail scan bounded. Values above this cap answer 422.
 LOG_TAIL_MAX_BYTES = 4 * LOG_CHUNK_MAX_BYTES
 
+#: ``410 Gone`` — the job's archived log aged out under the platform's log
+#: retention policy. TERMINAL: the bytes are gone, there is no second copy,
+#: and retrying cannot succeed. The window's length is a per-environment
+#: deployment value and is deliberately not restated here — see the module
+#: docstring's retention section for why a copy in this package would be a
+#: published number nobody maintains.
+LOG_ARCHIVE_EXPIRED_CODE = "log_archive_expired"
+#: ``410 Gone`` — the platform could not archive this job's terminal log
+#: bytes and, rather than retain them indefinitely, accounted for the loss
+#: and released them. Also TERMINAL, and deliberately DISTINCT from
+#: :data:`LOG_ARCHIVE_EXPIRED_CODE`: "your logs aged out under the documented
+#: policy" and "we could not keep your logs" are different statements, and a
+#: client that collapses them makes the retention guarantee above
+#: unverifiable from the outside.
+LOG_ARCHIVE_LOST_CODE = "log_archive_lost"
+#: Both unavailable-log codes. A client that treats "the logs are no longer
+#: available" as ONE user-facing outcome branches on this set; one that
+#: reports which condition occurred uses the two codes individually. Either
+#: way the outcome is terminal — never an empty log, and never a retry loop.
+LOG_ARCHIVE_UNAVAILABLE_CODES = frozenset({LOG_ARCHIVE_EXPIRED_CODE, LOG_ARCHIVE_LOST_CODE})
+
+#: ``503 Service Unavailable`` — the stored log could not be READ right now.
+#: The RETRYABLE counterpart of the two codes above, and deliberately a
+#: different status as well as a different code: a throttle, a credential
+#: problem, or a connection reset says nothing about whether the bytes still
+#: exist, so presenting it as "your logs are gone" would be wrong twice — it
+#: tells the user something false and it invites them to stop retrying.
+#:
+#: NOT a member of :data:`LOG_ARCHIVE_UNAVAILABLE_CODES`, and a client MUST
+#: NOT fold it in. It carries the same ``{"error": {"code", "message",
+#: "request_id"}}`` envelope as every other error; a client that recognizes it
+#: should say the logs are temporarily unreadable and suggest retrying.
+#:
+#: THE WIRE VALUE SAYS ``read_failed``, NOT ``unavailable``, on purpose. An
+#: earlier draft of this contract spelled it ``log_archive_unavailable`` —
+#: the one code deliberately EXCLUDED from a set named
+#: ``LOG_ARCHIVE_UNAVAILABLE_CODES``, which is a trap for every reader who
+#: greps for one and finds the other. Do not "align" it back.
+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})

{simulo_interfaces-0.16.0 → simulo_interfaces-0.18.0/src/simulo_interfaces.egg-info}/PKG-INFO

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