approval-engine/INTENT.md

INTENT

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.5.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 implementation.

Purpose

approval-engine owns the approval as a durable, authenticated, consumable object — issued before an action, verified at the moment of use, and provably not replayable.

It answers one question, totally and decidably:

Is this approval valid right now — for this exact action, target, actor, and purpose — and has it already been used?

Nothing else. It does not decide whether the action is permitted; that is access-engine's and it stays the only decision point. An approval is one input to that decision.

Why This Exists

The gap was raised by flex-auth on 2026-08-28 (FLEX-DEC-2026-001) while assenting to the security layer model. Splitting policy authoring from policy evaluation left one half of the approval contract without an owner:

• the design of the approval contract is gate-house's (Staff — doctrine);
• the validation of an approval at decision time is access-engine's;
• the durable object, authenticated entries, and atomic supersession were nobody's.

It is not gate-house's: Staff holds no state another layer depends on at runtime (standard §3.4). It is not access-engine's: it does not own the organizational approval lifecycle, and an evaluator that also owns the object it evaluates is self-dealing. It is not audit-core's: an approval needs mutable, in-path, current-state semantics, and an append-only audit fabric is built for the opposite property.

So it is a concept, and concepts get engines.

The Concept

An approval is an independent authorization artifact required for actions that exceed normal policy. It binds, at issue time, to:

• the action and the target it authorizes;
• the actor who may use it, and the principal on whose behalf;
• the purpose or task it was granted for;
• a validity window;
• the approvers — identified, authenticated, and countable, so that distinct-approver requirements are enforceable rather than aspirational.

And it carries state that is deliberately not a maturity ladder:

requested → approved → valid → consumed
                         ↓
                    superseded / revoked / expired

Rigidity Is the Point

This engine is deliberately small, boring, and strict. Its state model is a closed machine rather than a graded progression, because at the moment of use the answer must be binary, total, and reconstructable.

Atomic supersession and single consumption are the security properties that make Canon test T-06 — Approval Replay passable. An approval that is partly valid, or whose validity must be inferred by replaying a log, is an approval that can be replayed. Flexibility here is a defect.

Progression modelling — graded, evidence-based, open-ended — belongs to maturity-engine. The two engines are deliberate opposites and neither should drift toward the other.

What approval-engine Owns

• the durable approval object and its identifiers;
• authenticated approval entries, and distinct-approver counting;
• the state machine above, with atomic supersession and consumption;
• validity windows and expiry;
• 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 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.

The queue is local. The outbox lives in this engine's own transactional store. No synchronous dependency on audit-core sits inside the state-change transaction. With a local outbox, fail-closed triggers only when this engine's own store is unavailable — where the change could not have been recorded anyway — and an audit-core outage does not block a revocation. Emitting synchronously to audit-core inside the transaction would also be atomic, and would turn an audit outage into an inability to revoke: the operation least tolerable to block during an incident. Standard §9.4, raised by audit-core.

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.

The Claim Shape

access-engine consumes approvals as input claims. The claim MUST carry the approval identifier and a digest over the same canonical binding the decision point already computes, so that approved and approved for this exact request are distinguishable at decision time. Without it, wrong-action, wrong-target, and wrong-scope proofs have nothing to compare against.

Consumption Ordering — Unresolved

The decision precedes the action, and the action precedes consumption. Three states follow that neither engine closes alone:

• an allow rendered against an approval that is then never consumed;
• an approval consumed twice by racing callers;
• an approval consumed after the action it authorized has already failed.

approval-engine performs the mutation, because access-engine never mutates. But who signals consumption, at what point relative to the decision, and what happens on each of the three states above is a contract between the two engines and is not yet settled. It is recorded in the standard's §16 and is required before FLEX-WP-0017 T05. Raised by flex-auth.

Nothing here may be implemented by guessing that contract.

What approval-engine Does Not Own

• the decision — access-engine, always and only (standard §6);
• approval policy — which actions require approval, how many approvers, and which separations of duty apply: that is doctrine, and doctrine is 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 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.

The repository's seed README described this as "an engine for modelling and managing decisions". That wording is withdrawn: decision is access-engine's word under standard §8, and this engine must never claim it.

Design Principles

1. Binary at the point of use. Valid or not, consumed or not. No grades.
2. Atomic or it does not count. Supersession and consumption are compare-and-swap operations, never read-then-write.
3. The evaluator is not the owner. access-engine reads; it does not mutate.
4. Approvals are inputs, never authority. Holding one is not permission; 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, 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

• Not a policy decision point, and never one.
• Not a workflow or ticketing system; it stores the artifact, not the meeting.
• Not an approvals inbox or notification surface.
• Not an audit archive.
• Not a general state-machine service for other concepts.

What Would Make This Repository Wrong

• It starts deciding. Any endpoint that answers "may this actor do X" rather than "is this approval valid" is the failure standard §6 names.
• Supersession is not atomic. If two supersessions can interleave, the replay protection is theatre.
• It grows a policy layer. If it starts holding rules about who may approve 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

1. access-engine renders approval-bound decisions using this engine's claims, with the approval identifier reconstructable from the decision record;
2. Canon test T-06 — Approval Replay passes against a live implementation;
3. an approval can be revoked without the holder's cooperation, and the revocation is effective at the next use;
4. distinct-approver requirements are enforced by the engine rather than by convention;
5. no state change can be committed without its event — demonstrated by a test that fails the transaction when emission fails, not by inspection, and with the queue local so an audit-core outage never blocks a revocation;
6. the claim carries a binding digest, and a decision rendered against approval A for request R cannot be replayed for request R';
7. FLEX-WP-0017 T03 and T05 are unblocked.