codna 0.2.105__tar.gz → 0.2.106__tar.gz

{codna-0.2.105 → codna-0.2.106}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codna
-Version: 0.2.105
+Version: 0.2.106
 Summary: Understand. Fix. Evolve. Codna maps your repository before it spends a token, reviews pull requests, fixes bugs and proves which scanner findings are reachable. Runs on your machine.
 Author: Thyn
 Maintainer: Thyn

{codna-0.2.105 → codna-0.2.106}/codna/__init__.py

@@ -5,4 +5,4 @@ This package is the `codna` CLI. Users never touch "algenta" directly — the en
 is an internal dependency reached over HTTP.
 """
 
-__version__ = "0.2.105"
+__version__ = "0.2.106"

{codna-0.2.105 → codna-0.2.106}/codna/durable/roles.py

@@ -105,6 +105,7 @@ class AuthorizationError(RuntimeError):
 # what lets the router and the role table agree without one implying the other.
 ROUTE_ROLES: Final[Mapping[str, Role]] = {
     # reads
+    "runs.capabilities": VIEWER,
     "runs.list": VIEWER,
     "runs.get": VIEWER,
     "runs.events": VIEWER,

{codna-0.2.105 → codna-0.2.106}/codna/durable/run_api_backend.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import asyncio
 import threading
+from dataclasses import dataclass
 from http import HTTPStatus
 from typing import Any, Final, Mapping
 
@@ -29,10 +30,16 @@ from .config import DurableConfig
 from .run_api_support import RunApiError
 
 __all__ = [
+    "ALL_ROUTE_KEYS",
+    "READ_ROUTE_KEYS",
     "RPC_TIMEOUT_S",
+    "TEMPORAL_ROUTE_KEYS",
     "RunBackend",
+    "RunCapabilities",
     "TemporalRunBackend",
+    "durable_capabilities",
     "is_not_found",
+    "ledger_only_capabilities",
     "translate",
 ]
 
@@ -43,6 +50,132 @@ RPC_TIMEOUT_S: Final = 30.0
 CONNECT_TIMEOUT_S: Final = 30.0
 
 
+# Which routes this surface can serve WITHOUT a durable executor. Deliberately a declaration beside
+# the backend seam rather than something derived from the role table: "a viewer may read" and "a read
+# needs no Temporal" are two different facts that happen to agree today, and a role added later must
+# not silently move a route between the two sets.
+#
+# `runs.capabilities` belongs here rather than in its own third bucket: it describes the server itself,
+# needs no workflow, and is the route a ledger-only server must ANSWER to describe being ledger-only.
+READ_ROUTE_KEYS: Final[frozenset[str]] = frozenset(
+    {"runs.capabilities", "runs.list", "runs.get", "runs.events"}
+)
+# Every route that needs a workflow to act on. `tests/durable/test_run_api_capabilities.py` asserts the
+# two sets PARTITION `roles.ROUTE_ROLES`, so a route added without a decision here is a red test and
+# never a capability document that quietly omits it.
+TEMPORAL_ROUTE_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "runs.start",
+        "runs.steer",
+        "runs.approve",
+        "runs.budget",
+        "runs.pause",
+        "runs.resume",
+        "runs.cancel",
+    }
+)
+
+
+# The union, computed ONCE. `durable_capabilities` is called on every `GET /runs` (the IDE's poll), and a
+# per-request set union is an allocation with no purpose: the set of routes this build can serve is a property of
+# the BUILD, not of the request. Declared beside the two halves so a route added to either is in it automatically.
+ALL_ROUTE_KEYS: Final[frozenset[str]] = READ_ROUTE_KEYS | TEMPORAL_ROUTE_KEYS
+
+
+@dataclass(frozen=True)
+class RunCapabilities:
+    """What this server can ACTUALLY do, as data — not as prose a client has to interpret.
+
+    The problem this type exists for: a Run API started with ``--no-temporal`` is a legitimate mode
+    (it serves the run list, the ledger and the event history), but the only way a caller learned that
+    was by attempting a mutation and reading a 503 whose message said a flag had been passed. An
+    operator who had just been told to "run `codna serve`" read that as a broken install.
+
+    So the server states its capabilities UP FRONT, in the banner it prints and on the list route the
+    IDE already calls. ``available_routes`` / ``unavailable_routes`` name route keys rather than
+    sentences, because the client must branch on them; ``execution`` is the one-word summary of the
+    same fact for a human, and ``reason`` is the coded refusal a mutation would produce.
+
+    ``summary`` is what the MODE means, in the words a person needs: a degraded server is described
+    by what still works first, and by the one requirement it is missing second.
+    """
+
+    #: True only when this server can start, steer and control runs (i.e. it owns a Temporal client).
+    durable_execution: bool
+    #: The Temporal address this server is connected to; ``None`` in a ledger-only deployment.
+    temporal_address: str | None
+    #: Route keys this server serves. A client may call all of them.
+    available_routes: frozenset[str]
+    #: Route keys this server refuses. Calling one is a 503 with ``reason_code``.
+    unavailable_routes: frozenset[str]
+
+    @property
+    def mode(self) -> str:
+        """``durable`` or ``ledger-only``. One word, so a client does not have to infer a mode."""
+        return "durable" if self.durable_execution else "ledger-only"
+
+    @property
+    def reason_code(self) -> str | None:
+        """The code an unavailable route answers with, or ``None`` when everything is available."""
+        return None if self.durable_execution else "run_api_temporal_disabled"
+
+    @property
+    def summary(self) -> str:
+        """One sentence a human can read: what works first, then what is missing and why."""
+        if self.durable_execution:
+            return (
+                f"Durable execution is available via Temporal at {self.temporal_address}: "
+                "runs can be started, steered and controlled."
+            )
+        return (
+            "Ledger-only mode: listing runs and reading run history work; starting and controlling "
+            "runs needs Temporal. Start one with `codna durable dev-server start`, then restart "
+            "`codna serve` without --no-temporal."
+        )
+
+    def as_payload(self) -> dict[str, Any]:
+        """The JSON shape. Sorted lists, because a client diffing two banners must get a stable answer."""
+        return {
+            "mode": self.mode,
+            "durable_execution": self.durable_execution,
+            "temporal_address": self.temporal_address,
+            "available_routes": sorted(self.available_routes),
+            "unavailable_routes": sorted(self.unavailable_routes),
+            "reason_code": self.reason_code,
+            "summary": self.summary,
+        }
+
+
+def durable_capabilities(temporal_address: str) -> RunCapabilities:
+    """The capabilities of a server that owns a Temporal client. Every route is servable.
+
+    A function rather than a class constant because the address is part of the answer: a banner that
+    said "durable execution is available" without naming WHICH server would leave an operator unable
+    to tell a local dev server from a Cloud namespace.
+    """
+    return RunCapabilities(
+        durable_execution=True,
+        temporal_address=temporal_address,
+        available_routes=ALL_ROUTE_KEYS,
+        unavailable_routes=frozenset(),
+    )
+
+
+def ledger_only_capabilities() -> RunCapabilities:
+    """The capabilities of a `--no-temporal` server: the ledger routes, and nothing that starts work.
+
+    THE ONE DEFINITION of this mode. The banner, `GET /capabilities`, the copy on `GET /runs` and the
+    503 a mutation raises all read it, so an operator and a client cannot be told two different things
+    about the same process.
+    """
+    return RunCapabilities(
+        durable_execution=False,
+        temporal_address=None,
+        available_routes=READ_ROUTE_KEYS,
+        unavailable_routes=TEMPORAL_ROUTE_KEYS,
+    )
+
+
 class RunBackend:
     """The operations the Run API needs from a durable executor.
 
@@ -53,6 +186,15 @@ class RunBackend:
     raise the CLI's own coded error, which `translate` maps onto a status.
     """
 
+    def capabilities(self) -> RunCapabilities:
+        """What this backend can do. NO DEFAULT: an implementation has to state it.
+
+        A permissive default here would be the same defect this seam's guard rails exist to prevent
+        — a backend that forgot to answer would be described as fully capable, and the client would
+        only learn otherwise by failing a mutation.
+        """
+        raise NotImplementedError
+
     def start_run(self, *, payload: Mapping[str, Any], run_id: str, run_timeout_s: int) -> dict[str, Any]:
         raise NotImplementedError
 
@@ -187,6 +329,15 @@ def translate(exc: BaseException, *, run_id: str) -> RunApiError:
 class TemporalRunBackend(RunBackend):
     """The real backend, over the CLI's own Temporal calls."""
 
+    def capabilities(self) -> RunCapabilities:
+        """Connected to Temporal: every route is servable.
+
+        This is a statement about the CONNECTION, which is why it is a method and not a class constant:
+        the backend cannot be constructed without a client, so "connected" is true by construction here
+        and the answer is derived from the address it is actually connected to.
+        """
+        return durable_capabilities(self._config.address)
+
     def __init__(self, config: DurableConfig, *, connect_timeout_s: float = CONNECT_TIMEOUT_S) -> None:
         self._config = config
         self._loop = asyncio.new_event_loop()

{codna-0.2.105 → codna-0.2.106}/codna/durable/run_api_http.py

@@ -111,6 +111,7 @@ class Route:
 # THE route table. Every reachable route is one of these; `_resolve` cannot produce anything else, and
 # `_serve` authorizes the key BEFORE it calls the handler. There is no default and no fallback.
 ROUTES: Final[tuple[Route, ...]] = (
+    Route("runs.capabilities", "GET", "_capabilities"),
     Route("runs.start", "POST", "_create_run"),
     Route("runs.list", "GET", "_list_runs", needs_query=True),
     Route("runs.get", "GET", "_get_run", needs_id=True),
@@ -297,10 +298,17 @@ class RunApiHandler(BaseHTTPRequestHandler):
     def _resolve(self, method: str, path: str) -> "_Resolved":
         """Path + method -> `(route, run_id, action, query)`. Unknown shapes are 404, never a fallback."""
         parts = [segment for segment in path.strip("/").split("/") if segment]
+        query = parse_qs(urlsplit(self.path).query, keep_blank_values=True)
+        if parts == ["capabilities"]:
+            # The mode probe, OUTSIDE `/runs` on purpose: it is a fact about the server, not about a
+            # run, and a client asking "what can you do" must not have to guess a run id. It is still
+            # an authenticated, role-checked route like every other one.
+            if method != "GET":
+                self._method_not_allowed("GET")
+            return _Resolved(self._route_by_key("runs.capabilities"), "", "", query)
         if not parts or parts[0] != "runs":
             raise self._not_found(path)
         rest = parts[1:]
-        query = parse_qs(urlsplit(self.path).query, keep_blank_values=True)
         if method == "POST":
             if not rest:
                 return _Resolved(self._route_by_key("runs.start"), "", "", query)
@@ -610,6 +618,19 @@ class RunApiHandler(BaseHTTPRequestHandler):
         self.api.note_run_started(run_id, principal=self._principal)
         self._send_json(HTTPStatus.ACCEPTED, {"run": started})
 
+    # -- GET /capabilities -----------------------------------------------------
+
+    def _capabilities(self) -> None:
+        """What this server can do, before a caller has to discover it by failing.
+
+        The mode is a fact about the SERVER (`--no-temporal` vs a Temporal client), so it belongs
+        next to the address, not inside an error a mutation produces. `GET /runs` also carries it (see
+        `_list_runs`) because that is the route the IDE already calls on every refresh; this route
+        exists for a client that wants the answer WITHOUT listing runs, which is exactly the client
+        composing a new-task sheet.
+        """
+        self._send_json(HTTPStatus.OK, {"capabilities": self.api.backend.capabilities().as_payload()})
+
     # -- GET /runs -------------------------------------------------------------
 
     def _list_runs(self, query: Mapping[str, list[str]]) -> None:
@@ -652,7 +673,16 @@ class RunApiHandler(BaseHTTPRequestHandler):
         selected = entries[:limit]
         self._send_json(
             HTTPStatus.OK,
-            {"runs": selected, "count": len(selected), "total": len(entries), "limit": limit},
+            {
+                "runs": selected,
+                "count": len(selected),
+                "total": len(entries),
+                "limit": limit,
+                # The mode rides on the route the IDE already polls, so a window that can list runs
+                # has the capability facts without a second round trip — and a client that never reads
+                # /capabilities still cannot honestly claim it could not tell.
+                "capabilities": self.api.backend.capabilities().as_payload(),
+            },
         )
 
     # -- GET /runs/:id ---------------------------------------------------------

{codna-0.2.105 → codna-0.2.106}/codna/durable/serve_cli.py

@@ -6,8 +6,8 @@ that already exists. A reviewer asking "what does the IDE talk to" reads this fi
 
 Everything the surface enforces (loopback only, the 0600 bearer token, an identity on every mutation)
 lives in `run_api`; this is the translator that turns flags into `RunApiSettings` and a listen socket,
-plus the `--no-temporal` backend that answers "this server cannot reach Temporal" explicitly rather
-than pretending.
+plus the `--no-temporal` backend that answers "this server cannot start runs" explicitly rather than
+pretending, and states what it CAN do before a caller has to find out by failing.
 
 Not imported at module scope by anything that must work without the durable extra: `run_api` is
 imported inside `cmd_serve`.
@@ -17,7 +17,7 @@ from __future__ import annotations
 import sys
 from typing import Any
 
-from .run_api_backend import RunBackend
+from .run_api_backend import RunBackend, RunCapabilities, ledger_only_capabilities
 
 __all__ = ["add_serve_flags", "cmd_serve"]
 
@@ -62,6 +62,11 @@ def cmd_serve(args: Any) -> int:
     ``/runs/:id/events``): it starts the server with no Temporal client, so a read-only viewer does
     not require the durable extra or a running server. The routes that need Temporal answer 503 with
     a stable code rather than pretending.
+
+    THE BANNER STATES THE MODE, not only the address. `capabilities` names which route keys this
+    server serves and which it refuses, plus one sentence saying what still works; `temporal` stays
+    because a caller keying on its absence should keep working. A mode an operator chose is described
+    as a mode — never as a failure to reach something.
     """
     from . import require_durable
     from .identity import IdentityError, IdentityResolver
@@ -112,6 +117,7 @@ def cmd_serve(args: Any) -> int:
     except RunApiError as exc:
         backend.close()
         raise _error(str(exc), code=exc.code, details=dict(exc.details), hint=exc.hint) from exc
+    capabilities = backend.capabilities()
     _cli_module()._print(
         {
             "run_api": {
@@ -120,7 +126,10 @@ def cmd_serve(args: Any) -> int:
                 "port": server.port,
                 "token_path": str(settings.token_path),
                 "auth_mode": identity.mode,
-                "temporal": None if getattr(args, "no_temporal", False) else config.address,
+                # Kept as the ADDRESS-OR-NULL field existing callers already read. `capabilities`
+                # carries the rest; the two are derived from the same object, so they cannot disagree.
+                "temporal": capabilities.temporal_address,
+                "capabilities": capabilities.as_payload(),
                 "task_queue": config.task_queue,
             }
         }
@@ -208,20 +217,38 @@ class _LedgerOnlyBackend(RunBackend):
     be told the steering did not happen. ``run_api_temporal_disabled`` is that answer, and
     `require_run` still succeeds for a run whose ledger exists — which is exactly the read-only
     viewer's case.
+
+    `capabilities` is the SAME fact stated before the fact, so a caller does not have to provoke a 503
+    to discover the mode. Both come from `ledger_only_capabilities`, so the banner and the refusal
+    cannot describe two different servers.
     """
 
     def __init__(self) -> None:
-        self._reason = "this server was started with --no-temporal"
+        self._capabilities = ledger_only_capabilities()
+
+    def capabilities(self) -> RunCapabilities:
+        return self._capabilities
 
     def _unavailable(self) -> Any:
         from .run_api_support import RunApiError as _Error
 
         return _Error(
-            "this run API cannot reach Temporal: it was started with --no-temporal.",
+            "this run API is in ledger-only mode (it was started with --no-temporal): it can list "
+            "runs and read their history, but it cannot start or control a run.",
             code="run_api_temporal_disabled",
             status=503,
-            details={"no_temporal": True},
-            hint="restart without --no-temporal to start, steer or control a run",
+            details={
+                "no_temporal": True,
+                "mode": self._capabilities.mode,
+                # The routes that DO work, named in the refusal itself: an operator reading a 503 is
+                # owed the same statement the banner gives, not a hint to try something else.
+                "available_routes": sorted(self._capabilities.available_routes),
+            },
+            hint=(
+                "listing runs and reading their history work here; to start, steer or control a run, "
+                "start Temporal (`codna durable dev-server start`) and restart `codna serve` without "
+                "--no-temporal"
+            ),
         )
 
     def start_run(self, *, payload: Any, run_id: str, run_timeout_s: int) -> dict[str, Any]:
@@ -266,7 +293,9 @@ def add_serve_flags(serve: Any) -> None:
                        help="concurrent SSE streams to serve before answering 503 "
                             f"(default: {DEFAULT_MAX_STREAMS})")
     serve.add_argument("--no-temporal", action="store_true",
-                       help="serve the ledger routes only (no Temporal client, no durable extra)")
+                       help="LEDGER-ONLY mode: serve GET /runs and /runs/:id/events (the run list and "
+                            "its history); starting or controlling a run is refused with "
+                            "run_api_temporal_disabled. Needs no Temporal server and no durable extra.")
     # -- the identity layer ------------------------------------------------------------------
     #
     # `token` is the default because it is what every existing caller already has. `oidc` is the

{codna-0.2.105 → codna-0.2.106}/codna.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codna
-Version: 0.2.105
+Version: 0.2.106
 Summary: Understand. Fix. Evolve. Codna maps your repository before it spends a token, reviews pull requests, fixes bugs and proves which scanner findings are reachable. Runs on your machine.
 Author: Thyn
 Maintainer: Thyn

{codna-0.2.105 → codna-0.2.106}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codna"
-version = "0.2.105"
+version = "0.2.106"
 description = "Understand. Fix. Evolve. Codna maps your repository before it spends a token, reviews pull requests, fixes bugs and proves which scanner findings are reachable. Runs on your machine."
 readme = "README.md"
 requires-python = ">=3.12"