release: bump version to 0.11.0 and update dependencies; fix approval handler and health summary reporting

Author: tercel

CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to apcore-cli (Python SDK) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-09-02
+
+Bumps the required `apcore` floor to `0.28.0` and `apcore-toolkit` to `0.10.2`, and fixes **three defects the 0.28.0 upgrade made reachable or visible**. Full suite: 815 passed, 5 xfailed (798 → 815; 17 new regression tests). Each new test was confirmed to fail against the pre-fix behaviour rather than merely to pass against the new one.
+
+**Why a minor rather than a patch.** Every fix below restores behaviour that was already specified, but two of them change what a working consumer observes, and this ecosystem's rule — stated in apcore's own 0.28.0 release note — is that such a change "must ship as a **minor** (or major) version bump, never a patch". A script branching on exit code `1` from an `apcli` system command now sees `45`; a caller doing `handler.request_approval(...)["status"]` now gets a `TypeError`. Neither was correct behaviour, and both were reachable.
+
+### Fixed
+
+- **The `apcli health` summary line reported "no data" for a project whose modules it had just listed.** apcore classifies module health in **four** tiers — `healthy` / `degraded` / `error` / `unknown` — and the tally iterated only the first three. `unknown` means "no calls recorded yet", which is the state every module in a fresh project is in, so the common case rendered a populated table above a total that denied it:
+
+  ```
+    probe.echo                   unknown      0.0%         --
+  Summary: no data
+  ```
+
+  **Pre-existing, and not introduced by this upgrade** — all three SDKs have emitted `unknown` since the tier set existed. apcore 0.28.0 is what brought it into focus: `sys-health-summary.schema.json` had declared the enum as `["healthy", "degraded", "unhealthy"]`, a value **no SDK emits**, and the release corrects it to the four tiers actually produced, splitting the summary's `unhealthy` count field into `error` and `unknown`. With the canonical shape finally naming four tiers, rendering three is a plain omission. Fixed in all three SDKs together, with the tally now covering `unknown`; a genuinely empty tally still reads "no data".
+
+- **The approval gate crashed on every gate-routed approval — `CliApprovalHandler` returned a mapping where the protocol requires an `ApprovalResult`.** apcore's `BuiltinApprovalGate` reads the handler's answer by attribute (`result.status`, `result.approved_by` in `builtin_steps.py`), so the handler's `{"status": "approved", ...}` dict raised `AttributeError` *inside* the gate and reached the caller as `MODULE_EXECUTE_ERROR`. Every one of the eight return paths was affected, so a module annotated `requires_approval: true` could not execute through the wired handler at all — including the `--yes` and `APCORE_CLI_AUTO_APPROVE=1` bypasses, which return early and therefore failed the same way.
+
+  It survived because nothing exercised it: no test in this SDK called `request_approval`, and the class was only reachable through `executor.set_approval_handler` in `factory.py`. apcore-cli-rust converts through `cli_to_apcore_result` and apcore-cli-typescript's `ApprovalResult` is a structurally-typed interface, so neither had the defect — this was a Python-only divergence from a shape both other SDKs got right.
+
+  **Pre-existing, but apcore 0.28.0 widens the blast radius.** Before 0.28.0 the gate fired only for a module whose *annotation* said `requires_approval: true`. Since spec v1.28.0 §6.9 the gate fires on the union of three sources, so an ACL rule carrying `approval: required` (§6.1.6) now routes calls to modules annotated `requires_approval: false` through the same broken path — the exact shape argument-scoped approval was added for (`git push --force` needs a human, `git push` does not).
+
+  `_approval_result()` now constructs `apcore.approval.ApprovalResult`, falling back to the mapping shape when apcore is not importable so the handler stays usable in isolation.
+
+- **Every apcore error from an `apcli` system command exited 1 instead of its canonical code.** `exit_code_for_error` matched only on the CLI's own exception classes, none of which an apcore-raised `ModuleError` subclass is an instance of, so the wire code it carries was never read. `system_cmd._exit_on_system_error` documents the canonical taxonomy (44 module-not-found, 45 schema-validation, 46 approval-denied, 47 config-invalid, 77 ACL-denied) and delivered `1` for all of them. TS `exitCodeForError` falls through to a `codeMap` and Rust `map_module_error_to_exit_code` reads `err.code`; Python had the map — in `cli.py` — and never consulted it from this path.
+
+  **apcore 0.28.0 makes it newly reachable on a routine command.** `system.usage.summary` / `system.usage.module` now declare `"pattern": "^[1-9][0-9]*[hd]$"` on `period`, and 0.28.0 also stops `_DictSchemaAdapter.model_validate` being a pass-through, so dict-declared schemas are finally enforced. `apcore-cli apcli usage --period 0h` passes the flag through verbatim and now raises `SCHEMA_VALIDATION_ERROR` where it previously returned an empty window with exit 0 — and was reported as exit 1 rather than 45.
+
+  `APCORE_ERROR_CODE_MAP` moves to `exit_codes.py` as the single source of truth (`cli._ERROR_CODE_MAP` is now an alias, so the two copies cannot drift), gains the `DEPENDENCY_NOT_FOUND` / `DEPENDENCY_VERSION_MISMATCH` entries TS already had, and `exit_code_for_error` falls back to it.
+
+### Changed
+
+- **`apcore>=0.28.0`, `apcore-toolkit>=0.10.2`.** apcore-toolkit 0.10.2 is a dependency-tracking release with no source change; its stable surface consumed by the CLI (`format_*`, `DisplayResolver`, `BindingLoader`, `RegistryWriter`) is unchanged.
+
+- **Exit-code map parity pinned across the three SDKs.** A mechanical three-way diff of the maps found `DEPENDENCY_NOT_FOUND` and `DEPENDENCY_VERSION_MISMATCH` mapped to 44 here and in the other non-Rust SDK, but falling through to 1 in apcore-cli-rust (fixed in its 0.11.0). Both codes now carry an explicit assertion here too, so the three maps cannot drift again without a test going red.
+
+### Notes
+
+- **What the 0.27.0 → 0.28.0 delta does *not* touch.** The CLI never constructs or loads an `ACL`, never calls `check()` / `check_access()` (so §6.8.1's fail-closed legacy boolean does not reach it), never reads an `AuditEntry`, and never builds an `ACLRule` (so §6.1.5's `effect` value closure and the new `approval` field are inert here). `ExecutionPolicy.resolve()`'s new keyword-only call-site parameters are additive and the CLI configures no policy. `p99_latency_ms` changing value is display-only in `_format_usage_summary_tty`.
+- **`Executor.validate()` now reports the governance-effective requirement (§7.9.5), which is an improvement the CLI gets for free.** `apcli validate` and the `--dry-run` path forward `result.requires_approval` verbatim, so a call gated only by an ACL argument-scoped rule is now correctly reported as needing approval. Pinned by `test_preflight_reports_the_acl_sourced_requirement`.
+- **The CLI's own pre-execution `check_approval(module_def, ...)` still reads the static annotation**, which since spec v1.29.0 no longer means "no consent needed". That is correct here rather than a defect: the pre-check is an ergonomic early prompt, and a call it skips still meets the executor's gate, which now composes all three sources and routes to the same `CliApprovalHandler`. Verified end-to-end by `TestApprovalGateEndToEnd`.
+
 ## [0.10.5] - 2026-08-17
 
 Patch release. Bumps the required `apcore` floor to `0.27.0` to track the aligned apcore 0.27.0 release (2026-08-14). **No source changes** — the full test suite passes unchanged (798 passed, 5 xfailed) against apcore 0.27.0.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.10.5"
+version = "0.11.0"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -26,8 +26,8 @@ classifiers = [
     "Environment :: Console",
 ]
 dependencies = [
-    "apcore>=0.27.0",
-    "apcore-toolkit>=0.10.0",
+    "apcore>=0.28.0",
+    "apcore-toolkit>=0.10.2",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",

src/apcore_cli/approval.py

@@ -71,6 +71,30 @@ def _read_timeout_from_env() -> int | None:
     return parsed
 
 
+def _approval_result(status: str, approved_by: str | None = None, reason: str | None = None) -> Any:
+    """Build the apcore-protocol ``ApprovalResult`` the executor's gate expects.
+
+    The approval gate reads the handler's return value by attribute
+    (``result.status`` in apcore ``builtin_steps``), so a plain mapping raises
+    ``AttributeError`` inside the gate and surfaces to the caller as
+    ``MODULE_EXECUTE_ERROR``. Mirrors the Rust adapter's ``cli_to_apcore_result``
+    and TypeScript's structurally-typed ``ApprovalResult`` object.
+
+    Falls back to the mapping shape when apcore is not importable so the handler
+    stays usable in isolation (unit tests that stub the runtime out).
+    """
+    payload: dict[str, Any] = {"status": status}
+    if approved_by is not None:
+        payload["approved_by"] = approved_by
+    if reason is not None:
+        payload["reason"] = reason
+    try:
+        from apcore.approval import ApprovalResult
+    except ImportError:
+        return payload
+    return ApprovalResult(**payload)
+
+
 # ---------------------------------------------------------------------------
 # CliApprovalHandler — implements apcore ApprovalHandler protocol (FE-11 §3.5)
 # ---------------------------------------------------------------------------
@@ -109,25 +133,25 @@ async def request_approval(self, request: Any) -> Any:
         # (`if !get_requires_approval(module_def) { return Approved::not_required }`).
         requires_attr = getattr(request, "requires_approval", None)
         if requires_attr is False:
-            return {"status": "approved", "approved_by": "not_required"}
+            return _approval_result("approved", approved_by="not_required")
         module_def = getattr(request, "module_def", None)
         if module_def is not None:
             annotations = getattr(module_def, "annotations", None)
             if annotations is not None:
                 requires = _get_annotation(annotations, "requires_approval", None)
                 if requires is False:
-                    return {"status": "approved", "approved_by": "not_required"}
+                    return _approval_result("approved", approved_by="not_required")
 
         # Bypass: auto_approve flag
         if self.auto_approve:
             logger.info("Approval bypassed via --yes flag for module '%s'.", module_id)
-            return {"status": "approved", "approved_by": "auto_approve"}
+            return _approval_result("approved", approved_by="auto_approve")
 
         # Bypass: APCORE_CLI_AUTO_APPROVE env var
         env_val = os.environ.get("APCORE_CLI_AUTO_APPROVE", "")
         if env_val == "1":
             logger.info("Approval bypassed via APCORE_CLI_AUTO_APPROVE for '%s'.", module_id)
-            return {"status": "approved", "approved_by": "env_auto_approve"}
+            return _approval_result("approved", approved_by="env_auto_approve")
         if env_val != "" and env_val != "1":
             # D10-009 cross-SDK parity: emit to stderr (matching TS) so log
             # capture / handler config does not mask the warning. Spec at
@@ -140,10 +164,7 @@ async def request_approval(self, request: Any) -> Any:
 
         # Non-TTY: reject
         if not sys.stdin.isatty():
-            return {
-                "status": "rejected",
-                "reason": "Non-interactive session without --yes",
-            }
+            return _approval_result("rejected", reason="Non-interactive session without --yes")
 
         # TTY prompt
         annotations = getattr(request, "annotations", None) or {}
@@ -154,21 +175,18 @@ async def request_approval(self, request: Any) -> Any:
         try:
             approved = _tty_prompt(module_id, self.timeout)
         except ApprovalTimeoutError:
-            return {"status": "timeout", "reason": f"Timed out after {self.timeout}s"}
+            return _approval_result("timeout", reason=f"Timed out after {self.timeout}s")
 
         if approved:
-            return {"status": "approved", "approved_by": "tty_user"}
-        return {"status": "rejected", "reason": "User rejected"}
+            return _approval_result("approved", approved_by="tty_user")
+        return _approval_result("rejected", reason="User rejected")
 
     async def check_approval(self, approval_id: str) -> Any:
         """Check status of a previously pending approval (Phase B).
 
         CLI does not support async approval polling; always returns rejected.
         """
-        return {
-            "status": "rejected",
-            "reason": "CLI does not support async approval polling",
-        }
+        return _approval_result("rejected", reason="CLI does not support async approval polling")
 
 
 # ---------------------------------------------------------------------------

src/apcore_cli/cli.py

@@ -16,7 +16,11 @@
 from apcore_cli.approval import check_approval
 from apcore_cli.builtin_group import RESERVED_GROUP_NAMES as RESERVED_GROUP_NAMES  # noqa: PLC0414
 from apcore_cli.display_helpers import get_display as _get_display
-from apcore_cli.exit_codes import EXIT_SCHEMA_CIRCULAR_REF, EXIT_SCHEMA_VALIDATION_ERROR
+from apcore_cli.exit_codes import (
+    APCORE_ERROR_CODE_MAP,
+    EXIT_SCHEMA_CIRCULAR_REF,
+    EXIT_SCHEMA_VALIDATION_ERROR,
+)
 from apcore_cli.output import format_exec_result
 from apcore_cli.ref_resolver import (
     CircularRefError,
@@ -428,30 +432,10 @@ def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> Non
         )
 
 
-# Error code mapping from apcore error codes to CLI exit codes
-_ERROR_CODE_MAP = {
-    "MODULE_NOT_FOUND": 44,
-    "MODULE_LOAD_ERROR": 44,
-    "MODULE_DISABLED": 44,
-    "SCHEMA_VALIDATION_ERROR": 45,
-    "SCHEMA_CIRCULAR_REF": 48,
-    "APPROVAL_DENIED": 46,
-    "APPROVAL_TIMEOUT": 46,
-    "APPROVAL_PENDING": 46,
-    "CONFIG_NOT_FOUND": 47,
-    "CONFIG_INVALID": 47,
-    "MODULE_EXECUTE_ERROR": 1,
-    "MODULE_TIMEOUT": 1,
-    "ACL_DENIED": 77,
-    # Config Bus errors (apcore >= 0.15.0)
-    "CONFIG_NAMESPACE_RESERVED": 78,
-    "CONFIG_NAMESPACE_DUPLICATE": 78,
-    "CONFIG_ENV_PREFIX_CONFLICT": 78,
-    "CONFIG_ENV_MAP_CONFLICT": 78,
-    "CONFIG_MOUNT_ERROR": 66,
-    "CONFIG_BIND_ERROR": 65,
-    "ERROR_FORMATTER_DUPLICATE": 70,
-}
+# Error code mapping from apcore error codes to CLI exit codes. Single source
+# of truth lives in exit_codes so the dispatch paths that map by wire code and
+# exit_code_for_error cannot drift apart.
+_ERROR_CODE_MAP = APCORE_ERROR_CODE_MAP
 
 
 # D9-005: format_preflight_result and _first_failed_exit_code moved to

src/apcore_cli/exit_codes.py

@@ -61,14 +61,61 @@
 }
 
 
+# ---------------------------------------------------------------------------
+# Map: apcore wire error code -> exit code
+# ---------------------------------------------------------------------------
+# The CLI's own exception classes (above) never match an error raised by the
+# apcore runtime, which signals failure through ``ModuleError`` subclasses
+# carrying a ``code`` attribute. Matching on that code is what keeps the
+# canonical taxonomy (44 / 45 / 46 / 47 / 77) intact for every dispatch path —
+# ``apcli`` system commands included, which route apcore errors straight to
+# :func:`exit_code_for_error`. Mirrors the ``codeMap`` in TS ``exitCodeForError``
+# and Rust ``cli::map_apcore_error_to_exit_code``.
+APCORE_ERROR_CODE_MAP: dict[str, int] = {
+    "MODULE_NOT_FOUND": EXIT_MODULE_NOT_FOUND,
+    "MODULE_LOAD_ERROR": EXIT_MODULE_LOAD_ERROR,
+    "MODULE_DISABLED": EXIT_MODULE_DISABLED,
+    "DEPENDENCY_NOT_FOUND": EXIT_DEPENDENCY_NOT_FOUND,
+    "DEPENDENCY_VERSION_MISMATCH": EXIT_DEPENDENCY_VERSION_MISMATCH,
+    "SCHEMA_VALIDATION_ERROR": EXIT_SCHEMA_VALIDATION_ERROR,
+    "SCHEMA_CIRCULAR_REF": EXIT_SCHEMA_CIRCULAR_REF,
+    "APPROVAL_DENIED": EXIT_APPROVAL_DENIED,
+    "APPROVAL_TIMEOUT": EXIT_APPROVAL_TIMEOUT,
+    "APPROVAL_PENDING": EXIT_APPROVAL_DENIED,
+    "CONFIG_NOT_FOUND": EXIT_CONFIG_NOT_FOUND,
+    "CONFIG_INVALID": EXIT_CONFIG_INVALID,
+    "MODULE_EXECUTE_ERROR": EXIT_MODULE_EXECUTE_ERROR,
+    "MODULE_TIMEOUT": EXIT_MODULE_TIMEOUT,
+    "ACL_DENIED": EXIT_ACL_DENIED,
+    # Config Bus errors (apcore >= 0.15.0)
+    "CONFIG_NAMESPACE_RESERVED": EXIT_CONFIG_NAMESPACE_RESERVED,
+    "CONFIG_NAMESPACE_DUPLICATE": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_ENV_PREFIX_CONFLICT": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_ENV_MAP_CONFLICT": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_MOUNT_ERROR": EXIT_CONFIG_MOUNT_ERROR,
+    "CONFIG_BIND_ERROR": EXIT_CONFIG_BIND_ERROR,
+    "ERROR_FORMATTER_DUPLICATE": EXIT_ERROR_FORMATTER_DUPLICATE,
+}
+
+
 def exit_code_for_error(err: BaseException) -> int:
     """Return the configured exit code for an error instance.
 
-    Falls back to ``1`` (generic execute error) when no entry in
-    :data:`EXIT_CODES` matches. Mirrors TS ``exitCodeForError`` and the
-    Rust ``ExitCode::from`` mapping.
+    Resolves in two steps, matching TS ``exitCodeForError`` and the Rust
+    ``ExitCode::from`` mapping: first the CLI's own exception classes
+    (:data:`EXIT_CODES`), then the apcore wire code the error carries
+    (:data:`APCORE_ERROR_CODE_MAP`). Falls back to ``1`` (generic execute
+    error) when neither matches.
     """
     for cls, code in EXIT_CODES.items():
         if isinstance(err, cls):
             return code
+
+    # Fall back to the apcore wire code. None of the classes above match an
+    # error raised by the apcore runtime, so without this every apcore failure
+    # would collapse to 1 — losing the taxonomy that scripted callers read.
+    wire_code = getattr(err, "code", None)
+    wire_code = getattr(wire_code, "value", wire_code)
+    if isinstance(wire_code, str) and wire_code in APCORE_ERROR_CODE_MAP:
+        return APCORE_ERROR_CODE_MAP[wire_code]
     return 1

src/apcore_cli/system_cmd.py

@@ -101,8 +101,15 @@ def _format_health_summary_tty(result: dict[str, Any]) -> None:
         rate = f"{m.get('error_rate', 0) * 100:.1f}%"
         click.echo(f"  {m['module_id']:<28} {m['status']:<12} {rate:<12} {top_str}")
 
+    # The health tiers are healthy / degraded / error / unknown — four, not
+    # three. `unknown` means "no calls recorded yet", which is the state every
+    # module in a fresh project is in, so omitting it made the summary line
+    # contradict the table right above it: the rows listed modules while the
+    # total read "no data". apcore >= 0.28.0 declares the four-tier set
+    # canonically in sys-health-summary.schema.json (§6.6); the SDKs have
+    # emitted `unknown` all along.
     parts = []
-    for key in ("healthy", "degraded", "error"):
+    for key in ("healthy", "degraded", "error", "unknown"):
         count = summary.get(key, 0)
         if count:
             parts.append(f"{count} {key}")