net-kingdom/bounded-executor/README.md

Bounded executor (NK-WP-0056)

Runs one founder-approved Bounded Execution Admission (canon/standards/bounded-execution-admission_v0.1.md) exactly once. Founder decision 6d1adce9: net-kingdom writes the executor; rapp-bounded-executor deploys it as one Job per admission in sso.

executor.py is the core runner (T11):

• preflight, no effect:
  • the admission is valid (BEA-1..14);
  • the executed files match their pins;
  • the trust states hold;
  • every operation and check is known;
  • the window is open and longer than the wall-time budget;
  • the approval-engine approval binds this admission's digest, names this executor as actor and was approved only by listed HUMAN approvers at aal2. The name-to-subject map is configured; no guessing.
• consume once: request_digest = admission digest, decision_id = run id. An unclear outcome is resolved by reading the approval back, never by a second consume.
• custody: emit execution.run.started to audit-core. If the event can't be stored, the run stops.
• steps: in plan order, one consumer at a time. Checks run after every mutating step, after their settle time. The kill switch and the budget are checked between steps.
• failure:
  • A failed check, an exhausted budget or the kill switch reverts in reverse order.
  • Each revert must pass its own checks.
  • A clean revert may retry within attempts.
  • An outcome that can't be determined stops without guessing.
  • A failed revert stops and alerts.
• receipt: one execution.attribution.receipt per run, with PDP not-evaluated in the pilot. It never holds a value that an operation handled.

Operations, checks, the approval carrier, the trust oracle, the audit sink, alerts and clocks are injected.

operations.py (T12) holds the pilot's real operations:

• OpenBao KV v2 with CAS;
• LLDAP self-rotation;
• ExternalSecret force-sync and its status;
• rollout restart, where a rollout that never becomes ready is a definite failure and is reverted;
• the synthetic journey check.

An operation signals a known-bad outcome with definite_failure, and the runner reverts. Any other error stops without guessing.

synthetic_pilot.py runs a rotation and a deliberate revert on the T08 stack plus OpenBao: uv run bounded-executor/synthetic_pilot.py.

cli.py --journey-only (T10) is a read-only run with no admission. It uses the journey-read role only (CCR-2026-0059), runs the synthetic journey once and prints its value-free receipt. Exit codes: 0 pass, 1 fail closed, 4 refused. synthetic_journey_only.py proves it on the T08 stack: it passes when healthy and fails closed on a broken bind.

exercise_approval_identity.py (T19) runs the executor's real request phase, approval client, preflight and consume against KeyCape's pinned image and approval-engine's source. It uses synthetic keys and writes a value-free receipt: python3 bounded-executor/exercise_approval_identity.py --receipt FILE (defaults ~/key-cape, ~/approval-engine). It found that approval-engine stores an entry's assurance as the token's JSON object, not a bare aal2. The executor now parses that object (entry_is_aal2).

cli.py (T13) is the Job's entry point: one admission, one approval id, a non-secret config. Exit codes: 0 completed, 3 reverted, 4 refused before any effect, 5 stopped, unknown or failed revert, 6 consumed but not in custody. Containerfile builds the image, which .forgejo/workflows/bounded-executor-image.yaml publishes by digest.

Deployment is in rapp-bounded-executor, which pins the digest and renders one ConfigMap and Job per admission (make run, founder-run). That package also holds the ServiceAccount and Role, copied from sso-mfa/k8s/bounded-executor/rbac.yaml, and the executor's egress-only NetworkPolicy. The receiving side in sso is allow-bounded-executor-to-* in sso-mfa/k8s/network-policies/netpol-sso.yaml.

python3 -m pytest bounded-executor/tests     # or: make bounded-executor-test