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

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

Repository: gate-house Status: accepted Date: 2026-10-22 Accepted: 2026-10-22 Revision: 2026-10-22 — a store may serve several engines; an engine enables a capability and is not an access-control mechanism.

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.

A first draft of this ADR also made each engine the only client of its store. That rule is withdrawn. One store can back several capabilities, and each capability can be an engine. Exclusive clientship would turn every engine into a gate on the records.

Decision

An engine is a tool of automation for one capability. It encapsulates the complexity of that capability in a consistent, often simpler interface than doing the work by hand. The same inputs yield the same result. That determinism is what reduces failure modes and what makes the work more reliable and more efficient.

An engine implements its capability from the domain canon. It does not hold the domain's records. Tooling holds the records. Several engines may use one store. Each engine provides a different capability over those records. Being an engine does not make a process the store's only client, and it does not make the engine an access-control mechanism. An engine enables the capability. Restricting who may act remains the domain of access-engine, not a property of engines in general.

The implementation has three manifestations of one library:

1. Library. The capability: validate, explain, plan, and compute the next state. A caller may use these 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 reach the inputs and outputs of its capability. 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 enables credential lifecycle as a reliable operation. Another engine may use OpenBao for a different capability. 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 enables that instance to perform its capability. The operator does not possess it, see it, or reuse it outside the process. Holding it inside the process does not turn the engine into a restriction on the store.
• 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 does not decide it and does not become the access control for its store. A use-privilege is not a grant of the encapsulated credential. It is permission to use the enabling interface.

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. Engines stay deterministic, so the enabled operation stays consistent. Operators stay flexible and are expected to be reliable in the work they choose and assign. That reliability is a Staff expectation. It is not a second restriction inside the engine.

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. The engine is a client of that store for its capability. Other engines may be clients of the same store for other capabilities.
• user-engine, tenant-engine, approval-engine, and the access decision log are enabling processors over records in Tooling. Another engine may use the same records for a different capability. Approval consumption remains the approval capability's own transaction. It is not an exclusive lock on the store.
• audit-core enables append and verification. 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.
• Accepted on 2026-10-22. The engine section is assembled into proposed security-layer-model_v0.9 §3.3 (docs/amendments/adr-015-engine-section.md). Accepted v0.8 still governs.

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.

Exactly one engine is the client of a store

Rejected because one store can back several capabilities. Each capability is an engine. Exclusive clientship would block a second engine from offering a different interface over the same records, and it would make the first engine a gate.

The engine is the access control for its store

Rejected because an engine enables a capability. It encapsulates complexity so the operation is consistent, reliable, and efficient. Restricting who may act is access-engine's domain. An injected credential does not create a second restriction mechanism.

The operator receives the encapsulated credential

Rejected because the operator would then perform the complex operation by hand. The engine exists so that work goes through the reliable interface. The use-privilege names who may invoke that interface. It does not hand over the store credential.

The engine decides who may use it

Rejected because that decision is an access rule. An engine that renders it takes on an access-control role this ADR withholds from engines in general.

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 capability, 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.