diff --git a/INTENT.md b/INTENT.md index 4b95e60..bfb8cf2 100644 --- a/INTENT.md +++ b/INTENT.md @@ -2,7 +2,7 @@ > **Layer: Engine.** NetKingdom Security Layer Model §4 catalog — a deterministic > API for a modeled concept, where the same authoritative input state yields the -> same result. Standard: `net-kingdom/canon/standards/security-layer-model_v0.3.md`. +> same result. Standard: `net-kingdom/canon/standards/security-layer-model_v0.4.md`. > > This file captures why this repository exists and the kind of system it is > meant to become. It is aspirational and stable, not a description of current @@ -87,8 +87,35 @@ drift toward the other. - binding to action, target, actor, principal, and purpose; - revocation that does not require the holder's cooperation; - an introspection API that `access-engine` consumes as an **input claim**; -- emission of every issuance, use, supersession, and revocation to `audit-core` - as tamper-evident evidence. +- **emission atomicity** — every issuance, use, supersession, and revocation is + emitted to `audit-core` in the **same transaction** as the state change + (transactional outbox or equivalent). See below; this is a contract, not an + implementation detail. + +## Emission Atomicity + +An approval MUST NOT be issued, consumed, superseded, or revoked without the +corresponding event being durably queued in the same transaction that changed +the state. Transactional outbox, or an equivalent that cannot separate the two. + +This is a condition of `audit-core`'s assent (`AUDIT-IN-0001`) and is in the +standard at §9.4. The reasoning is worth carrying here rather than by reference, +because it constrains the implementation from the first commit: + +An append-only archive with a verified hash chain proves that records were not +**altered or truncated after arrival**. It cannot prove that a record was never +sent (standard §9.6). A suppressed event leaves the chain perfectly intact and +verification reports intact. `audit-core` reports what it received and will not +imply it is everything that happened — correctly, because it cannot. + +For an approval object this is not a corner case. **The single most valuable +event for an adversary to suppress is a revocation**, and its absence is exactly +what chain verification cannot see. Completeness is therefore this engine's +obligation and nothing downstream can retrofit it. + +Consequence for design: emit-after-commit is a defect, not an optimization. A +best-effort publish, a fire-and-forget queue, or any path where the state change +can succeed while the event is lost is out of contract. ## What approval-engine Does Not Own @@ -98,8 +125,11 @@ drift toward the other. `gate-house`'s (standard §6.2, reaching decisions as input claims or versioned policy rules); - **identity and authentication of approvers** — `key-cape`, consumed as claims; -- **the evidence record** — `audit-core` holds the tamper-evident archive; this - engine holds only the operative current state; +- **the evidence record** — `audit-core` holds the archive; this engine holds + only the operative current state. Note the guarantee is bounded: `audit-core` + is not WORM or object-locked, and its tamper evidence is conditional on live + preconditions. Whether approvals warrant stronger custody is an open gap in + the standard's §13, and this engine must not assume it has been closed; - **credentials** materialized after a decision — `secrets-engine`; - **maturity, readiness, or progression of anything** — `maturity-engine`. @@ -117,8 +147,10 @@ word under standard §8, and this engine must never claim it. is one claim the decision point weighs. 5. **Revocation beats cooperation.** An approval can be killed without the holder's participation. -6. **Every transition is evidence.** Issuance, use, supersession, revocation all - reach `audit-core`. +6. **Every transition is evidence, atomically.** Issuance, use, supersession, + and revocation reach `audit-core` in the same transaction that made them + true. An event that can be lost is a state change that never happened, as far + as anyone auditing can tell. 7. **Small on purpose.** Scope growth here is a security regression. ## Non-Goals @@ -139,6 +171,9 @@ word under standard §8, and this engine must never claim it. what, it has taken doctrine from `gate-house`. - **Nobody consumes it.** If `access-engine` does not read approvals as input claims, the object is decorative. +- **Emission is best-effort.** If a revocation can succeed while its event is + lost, the evidence half is silently incomplete and the most security-relevant + transition is the one most likely to vanish. ## Success Criteria @@ -149,4 +184,6 @@ word under standard §8, and this engine must never claim it. revocation is effective at the next use; 4. distinct-approver requirements are enforced by the engine rather than by convention; -5. `FLEX-WP-0017` T03 and T05 are unblocked. +5. no state change can be committed without its event — demonstrated by a test + that fails the transaction when emission fails, not by inspection; +6. `FLEX-WP-0017` T03 and T05 are unblocked.