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.3.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 of every issuance, use, supersession, and revocation to audit-core as tamper-evident evidence.

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 tamper-evident archive; this engine holds only the operative current state;
• 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. Issuance, use, supersession, revocation all reach audit-core.
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.

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. FLEX-WP-0017 T03 and T05 are unblocked.