cortexdbai 0.13.0__tar.gz → 0.13.1__tar.gz

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/COVERAGE.md

@@ -320,8 +320,10 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `idempotency_key` on a declared belief; `owner` on `POST /v1/scopes`; `scope` on a temporal phrase; `batch_id` on the lifecycle stream | those routes | `idempotency_key=`, `owner=`, `scope=`, `batch_id=` | covered |
 | `events_under_legal_hold`, `derived_under_legal_hold`, and `matched` counting what a hold kept | `POST /v1/forget`, `/v1/forget/preview` | in the answer (documented on both methods) | covered |
 | `in_band`, `in_band_parts` of a change set's preview; the operator key's in-band activation under `deny` (`BREAK_GLASS_REQUIRED` class `in_band`, `NOTICE_UNAVAILABLE`, `REGISTRY_STALE`) | `POST /v1/access/changes/{id}/preview`, `/activate` | `ChangeSetPreview` in `cortexdb.v1.models`; `client.break_glass(...).changeset_activate(...)` | covered |
+| A change set's 202 while its evaluation runs (0.14.1; `Retry-After`, a preview's `{state: "previewing"}`) | `POST /v1/access/changes`, `/{id}/parts`, `/{id}/preview`, `/{id}/activate` | sent again after `Retry-After` for at most `wait` seconds (`CHANGESET_WAIT_SECONDS`), then `V1EvaluationPendingError`; `wait=0` returns `EvaluationPending` | covered |
+| `operator_plane` of a tenant binding, its dry run's included (0.14.1) | `POST /v1/admin/access/tenant-binding` | `TenantBindingResponse` in `cortexdb.v1.models`; `admin_tenant_binding` | covered |
 | `deployment_mode` (`tenant_access_settings_v1`) | `GET`, `PUT /v1/admin/access/tenant-settings`; the access report's `tenant_settings` | `TenantAccessSettings` in `cortexdb.v1.models` | covered |
 | `resend` of a write status (`"no"` for a failed write, never re-sent; `"new_key"` gone) | `GET /v1/experience/status` | `write_status(...)`; `IndexingFailedError` says never to re-send | covered |
 | An omitted `X-Cortex-Actor` (issuers-file `prefix`, `hash` and `directory` tokens; SCIM clients) | every route | `actor=None`, `with_options(actor=None)`; derived from a token's `sub` when no `actor` is given (none for a mapped subject) | covered |
 | `view` left to the server (granular at an org tree's shared scope) | `/v1/recall`, `/v1/answer`, `/v1/compose` | `view=None` (the default) | covered |
-| Typed errors with `retriable` and `details` | every route | one class per code (`cortexdb.v1.errors`, 362 codes from `scripts/error_codes.json`, built from the error catalog, `docs/API_REFERENCE_V1.md` §16) under status-family classes; documented `details` keys as properties; `retry_after` | covered |
+| Typed errors with `retriable` and `details` | every route | one class per code (`cortexdb.v1.errors`, 363 codes from `scripts/error_codes.json`, built from the error catalog, `docs/API_REFERENCE_V1.md` §16) under status-family classes; documented `details` keys as properties; `retry_after` | covered |

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexdbai
-Version: 0.13.0
+Version: 0.13.1
 Summary: The Long-Term Memory Layer for AI Systems
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://docs.cortexdb.ai
@@ -319,6 +319,27 @@ sending it, with the code the server would answer. A value a route always
 refuses (an `extra_scopes` list past 40, a malformed break-glass header, a mint
 the server never accepts) raises `ValueError` before anything is sent.
 
+## What's new in 0.13.1 for CortexDB 0.14.1
+
+- **Long change-set evaluations are waited for.** A staging, a preview or an
+  activation whose evaluation runs past the server's own wait answers 202
+  with `Retry-After`; each change-set method sends the same call again until
+  the answer comes, for at most `wait` seconds (120 by default,
+  `CHANGESET_WAIT_SECONDS`; `changeset_apply`'s bounds its three steps
+  together), then raises `V1EvaluationPendingError`. `wait=0` returns the
+  raw 202 as an `EvaluationPending`. The preview waited 60 s by default.
+- **A version downgrade names what it drops**: `INVALID_ACCESS_RECORD` (a
+  change set without `convert`) or `INVALID_SCOPE_TREE` (a legacy registry
+  write), `reason == "version_downgrade"`, with `path` and `dropped`.
+- **A tenant binding's dry run** answers `operator_plane`
+  `{registers_root, in_band, mode, break_glass_required}`.
+- **Lifetime ceilings are the server's settings**: `lifetime_ceiling()` gives
+  the defaults, now 90 days for a person (a week for an agent, 30 days for a
+  service, a day for a chain token), `admin_metrics()["auth"]
+  ["lifetime_ceilings"]` the server's own, and `check_mint` leaves a chain
+  token's lifetime to the server. `InvalidBodyError` and
+  `InvalidTokenClaimError` read `lifetime_s` and `ceiling_s`.
+
 ## What's new in 0.13.0 for CortexDB 0.14.0
 
 `cortexdbai` 0.13.0 covers the whole v1 API of CortexDB 0.14.0
@@ -478,8 +499,20 @@ print(status["state"], status["consistency_token"][:4])  # activated ct1.
 A refusal raises its typed error: `PREVIEW_CHANGED` (the registry moved since
 the preview), `ACCESS_ASSERTION_FAILED` (a widening breaks one of the tenant's
 policy cases), `CHANGESET_STALE` (a record changed after staging),
-`ACCESS_LIMIT_REACHED`. `changeset_get` and `changeset_discard` read and drop a
-staged change set.
+`ACCESS_LIMIT_REACHED`, and since 0.14.1 `INVALID_ACCESS_RECORD` with
+`reason == "version_downgrade"` for a put that would make a version-2 record a
+version-1 one (`err.dropped` lists the stored record's version-2 fields the put
+leaves out: state them, or stage with `convert=True`). `changeset_get` and
+`changeset_discard` read and drop a staged change set.
+
+A large evaluation can run past the server's own wait (20 s by default): from
+0.14.1 a staging, a preview or an activation then answers 202 with
+`Retry-After`, and each method sends the same call again until the answer
+comes, for at most `wait` seconds in all (`CHANGESET_WAIT_SECONDS`, 120, by
+default; `changeset_apply`'s `wait` bounds its three steps together). Past it
+the method raises `V1EvaluationPendingError`, and the same call sent again
+joins the evaluation. `wait=0` returns the first answer as it came, a 202 as
+an `EvaluationPending` (its body, `status` and `retry_after`).
 
 Under a tenant whose operator mode is `deny`, the operator key's activation of
 a change set that registers a record, names a `service:` principal or widens
@@ -917,20 +950,25 @@ principal; its chain fields say who is acting for whom: `act` (an agent acting
 for the subject; it writes only with a `run`), `app` and `client` (an
 application, and whether a person or an agent drives it), `run` and
 `run_start`, and `taint` tags. `mint_agent_token` and `mint_app_token` mint
-the two common chains. A token with a chain field lives at most a day
-(`CHAIN_TOKEN_MAX_TTL_SECONDS`), and an agent chain token names its `caps`
-with `scopes` that confine each; the SDK refuses before sending what the
-server always refuses (`check_mint`, a `ValueError`). Other tokens live at
-most `lifetime_ceiling(subject)`: a week for a person or an agent, 30 days for
-a service. `with_token` derives a client that uses another token over the
-same connections.
+the two common chains. A token with a chain field lives at most a day by
+default (`CHAIN_TOKEN_MAX_TTL_SECONDS`), and an agent chain token names its
+`caps` with `scopes` that confine each; the SDK refuses before sending what
+the server always refuses (`check_mint`, a `ValueError`). Other tokens live at
+most their kind's ceiling, by default `lifetime_ceiling(subject)`: 90 days for
+a person (a week on a 0.14.0 server), a week for an agent, 30 days for a
+service. Since 0.14.1 each ceiling is a server setting
+(`CORTEX_MINT_MAX_LIFETIME_PERSON`, `_AGENT`, `_SERVICE`, `_CHAIN`):
+`admin_metrics()["auth"]["lifetime_ceilings"]` reports the server's, and a
+mint over one is 422 `INVALID_BODY` `ttl_too_long` with `ceiling_s`.
+`with_token` derives a client that uses another token over the same
+connections.
 
 <!-- example: tokens -->
 ```python
 from cortexdb.v1 import lifetime_ceiling
 
 erin = Cortex(URL, bearer=operator.mint_token(subject="user:erin", scope=ROOT)["token"])
-print(erin.actor, lifetime_ceiling("user:erin"))                 # user:erin 604800
+print(erin.actor, lifetime_ceiling("user:erin"))                 # user:erin 7776000
 
 home = f"{ROOT}/user:alice"
 planner = alice.with_token(alice.mint_agent_token(

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/README.md

@@ -204,6 +204,27 @@ sending it, with the code the server would answer. A value a route always
 refuses (an `extra_scopes` list past 40, a malformed break-glass header, a mint
 the server never accepts) raises `ValueError` before anything is sent.
 
+## What's new in 0.13.1 for CortexDB 0.14.1
+
+- **Long change-set evaluations are waited for.** A staging, a preview or an
+  activation whose evaluation runs past the server's own wait answers 202
+  with `Retry-After`; each change-set method sends the same call again until
+  the answer comes, for at most `wait` seconds (120 by default,
+  `CHANGESET_WAIT_SECONDS`; `changeset_apply`'s bounds its three steps
+  together), then raises `V1EvaluationPendingError`. `wait=0` returns the
+  raw 202 as an `EvaluationPending`. The preview waited 60 s by default.
+- **A version downgrade names what it drops**: `INVALID_ACCESS_RECORD` (a
+  change set without `convert`) or `INVALID_SCOPE_TREE` (a legacy registry
+  write), `reason == "version_downgrade"`, with `path` and `dropped`.
+- **A tenant binding's dry run** answers `operator_plane`
+  `{registers_root, in_band, mode, break_glass_required}`.
+- **Lifetime ceilings are the server's settings**: `lifetime_ceiling()` gives
+  the defaults, now 90 days for a person (a week for an agent, 30 days for a
+  service, a day for a chain token), `admin_metrics()["auth"]
+  ["lifetime_ceilings"]` the server's own, and `check_mint` leaves a chain
+  token's lifetime to the server. `InvalidBodyError` and
+  `InvalidTokenClaimError` read `lifetime_s` and `ceiling_s`.
+
 ## What's new in 0.13.0 for CortexDB 0.14.0
 
 `cortexdbai` 0.13.0 covers the whole v1 API of CortexDB 0.14.0
@@ -363,8 +384,20 @@ print(status["state"], status["consistency_token"][:4])  # activated ct1.
 A refusal raises its typed error: `PREVIEW_CHANGED` (the registry moved since
 the preview), `ACCESS_ASSERTION_FAILED` (a widening breaks one of the tenant's
 policy cases), `CHANGESET_STALE` (a record changed after staging),
-`ACCESS_LIMIT_REACHED`. `changeset_get` and `changeset_discard` read and drop a
-staged change set.
+`ACCESS_LIMIT_REACHED`, and since 0.14.1 `INVALID_ACCESS_RECORD` with
+`reason == "version_downgrade"` for a put that would make a version-2 record a
+version-1 one (`err.dropped` lists the stored record's version-2 fields the put
+leaves out: state them, or stage with `convert=True`). `changeset_get` and
+`changeset_discard` read and drop a staged change set.
+
+A large evaluation can run past the server's own wait (20 s by default): from
+0.14.1 a staging, a preview or an activation then answers 202 with
+`Retry-After`, and each method sends the same call again until the answer
+comes, for at most `wait` seconds in all (`CHANGESET_WAIT_SECONDS`, 120, by
+default; `changeset_apply`'s `wait` bounds its three steps together). Past it
+the method raises `V1EvaluationPendingError`, and the same call sent again
+joins the evaluation. `wait=0` returns the first answer as it came, a 202 as
+an `EvaluationPending` (its body, `status` and `retry_after`).
 
 Under a tenant whose operator mode is `deny`, the operator key's activation of
 a change set that registers a record, names a `service:` principal or widens
@@ -802,20 +835,25 @@ principal; its chain fields say who is acting for whom: `act` (an agent acting
 for the subject; it writes only with a `run`), `app` and `client` (an
 application, and whether a person or an agent drives it), `run` and
 `run_start`, and `taint` tags. `mint_agent_token` and `mint_app_token` mint
-the two common chains. A token with a chain field lives at most a day
-(`CHAIN_TOKEN_MAX_TTL_SECONDS`), and an agent chain token names its `caps`
-with `scopes` that confine each; the SDK refuses before sending what the
-server always refuses (`check_mint`, a `ValueError`). Other tokens live at
-most `lifetime_ceiling(subject)`: a week for a person or an agent, 30 days for
-a service. `with_token` derives a client that uses another token over the
-same connections.
+the two common chains. A token with a chain field lives at most a day by
+default (`CHAIN_TOKEN_MAX_TTL_SECONDS`), and an agent chain token names its
+`caps` with `scopes` that confine each; the SDK refuses before sending what
+the server always refuses (`check_mint`, a `ValueError`). Other tokens live at
+most their kind's ceiling, by default `lifetime_ceiling(subject)`: 90 days for
+a person (a week on a 0.14.0 server), a week for an agent, 30 days for a
+service. Since 0.14.1 each ceiling is a server setting
+(`CORTEX_MINT_MAX_LIFETIME_PERSON`, `_AGENT`, `_SERVICE`, `_CHAIN`):
+`admin_metrics()["auth"]["lifetime_ceilings"]` reports the server's, and a
+mint over one is 422 `INVALID_BODY` `ttl_too_long` with `ceiling_s`.
+`with_token` derives a client that uses another token over the same
+connections.
 
 <!-- example: tokens -->
 ```python
 from cortexdb.v1 import lifetime_ceiling
 
 erin = Cortex(URL, bearer=operator.mint_token(subject="user:erin", scope=ROOT)["token"])
-print(erin.actor, lifetime_ceiling("user:erin"))                 # user:erin 604800
+print(erin.actor, lifetime_ceiling("user:erin"))                 # user:erin 7776000
 
 home = f"{ROOT}/user:alice"
 planner = alice.with_token(alice.mint_agent_token(

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/__init__.py

@@ -84,7 +84,7 @@ from cortexdb import v1  # the explicit submodule namespace
 Cortex = V1Client
 AsyncCortex = AsyncV1Client
 
-__version__ = "0.13.0"
+__version__ = "0.13.1"
 __all__ = [
     # Clients (preferred top-level names)
     "Cortex",

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/__init__.py

@@ -51,6 +51,7 @@ from cortexdb.v1.exceptions import (
     V1ConflictError,
     V1ConnectionError,
     V1Error,
+    V1EvaluationPendingError,
     V1GoneError,
     V1InvalidRequestError,
     V1MisdirectedRequestError,
@@ -94,6 +95,8 @@ from cortexdb.v1._transport import StreamEvent
 from cortexdb.v1.consistency import ConsistencyTokens
 from cortexdb.v1.ops.access import (
     ACCESS_ROLES,
+    CHANGESET_WAIT_SECONDS,
+    EvaluationPending,
     authzen_subject,
     changeset_part,
     delete_record,
@@ -133,6 +136,8 @@ __all__ = [
     "StreamEvent",
     "ConsistencyTokens",
     "ACCESS_ROLES",
+    "CHANGESET_WAIT_SECONDS",
+    "EvaluationPending",
     "authzen_subject",
     "changeset_part",
     "delete_record",
@@ -165,6 +170,7 @@ __all__ = [
     "V1ServerError",
     "V1ServerTimeoutError",
     "V1TimeoutError",
+    "V1EvaluationPendingError",
     "V1RateLimitError",
     "V1NotConfiguredError",
     "V1PolicyDeniedError",

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/_transport.py

@@ -77,12 +77,26 @@ class Poll:
 
     The wait between attempts is the response's ``Retry-After`` (seconds),
     else ``interval``; the last attempt starts before ``timeout`` seconds have
-    passed, and its answer is returned whatever it is.
+    passed. ``pending`` narrows which answers of ``statuses`` are sent again
+    for (default: every one). An answer still pending once ``timeout`` has
+    passed is handed to ``expired`` with the seconds waited, when it is set;
+    otherwise it is returned as any other answer is.
     """
 
     statuses: frozenset
     timeout: float = 60.0
     interval: float = 1.0
+    pending: Optional[Callable[["Response"], bool]] = None
+    expired: Optional[Callable[["Response", float], Any]] = None
+
+    def again(self, response: "Response") -> bool:
+        """Whether ``response`` is one to send the request again for."""
+        return response.status in self.statuses and (self.pending is None or self.pending(response))
+
+    def pause(self, response: "Response") -> float:
+        """Seconds to wait before the next attempt: ``Retry-After``, else ``interval``."""
+        seconds = retry_after_seconds(response)
+        return self.interval if seconds is None else seconds
 
 
 #: How a consistency tracker may extend a request (see

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/auth.py

@@ -1,4 +1,4 @@
-"""Credentials and operator headers (CortexDB 0.14.0).
+"""Credentials and operator headers (CortexDB 0.14.0 and 0.14.1).
 
 * :func:`break_glass_header` builds ``X-Cortex-Break-Glass``
   (``operator_break_glass_v1``): ``reason=<reason>; ticket=<ticket>[;
@@ -11,7 +11,8 @@
   derives ``X-Cortex-Actor`` from a token's ``sub`` when no actor is given.
 * :func:`check_mint` holds a mint request to the rules the server always
   applies to the chain fields (``mint_chain_v1``), and
-  :func:`lifetime_ceiling` gives the lifetime ceiling of a subject's kind.
+  :func:`lifetime_ceiling` gives the server's default lifetime ceiling of a
+  subject's kind (each a server setting since 0.14.1).
 """
 
 from __future__ import annotations
@@ -34,15 +35,22 @@ _TICKET = re.compile(r"^[A-Za-z0-9._:-]{1,64}$")
 _ACTOR = re.compile(r"^(user|agent|service|system):[A-Za-z0-9_.@-]{1,128}$")
 
 #: The longest a token minted with a chain field (``act``, ``app``,
-#: ``client``, ``run``, ``run_start``, ``taint``) lives, in seconds.
+#: ``client``, ``run``, ``run_start``, ``taint``) lives by default, in
+#: seconds: a day. Since 0.14.1 the server's ``CORTEX_MINT_MAX_LIFETIME_CHAIN``
+#: sets it, whatever ``CORTEX_MINT_LIFETIME_ENFORCE`` says.
 CHAIN_TOKEN_MAX_TTL_SECONDS = 86_400
-#: The lifetime ceiling of a minted token by its subject's kind, in seconds:
-#: a week for a person or an agent, 30 days for a service or the system.
-#: The server enforces it unless its ``CORTEX_MINT_LIFETIME_ENFORCE`` is
-#: ``off`` (422 ``INVALID_BODY`` ``ttl_too_long`` at the mint; 401
-#: ``INVALID_TOKEN_CLAIM`` ``lifetime_over_ceiling`` for a token over it).
+#: The default lifetime ceiling of a minted token by its subject's kind, in
+#: seconds: 90 days for a person (``user:``; 7 days on a 0.14.0 server), a
+#: week for an agent, 30 days for a service or the system. Since 0.14.1 each
+#: is a server setting (``CORTEX_MINT_MAX_LIFETIME_PERSON``, ``_AGENT``,
+#: ``_SERVICE``), and ``admin_metrics()["auth"]["lifetime_ceilings"]``
+#: reports the ones a server runs with. The server enforces them unless its
+#: ``CORTEX_MINT_LIFETIME_ENFORCE`` is ``off`` (422 ``INVALID_BODY``
+#: ``ttl_too_long`` at the mint, with ``details.lifetime_s`` and
+#: ``details.ceiling_s``; 401 ``INVALID_TOKEN_CLAIM`` ``lifetime_over_ceiling``
+#: for a token over it).
 LIFETIME_CEILING_SECONDS = {
-    "user": 604_800, "agent": 604_800, "service": 2_592_000, "system": 2_592_000,
+    "user": 7_776_000, "agent": 604_800, "service": 2_592_000, "system": 2_592_000,
 }
 
 
@@ -116,9 +124,13 @@ def is_actor_id(value: Any) -> bool:
 
 
 def lifetime_ceiling(subject: str) -> int:
-    """The lifetime ceiling, in seconds, of a token minted for ``subject``
-    (:data:`LIFETIME_CEILING_SECONDS`), before any chain field lowers it to
-    :data:`CHAIN_TOKEN_MAX_TTL_SECONDS`."""
+    """The server's default lifetime ceiling, in seconds, of a token minted
+    for ``subject`` (:data:`LIFETIME_CEILING_SECONDS`), before any chain
+    field lowers it to the chain ceiling (:data:`CHAIN_TOKEN_MAX_TTL_SECONDS`
+    by default). A server may set each otherwise (0.14.1,
+    ``CORTEX_MINT_MAX_LIFETIME_*``): ``admin_metrics()["auth"]
+    ["lifetime_ceilings"]`` says what it runs with, and its refusal names
+    the ceiling (``details.ceiling_s``)."""
     kind = subject.split(":", 1)[0]
     if kind not in LIFETIME_CEILING_SECONDS:
         raise ValueError(f"not a principal id (user:, agent:, service:, system:): {subject!r}")
@@ -143,19 +155,20 @@ def check_mint(
     ``agent:`` id other than the subject; ``app`` a ``service:`` id;
     ``client`` ``"person"`` or ``"agent"``, and ``"person"`` never beside
     ``act`` or ``run``; ``run`` 1 to 128 bytes and ``run_start`` only with
-    it; each ``taint`` tag 1 to 64 bytes; a token with any chain field lives
-    at most a day; and an agent chain token (``act`` or ``run``, or ``app``
-    without ``client="person"``, or ``client="agent"``) names its ``caps``
-    with ``scopes`` that confine them. What the server checks against its
-    state (an Owner of the application, ``auth.mint.on_behalf_of``, an AI
-    employee named in ``act``) it answers itself."""
+    it; each ``taint`` tag 1 to 64 bytes; and an agent chain token (``act``
+    or ``run``, or ``app`` without ``client="person"``, or
+    ``client="agent"``) names its ``caps`` with ``scopes`` that confine them.
+    What the server checks against its settings or its state it answers
+    itself: the lifetime ceilings, the chain ceiling included (a day by
+    default, ``CORTEX_MINT_MAX_LIFETIME_CHAIN`` since 0.14.1: 422
+    ``INVALID_BODY`` ``ttl_too_long`` with ``details.lifetime_s`` and
+    ``details.ceiling_s``), an Owner of the application,
+    ``auth.mint.on_behalf_of``, an AI employee named in ``act``."""
     if not is_actor_id(subject):
         raise ValueError(f"not a principal id (user:, agent:, service:, system:): {subject!r}")
     chain = any(v is not None for v in (act, app, client, run, run_start, taint))
     if not chain:
         return
-    if max(int(ttl_seconds), 60) > CHAIN_TOKEN_MAX_TTL_SECONDS:
-        raise ValueError("a token that carries a chain field lives at most 86400 s (ttl_too_long)")
     if act is not None:
         if not (is_actor_id(act) and act.startswith("agent:")):
             raise ValueError("act is an agent: id (not_an_agent)")

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/client.py

@@ -41,7 +41,6 @@ from cortexdb.v1._transport import (
     async_stream_op,
     dig,
     page_spec,
-    retry_after_seconds,
     sync_op,
     sync_proc,
     sync_stream_op,
@@ -549,14 +548,18 @@ class _SyncTransport(_ClientCore):
         return self._send_polling(req)
 
     def _send_polling(self, req: Request) -> Any:
-        deadline = time.monotonic() + (req.poll.timeout if req.poll else 0.0)
+        poll = req.poll
+        start = time.monotonic()
+        deadline = start + (poll.timeout if poll else 0.0)
         while True:
             resp = self._send(req)
-            if req.poll and resp.status in req.poll.statuses:
-                wait = retry_after_seconds(resp) or req.poll.interval
+            if poll and poll.again(resp):
+                wait = poll.pause(resp)
                 if time.monotonic() + wait < deadline:
                     time.sleep(wait)
                     continue
+                if poll.expired is not None:
+                    return poll.expired(resp, time.monotonic() - start)
             return _finish(req, resp)
 
     def _send(self, req: Request, *, stream: bool = False) -> Any:
@@ -1031,14 +1034,18 @@ class _AsyncTransport(_ClientCore):
         return await self._send_polling(req)
 
     async def _send_polling(self, req: Request) -> Any:
-        deadline = time.monotonic() + (req.poll.timeout if req.poll else 0.0)
+        poll = req.poll
+        start = time.monotonic()
+        deadline = start + (poll.timeout if poll else 0.0)
         while True:
             resp = await self._send(req)
-            if req.poll and resp.status in req.poll.statuses:
-                wait = retry_after_seconds(resp) or req.poll.interval
+            if poll and poll.again(resp):
+                wait = poll.pause(resp)
                 if time.monotonic() + wait < deadline:
                     await asyncio.sleep(wait)
                     continue
+                if poll.expired is not None:
+                    return poll.expired(resp, time.monotonic() - start)
             return _finish(req, resp)
 
     def _httpx_args(self, req: Request) -> Dict[str, Any]:

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/errors.py

@@ -2010,17 +2010,21 @@ class InvalidAccessRecordError(V1ValidationError):
     change set's record, an application record (``PUT /v1/apps/{id}``), a registry write, or an
     edit of an application's reference root, whose shape is fixed (``reason: reference_root``);
     a ``when: {purpose}`` id outside a read's ``purpose`` grammar on a roster entry, a set entry
-    or a unit grant is ``reason: when_purpose``; ``details.path``, ``details.reason``.
+    or a unit grant is ``reason: when_purpose``; a change set's put that would make a version-2
+    record a version-1 one, without ``convert``, is ``reason: version_downgrade`` with
+    ``details.dropped`` (since 0.14.1); ``details.path``, ``details.reason``.
 
-    Fix the record; ``details.path`` and ``details.reason`` say what.
+    Fix the record; ``details.path`` and ``details.reason`` say what. For ``version_downgrade``,
+    state the fields ``details.dropped`` names, or say ``convert``.
 
-    ``details``: ``path``, ``reason``.
+    ``details``: ``path``, ``reason``, ``dropped``.
     """
 
     CODE = "INVALID_ACCESS_RECORD"
     STATUS = 422
     RETRIABLE = False
     path = _detail("path")
+    dropped = _detail("dropped")
 
 
 class InvalidAuditError(V1ValidationError):
@@ -2043,7 +2047,7 @@ class InvalidBodyError(V1ValidationError):
     ``details.reason`` where known.
 
     ``details``: ``part``, ``reason``, ``field``, ``unsupported_fields``,
-    ``required_capabilities``, ``field_path``, ``entry``.
+    ``required_capabilities``, ``field_path``, ``entry``, ``lifetime_s``, ``ceiling_s``.
     """
 
     CODE = "INVALID_BODY"
@@ -2055,6 +2059,8 @@ class InvalidBodyError(V1ValidationError):
     required_capabilities = _detail("required_capabilities")
     field_path = _detail("field_path")
     entry = _detail("entry")
+    lifetime_s = _detail("lifetime_s")
+    ceiling_s = _detail("ceiling_s")
 
 
 class InvalidBoundaryError(V1ValidationError):
@@ -2400,15 +2406,19 @@ class InvalidScopeGrammarError(V1ValidationError):
 class InvalidScopeTreeError(V1ValidationError):
     """422 ``INVALID_SCOPE_TREE`` (not retriable). Org-tree attributes out of their rules (0.13.0):
     ``details.reason`` names the rule, ``details.field`` the field (``tree.display_name`` is
-    refused under ``CORTEX_DISPLAY_NAME_IN_RECORD_ENFORCE``: put the name in the directory)
+    refused under ``CORTEX_DISPLAY_NAME_IN_RECORD_ENFORCE``: put the name in the directory);
+    since 0.14.1 also a legacy registry write that would make a version-2 record a version-1
+    one, ``reason: version_downgrade``, with ``details.path`` and ``details.dropped``.
 
-    ``details``: ``reason``, ``field``.
+    ``details``: ``reason``, ``field``, ``path``, ``dropped``.
     """
 
     CODE = "INVALID_SCOPE_TREE"
     STATUS = 422
     RETRIABLE = False
     field = _detail("field")
+    path = _detail("path")
+    dropped = _detail("dropped")
 
 
 class InvalidSubtreeError(V1BadRequestError):
@@ -2469,7 +2479,7 @@ class InvalidTokenClaimError(V1AuthError):
 
     Mint a correct token; an AI employee runs as itself, never through ``act``.
 
-    ``details``: ``claim``, ``reason``, ``issuer``.
+    ``details``: ``claim``, ``reason``, ``issuer``, ``lifetime_s``, ``ceiling_s``.
     """
 
     CODE = "INVALID_TOKEN_CLAIM"
@@ -2477,6 +2487,8 @@ class InvalidTokenClaimError(V1AuthError):
     RETRIABLE = False
     claim = _detail("claim")
     issuer = _detail("issuer")
+    lifetime_s = _detail("lifetime_s")
+    ceiling_s = _detail("ceiling_s")
 
 
 class InvalidTokenSignatureError(V1AuthError):
@@ -2866,10 +2878,10 @@ class NoticeUnavailableError(V1UnavailableError):
 
     Retriable: yes, but for ``arming_disabled`` and ``reserved_path_in_use``.
 
-    Retry after the move; nothing was delivered. ``arming_disabled``: not until the operator
-    raises a ceiling set below the default; ``reserved_path_in_use``: not until the operator
-    migrates the scope's events out and deletes the record; ``members_behind``: once every
-    member is armed. ``limit``: retry once the age sweep has dropped older notices.
+    Retry after the move; nothing was delivered. ``arming_disabled`` and
+    ``reserved_path_in_use``: not until the operator raises the ceiling, or migrates the scope's
+    events out and deletes the record; ``members_behind``: once every member is armed.
+    ``limit``: retry once the age sweep has dropped older notices.
 
     ``details``: ``reason``, ``refusal``.
     """
@@ -3566,6 +3578,23 @@ class RepoScopeInUseError(V1ConflictError):
     RETRIABLE = False
 
 
+class RequestAbandonedError(V1UnavailableError):
+    """503 ``REQUEST_ABANDONED`` (retriable). A change set's evaluation stopped: every caller
+    waiting on it went away (since 0.14.1). The change-set routes (``POST /v1/access/changes``,
+    ``…/parts``, ``…/preview``, ``…/activate``) and a SCIM Group write's checks answer it once
+    the request's client has gone, and so has every other caller waiting on that evaluation.
+    Nothing was staged or activated. Only a request whose client has gone meets it, so no client
+    reads it.
+
+    None: only a request whose client has gone is answered with it, so no client reads it;
+    nothing was staged or activated.
+    """
+
+    CODE = "REQUEST_ABANDONED"
+    STATUS = 503
+    RETRIABLE = True
+
+
 class RequestTimeoutError(V1ServerTimeoutError):
     """408 ``REQUEST_TIMEOUT`` (not retriable). Cluster ingress: the body did not arrive within
     ``body_timeout_s``.
@@ -4937,6 +4966,7 @@ BY_CODE: Dict[str, Type[V1APIError]] = {
     "REPO_PURGE_PANICKED": RepoPurgePanickedError,
     "REPO_REGISTRY_WRITE_FAILED": RepoRegistryWriteFailedError,
     "REPO_SCOPE_IN_USE": RepoScopeInUseError,
+    "REQUEST_ABANDONED": RequestAbandonedError,
     "REQUEST_TIMEOUT": RequestTimeoutError,
     "RESOLVE_FAILED": ResolveFailedError,
     "RESOURCE_DELETED": ResourceDeletedError,
@@ -5302,6 +5332,7 @@ __all__ = [
     "RepoPurgePanickedError",
     "RepoRegistryWriteFailedError",
     "RepoScopeInUseError",
+    "RequestAbandonedError",
     "RequestTimeoutError",
     "ResolveFailedError",
     "ResourceDeletedError",

{cortexdbai-0.13.0 → cortexdbai-0.13.1}/cortexdb/v1/exceptions.py

@@ -66,6 +66,33 @@ class V1TimeoutError(V1Error):
     """Request exceeded the configured client timeout."""
 
 
+class V1EvaluationPendingError(V1TimeoutError):
+    """A change-set call's evaluation still ran when its ``wait`` ran out.
+
+    Since 0.14.1 a staging, a preview or an activation whose evaluation runs
+    past the server's wait answers 202 with ``Retry-After``, and the client
+    sends the same call again until it gets its answer, for at most the
+    call's ``wait`` seconds. Nothing failed and the work goes on: send the
+    same call again (it joins the evaluation, or is answered by it for 60 s
+    after it ended), or give it a longer ``wait``. ``method`` and ``path``
+    name the call, ``waited`` the seconds it waited, ``retry_after`` the
+    last answer's ``Retry-After`` and ``body`` its body (a preview's
+    ``{"state": "previewing"}``; a staging's and an activation's are empty).
+    """
+
+    def __init__(self, method: str, path: str, waited: float,
+                 retry_after: Optional[float] = None, body: Any = None) -> None:
+        super().__init__(
+            f"{method} {path}: the change set's evaluation still runs after {waited:.0f} s "
+            "(202); send the same call again, or give it a longer wait"
+        )
+        self.method = method
+        self.path = path
+        self.waited = waited
+        self.retry_after = retry_after
+        self.body = body if body is not None else {}
+
+
 class V1APIError(V1Error):
     """Server returned a non-2xx response with a v1 error envelope.