Designing an AI Evidence Gateway: Durable WAL, Portable MMR Proofs, and Bounded Formal Checks

AI gateways are often discussed as routing layers: authenticate a caller, apply policy, forward a request, and record what happened. For higher-assurance deployments, the harder engineering question is what evidence remains after a request completes—and exactly what that evidence proves.

Aegis Latent Core is an AI Governance and Evidence Gateway for governed LLM traffic. Its current source implements provider-aware request controls, bounded streaming redaction, durable evidence records, portable Merkle Mountain Range (MMR) inclusion proofs, Python and TypeScript integrations, and narrowly scoped formal checks.

This article walks through those mechanisms and, just as importantly, their boundaries.

Version note: GitHub currently exposes a Release labeled v4.0.1, while the source anchors, all ten named Release assets, and the published SDKs identify version 4.0.0. The v4.0.1 ref points directly to a commit, making it a lightweight tag. Treat v4.0.1 as the GitHub Release label—not as evidence that the artifacts were rebuilt as 4.0.1, that the tag is signed, or that the tag-triggered publication workflows produced the public objects.

The request and evidence path

At a high level, Aegis sits between an application and a configured model provider. The non-streaming and streaming paths share admission controls, but they cross the evidence boundary differently.

Client application
    |
    | request
    v
Aegis gateway
    |-- authenticate caller and assign request identity
    |-- enforce body bounds and canonicalize input
    |-- apply WAF, egress, session, and rate-limit controls
    |
    | admitted request
    v
Configured upstream model provider
    |
    | response or terminal error
    v
Aegis gateway
    |
    |-- non-streaming ---------------------------------------|
    |   canonicalize outcome                                |
    |   hash and commit evidence to authoritative JSONL WAL |
    |   flush + fsync                                       |
    |   return governed response                            |
    |                                                       |
    |-- SSE streaming --------------------------------------|
        incrementally sanitize canonical events             |
        emit through a bounded, byte-accounted queue        |
        hash the exact bytes emitted                         |
        commit one terminal summary                          |
        emit the protocol terminal marker only after commit |
                                                            v
                                                proof lookup / audit views

For non-streaming traffic, the response crosses the durable evidence gate before it is returned. For admitted Server-Sent Events (SSE), sanitized non-terminal events can be emitted incrementally. Initial evidence and proof status is therefore pending-terminal; the success terminal marker is withheld until the terminal summary commits.

The replay authority is an append-only JSONL WAL at the configured storage path. It stores chain linkage, request and response hashes, portable proof metadata, signature metadata, and request identity. Calling fsync means the process asked the operating system to synchronize the descriptor; it does not by itself prove power-loss behavior, replicated-volume durability, immutable retention, or external custody. Those remain deployment questions.

Where Rust fits—and where it does not

The repository includes an optional native RustWal. When the extension is available, it receives an auxiliary copy of terminal streaming frames in a bounded memory-mapped, CRC32-framed segment at <wal_path>.stream.rwal.

That distinction matters: the Rust segment is not the replay authority. The authoritative record is the fsynced JSONL WAL. Describing the architecture as a purely Rust-backed ledger, a zero-copy path, or a latency-free evidence layer would overstate the implementation.

Bounded streaming redaction

Streaming privacy controls have a chunk-boundary problem. An identifier can begin in one event and finish in the next. Aegis addresses supported identifier forms with a finite character holdback rather than buffering an entire response.

The stream path also applies per-admitted-stream bounds to queue bytes, queue items, event size, cumulative output, preview retention, de-identification window, and duration. SHA-256 covers the exact emitted bytes, and the implementation commits one terminal outcome. On byte, event, duration, cancellation, incomplete-upstream, or upstream-error paths, it closes the upstream iterator where applicable and omits the success terminal marker.

These are useful, testable controls—not universal de-identification. Aggregate retained memory still scales with admitted concurrency, so deployment-level admission and concurrency controls remain necessary.

Portable MMR inclusion proofs

Aegis uses the aegis-mmr-inclusion-v1 format so a client can verify that a disclosed leaf digest is included relative to a supplied root without possessing the gateway's in-memory MMR state.

The construction is deliberately specific:

1. A raw leaf becomes the lowercase hexadecimal SHA-256 digest of its bytes.
2. An internal node is SHA-256 over the ASCII concatenation of the left and right lowercase hexadecimal digests.
3. Current peaks are ordered by descending mountain height.
4. The displayed root is SHA-256 over the ASCII concatenation of those ordered peak digests.
5. Verification checks the leaf index and count, mountain boundaries, path length, sibling direction, complete peak set, containing peak, and final root.

For a durable non-streaming response, proof data can be returned in X-Aegis-MMR-* headers. An SSE response cannot update its initial headers after streaming begins, so its proof must be retrieved from the authenticated proof link after terminal commit.

The trust anchor is crucial. A verifier must pin or otherwise obtain the root through an independent trust policy. Copying a root from the same untrusted response does not make it independent. A valid proof establishes inclusion relative to that root; it does not establish that the source event is true, that timestamps are externally trusted, that storage is immutable, or that the evidence is legally admissible.

Python quickstart

The published Python distribution is aegis-latent-sdk==4.0.0. The install name uses hyphens; the import namespace is aegis_sdk. Python 3.11 or newer is required.

python -m pip install 'aegis-latent-sdk[openai]==4.0.0'

import os
from aegis_sdk.openai import OpenAI

client = OpenAI(
    aegis_api_key=os.environ["AEGIS_API_KEY"],
    gateway_url=os.environ["AEGIS_GATEWAY_URL"],
    tenant_id=os.environ["AEGIS_TENANT_ID"],
)

response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "hello"}],
)

The package supplies tested OpenAI and Anthropic subclasses within declared dependency ranges. Subclassing does not make every vendor route available through the gateway. Native Anthropic Messages ingress requires the gateway to be configured with AEGIS_PROVIDER=anthropic.

For automatic non-streaming proof verification, callers can set verify_proof=True and provide a pinned trusted_mmr_root. Streaming proofs are retrieved after terminal commit instead of being completed in the initial headers.

TypeScript quickstart

The npm package is aegis-latent-sdk@4.0.0. The current package declares Node.js 18 or newer and provider SDKs as peer dependencies.

npm install aegis-latent-sdk@4.0.0 openai@^6.49.0

import OpenAI from "openai";
import { openAIGatewayOptions } from "aegis-latent-sdk";

const client = new OpenAI(openAIGatewayOptions({
  aegisApiKey: process.env.AEGIS_API_KEY!,
  gatewayUrl: process.env.AEGIS_GATEWAY_URL!,
  tenantId: process.env.AEGIS_TENANT_ID!,
}));

Proof verification is available as a separate operation:

import {
  parseInclusionProof,
  verifyInclusionHash,
} from "aegis-latent-sdk/proof";

const proof = parseInclusionProof(untrustedJson);
const valid = await verifyInclusionHash(
  leafHashHeader,
  proof,
  pinnedRoot,
);

The verifier uses Web Crypto-compatible primitives. The package also offers provider-native integration surfaces, but compatibility remains bounded to the versions, routes, and behaviors covered by its tests.

What the formal gate checks

The repository's formal gate combines two SMT-LIB checks, one Lean 4 theorem, and three finite TLA+/TLC models. Its declared checks include token-bucket arithmetic, per-stream retained-memory arithmetic, a durable-before-emission phase theorem, append-only ledger prefixes, commit-before-emission in a finite request model, and session-to-ledger binding.

This is stronger and more precise than saying “formally verified.” The artifacts verify their stated formulas and bounded abstractions. They do not provide a machine-checked refinement proof connecting every Python or Rust transition—or the operating system and target filesystem—to those models. In particular, the lifecycle abstraction does not model every incremental SSE event as withheld; it models committed outcomes and the terminal transition.

From a source checkout, the formal entry point is:

bash scripts/verify_formal_artifacts.sh

Treat a successful run as evidence about those named artifacts and bounds, not as certification of the whole product.

Run the audit dashboard locally

The repository includes a read-only dashboard for health, retained ledger views, proof lookup, current metrics, and bounded forensic export. The dashboard uses the sibling TypeScript SDK through a local file dependency, so build that source package first even though an SDK is now published on npm.

git clone https://github.com/JuanLunaIA/aegis-latent-core.git
cd aegis-latent-core
git checkout 6469904380218584ae0b5221334bc9a46500f5ba

cd sdk/typescript
npm ci
npm run build

cd ../../dashboard
npm ci
export AEGIS_PRIMARY_BASE_URL='https://aegis.internal'
export AEGIS_DASHBOARD_API_KEY='read-only-audit-token'
npm run build
npm start

For interactive development, run npm run dev instead of the final build/start pair. Use a dedicated least-privilege audit token and place the dashboard behind an authenticated reverse proxy. Although the UI does not mutate ledger records, the Forensics page can request a bounded evidence ZIP and requires audit:export; treat that as a sensitive export operation.

The dashboard does not fabricate missing data. An unavailable endpoint remains unavailable rather than becoming a zero or a demo value. Its MMR page can run the shared verifier in the browser, but a root returned by the same gateway is still not an independent trust anchor.

Evaluate the evidence, not the adjectives

A useful review starts with narrow questions:

• Which WAL is authoritative, and what happens on append or fsync failure?
• Which SSE bytes are hashed, and when does proof status leave pending-terminal?
• Where does the verifier obtain an independently trusted MMR root?
• Which provider routes and dependency ranges are covered by integration tests?
• Which formal property, state-space bound, and implementation gap apply to each claim?
• Which deployment controls provide identity, durable storage, key custody, retention, ingress, and recovery?

Aegis implements technical controls and produces structured cryptographic evidence under declared conditions. It is not, by repository evidence alone, a compliance certification, a legal-admissibility ruling, a production SLO, a WORM guarantee, or proof of external immutability.

Source and packages

• Repository
• GitHub Release labeled v4.0.1
• Python SDK 4.0.0 on PyPI
• TypeScript SDK 4.0.0 on npm

If you review the project, feedback on the authoritative/auxiliary WAL boundary, portable-proof trust anchoring, and streaming terminal semantics would be especially useful.