net-kingdom/docs/bounded-execution-contract-table.md

Bounded execution: cross-repo contract table

NK-WP-0058-T01 (part 1), as of 2026-11-05. Parts 2 (T09: approval, case and custody chain) and 3 (T10: operations and the founder) add rows to this file. NK-WP-0057-T01 takes the rows marked owner decision as inputs and does not inventory them again.

Each row is one interface on the bounded-execution path. Every claim cites the file that defines it, at these revisions: net-kingdom 23a99c1, rapp-bounded-executor 3ecd462, approval-engine f41a9ca, informed-decision 77161fe, audit-core 3157454, key-cape 82b471f, railiance-platform 31cf74d.

Marks.

• keep: one owner, one source, so it only needs a contract test (T02).
• merge: the contract is written down in more than one place. Keep the named source and derive or check the copies.
• delete: the piece is redundant.
• owner decision: the owner or the boundary is unclear. It goes to NK-WP-0057 or to the named owner.

Tested today. The levels are:

• CI: runs in a Forgejo workflow on every change;
• local: a test that needs a sibling checkout and skips without one;
• manual: an exercise script someone has to run;
• live: proven only by a founder-run step;
• none.

Two facts frame this column:

• net-kingdom CI (.forgejo/workflows/identity-journeys.yaml) tests a source tarball of net-kingdom alone, so every sibling-dependent test skips there.
• rapp-bounded-executor has no CI workflow.

Part 1: the executor and its services

ID	Interface	Owner and source of truth	Consumer	Tested today	2026-11-04/05 failure	Mark
E1	OpenBao: Kubernetes login and KV, three lanes	railiance-platform: CCR-2026-0058, -0059, -0061 and openbao/policies/	executor (operations.py OpenBao); executor-lanes.py creates and deletes the write role	CI: fake OpenBao. Local: tests/test_executor_lanes.py against the CCRs	Write role left open overnight; window-close failed as bare LaneError	merge
E2	KeyCape client_credentials token	key-cape: src/internal/server/oidc/token.go. Client registration: net-kingdom sso-mfa/k8s/keycape/ with keycape-client.py	executor (clients.py KeyCapeClientCredentials)	CI: fakes. Manual: exercise_approval_identity.py (T19) against KeyCape source/image	none (the request phase worked)	keep; registration ownership is an owner decision
E3	approval-engine: create, get and consume	approval-engine: approval_engine/api.py, store.py	executor (clients.py ApprovalEngine, executor.py _check_approval)	CI: fakes. Manual: T19 against approval-engine source	platform-root approval refused as approval_entry; finding which field failed took diagnostic pod 4	keep
E4	informed-decision: memo intake (present_existing)	informed-decision: informed_decision/intake_service.py, deploy/lifecycle/intake-submitters.json	executor (clients.py InformedDecision, cli.py admission_memo)	Local: test_approval_request.py, path hard-coded to /home/worsch/informed-decision	Memo reached platform-root only, so one window was wasted (routing, E5)	keep
E5	The approver's identity across repos	None. It is defined four times (below)	executor _check_approval, informed-decision routing, the founder	none	One wasted window: the admission named admin, routing went to platform-root	merge; owner decision (NK-WP-0057)
E6	audit-core: event ingest	audit-core: docs/event-envelope.md, audit_core/ingestion.py, sender registry. Receipt schema: net-kingdom canon/schemas/execution-attribution-receipt_v0.1.schema.json	executor (clients.py AuditCore)	CI: fakes. Manual: exercise_audit_sender.py (T15) against audit-core source. Receipt validator not in a workflow	none (receipt accepted 2026-11-05)	keep
E7	LLDAP: sign-in and self password change	LLDAP upstream. The runtime in sso has no owner in docs/responsibility-map.md; its reference manifests are in net-kingdom sso-mfa/k8s/	executor (operations.py Directory, the image's lldap_set_password)	CI: fakes. Nothing pins the image's tool version against the server	none	keep; runtime ownership is an owner decision
E8	Kubernetes API: ESO force-sync and Deployment restart	API: railiance-cluster. Role content: net-kingdom sso-mfa/k8s/bounded-executor/rbac.yaml, copied to rapp manifests/rbac.yaml	executor (operations.py KubeDelivery, KubeRestart)	Make only: test_rbac.py needs no sibling, but no workflow runs it. Local: rapp test_ceiling_is_the_net_kingdom_source	none in the run (ESO server-side apply was a founder step, T10)	merge
E9	Network path of the executor pod	rapp manifests/networkpolicy.yaml (egress). Ingress belongs to each target: net-kingdom netpol-sso.yaml (lldap, keycape), approval-engine e9e9f93, audit-core 7728fde, informed-decision :8081, OpenBao	executor wait_all_reachable, make netcheck	Local: rapp test_every_in_namespace_egress_is_admitted_by_net_kingdom. Live: make netcheck	Two windows refused setup:URLError; four diagnostic pods; live approval-engine had a policy its file lacked	keep; add a cross-owner ingress test
R1	Image build and pin chain	net-kingdom builds (.forgejo/workflows/bounded-executor-image.yaml); rapp pins (Makefile IMAGE_DIGEST); the admission pins source files (plan.source.commit and file sha256)	renderer (tools/render_job.py), the executor's checks	none: commit to digest is recorded only in the rapp commit message	A re-pin and a new admission after c2a0f2f, all by hand	merge
R2	Runtime config, Job template and exit codes	net-kingdom bounded-executor/cli.py (config keys in its docstring, EXIT). Copies: rapp examples/config.pilot.json, docs/runtime-contract.md, render_job.py allow-lists	rapp renderer, pilot-run.sh, the founder	Local: rapp test_packaging.py reads cli.py (skips without sibling); no rapp CI	pilot-run.sh edits trust_satisfied into a temporary copy of the config	merge

Row details

E1: OpenBao lanes

• Contract:
  • address http://openbao.openbao.svc:8200;
  • login POST /v1/auth/kubernetes/login with the projected token, audience openbao, from /var/run/secrets/openbao/token;
  • one role per lane, with leases of at most 15 minutes, each revoked at exit:
    • write: net-kingdom-bind-executor-svc-authelia-write, KV platform/workloads/net-kingdom/directory-binds/svc-authelia, field LDAP_BIND_PASSWORD, cas_required;
    • journey: net-kingdom-bind-executor-syn-journey-read, KV .../synthetic-journey/syn-journey, fields PASSWORD, TOTP_SEED;
    • approval client: keycape-nk-bind-executor-approval-bounded-executor-workload-kv-read, field CLIENT_SECRET, read once and revoked at once.
• Window: the write role exists only between executor-lanes.py window-open and window-close.
• Duplicates: role names, KV paths and fields appear in four places: the CCR files, executor-lanes.py LANES, rapp config.pilot.json and the rapp renderer's role allow-list. LANES also carries the write and journey policy text inline.
• Proposal:
  • LANES reads names, paths and fields from the CCRs. The policy text is compared against railiance-platform's policy file, not kept as a second copy.
  • The renderer's allow-list is checked against the same source.
  • executor-lanes.py names the lane error's cause. On 2026-11-05 phase: identity, LaneError hid "no platform-admin login" (T03).

E2: KeyCape client

• Contract:
  • POST http://keycape.sso.svc.cluster.local:8080/token with Host kc.coulomb.social, client_secret_basic, client nk-bind-executor-approval;
  • one scope per token (approval:create, approval:read, approval:consume);
  • the answer must be a bearer token with expires_in of at most 900;
  • a scope outside the list must be answered invalid_profile_usage.
• Owners: KeyCape owns the token behaviour. The client's registration lives in net-kingdom sso-mfa/k8s/keycape/ (deployment env and keycape-client.py), and its case is security-cases/nk-bind-executor-approval.yaml (oidc-service-client).
• Open:
  • excess-scope-refused is not yet proven against live KeyCape.
  • Owner decision: ADR-0015 moves runtime packages to rapp-*, but there is no KeyCape rapp, so the client registration sits in net-kingdom's reference manifests. Who owns registering a KeyCape client?

E3: approval-engine

• Contract:
  • create: POST /v1/approvals answers 201. binding.actor must equal the token's sub (api.py); the executor sends human_control: true, pdp_path: false and required_count = the number of approvers.
  • read: GET /v1/approvals/{id}.
  • consume: POST /v1/approvals/{id}/consume with request_digest and decision_id.
  • the executor accepts an entry only if:
    • subject_id is a listed approver;
    • principal_type is human;
    • the assurance is aal2;
    • the subject is not the executor itself.
  • approval-engine also has required_assurance. The executor doesn't send it, and checks aal2 itself ("recorded, not enforced").
• Proposal:
  • approval_entry names the failed field: subject, principal type or assurance. That alone would have replaced diagnostic pod 4.
  • Whether to send required_assurance is a question for approval-engine, not a local change.

E4: informed-decision intake

• Contract:
  • POST /v1/memos on informed-decision-workload.informed-decision.svc:8081;
  • the bearer is the projected ServiceAccount token, audience informed-decision-intake, checked by TokenReview;
  • the registry row is system:serviceaccount:sso:nk-bind-executor → submitter nk-bind-executor, memo class bounded-execution, review group net-kingdom-admins, present_existing.approval_actor service:nk-bind-executor, daily limit 10;
  • the receipt must echo memo_id, approval_id and approval_binding_digest;
  • cli.py --request exits 7 when the memo is not accepted. Resubmitting is idempotent.
• Test gap: bounded-executor/tests/test_approval_request.py:216 hard-codes /home/worsch/informed-decision (T07: no hard-coded paths).

E5: approver identity, defined four times

Where	Value on 2026-11-05	Owner
net-kingdom admissions/BEA-2026-0003.yaml spec.approval.approvers	[admin] (a name)	net-kingdom (prepare_admission.py)
rapp examples/config.pilot.json approver_subjects, approver_issuer	admin → uid=admin,ou=people,dc=netkingdom,dc=local, https://kc.coulomb.social	rapp-bounded-executor
informed-decision deploy/lifecycle/review-groups.json	net-kingdom-admins → uid=admin,… (interim, decision c9bedd9c; it was platform-root until 77161fe)	informed-decision
key-cape LLDAP adapter	sub = the LDAP DN	key-cape

Nothing checks that these four agree, and a mismatch shows only as a refused approval after a window has opened. Until NK-WP-0057 decides who routes: the T03 readiness check compares them. The admission's approver names resolve through the rapp config and must equal the routing recipient for the memo's review group.

E6: audit-core

• Contract:
  • POST /v1/events with Idempotency-Key equal to the event's id, and all eight envelope fields;
  • answers: 202 accepted, 200 duplicate, 400 dead-lettered with a named reason, and 409 for a reused run id with a different body (a defect, never retried);
  • the bearer is the file /var/run/secrets/bounded-executor/audit-core, from sso/bounded-executor-tokens key audit-core (custody in part 2);
  • the source is checked against the sender registry;
  • receipt schema v0.1 and its EAR rules (tools/execution-attribution-receipt).
• Proposal: fold the T15 exercise into the T02 suite, and run make execution-attribution-receipt-test in CI.

E7: LLDAP

• Contract:
  • http://lldap.sso.svc.cluster.local:17170;
  • sign-in checks over its HTTP API;
  • the password change runs the image's /app/lldap_set_password with --base-url, --token, --username (OPAQUE).
• Gap: nothing checks that the tool in the executor image is compatible with the running LLDAP server.
• Owner decision: docs/responsibility-map.md names no owner for the LLDAP, Authelia or KeyCape runtimes in sso. SCOPE says the sso-mfa/k8s/ material is "migration inputs, not blanket authority".

E8: Kubernetes API

• Contract:
  • force-sync: merge-patch metadata.annotations.force-sync on /apis/external-secrets.io/v1/namespaces/sso/externalsecrets/authelia-secrets, then poll its status;
  • restart: merge-patch spec.template.metadata.annotations["kubectl.kubernetes.io/restartedAt"] on Deployment authelia, then wait for the rollout;
  • Role: get/watch/patch on that Deployment and get/patch on that ExternalSecret. No Secret access.
• Duplicate: the Role is written in net-kingdom and copied by hand into rapp (make ceiling-sync: "copy, never edit"). The compare test skips without the sibling checkout, and rapp has no CI.
• Proposal: keep net-kingdom as the source, and make the compare test a T02 contract test that runs in CI.

E9: network path

• Contract:
  • the executor pod is labelled app.kubernetes.io/name=bounded-executor in namespace sso;
  • egress per the rapp policy;
  • each target admits it on its own port: approval-engine and audit-core on 8080, informed-decision on 8081, KeyCape and LLDAP through netpol-sso.yaml, and OpenBao on 8200;
  • the executor waits up to 30 s for all five endpoints. A setup failure names the unreachable one (since c2a0f2f).
• Gap: the ingress side lives in five repos, and only the sso part is compared. The live approval-engine policy differed from its file.
• Proposal: a T02 test that renders every owner's ingress policy for this label, plus a live comparison in the T03 readiness check.

R1: image and pins

• Chain:
  1. a net-kingdom commit;
  2. the Forgejo image workflow builds a digest;
  3. the digest is pinned by hand in rapp's Makefile IMAGE_DIGEST, with the source commit only in the rapp commit message;
  4. separately, prepare_admission.py --commit pins the admission to source file sha256s (plan.source.files).
• Gap: no record links the digest to the commit to the admission pins, so "the admission's pins match the pinned image" cannot be checked.
• Proposal:
  • the image workflow writes a value-free pin record (commit, file sha256s, digest);
  • rapp pins that record;
  • the renderer refuses when the admission's file hashes are not the image's (T03).

R2: config, Job and exit codes

• Source: the config keys and exit codes are defined in cli.py: 0 completed, 3 reverted, 4 refused, 5 unknown, 6 not in custody, and 7 for a request whose memo was not accepted.
• Copies:
  • rapp docs/runtime-contract.md (prose);
  • config.pilot.json (values);
  • render_job.py allow-lists (token paths, role names);
  • pilot-run.sh sets trust_satisfied by editing a temporary copy of the config.
• Proposal:
  • a versioned config schema file in net-kingdom, which the renderer validates against;
  • the exit codes stated once, in that file;
  • trust_satisfied becomes a run input recorded in the state file (T04), not a config edit.

Summary for part 1

• keep: E2, E3, E4, E6, E7, E9. Each needs its T02 contract test. The T15 and T19 exercises become CI tests.
• merge:
  • E1: lane names and policy text, from the CCRs;
  • E5: the approver, compared until it has one source;
  • E8: the RBAC copy;
  • R1: the pin record;
  • R2: the config schema.
• delete: nothing yet. The candidates are the hand copies named under merge, once they are derived or checked.
• owner decision (to NK-WP-0057-T01 or the named owner):
  • E5: who owns the approver and routing;
  • E2: KeyCape client registration with no KeyCape rapp;
  • E7: the LLDAP, Authelia and KeyCape runtime owner in sso;
  • E3: whether approval-engine should enforce required_assurance.
• Transparency findings for T03:
  • executor-lanes.py lane errors without a cause;
  • approval_entry without the failed field.
• Hard-coded path for T07: test_approval_request.py:216.