KeizAI The technical
The rule is enforced in architecture, not in copy.
"AI proposes, a person decides" is easy to write on a page. The KeizAI specification makes it a structural property: the verbs of authority do not exist where the machine operates, the record of every decision is written where it cannot be edited, and every boundary fails closed.
Four falsifiable claims about where truth lives.
PostgreSQL is the sole authoritative store: all durable business state commits transactionally to it, in a single write region. Everything else in the system — caches, distributed objects, edge state, local client stores — is derived, and the specification states each derivation as a claim you could disprove by deleting things.
A cache that is required is not a cache; it is a second database with weaker durability. That distinction shapes the whole design: a revoked permission must take effect on the next request, so no cached grant may ever answer for the authority of the store.
- Redis
-
Delete every key — lose nothing
Redis is optional and ephemeral, and is not even deployed until a measurement demands it. The specification's test: delete every key in the deployment and the system loses no accepted business state and no authority decision — a latency spike and a rate-limit reset, nothing more.
- Edge state
-
Erase every object — lose nothing
Durable Objects hold only delivery ordinals the core assigned, a bounded replay buffer, and live connection presence. Erase them all and no accepted business state is lost; replay authority is PostgreSQL, never the object.
- The edge
-
Remove it entirely — lose speed only
With the edge network absent, the core still serves the complete product over plain TLS. What is lost is latency, caching and fan-out — never correctness, and never authority.
- Clients
-
The local store never outranks the server
Native clients keep a per-account, per-tenant local read model — SQLite through a thin owned wrapper, not an ORM — encrypted at rest and evicted as one atomic file. A client may render optimistically, but never shows "approved", "accepted" or "issued" before the server confirms.
Every request starts as a denial.
The authorisation kernel's first instruction sets the verdict to Deny. Fifteen ordered checks may upgrade it to Allow; nothing falls through. Unknown actions, missing tenant context, expired delegations, suspended principals — and any internal error — fail closed. An exception inside the kernel is a denial, never a default allow.
Every call — allowed and denied alike — writes one audit event carrying the full decision trace: each step, its outcome, and a stable reason code. The trace is internal; the response carries only the code, so a denial can never be used to probe which grants exist. Credentials are opaque reference tokens — revocable within seconds — because a self-contained token cannot be revoked inside its own lifetime.
The product invariant is enforced grammatically: the scope language for AI agents simply omits the verbs approve, accept, veto and export. An agent cannot be granted the authority to decide, because the words for it do not exist in the grammar — ungrantable by absence, not blocked by a runtime check. High-authority commands additionally require a recent, user-verified passkey step-up and an exact resource version.
- Verdict
- Starts at Deny; no fall-through to Allow
- Trace
- Recorded on every allow and every deny
- Agents
- Approve / accept / veto / export — not in the grammar
- High authority
- Human principal + passkey step-up + exact version
- Errors
- An internal error is a denial, audited as one
Append-only, in the same transaction, attributed twice.
Every nomination, delegation, approval, acceptance, review decision and invoice issuance writes an audit record in the same transaction as the change itself — recording the acting human, the represented actor if any, the exact resource version and the moment. The audit table is append-only at the database layer twice over: write privileges are revoked, and a trigger refuses updates and deletes even if they were re-granted. Corrections are compensating events, never edits.
Attribution is dual and always rendered in full: the person and, where they acted for a company, the company — never the company alone. A decision is a person's act, and the record keeps the person in it.
Asynchronous work follows the same commit: an outbox row is written with the transaction, and separate Go workers claim and process it idempotently, at-least-once. Workers perform no domain mutations and write no audit events; they read committed facts and act on them. A hostile file upload can never take the record-keeping machinery down with it.
- Money
- Integer minor units + ISO 4217; floats prohibited stack-wide
- Acceptance
- Binds to an exact revision hash; changed terms void prior acceptance
- Time
- UTC instants; display zoned by IANA name
- Identifiers
- Server-generated UUIDv7 with typed public prefixes
- Contracts
- REST canonical; clients generated from OpenAPI, never hand-written
The edge accelerates; the core decides.
Edge workers authenticate tokens, validate request shape, rate-limit, route, admit sockets and webhooks, and create signed upload sessions. What they may never do is decide: no authorisation verdict, no domain state change, no audit event and no money arithmetic may originate at the edge.
The distinction is enforced, not aspirational: the edge's database credentials are read-only at the role level, edge code cannot import the domain or authorisation packages, the built edge bundle is scanned for any audit or outbox write, and the core re-does every edge check authoritatively. Because the edge never grants, an edge failure — or an edge compromise — can only ever reduce access, never create authority.
Real-time delivery follows the same discipline: sockets notify and resume, they never carry authority. A notice holds identifiers and a safe summary — never private graph edges, contact fields, or money the viewer could not fetch — and mutation happens only through versioned REST.
- May
- Validate, shape, rate-limit, route, admit, cache public
- Never
- Verdicts, state changes, audit events, money arithmetic
- Reads
- No query caching for any mutable authorisation or money read
- Failure
- Can only reduce access — deny-by-default survives the edge
KeizAI is in an early specification phase. This page describes the architecture as specified in the project's invariants and ADRs — design intent under construction, not a description of running software.