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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.16.0
+Version: 0.17.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.17.0}/pyproject.toml

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

@@ -205,6 +205,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 +331,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",

{simulo_interfaces-0.16.0 → simulo_interfaces-0.17.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.17.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.17.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