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` (T12).

`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`.

T13 adds the CLI, the Containerfile, the image workflow and the rapp package.

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