audit-core/docs/bounded-executor-receipts.md

Bounded-executor execution-attribution receipts — owner answer

Answers NetKingdom NK-WP-0056-T02 (owner request net-kingdom/docs/proposals/2026-10-31-nk56-t02-owner-requests.md, section "audit-core"; hub message 755cbeed-ecbd-46d9-883e-958fbd88378b). Reviewed 2026-10-31 against net-kingdom/canon/standards/bounded-execution-admission_v0.1.md section 6 and playbook-capability-contract_v0.2.md "Execution Attribution Receipt (proposed)". Work: AUDIT-WP-0018. Canonical receipt validation remains AUDIT-WP-0014-T02.

This is an owner proposal. It activates nothing: registration, ingress and the sender bearer require the owner deliveries and the approved live change listed at the end.

Answer 1 — will audit-core hold the receipts?

Yes. Audit-core accepts the evidence-holder role for the bounded executor's receipts, as it already did for NK-WP-0040 (docs/cross-repo-evidence-admission.md, "Execution-attribution receipts"). What changes is the emitter: no longer a Railiance component but the NetKingdom-written executor, deployed by the new rapp-* package, running as service:nk-bind-executor in namespace sso.

Holding means what it means for every other sender (docs/event-envelope.md): audit-core authenticates the sender, checks source and tenant against the registered identity, stores the event verbatim, and chains it. It records that the executor said the run happened this way. It does not decide whether the decision_refs authorized the run, and it does not authenticate the initiator chain. That check belongs to the independent verifier in BEA section 6 ("Verify"), which reads the receipt from audit-core and compares it with the carrier record.

Until AUDIT-WP-0014-T02 ships canonical schema validation, an accepted receipt is generic JSON custody, not a schema-validated receipt. Audit-core will not describe it otherwise.

Answer 2 — one event, or separate events by run_id?

Both, in a fixed shape: one receipt event per run carries all per-step detail, plus one started event emitted when the executor has consumed the approval and before it takes its first step. Do not split steps into separate events.

Why the steps stay inside the receipt:

• The envelope stores data verbatim as one object (docs/event-envelope.md). Per-step outcomes, check results, revert yes/no and budget used are the sender's claims. They belong in data, where they read as claims. The stored outcome is always recorded and actor is always null (docs/event-envelope.md, "What the receiver derives").
• One receipt is the retained evidence unit. BEA section 6 says the receipt is "kept by hash". If steps were split into separate events, nobody could tell whether a step event was missing without a declared count. The receipt would then become a reconstruction, not a record.
• The validator then sees one document, so decision_refs, budget and step list are checked together.

Why a separate started event is still needed: a receipt is emitted at the end of a run. If the executor crashes mid-run after it has consumed its single approval, it emits nothing. Without a second event, a run that partly executed leaves no record in custody. With a started event, a started that has no matching receipt after the admission window is detectable. Both events share the run_id.

Event mapping (proposal)

Both events use the existing eight-field envelope. No envelope change is needed.

Envelope field	started event	Receipt event
type	execution.run.started	execution.attribution.receipt
id / Idempotency-Key	run:<run_id>:started	run:<run_id>:receipt
source	net-kingdom.bounded-executor (exact; emitter confirms)	same
subject	admission:<spec.id>	same
tenant	the admission's tenant, exact string (owner-bound, never inferred from namespace)	same; must equal data.tenant
correlation_id	<run_id>	<run_id>
occurred_at	consume time, offset-aware	time_interval.end, offset-aware
data	run_id, admission_id, admission_digest, approval_ref, executing_workload, runtime_principal, plan_digest, steps_planned	the canonical receipt (below)

Each id is derived deterministically from run_id. A retry is therefore a 200 duplicate. A second, different body under the same id is a 409 conflict (audit_core/ingestion.py response table), which exposes reuse of a run id.

Proposed receipt data. The schema belongs to NetKingdom (NK-WP-0040-T02); this lists what audit-core needs to see in it:

{
  "receipt_version": "<canonical schema version>",
  "run_id": "…",
  "initiator": {"iss": "…", "sub": "admin"},
  "executing_workload": "service:nk-bind-executor",
  "runtime_principal": "system:serviceaccount:sso:<sa>",
  "tenant": "…",
  "environment": "…",
  "source_commit": "<plan.source.commit>",
  "artifact_digest": "<plan_digest>",
  "target": "<admission-level target>",
  "action": "bounded-execution",
  "decision_refs": [
    {"kind": "admission", "id": "<spec.id>"},
    {"kind": "admission_digest", "id": "sha256:…"},
    {"kind": "approval", "id": "<carrier approval reference>"}
  ],
  "time_interval": {"start": "…+00:00", "end": "…+00:00", "clock_source": "…"},
  "steps": [
    {"index": 1, "operation": "…", "target": "…", "action": "…",
     "outcome": "succeeded|failed|skipped",
     "checks": [{"id": "…", "result": "pass|fail|unknown"}]}
  ],
  "reverted": false,
  "budget": {"limit": {"…": 0}, "used": {"…": 0}},
  "outcome": "succeeded|failed|reverted"
}

The points that fit the existing model and need NetKingdom to decide:

1. target/action are singular in the canonical field list but per-step in BEA section 6. Proposal: the receipt-level target is the admission's target and the receipt-level action is bounded-execution. Each step's target and action go in steps[]. Audit-core needs one answer in the schema. It will not pick one.
2. decision_refs must be typed. The admission id, the admission digest and the approval reference are three different things. An untyped list cannot be checked against the carrier.
3. delegation stays absent when there is none. time_interval.bound stays absent when no bound is established. Unknown attribution stays the explicit unknown. This is unchanged from docs/cross-repo-evidence-admission.md.
4. Check results carry an id and a result only. They carry no response bodies, tokens, password values or LLDAP/OpenBao payloads.

Registration (proposal)

Registry field	Proposed value	Reason
name	nk-bounded-executor	one identity per executor deployment
sources	["net-kingdom.bounded-executor"]	exact, no wildcard
tenants	the exact admission tenant(s)	not *; the executor acts for named tenants only
may_write / may_read	true / false	the verifier reads with its own read identity
secret_policy	reject	a receipt is kept by hash. If audit-core redacted it silently, the stored body would no longer match the hash the executor computed, so a secret-shaped field must refuse the event (400 secret_shaped_field). The executor treats that as a defect
evidence_kind	load-bearing, if the started + receipt pair is adopted. Otherwise attributive with an explicit completeness_trade	the pair is what makes a missing receipt detectable

Ingress: a new NetworkPolicy in deploy/networkpolicies.yaml admitting namespace sso and the executor's exact pod labels, following audit-core-tenant-engine-ingress. Do not admit the whole sso namespace, because Authelia, LLDAP and KeyCape run there too. The bearer is ESO-projected by railiance-platform, like the other in-cluster senders. No token value appears in this repository.

What audit-core needs back

• NetKingdom (NK-WP-0040-T02 / NK-WP-0056):
  • the versioned receipt schema, validator, path and digest, with positive and negative fixtures, covering steps, reverted, budget and the typed decision_refs;
  • an answer to point 1;
  • the exact source and event types;
  • the tenant binding;
  • a decision on the started event and the emission guarantee.
• The rapp-* package owner: the exact pod labels and ServiceAccount, and the image revision that emits.
• railiance-platform: the ESO projection of the sender bearer (catalog/route via warden route), and the attended seed of the registry entry.
• Founder: the live registry entry and NetworkPolicy rollout are an approved live change. Audit-core prepares them; the founder runs them.

Status 2026-10-31 — T02 prepared after NetKingdom's answers

NetKingdom answered on hub messages ed03ba30 and deea5bf8. The answers are based on executor.py at net-kingdom a020758 and rapp-bounded-executor 9826a24.

• Source net-kingdom.bounded-executor. Event types execution.run.started and execution.attribution.receipt. Tenant platform, which is the exact string. Note that it is not tenant:platform, which approval-engine and informed-decision use. The started event is adopted, so the stream is load-bearing.
• Registry entry (prepared, not seeded): nk-bounded-executor in deploy/senders-scope.json and deploy/senders-scope.yaml. The entry admits nothing until the Secret carries a token for that name. The overlay may now tighten secret_policy from redact to reject, but it may never relax it (audit_core/senders.py). Even if the Secret entry is minted with the default, the result is therefore reject.
• Ingress (prepared, not applied): audit-core-nk-bounded-executor-ingress in deploy/networkpolicies.yaml admits only namespace sso combined (AND) with pod label app.kubernetes.io/name=bounded-executor, on TCP 8080.
• Tests: tests/test_bounded_executor_sender.py runs on the executor's envelope shape. It checks: 202 accept; 200 duplicate on retry; 409 on a reused run id with a different body; 400 source_not_allowed and tenant_not_allowed; 400 secret_shaped_field for a secret-shaped step check.
• Defect found in the emitter: bounded-executor/clients.py AuditCore.emit accepts only 200 and 201. Audit-core answers a first accept with 202, so the executor would treat a stored started event as a failure and stop with audit_unavailable. NetKingdom has to accept 202 (accepted) and 200 (duplicate). It should treat 409 as a run-id-reuse defect and must not retry it.
• T03 window bound: a started event that has no receipt with the same correlation_id becomes a finding after the admission's window.not_after. Pilot windows are 2 h.

Remaining work:

• Founder-run: mint and seed the Secret entry, then roll out the ConfigMap and the NetworkPolicy.
• NetKingdom: the versioned receipt schema with fixtures (NK-WP-0040-T02) and the 202 fix.
• railiance-platform: custody of the sender bearer (ESO projection to sso).