dbl-gateway 1.0.0

DBL Gateway

dbl-gateway

Records what was allowed before anything runs.

dbl-gateway puts a deterministic decision layer in front of non-deterministic execution. Every request is recorded as:

INTENT → DECISION → PROOF → EXECUTION

DECISION happens first. Execution stays non-normative. The full chain is replayable.

1.0.0 marks the core boundary-to-decision contract as stable.

For the architecture entry point, see deterministic-boundary-layer.

Run it in 1 minute with Docker, or install the package and connect your own provider.

No API keys required:

docker compose --profile demo up demo

Open http://localhost:8010/ui and click Start Demo.

The demo runs scripted scenarios through the full governance pipeline. Use Manual Intent in the observer to submit your own requests — the gateway is a working runtime, not just a demo harness.

How it works

Every request passes through the same deterministic chain:

INTENT  →  DECISION  →  PROOF  →  EXECUTION

INTENT records what was asked. DECISION records what policy allowed — the only normative event. PROOF records what will be sent to the provider. EXECUTION records what happened.

Execution output never feeds back into policy.

Part of the Deterministic Boundary Layer architecture.

Use your own provider

cp .env.example .env        # add one API key (OpenAI, Anthropic, or Ollama)
docker compose up

One active provider is enough. See .env.example for all options.

The default runtime boundary profile is operator:

• /ingress/intent, /capabilities, /snapshot, /tail, /status, /surfaces, and /intent-template stay available
• /ui/* is not exposed

For the boundary contract in detail, see env_contract.md, wire_contract.md, and CAPABILITIES.md.

Install

pip install dbl-gateway

Or from source:

pip install -e .

For a minimal Python helper over the raw HTTP surfaces, use dbl_gateway.client.GatewayClient.

Reference implementation

dbl-gateway implements the Deterministic Boundary Layer (DBL) as a runtime system.

It realizes the event chain INTENT → DECISION → PROOF → EXECUTION, where DECISION events are recorded before any execution and remain the only normative layer. Execution outputs are treated as non-normative observations.

The gateway enforces the core invariants of the model:

• append-only event stream
• strict ordering of DECISION before EXECUTION
• governance input purity (authoritative inputs only)
• deterministic replay under fixed inputs and policy configuration

As such, it serves both as a usable governed gateway and as a reference implementation of the DBL model.

For the stable-core versus evolving-surface split, see CONTRACT_BOUNDARY.md.

For the shortest practical start path, see FIRST_INTEGRATION.md.

For the raw 5-minute send → decision → replay path, see INTEGRATION_SLICE.md.

For token-based identity docking, including a concrete Entra example, see OIDC_INTEGRATION.md.

For empirical validation, including replay equivalence and policy variation benchmarks, see EMPIRICAL_VALIDATION.md.

Observer UI

Open /ui only when the active boundary profile is demo.

The built-in observer includes the event stream, decision replay, chain verification, a policy inspector for DECISION events, manual intent submission, and the integrated demo controller.

Documentation

• QUICKSTART.md — first request, reading events, UI verification
• ARCHITECTURE.md — surfaces, component ownership, invariants
• CONTRACT_BOUNDARY.md — stable core contract vs evolving surface
• FIRST_INTEGRATION.md — start gateway, send one request, read decision, verify replay
• INTEGRATION_SLICE.md — raw send, decision inspection, and replay path
• OIDC_INTEGRATION.md — OIDC token mapping and concrete Entra example
• EMPIRICAL_VALIDATION.md — optional replay bench and policy-diff notes
• wire_contract.md — envelope format, tool gating, budget, refs
• env_contract.md — all environment variables
• observer.md — UI layout and verification routes
• demo.md — demo modes and scenario definition
• Full manifest