gate-house/docs/adr/ADR-015-engine-is-a-processor.md

ADR-015 — Engine as processor and operator use-privilege

Repository: gate-house Status: proposed Date: 2026-10-22

Context

The security-layer standard defines an Engine as a deterministic API for a modeled concept. It types that layer into PDP, PIP, Evidence, and Lifecycle. It does not say whether an engine is a library, a command, or a service, or where the records of the concept live.

Repository intents filled that gap in incompatible ways. Some engines describe themselves as the store of their facts. secrets-engine describes itself as a processor over OpenBao: the vault holds the credential records, and the engine turns an already-rendered access decision into a scoped change and a one-shot delivery. The same estate also needs a rule for who may start that process. The process holds credentials the calling operator must not hold. Without a separate use-privilege, "the operator uses the engine" collapses into "the operator receives the engine's credentials," or into the engine deciding for itself who may call it.

Decision

An engine is a deterministic processor for one domain. It implements that domain from its canon. It does not hold the domain's records. Tooling holds the records. The engine owns the record type: the schema, the invariants, and the legal transitions. It is the only admitted client of its store.

The implementation has three manifestations of one library:

1. Library. The domain operations: validate, explain, plan, and compute the next state. A caller may use these pure operations without receiving a store credential.
2. CLI. The library in a process. At start, the process is injected with the credential for one scoped environment. That credential lets the process read its inputs and write its outputs. It is not returned to the caller.
3. Service. The same process, kept running for a scoped environment that needs a standing processor. A service is not a second implementation and does not receive the credentials of any other environment.

secrets-engine is the reference shape. OpenBao is the store. The engine is the lifecycle processor. Build, test, and production are different scoped environments and different processes.

Authentication and the operator

An operator is a Staff actor, human or agent, who starts or calls an engine. Authentication, by key-cape, establishes who the operator is. It does not grant use of an engine.

Two privileges stay distinct.

• The encapsulated privilege is the credential injected into one engine instance at start. It is how that process reads its inputs and writes its outputs. The operator does not possess it, see it, or reuse it outside the process.
• The use-privilege is permission to start and call one named engine instance, or a named set of instances. access-engine renders that permission. The engine enforces the rendered result and does not decide it. A use-privilege is not a grant of the encapsulated credential, and it is not permission for every operation the domain can perform. The engine still applies its own deterministic rules to each call, including any decision record that domain requires.

Starting an instance and calling it both require a use-privilege for that instance. The operator who starts it is the operator under whose use the process is injected. One process is injected for one scoped environment.

Delegation between operators

An operator who is allowed to delegate tasks may assign a task to another operator who holds a use-privilege the delegator does not hold. The delegate uses the engine. The delegator does not gain the use-privilege and does not gain the encapsulated credential.

Delegation assigns work. It does not transfer either privilege. The delegate must already hold the use-privilege. The assignment cannot widen what the delegate is allowed to do, and it cannot authorize an operation the engine's own rules refuse. Engines stay deterministic and stringent. Operators stay flexible. Reliability of an operator is a Staff expectation. It does not relax an engine check.

Consequences

• An engine intent that says the running service is the store of record is aligned later: the database, the vault, or the log is Tooling, and the engine remains the only admitted client and the owner of the record type.
• user-engine, tenant-engine, approval-engine, and the access decision log are processors over records in Tooling. Approval consumption remains one transaction that the engine opens against its store. A user or tenant fact remains readable only through the engine.
• audit-core appends and verifies. The tamper-evident store is Tooling.
• A Deployment exists when a scoped environment keeps the process running. A one-task environment manifests the same binary as a CLI. Absence of a Deployment does not make the engine incomplete.
• This ADR selects no database, framework, or hosting technology, and it creates no Gate House runtime surface.
• Acceptance of this ADR is a later edit of its status. The security-layer standard's engine section is amended only after that acceptance.

Alternatives rejected

The engine holds the records

Rejected because the layer cut already gives persistence to Tooling. Putting the store inside the engine makes the process the system of record and invites every other engine intent to do the same.

The operator receives the encapsulated credential

Rejected because the operator could then bypass the processor and call Tooling directly. That is the failure the use-privilege exists to prevent.

The engine decides who may use it

Rejected because that decision is an access rule. An engine that renders it becomes a second policy decision point.

Delegation transfers the delegate's privileges to the delegator

Rejected because assigning a task would then widen the delegator. The delegate already holds the use-privilege. The delegator remains without it.

Library only, or service only

Rejected because the domain implementation, the process boundary, and the standing manifestation are one implementation. Collapsing them either gives callers the store credential inside a library, or forces a Deployment for a one-task environment.