# luxfi/aml

## Overview

Go module: `github.com/luxfi/aml`

Real-time AML/CFT transaction monitoring engine. Pure Go, single binary, embedded SQLite via Hanzo Base. Configurable rules DSL (expr-lang), sanctions screening (OFAC/UN/EU/HMT), case management, scored alerting.

## Tech Stack

- **Language**: Go 1.26.4
- **Database**: Hanzo Base (embedded SQLite per-org)
- **Rules DSL**: github.com/expr-lang/expr v1.17
- **Scoring**: Weight-of-evidence (pure Go math)
- **Sanctions**: Jaro-Winkler + token-based fuzzy name matching
- **HTTP**: Hanzo Base router (net/http)
- **Auth**: IAM access token verified in-process (`api.IAMIdentity`) — the brand of the request's own Host decides the issuer, `aud` must be this deployment's IAM clientId, `tokenType` must be `access-token`, and the `owner` claim names the tenant. `api.TrustedProxyHeader` remains for a deployment that can prove a gateway is its only route in
- **Tenant**: `<brand>/<org>` — the brand qualifies the org, in the store index and in the tokenisation vault's HKDF salt alike
- **White-label**: brand per request Host (`pkg/brand`, mirroring HIP-0111) — one `amld` serves lux.network, hanzo.ai, zoo.ngo, pars.network. A Host no brand claims is refused, never defaulted

## Build & Run

```bash
make build                  # Go build -> ./amld (the daemon)
make test                   # go test -race -count=1 ./...
make vet                    # go vet ./...
make ui                     # npm ci && npm run build -> ui/dist (the console)
make run                    # Build + run dev
```

Two artifacts, because they are two deploy units. `make build` produces the
daemon, which serves the API and nothing else; `make ui` produces the console
bundle, which is served by `ghcr.io/hanzoai/static` on its own host. No Node
toolchain is needed to build, vet, test or install the module.

## Module Layout

```
cmd/amld/main.go          -- Single binary: serve, version
migrations/0001_core.sql   -- 9 SQLite collections
ui/                        -- The console: its own bundle, its own image, its own host
  Dockerfile               -- node build -> ghcr.io/hanzoai/static -root /public -spa
  src/
    main.tsx               -- React 19 entry
    gui.ts                 -- The kit, and the one way its stylesheet reaches the DOM
    app.tsx                -- Shell: brand from /v1/aml/config, PKCE gate, 6 routes
    app.css                -- The one stylesheet: the kit's theme under this
                              file's names, plus the arrangements the kit has no
                              equivalent for. No inline styles.
    config.ts              -- API origin derived from the host; clientId from the API
    api.ts                 -- One function per route the engine serves
    ui.tsx                 -- The screens' whole vocabulary, on @hanzo/gui
    pages/
      overview.tsx         -- Readiness, coverage, the published gaps, model state
      cases.tsx            -- Queue, detail panel, timeline, resolve with rationale
      rules.tsx            -- Visual builder over the engine vocabulary + replay
      flow.tsx             -- Evaluate or score a transaction; alerts by transaction
      sanctions.tsx        -- Screen a party (agree/conflict), list readiness
      relationships.tsx    -- Art. 78 lookback as a graph; open and close
  e2e/
    session.ts             -- A signed-in console, seeded the way the SDK stores one
    serve.mjs              -- Serves dist under csp.txt, with a mock API on-origin
    console.spec.ts        -- The served CSP, signed in, on every screen the rail offers
    kit.spec.ts            -- Whether the kit actually reaches the screens
    origin.spec.ts         -- apiOrigin over 22 hosts
  csp.txt                  -- The policy under test, byte-identical to the chart
  dist/                    -- Built output (gitignored)
pkg/
  types/types.go           -- Canonical domain types (Transaction, Entity, Rule, Alert, Case)
  engine/
    engine.go              -- Core engine: evaluate tx -> alerts + score + action
    evaluator.go           -- expr-lang compiler + evaluator with helper functions
    scoring.go             -- Weight-of-evidence scoring + the Scorer seam
  velocity/velocity.go     -- Constant-time sliding aggregates per (key, window):
                              bucketed ring, fixed memory per key, Deviation
  anomaly/
    forest.go              -- Half-space trees: data-independent geometry, mass
                              counters, exponential reference fold, mass invariant
    feature.go             -- The typology->feature inventory (9 dimensions, each
                              citing the instrument behind it) + projection
    anomaly.go             -- Per-tenant model, Appetite, attribution by
                              counterfactual, State, Snapshot/Restore
  rules/library.go         -- 20 starter AML rules (CTR, structuring, velocity, sanctions, etc.)
  sanctions/
    match.go               -- Jaro-Winkler + token-based fuzzy name matching
    lists.go               -- Default list configurations (OFAC, UN, EU, HMT)
    ingest.go              -- OFAC SDN XML parser + HTTP fetcher
  cases/
    case.go                -- Case store (create, update status, assign, resolve, events)
    errors.go              -- Sentinel errors
  retention/
    record.go              -- Record, the three Art. 77(3) clocks, expiry arithmetic
    ledger.go              -- Retain/Close/Extend, party index, purpose-gated reads,
                              five-year lookback, proven disposal
    cron.go                -- Daily disposal at 03:30 UTC
  token/token.go           -- Per-org HKDF key schedule; deterministic pseudonyms
                              for index keys, AES-256-GCM seal for record bodies
  replay/replay.go         -- Rule sandbox: replays a candidate over real history
                              through the engine's own evaluator, writes nothing
  webhook/webhook.go       -- Signed delivery (HMAC-SHA256) with retry + dead-letter
  lists/                   -- The institution's own allow and deny lists, and the
                              one rule term over them: Listed(name, value)
  suppress/                -- The decisions to keep a detection out of a queue:
                              reason, decider, window, and the narrowest-wins cover
  watch/                   -- Every activation as it fires, the rungs that raise a
                              response, the fold that marks a repeat, the live feed
  dictionary/              -- What a tenant's payloads carry: declared fields by
                              reflection, the tenant's own Raw keys, fill, blindness
                              and a distinct count kept as a bitmap and never values
  topology/                -- The space of model shapes, searched over a tenant's
                              own history. Pure: no store, nothing it could write to
    budget.go              -- The machine's share for study work, so ingest keeps
                              the rest. Tokens ARE trial workers, taken before the
                              history is read; the wait is the queue and it cancels
  models/                  -- The record of every search and every fitted state, and
                              the one path that adopts one into the live model
  receipt/                 -- What an institution was told about a transaction,
                              kept so that offering it again returns the same
                              answer instead of computing a second one
  roster/                  -- The set of tenants a process holds live state for,
                              and the ceiling on how many. Admits, never removes
  api/wire.go              -- THE assembly: every collection, every shelf, every
                              join, and what runs on a cadence. One function,
                              called by cmd/amld and by the tests alike
  api/load.go              -- One door for "is anything of mine quietly degraded"
  api/typed.go             -- One operation shape, two adapters: the tenant is an
                              argument, the input is one struct, the output another
  api/gate.go              -- Admission for the expensive work: one per tenant, and
                              a deadline, as two combinators over the same shape
  api/planes.go            -- The five planes on the router, and the one place
                              ingest meets them
  api/routes.go            -- /v1/aml/* HTTP routes + SanctionsStore on Base
  api/records.go           -- The one place retention, token and replay are joined
  api/anomaly.go           -- Model state for governance + candidate scoring
  api/tenant.go            -- The Identity seam and the tenant key: <brand>/<org>,
                              minted in one place and checked at the boundary
  api/iam.go               -- Identity from an IAM token: Host pins the issuer, aud
                              pins the application, tokenType refuses an id_token,
                              `owner` must be an org the caller belongs to
  api/jwks.go              -- Published signing keys: RSA/EC/ML-DSA-65, per-issuer
                              single-flight cache, refresh + staleness bounds
  api/mldsa.go             -- ML-DSA-65 (FIPS 204) JWT verification
  api/brand.go             -- GET /v1/aml/config: the brand identity of this Host
  brand/brand.go           -- Brand id and request Host -> issuer + domains
                              (HIP-0111; the same registry as hanzoai/cloud brand)
  brand/tenant.go          -- The tenant key <brand>/<org>: Qualify, Qualified and
                              the boundary check every record plane calls
```

## Behavioural detection

Rules catch typologies someone has already named. `anomaly` answers the other
question — is this where this customer's behaviour normally lives — which is the
statutory test, since consistency is assessed against knowledge of *this*
customer and no fixed threshold can express that.

**Detector: half-space trees** (Tan, Ting & Liu, IJCAI 2011). Trees are built
before any data arrives — a random dimension split at the midpoint of the node's
range — so there is no training pass, no sample retained, and no retraining job:
the model is a set of mass counters over a fixed geometry. Scoring walks a fixed
depth. Rejected: isolation forest (batch, so a retraining job per tenant, and
attribution needs a bolt-on), and robust random cut forest (stores the points, and
its attribution is to *other points* rather than to features — the wrong shape for
the question a supervisor asks).

Two deliberate departures from the paper, both recorded at the code:

1. **Votes are averaged, not summed.** `mass * 2^depth` is heavy-tailed, so one
   tree finding the point in a dense region returns a value many times the uniform
   one and swamps every tree that found emptiness. Ranking survives that; a
   calibrated score does not, and an appetite expressed as a quantile needs a
   calibrated score. Each tree is clamped to [0,1] against its own root mass
   before averaging, which also makes the score self-calibrating during warm-up.
2. **The reference folds exponentially** (`Blend`, default 0.25) rather than being
   replaced. `Blend: 1` is the published algorithm. Below 1, making the reference
   look like your own behaviour needs sustained volume against the whole tenant
   rather than one window's worth.

**Why attributability decided it.** HIP-518 §6 admits ML detection only behind a
typology→feature mapping, a stated miss-rate appetite, and per-alert feature
attribution. The third eliminates a neural scorer: its contribution to a score is
not attributable to an input, so it needs a second model fitted to guess at its
own reasons. A tree is interrogated directly — move one coordinate to its neutral
value, rescore, and the drop *is* that feature's contribution, exactly, on the
model that raised the alert. `Cause.Without` carries that counterfactual.

**The appetite is the governed knob.** `Appetite.Review` is the share of the
stream the model may send for examination; the threshold is the quantile of
observed scores that admits it, recomputed each window, taking the upper bucket
edge so the realised share stays at or below the stated one. The miss rate cannot
be computed without labels, so `Appetite.Sample` retains a share of *non*-alerted
transactions for review below the line — selected by hash of the transaction id,
so the sample is reproducible and cannot be steered. `GET /v1/aml/anomaly` reports
stated against realised.

**What it cannot do.** Evidence is capped at `types.ActionCeiling` (review): the
model summons a person, it does not act. Weight is non-negative and NaN/Inf are
rejected, so it can only add to a score the rules built, never subtract. A panic
in the Scorer is contained and counted — the rule plane's verdict stands. Where it
cannot score (warming, unusable coordinates, no subject) the transaction is
evaluated on rules alone and the refusal is counted per reason, because silence
must never read as a clean result.

Models are per tenant, including the tree geometry, seeded from
`mix(cfg.Seed, orgID)`. 336 KB per tenant measured, bounded by `MaxOrgs`
(default 256 → 84 MB). `AML_ANOMALY=live` leaves shadow; until then the model
scores, learns and reports what it *would* have alerted on, changing nothing.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/aml/transactions | Ingest transaction, sync rule eval, returns action |
| GET | /v1/aml/transactions/{id}/alerts | Alerts for a transaction |
| GET | /v1/aml/cases | List cases (filter by status) |
| GET | /v1/aml/cases/{id}/events | The case timeline, scoped by the case's tenancy |
| POST | /v1/aml/cases/{id}/events | Add case event (note, status change) |
| GET | /v1/aml/rules | List all rules |
| POST | /v1/aml/rules/test | Replay a candidate rule over history (dry run) |
| GET | /v1/aml/anomaly | Model state: appetite, inventory, threshold, stated vs realised rate, refusals, blind features, below-the-line sample |
| POST | /v1/aml/anomaly/test | Score a candidate against the tenant's model, learning nothing |
| POST | /v1/aml/cases/{id}/resolve | Close a case against a retained assessment |
| POST | /v1/aml/relationships | Open a business relationship |
| POST | /v1/aml/relationships/{id}/close | End one, starting the retention clocks |
| POST | /v1/aml/relationships/search | Art. 78 five-year lookback by party |
| POST | /v1/aml/sanctions/search | Search sanctions lists by name |
| GET | /v1/aml/sanctions/sources | Per-list readiness: count, date, fitness |
| GET | /v1/aml/catalog | Coverage: installed rules, their citations, and the stated gaps |
| GET | /v1/aml/load | What this engine holds for the caller's tenant, and what it has had to let go |
| GET | /v1/aml/health | Health check, 503 when records cannot be kept |
| GET | /v1/aml/config | Brand identity of the request's Host: brand, display name, issuer, domain |
| GET/POST | /v1/aml/lists | The tenant's declared lists / declare one |
| GET/POST | /v1/aml/lists/{name}/entries | Read a list / put values on it |
| POST | /v1/aml/lists/{name}/entries/remove | Take a value off; the row stays |
| GET | /v1/aml/lists/{name}/lookup | Is this value listed, and on what entry |
| GET/POST | /v1/aml/suppressions | The suppression ledger / declare one |
| POST | /v1/aml/suppressions/{id}/lift | End one, with its own reason and decider |
| GET/POST | /v1/aml/activations | The activation feed / record one |
| GET | /v1/aml/activations/rates | Per rule: fired, live, silenced, folded, elevated |
| GET/POST | /v1/aml/rungs | The declared ladder / declare a rung |
| POST | /v1/aml/rungs/{id}/retire | Retire one; the row stays |
| GET | /v1/aml/dictionary | What this tenant's payloads carry, and what is blind |
| GET/POST | /v1/aml/models/runs | Past searches / run one over this tenant's history |
| GET | /v1/aml/models/runs/{id} | One whole search: every trial, every curve |
| GET/POST | /v1/aml/models/fits | Fitted states / fit one under a shape |
| POST | /v1/aml/models/fits/{id}/adopt | Install a fit into the live model |

Every route above is `get(h, <plane>.<Op>)` or `post(h, <plane>.<Op>)` and nothing
else — see "The five planes" below.

Every route resolves its tenant through `Handler.Identity`. Exactly two do not:
`/v1/aml/config`, which names the issuer a caller needs in order to obtain a token
— requiring one would be a lock whose key is behind it — and `/v1/aml/health`,
which a probe reads on a Host that names no brand. The rule list and sanctions
search require a tenant too: the first is the map of what this institution's
monitoring looks for, and the second runs a fuzzy match over every designation in
the set, which is not work an unauthenticated caller gets to spend.

Two identities, one seam, one tenant key.
`api.IAMIdentity(api.JWKS(ttl, stale), clientId)` is what `amld` runs: it verifies
the bearer itself, and four things must hold before a token names a tenant.

| Check | Why |
|---|---|
| signature under a key the brand of THIS Host publishes | a Lux token does not authenticate on a Zoo host, even where one in-cluster IAM publishes both brands' signing certificates. A Host no brand claims refuses |
| `aud` contains `AML_CLIENT_ID` | IAM stamps aud = the app's clientId, so without the pin a token minted for a marketing site — or any other tenant's app on the same issuer — is a credential here (RFC 9068 §4) |
| `tokenType == "access-token"` | an id_token is issued to a browser, carries the same `iss` and `aud`, and is not an API credential |
| `owner` ∈ `orgs`, when `orgs` is present | IAM stamps the APP's org as `owner`, so a shared or org-choice application would make all of its users one tenant. A machine token has no membership set: its org is its application's, and the application is pinned by `aud` |

`api.TrustedProxyHeader("X-Org-Id")` takes the ORG from the header a gateway writes
from that same claim — sound only where the gateway authenticates the caller, strips
any client-supplied copy, and is the only route to this service. It takes the BRAND
from the Host either way, so both identities produce the same key.

The AML application must be dedicated to one financial institution: not
`IsShared`, no `OrgChoiceMode`. IAM enforces same-org login for such an app
(`internal/oidc/login.go`), which is what makes `owner` the caller's own org.

## White-label

`pkg/brand` maps a brand id, and a request Host, to that brand's public identity:
its OIDC issuer and the domains it serves on. It is a copy of the fleet's canonical
registry (HIP-0111, `hanzoai/cloud` `brand/brand.go`) kept as a leaf, so one
`amld` answers as Lux on lux.network, as Zoo on zoo.ngo and zoo.cloud, as Hanzo on
hanzo.ai, and as Pars on pars.network — brand, console identity and trusted issuer
all from the Host. A Host no brand claims resolves to NO brand, and there is no
resolver that answers otherwise: the auth path is a caller that must not be handed
a default, or one brand's issuer authenticates every request arriving on a pod IP,
an in-cluster service name, localhost or a misrouted vhost.

Org names are unique within an issuer, not across issuers, so the tenant is the
KEY `<brand>/<org>` and never the bare org. It is minted in one place
(`pkg/api/tenant.go`, `qualify`) and is the same value that indexes alerts, cases
and retained records, scopes a history row, and salts the tokenisation vault. The
salt is the sharp end: keyed on the bare org, two brands' institutions of the same
name derive the SAME keys, so one brand's customer names tokenise to the other's
pseudonyms and its sealed records open under the other's tenant.

The isolation boundary is the deployment: each brand runs its own store, issuer and
ingress host. Brand-qualifying the key is what makes that boundary something other
than the only thing standing between two institutions.

## The five planes

Five capabilities an institution operates its monitoring programme through, each
its own package, each a durable record plane, and none of them able to destroy
anything: disposal is `pkg/retention`'s decision alone (AMLR Art. 77), per tenant,
and every one of these packages has a test that reads its own source for a call to
`Delete`.

| Plane | Package | What it is | What it refuses |
|---|---|---|---|
| Lists | `pkg/lists` | The institution's own allow and deny lists, by class, reachable from a rule as `Listed(name, value)` | A list nobody declared, and an empty value — both would be a rule that is catalogued, reported as coverage, and incapable of firing |
| Suppression | `pkg/suppress` | The decisions to keep a detection out of a queue: reason, decider, window | A suppression naming neither a rule nor a subject: that is a kill switch, not a suppression |
| Watcher | `pkg/watch` | Every activation as it fires, what became of it, and a live feed over the durable rows | An activation with no subject — it would pool every anonymous detection under one imaginary customer |
| Dictionary | `pkg/dictionary` | What a tenant's payloads carry: fill, blindness, distinct-count, and the model's own inventory | Nothing. It is a diagnostic and must never be able to refuse a payment |
| Models | `pkg/topology` + `pkg/models` | The space of model shapes searched over a tenant's own history, and the record of every search and fit | A winner nobody can justify, and a fit installed into a model of another shape |

### The decider is the credential, never the body

Every governed act on these planes — declaring a list, putting a value on one,
suppressing a detection, lifting a suppression, declaring a rung, retiring one,
running a search, fitting a shape, adopting a fit, closing a case — is asked for a
reason and a decider so that a supervisor asking "who turned this off" has an
answer. That answer is worth nothing if the caller writes it.

So the decider is a DISTINCT TYPE, `types.Decider`, and it is the one input a
caller does not supply. Fields of that type carry `json:"-"`: the body decoder, the
query binder and the path overlay all skip it, and `pkg/api/typed.go` (`decide`)
writes the AUTHENTICATED SUBJECT onto it after the body and after the path. A
caller that sends `"by":"the head of compliance"` has written a field that does not
exist. `pkg/api/tenant.go`'s `Caller` is the two projections of one verified
credential — the tenant that indexes every store, and the subject that names a
decision — and both come from the same signature (`iam.go`, the token's `sub`).

The value is the SUBJECT rather than a display name, because attribution must
survive a rename. Where the deployment's identity cannot name one, authentication
still succeeds — reads and ingest are the tenant's work, not a person's — and every
operation that would record a decision refuses with the plane's own `ErrDecider`:
a decision naming nobody is refused rather than recorded.

### Suppression is a marking, never a drop

A detection a suppression covers, or a repeat inside a fold window, is WRITTEN and
marked with the reason it did not reach a queue. `Action` is what the rule asked
for; `Response` is what the plane concluded. A monitoring system that discards what
it decided not to show cannot answer how much it is not showing, and "no alerts"
then means either a quiet institution or a silent control with no way to tell
which. Because the suppression's id is on every activation it covered, "how much
has this silenced" is a query — which is why nothing keeps a counter of it.

### Elevation and folding are one mechanism

A RUNG is a tenant's declared policy: when this rule has fired this many times on
one subject within this window, do this. `To: watch.Fold` marks the repeat as a
duplicate; `To: <action>` raises the response. A rung can only RAISE — lowering is
a suppression by another name, and a suppression is asked for a reason and a
decider that a rung is not asked for on every activation it touches. Elevation
beats folding, because an activation that reached an escalation rung IS the
escalation and not a repeat of one. With no rung declared nothing folds: silence is
a decision, never a default.

A rung's `Count` becomes the LIMIT of a read on the INGEST path — the streak query
reads exactly as many prior activations as the deepest declared rung needs — so it
is bounded (`MaxCount`, `MaxWithin`) at declaration, where a refusal costs one
operator request, and clamped again where it is USED, because a bound introduced
after a row was written does not reach that row. Undeclared, a count of ten million
turns every activation of that rule into a ten-million-row scan of the tenant's own
store, on the path that has to answer before a payment can be taken.

### One assembly, and both the deployment and the tests use it

`pkg/api/wire.go` is the only place this engine is built: every collection
(`Ensure`), every shelf (`NewBase`), every join between them, and everything that
has to run on a cadence for the durable state to stay honest. `cmd/amld` calls
`api.Wire(app, api.Deployment{…})` and supplies only what an INSTALLATION answers
differently — who a caller is, which IAM application this is, what it detects,
its key material, its designations, its business day, its rates. The tests build
the same function.

That is a correctness property and not tidiness. The previous review's defining
failure was two wirings: `cmd/amld` assembled a Handler by hand and the tests
assembled a different one, so the record fingerprint could be a struct field the
tests exercised and no column stored — every retry a permanent 409 in production
while every test passed. The bug was not in the ledger; it was that there were
two arrangements and only one of them was under test.

Three tests keep it that way, each doing one thing:

| Test | What it refuses |
|---|---|
| `TestTheDeploymentDoesNotAssembleItsOwnHandler` | an `api.Handler` composite literal anywhere in `cmd/amld`, read from the AST (`internal/source.NoLiteral`) |
| `TestWireLeavesNothingUnwired` | any exported `Handler` field left nil, empty or zero after `Wire`, found by reflection rather than by a list that would be a third copy |
| `TestWireCreatesEveryCollectionItWritesTo` | a missing collection, by ingesting one transaction through every plane |

### A retry is not a second transaction

`pkg/receipt` is the identity of an OFFER, resolved once, at the top of ingest,
before anything is read or written — and the answer that was given for it.

Every number this engine exists to compute is a count of transactions over a
window, so a retry that is counted is an aggregate wrong by the number of times
the network failed. Worse: the second offer of an UNCHANGED transaction saw a
window it had already put itself in, the verdict flipped from allow to block, and
`retain` filed a REFUSAL under AMLR Art. 77(3) — a regulatory record of a refusal
the institution never made, and a customer's payment declined, because a client
retried.

The ledger was idempotent. Nothing else was, and an engine whose ledger holds one
record while its aggregates hold three is worse than one that double counts
everywhere, because the numbers disagree and nothing says which is right.

- The offer is `(Ref, Mark)`. `Mark` digests the request body decoded and
  re-encoded, so a client that re-serialises is recognised; it covers nothing this
  engine derived, because a digest over a value this process invented differs on
  every offer — which is precisely the defect that made every retry a permanent
  conflict once before.
- A prior receipt is returned **byte for byte**. A client cannot tell a retry from
  a first offer, which is what idempotent means.
- Two different transactions under one reference is not a retry. It is refused
  (`409`), never answered from the wrong one, and never on a 5xx: `503` reads as
  "retry", and a client retrying a permanent refusal retries forever.
- The shelf is durable because the deployment is Recreate at one replica: the
  process that answered the first offer is gone by the time a client retries
  across a rollout.
- Receipts are kept for `Window(widest aggregate) = widest + 24h`, DERIVED rather
  than chosen, so tuning a window cannot leave the receipt outlived by the
  aggregate it protects. Disposal is a daily cron and destroys nothing an
  obligation covers.

**And every plane past it recognises the transaction for itself.** The receipt is
written after the work and before the response, so a process that dies in between
leaves the work done, no receipt, and a caller who — never answered — offers
again. The receipt cannot catch that one, so nothing relies on being sequenced
behind it: the ledger has its fingerprint, an activation's id is
`hash(tenant, tx, rule, subject)`, `history.Base.Append` does not append a second
row for a transaction it already holds, `AlertStore.add` keeps the first
judgement, and a transaction that has already been judged does not open a second
case. Velocity is not in that list because it is in memory — the crash that loses
the receipt loses the aggregate too. `TestAnInterruptedOfferIsStillCountedOnce`
produces exactly that state and checks all of them.

### A bound over a count of caller-sized things is not a bound

Three bounds in this engine are stated in BYTES, and each derives its count from
its cost in one place so the two cannot disagree:

| Bound | Where | Worst case weighed by |
|---|---|---|
| `types.MaxIdent` (256) | every identifier a transaction carries, refused at the door | `TestAnOversizedIdentifierIsRefusedAtTheDoor` |
| `velocity.Store.Ceiling()` | tenants × keys × `keyCost(windows)` | `TestTheCeilingIsInBytesAndItIsHonest` |
| `dictionary.Ceiling()` | `(MaxCustom + declared) × nameCost()`, where `nameCost` needs `MaxName` (128) | `TestOneNamesCeilingIsInBytes` |

`MaxIdent` is what turns every count downstream into a figure in bytes: a
sliding-aggregate key is a fixed ring plus that string, a catalog name is that
string, a retained record's slot is that string. Refusing is right where
truncating is not — an identifier this engine shortened is an aggregate kept
under a key naming a different account.

### Per-tenant state, per-tenant bounds, and no eviction anywhere

`pkg/roster` is the set of tenants a process holds live state for. It **admits and
never removes**: there is no `Drop`, no evict, no `delete` in the package, and
`internal/source.NoRemoval` reads the file to keep it that way. A tenant that is
held keeps what it holds; a tenant arriving when the roster is full is REFUSED,
and the refusal is counted and published.

The banned shape is one map of every tenant's state under one cap with LRU
eviction. It is a defect every time: the cap is spent from a pool every tenant
draws on, so a busy institution's traffic takes a quiet one's CONTROL — its
aggregates return to zero and its model returns to warming, both of which read
exactly like an institution with nothing to report. No error, no log. It is also
cheap to cause on purpose, from any tenant, with ordinary traffic.

`velocity.Store`, `anomaly.Store` and `dictionary.Shelf` all hold their
per-tenant state in a roster, and each has a `source.NoTable` test refusing a
string-keyed map on the type. `roster.Default` is ONE answer to how many
institutions this process holds state for, so every per-tenant bound multiplies
by the same figure and the products add up against a pod's memory limit.

The same rule applies to a table keyed by anything else a caller writes.
`engine.Evaluator` holds NO compiled rules for that reason: a candidate rule's
text arrives on the wire at `/v1/aml/rules/test`, so a compiled-rule cache would
be keyed by a string a caller wrote, sized by how many distinct ones a caller
sends, with no cap and no removal, in the memory every institution's ingest runs
in. A rule's compiled form is a VALUE — `engine.Ruleset` — belonging to whoever
asked for it: the engine's owner is the installed library, a replay's owner is the
one request, and both are dropped with their owner.

### Reaching a bound is allowed; reaching it quietly is not

Every live bound here can bind, and when one does an aggregate stops being kept,
a model is not planted, or an observation is turned away. None of those raises an
error, because refusing a payment because a cache is full would be the worse
failure. What is NOT allowed is for it to happen silently: an aggregate that reads
zero is what a clean account also reads, and a model that is warming reports
nothing, which is what a clean institution also reports. A control that switches
itself off without saying so is worse than no control, because it is a control
somebody is relying on.

So there is ONE door — `GET /v1/aml/load` — per tenant, answering in words rather
than in ratios a reader has to interpret: the tenant's aggregates against its own
ceiling in bytes with a grade (`clear`/`crowded`/`full`), whether it has a
behavioural model at all, the field catalog's own pressure, and the process's
counts of institutions held, refused and turned away. Nothing there names another
institution.

### The machine is one budget, and the expensive read demands its receipt

`topology.Budget` is half the cores for every study, replay and fold together;
the other half is ingest's. Tokens ARE trial workers and the hold is taken by the
CALLER THAT READS, not the callee that computes — that distinction is the whole
of the memory property, because the read is a tenant's whole retained history
opened record by record, and a token taken after it bounded nothing. Eight tenants
once held eight full histories at once against a budget of one worker.

`Handler.history` is the one function that materialises a whole retained history,
so it REQUIRES a `*topology.Grant`, and a `Grant` comes from `Budget.Admit` and
from nowhere else. An ungated whole-history read is therefore something a caller
has to go out of their way to write rather than something they can forget.
`api.costly` puts the same budget in front of a fold that is not a page —
`GET /v1/aml/activations/rates` examines up to `MaxExamined` rows however few the
caller asked for, and row-bounded is not rate-bounded. A paged read is
deliberately NOT wrapped: a page is bounded work with a cursor, and putting the
machine's budget in front of every list would make an ordinary console screen wait
behind a study.

### Ingest degrades; it does not refuse for volume

Two things run on the ingest path once per activation, and neither may be a way for
a tenant to stop its own payments.

A cover check reads this tenant's suppressions bearing on the rule. Past
`MaxCandidates` it answers over what it read and MARKS the answer
(`Cover.Partial`, `Activation.Unchecked`) instead of failing. The crowding is
refused at DECLARATION instead (`MaxInForce`, `ErrCrowded`), where a refusal costs
one operator request rather than every payment. Degrading in that direction
produces an alert a suppression would have silenced — noise, which a reviewer
dismisses — where refusing produces silence, which nobody sees.

An activation naming a transaction IS one rule firing on one subject in one
transaction, so its id is derived from `(tenant, transaction, rule, subject)` and
the row is looked up before anything is computed. With a fresh id each time, a
retry writes a second row, the second row is counted in the streak, and a declared
repetition policy fires on a repeat that never happened — a payment blocked
because the client retried.

The retained record is idempotent by the same means: `token.Vault.Fingerprint`
names the plaintext deterministically (a seal draws a fresh nonce, so sealed bytes
never match), it is a COLUMN and not only a struct field, and the transaction
carries ONE clock — its own. A reception clock stamped at ingest made every retry
a different fact under one id, a conflict no retry could ever clear. A fingerprint
that was a struct field no column stored had the same effect on the durable shelf
and none on the memory one, which is why every identity test now runs on the shelf
`cmd/amld` wires. See "A retry is not a second transaction" for the identity that
gates all of it.

### The dictionary stores no value, ever

A distinct-value count is a bitmap sketch (linear counting, 4096 bits per field per
tenant), hashed with the tenant in the key so two tenants' bitmaps cannot be
compared to learn whether they share a customer. Identifiers belong in the retained
record plane, sealed and purpose-gated; a statistics table does not get a second
copy of them under a weaker regime. The estimate SATURATES — "at least this many,
and no longer a count" — rather than drifting down, because a cardinality that
silently stops rising reads as a field that stopped varying.

That holds for numbers too, and numbers are where it is easiest to lose. A minimum
IS a payload value, exactly, at any volume; at a count of one so are the sum and
the mean derived from it. A DECLARED number is a measurement of the transaction
model this engine defines — a notional, a converted amount, a score — and its range
is the statistic a reviewer asks for, so it keeps its moments. A CUSTOM number is
whatever the institution put under its own key, and nothing here knows whether that
is an amount or a national identifier, so it gets the sketch and nothing else: min,
max, mean and deviation are ABSENT rather than zero.

The catalog is write-behind: observations accumulate and are written on a cadence
and at shutdown. That is deliberate — a field statistic is not a compliance record,
and paying an indexed write per field per transaction would spend the ingest path's
latency on a diagnostic. What is not acceptable is silence about it, so `Pending`
is published: a restart loses exactly that many observations and the answer says
so.

The vocabulary is bounded PER TENANT (`MaxCustom`), in the accumulator and in the
stored rows alike. `MaxKeys` bounds one payload used as a bag; it does not bound a
tenant that sends a different key on every transaction, and that tenant's growth is
in the memory every other institution's ingest runs in. Reaching the bound degrades
only the tenant that reached it — no error, no refused payload, the names it
already has keep measuring — and `Crowded` publishes the readings turned away,
because a catalog that quietly stopped taking names would report a payload surface
the institution does not have.

### A search names no winner it cannot justify

Ranking model shapes needs an outcome, and the only honest one is whether a shape
separates the events a human judged productive from the events a human dismissed
(the area under the ROC curve of its scores against those dispositions). Where
nothing has been judged, `topology.Search` reports every trial and NO winner, with
the reason. A ranking invented from unlabelled data — most alerts, fewest alerts,
best-behaved threshold — would look like a recommendation and would be a
preference. Ties go to the smaller model: a shape that ties on evidence and costs
less is the better answer, and preferring the bigger one drifts the fleet upward
every time a search runs.

`pkg/topology` has no store and imports nothing that has one, exactly as
`pkg/replay` does not — and a test reads its imports to keep it that way. A trial
builds its own detector and its own aggregate store, uses them, and drops them.

`models.Fit` produces learned state, and `anomaly.Restore` will only install it
into a model of the SAME shape (the digest). That is a governance property, not a
limitation: a tenant's model shape cannot be swapped underneath it by restoring a
file. The learned state itself never leaves the store — mass counters describe
where a tenant's activity is dense, and handing them out over an API would publish
the shape of an institution's customer behaviour to whoever holds a token.

### A study is admitted, bounded, cancellable — and ingest keeps the machine

A search replays a tenant's history through up to `MaxTrials` candidate detectors
and a fit replays it through one. Either is minutes of arithmetic asked for by one
request, on a single-replica process that also has to answer ingest, and a
transaction that cannot be recorded cannot be processed. Four bounds, each doing
one thing:

| Bound | Where | What it stops |
|---|---|---|
| One study per tenant | `api.gate`, `one(...)` | a tenant queueing studies against itself. Per tenant and never global: one institution's study is never refused because another is studying, and nothing is ever evicted from the map |
| A deadline (`maxStudy`, 2 min) | `api.within(...)` | a legitimate space whose total is hours. Derived from the REQUEST's context, so a client that goes away cancels the work |
| `topology.Budget` | wired in `api.Wire` | every study, replay and fold together taking the machine. Tokens ARE trial workers, taken by the CALLER THAT READS before the history is read, so CPU, the events held in memory, and the queue are one mechanism. `Handler.history` refuses without a `*topology.Grant`. Half the cores, so the other half is ingest's. The wait is the queue and it is cancellable |
| `MaxWorkers`, `MaxTrials`, `MaxEvents` | `pkg/topology` | one request naming the width of its own study |

The budget is a bound on the PROCESS and is the one thing here that is not per
tenant — deliberately, because the CPU is shared however it is modelled, and
waiting for the machine is not the same as being refused because of another
tenant. A rule replay is admitted the same way: one per tenant, and the same
deadline.

Every fit records what it cost (`Fit.Elapsed`), as every run already did
(`Report.Elapsed`), so a tenant's spend on the expensive plane is answerable from
what was kept rather than from a counter a restart resets.

### An adopted control cannot go quiet on its own

Adoption is the one governed act whose EFFECT was not durable. The fit is a row and
the adoption is a row, but what adoption DOES is install learned state into a model
that lives in memory — and this deployment is one replica with a Recreate strategy,
so a rollout empties it, and the live store holds a bounded number of tenants'
models at once, so an idle institution's can be dropped for a busy one's. Neither
is a decision anybody took, and both return the tenant to warming, which reports no
alerts, which is what a quiet institution also reports.

So `anomaly.Store` asks `models.Shelf.Adopted` when it plants a tenant's model:
per tenant, one indexed read, at most once per planting, and the installing is the
model's own `Restore` with its own digest and mass checks. `State.Planted` and
`State.Restored` publish the rest — when the model a tenant is being scored by
started, and whether it started from an adoption — so a reset is visible from
outside instead of being inferred from a silence.

### One operation shape, two faces

Every operation on every plane is

```go
func(ctx context.Context, org string, in *In) (*Out, error)
```

— the tenant is an argument and never something the operation resolves for itself,
the input is one typed struct, the output is another. `pkg/api/typed.go` is the
whole of what turns one into an HTTP route: `get` binds the input from the query
string, `post` from the body, both driven by the same json tags, and the route's
own path parameters are bound last and win. `pkg/api/planes.go` is then a routing
table with no handler bodies in it, and a test reads it as source to keep it that
way.

The point is that the CONTRACT is the pair of Go types and nothing else. The cloud
mount wraps the same functions as zip typed operations — where the same In and Out
become the OpenAPI schema, the CLI, the SDKs and the MCP tools — with no line of
the contract restated. See "A native zip conversion" below for what that costs.

### The tenant key, and where it is checked

`brand.Qualify(brandID, org)` mints `<brand>/<org>` and `brand.Qualified` is
derived from it, so there is one definition of the shape. `pkg/api/tenant.go`'s
`qualify`/`qualified` are aliases of those, not a second implementation.

Every one of the five planes calls `brand.Tenant(org)` at its own boundary before
it writes. The check is in the planes and not only where the key is minted because
the identity comes from a seam the DEPLOYMENT supplies: this is where the value
crosses into a store index, and an unqualified org reaching one puts two brands'
institutions of the same name into one tenant. Each plane has a
`TestBareOrgIsRefused` over every operation and a `TestTenantIsolation` that uses
the same org name under a second brand — which is the case a bare-org regression
collides.

## A native zip conversion

The typed operations above were written so that the cloud mount is a wrap. What a
full native-zip conversion of this engine would take, measured against the code as
it stands:

**Already done, and it is most of the work.** The 19 plane routes are typed
operations over 24 In/Out struct pairs with json tags on every field. A zip face
over them is one line each:

```go
zip.Post(g, "/lists", ops.declare, zip.WithOperationID("amlDeclareList"), zip.WithTags("aml"))
```

where `ops.declare` reads the tenant from the validated principal and calls
`lists.Shelf.Declare` — the same function this repo's Base router calls. Nothing in
the contract is restated.

**What is left, and it is the older half.** The 19 pre-existing routes in
`api/routes.go` are `func(*core.RequestEvent) error` closures that decode an
anonymous struct inline, so each one's request shape exists only inside its
handler. Converting them is: lift each anonymous struct to a named In type, lift
each `e.JSON(...)` literal to a named Out type, and move the body to
`func(ctx, org, *In) (*Out, error)`. `POST /v1/aml/transactions` is the largest —
its In is the embedded `types.Transaction` plus `relationship` and `entity`, and
its Out is the anonymous `EvalResult`+`record` struct at routes.go. Roughly 19
types to name and 19 handler bodies to move; no logic changes and no behaviour
changes.

**Four things a conversion must decide rather than discover.**

1. **Schema names are flat across the fleet.** Every type this repo would publish
   needs a prefix — `amlDeclareListIn`, `amlActivation`, `mlSearchRun` — because a
   weave refuses one name with two shapes and binds an SDK to whichever it read
   last. The plane types here are currently named for their package
   (`lists.DeclareIn`, `watch.DeclareIn`) and are distinct only by import path,
   which a flat namespace does not have.
2. **`GET /v1/aml/health` cannot be a typed operation.** A real probe answers 503
   carrying the degraded report AS ITS BODY (`readiness.go`), and a typed operation
   reaches a non-2xx only by returning an error, which renders as the framework's
   envelope and drops the report. It stays untyped, deliberately, and belongs on
   whatever closed list the mount keeps of routes that are untyped by design.
3. **The tenant must come from the principal, not from an In field.** Every
   operation here already takes `org` as its first argument for exactly this
   reason. A conversion that put the org on the In struct would make it
   caller-supplied, which is a cross-tenant read the caller asserted for itself.
4. **So must the decider, and it already is.** `types.Decider` fields carry
   `json:"-"`, so they are not part of the published schema and no generated CLI,
   SDK or MCP tool offers a `by` argument — which is correct, because there is
   nothing for a caller to pass. The mount does what `pkg/api/typed.go` does:
   decode, overlay the path, then write the validated principal's subject onto
   every decider field. A conversion that published `by` would put the field back
   on the wire in the generated surface even though this engine ignores it.

**What does not convert.** `watch.Shelf.Subscribe` is a channel, not a request. A
live feed is a transport concern (server-sent events, or a ZAP stream) over the
same durable rows that `GET /v1/aml/activations` pages; it is not a typed operation
and should not be made to look like one.

## Records, tokenisation, and the sandbox

Three obligations, three packages, one join in `pkg/api/records.go`.

**Retention (`pkg/retention`)** — HIP-0518 §9. Five years from the end of the
relationship, from the occasional transaction, or **from the date of refusal**
(AMLR Art. 77(3)); a blocked transaction is therefore retained as a refusal with
the rules that refused it, running from its own clock. A record retained inside a
relationship has *no* expiry until `Close` cascades the clock to it. Extensions
are case-by-case, capped at five further years, refused without a reason and a
decider. Reads take a `Purpose` from a closed set, because retained personal data
may be processed only to prevent ML/TF (AMLD4 Art. 41(2)).

*Deletion on expiry against no redaction* — the unit of disposal is the whole
record, never a field. Nothing in the package removes, masks or rewrites part of a
retained record; reads hand out deep copies so a reader cannot either. At expiry
the record is destroyed in full with every index entry that referenced it, and
`Dispose` verifies its own post-conditions before reporting a count — a run that
cannot prove what it destroyed reports the error and nothing else. It also refuses
a date the caller's clock has not reached, so a clock lie cannot bring destruction
forward.

*The five-year lookback* (Art. 78) is answered from a per-party index, not a scan.
`Answer.Examined` is the evidence: it counts one party's records and does not grow
with the ledger.

**Tokenisation (`pkg/token`)** — one root from KMS, per-org keys by HKDF with the
org as salt, per-domain keys by HKDF info. Two operations: a deterministic
pseudonym, which is what the ledger indexes and correlates on, and an AES-256-GCM
seal bound to the org and the record slot, which is what holds the record body. It
is deliberately **not** one-way: a hash-only design can neither reconstruct a
transaction (MLR reg. 40(2)(b)) nor re-screen a customer base against a new
designation (EBA/GL/2024/15 §4.1.4), so it would fail the obligations it is
protecting. Correlation is per org and never across orgs — the same customer in
two orgs is two unrelated keys, so a cross-tenant join is not computable.

**The sandbox (`pkg/replay`)** — JMLSG 5.7.18 requires new typologies to be tested
before live activation, and FCG 3.2.5A requires a retirement to be justified
against the outgoing rule's performance. `/v1/aml/rules/test` replays a candidate
over the org's retained transactions through *the engine's own evaluator*, and
reports how many alerts it would raise, on what, and the added/dropped/kept
difference against the rule it would replace. An empty history is refused rather
than reported as zero alerts, and the false-positive proportion and
intelligence-value are absent rather than zero when nothing was judged. It reaches
the engine through a one-method interface and history through another, so it has
nothing it could write to.

`AML_TOKEN_KEY` carries the KMS-held root — 32 bytes or more, hex encoded. There
is no default. Without it an instance reports itself unfit on `/v1/aml/health` and
refuses to ingest, because a transaction that cannot be recorded must not be
processed.

## Environment

| Variable | Effect |
|---|---|
| `AML_CLIENT_ID` | This deployment's IAM application clientId, pinned as the token audience. **No default: `amld` refuses to start without it**, because an instance that cannot check which application a token was minted for cannot identify a caller |
| `AML_TOKEN_KEY` | KMS-held tokenisation root, hex, ≥32 bytes. No default |
| `AML_DEFAULT_ORG` | Label carried by the rule catalog. The catalog is the deployment's, not a tenant's |
| `AML_BUSINESS_ZONE` | Zone business-day and business-hour rules are answered in. Default UTC |
| `AML_ANOMALY` | `live` leaves shadow mode. Anything else scores without contributing. The assembly states it from the LIVE side (`api.Deployment.Live`) so the zero value is shadow — a default that armed the statistical plane for anyone who did not think about it is the one direction a default must not fail in |

The five planes take no configuration. A list, a suppression and a rung are all
tenant DECLARATIONS carrying a reason and a decider, so none of them is a switch an
operator flips in a manifest — which is the point: a control that can be turned off
by an environment variable has no record of who turned it off.

## Console (`ui/`)

A compiled SPA, its own image, its own host. `ghcr.io/luxfi/aml-ui` is
`ghcr.io/hanzoai/static` with the bundle in `/public`, served with `-spa` so a
hard refresh on `/cases` resolves. It is NOT embedded in the daemon: the API is
one door (`api.<brand>/v1/aml`) and the console is another (`aml.<brand>`), and
putting them in one pod puts them in one blast radius.

```bash
make ui                                  # npm ci && npm run build -> ui/dist
cd ui && npm run dev                     # port 3000, proxies /v1/aml to aml.hanzo.ai
docker build -f ui/Dockerfile ui/        # what CI builds
```

Screens: overview (readiness, coverage and the published gaps), cases (queue +
timeline + resolve), rules (visual builder over the engine's own vocabulary,
with the replay report), transactions (evaluate or score, alerts by
transaction), sanctions (screen a party, list readiness), relationships (Art. 78
lookback drawn as a graph, open and close).

There is no deploy-time configuration at all. The console derives its API from
the host it is served on (`aml.<domain>` -> `api.<domain>`; a bare domain or an
address literal means same origin, which is what the dev proxy serves) and reads
its brand, display name, issuer AND IAM `client_id` from that API's
`/v1/aml/config`. No config.json, no SPA_* env, no baked clientId — so there is
no setting that points authenticated requests anywhere, and one image is every
brand's. Nothing writes the served root, so the container runs
`readOnlyRootFilesystem` and `runAsNonRoot`.

Auth is **`@hanzo/iam/browser`** — the SDK every Hanzo app uses, not a local
copy of it. `configureIam({issuer, clientId, redirect})` with both values from
`/v1/aml/config`, then `startLogin` / `handleCallback` / `getSession` /
`getUser` / `logout`. There is no auth code in this repo to review, drift or get
wrong: PKCE, token storage, refresh and RP-initiated logout are the SDK's, so
when IAM changes every app gets it.

Verified against production IAM: `hanzo.id` reflects `https://aml.hanzo.ai` on
discovery, token and userinfo, so the flow works cross-origin from the console
host.

Tech: React 19, wouter, Vite 8, `@hanzo/iam` for auth, **`@hanzo/gui`** for the
kit — the Hanzo design system, so this console wears the fleet's identity rather
than a lookalike assembled here. The kit is imported at the part
(`@hanzogui/stacks`, `@hanzogui/button`, …) rather than at the barrel, because
the barrel re-exports components built on react-native primitives this bundle
never renders. One kit, one version pin.

### The kit reaches the screens

`ui/src/ui.tsx` is the screens' whole vocabulary, and it is the ONLY place that
writes an HTML control or names a stylesheet class. A page composes `Row`,
`Col`, `Stack`, `Cols`, `Tiles`, `Split`, `Scroll`, `Body`, `Frame`, `Card`,
`Field`, `Input`, `TextArea`, `Select`, `Button`, `Tabs`/`Tab`, `Badge`, `Tile`,
`Meter`, `Panel`, `Hint`, `Mono`, `Sub`, `Code`, `Kv`, `Go` — and writes no
`<input>`, `<button>`, `<select>` or `<textarea>` of its own.

That boundary is checked rather than intended. `ui/e2e/kit.spec.ts` reads these
sources and fails on a raw control or a stylesheet-class arrangement in a page,
so "the console is on the kit" cannot decay into "the shell is on the kit".

Four things are deliberately not the kit's, each because the kit's answer would
be wrong here (`ui/src/ui.tsx` states each at the code):

| Not the kit's | Why |
|---|---|
| The four state colours | A state must read the same in every theme and in a screenshot of one. It never carries meaning alone: every badge, accent and dot ships with its label |
| The meter | Geometry is an SVG attribute. A width that varies with data is the one thing that would otherwise reach the DOM as an inline style |
| `Cols`, `Tiles`, `Split` | `repeat(auto-fit, minmax(…))`, which reflows on its own width with no breakpoint. The kit's stacks are flexbox; `flex-wrap` strands the last item rather than dividing the row |
| `Select` | The kit's is built on Sheet and Adapt, whose pan responder needs a react-native runtime this bundle does not carry. One native `<select>`, in one place |

Three properties of the kit are worth knowing before changing `ui.tsx`, because
each produced a defect that a build, a typecheck, a CSP run and a render test
all passed, and only looking at the screen found:

1. **`size` is a size token.** The kit derives the box AND the type from it, so a
   button asked for by height comes out with type to match. Box and type are
   given separately, from the console's scale (13px, or 11px when quiet), once.
2. **Button does not forward `className`.** A tone written as a class is dropped
   in silence: the one action a screen exists for looks like every other action,
   and a segment strip shows no selection. Tone is style props.
3. **A custom property is substituted where it is DECLARED.** The kit publishes
   themes as `:root .t_dark` — a descendant selector — so a theme is always a
   subtree and never reaches `:root`. `app.css` therefore bridges the theme on
   `.shell, .gate`, which are inside it. Bridged at `:root` it reads the kit's
   OS-preference default instead, and a control whose ground and ink both come
   through it becomes white on white.
   The kit's default web config is also worth knowing about here: its Button
   sub-theme carries placeholders (`--t0: dark`, `--t1: button`), which are
   names and not colours, so `$color` inside a Button is not a colour. Tone
   reads the bridge, which is where this console reads the theme, once.

`kit.spec.ts` asserts all three as invariants rather than as three regression
cases — a label is measured, a primary button is compared against a plain one, a
pressed segment against an unpressed one, and no control may paint its text in
its own background colour. Each was mutation-proven: reintroduce the defect and
the matching assertion fails.

### The console and the CSP

The served policy carries no `'unsafe-inline'`, and the kit styles at runtime.
That is not a contradiction; it is an arrangement, and it is in one file
(`ui/src/gui.ts`).

`GuiProvider` would render the config's stylesheet as `<style>{getCSS()}</style>`
— an inline style element, whose text `style-src` governs. `disableInjectCSS`
turns that off and the same CSS goes on the document through a **constructed
stylesheet**. CSP does not govern the CSSOM: the script that called it had
already passed `script-src`. The kit's per-component rules take the same route,
into **empty** `<style>` holders, and `'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='`
— the SHA-256 of the empty string — is what allows those and nothing else.

One style *attribute* survives, on the kit's theme root. It is written through
`element.style`, which is CSSOM again, so it applies and raises nothing. A style
attribute **parsed from markup** — the shape an injection takes — is refused,
and `ui/e2e/console.spec.ts` asserts that too, as a positive control: "no
violations" proves nothing without evidence that a violation would have been
noticed.

`ui/csp.txt` is the policy under test, byte-identical to the `HANZO_STATIC_CSP`
in `charts/app/values/hanzo/aml-ui.yaml`. The two are the one place each side
states it; changing one means changing the other.

```bash
npm --prefix ui run e2e     # builds, serves under csp.txt, drives Chromium
```

The harness signs in before the first script runs, so what it exercises is the
SIGNED-IN tree — six screens, every control — not the sign-in gate. It walks
whatever the rail offers rather than a hard-coded list, so a screen added
without a test is still a screen it covers. It serves the mock API on its own
origin, which is not a relaxation: a host with no parent domain means same
origin (`ui/src/config.ts`), so `connect-src 'self'` covers it and the policy
stays byte-identical to the deployed one.

## Transaction Ingest Flow

```
POST /v1/aml/transactions
  -> Parse + validate
  -> Resolve entity from user_id
  -> EvalAll(rules, {tx, entity})
     -> Filter by jurisdiction, asset_class, enabled
     -> Compile + run each rule DSL via expr-lang
  -> Score(hits) -> weight-of-evidence [0,1]
  -> resolveAction(alerts) -> highest severity action wins
  -> If block/report: auto-create Case
  -> Return {action, score, alert_ids, case_id?}
```

## Starter Rules (20)

| # | Rule | DSL Pattern | Action |
|---|------|-------------|--------|
| 1 | CTR Threshold | notional > 10000 && USD | report |
| 2 | Structuring | notional in [9000, 10000) | flag |
| 3 | Velocity Daily | sum_last_24h > 50000 | review |
| 4 | Velocity Monthly | sum_last_30d > 500000 | review |
| 5 | First-Time Large | first_tx && notional > 25000 | review |
| 6 | Round-Trip | is_round_trip 24h | flag |
| 7 | Sanctioned Jurisdiction | jurisdiction in sanctioned list | block |
| 8 | PEP Large | PEP && notional > 10000 | review |
| 9 | Unusual Hour | hour in [2,3,4] | flag |
| 10 | New Counterparty Large | first_counterparty && notional > 5000 | review |
| 11 | Dormant Reactivation | last_tx > 180d && notional > 10000 | review |
| 12 | Crypto Mixer | is_mixer_address | block |
| 13 | Darknet Market | is_darknet_market | block |
| 14 | IP/Geo Mismatch | !geo_match | flag |
| 15 | Layering | layering_score > 0.8 | review |
| 16 | Smurfing | smurfing_detected 7d | review |
| 17 | Wash Trading | wash_trade_detected 1h | flag |
| 18 | Sanctions Direct | sanctions_hit(entity) | block |
| 19 | Sanctions Counterparty | sanctions_hit(counterparty) | block |
| 20 | Travel Rule | notional > travel_rule_threshold | report |

## Compliance Client Compatibility

`luxfi/compliance` AML client connects via HTTP:

| Client Method | Endpoint |
|---|---|
| ScreenTransaction | POST /v1/aml/transactions |
| CheckSanctions | POST /v1/aml/sanctions/search |
| CreateCase | POST /v1/aml/cases/{id}/events |
| GetCases | GET /v1/aml/cases |

Webhook events: `aml.flagged`, `aml.cleared`, `kyc.approved`, `trade.executed`.

## Deferred

- Hanzo Tasks durable workflows (sanctions-refresh, case-automation, backtest)
- Base realtime subscription for live transaction monitoring
- Full OFAC/UN/EU/HMT list refresh automation
- Per-org KMS key material. `token.Source` already takes the org, so this is a
  different Source and not a different design; today one root is derived per org
  by HKDF, which means no cross-org correlation but one blast radius.
- Exposing `Ledger.Extend` over HTTP. The cap and the refusals are implemented and
  tested; there is no route yet. The reason there was none is closed —
  `types.Decider` makes the decider the credential's — so this is now a route to
  write rather than a design to decide.
- Tokenising the operational transaction store. `pkg/engine/basestore.go` still
  writes `user_id`, `counterparty` and `ip_address` in the clear for its aggregate
  queries; the retention ledger holds pseudonyms and sealed bodies, so the two
  planes do not agree yet.
- The field catalog's flush is one `SELECT` and up to one `SAVE` per field, per
  tenant, inside one transaction, on the database ingest also writes to. Per-tenant
  bounds make the worst case statable (`MaxCustom` names × `roster.Default`
  tenants per five-minute window) and that is what closed the unbounded version,
  but the aggregate on a one-replica pod is still the largest write this process
  makes. A single upsert per field, or a flush that yields between tenants, would
  remove it.
- `cases.AutoClose` closes low-severity cases on inactivity without a retained
  assessment — the one path that closes a case without a recorded decision. Needs
  a compliance decision: escalate instead of closing, or record a system rationale.

## Dependency pinning

Every dependency resolves through `proxy.golang.org` and is verified against
`sum.golang.org`. Both are append-only: the proxy serves the zip it first
recorded for a version, and the checksum database is a transparency log of that
zip's hash. A tag that moves afterwards therefore cannot change what this repo
compiles — which is the whole point, because tags in this fleet do move.

The builds pin that policy themselves rather than inheriting it. A machine may
carry a `go env` file whose `GOPRIVATE`/`GONOPROXY`/`GONOSUMDB` route
`luxfi/*` and `hanzoai/*` around both, so `ci.yml` and `release.yml` set
`GOENV: off`, the one documented switch that ignores the file. `GOPRIVATE=` in
the environment does **not** override it: Go reads an empty environment variable
as unset and falls back to the file.

Rules:

1. **Never write a hash `sum.golang.org` does not corroborate.** The log is the
   authority; if `go.sum` disagrees with it, `go.sum` is wrong. Two commits in
   this history (`9821aff`, `77173ad`) wrote hashes taken from whatever the git
   host was serving, which is the failure this rule exists to prevent.

   ```bash
   curl -sS https://sum.golang.org/lookup/github.com/luxfi/pq@v1.0.3
   ```

2. **`go mod verify` does not check `go.sum`.** It compares the extracted module
   against the hash recorded in the local module cache, so it reports
   "all modules verified" while a `go.sum` entry that matches nothing sits right
   next to it. Only a download can catch that — on a *clean* `GOMODCACHE`, since
   a cache entry fetched from the git host keeps serving those bits.
3. **Prefer the lowest unmoved patch successor** (`x.y.z` -> `x.y.z+1`). Never
   jump a major; never go above `v1.x.x`.
4. If a module has no version whose host content, proxy content, and log record
   all agree, that repo's owner must cut one. Do not work around it here.

Tags known to have been force-moved, and how each was resolved:

| Module | Moved tag | Resolution |
|---|---|---|
| `github.com/luxfi/age` | v1.5.0 | pinned v1.5.1 — same commit `b13d4cb0`, unmoved |
| `github.com/luxfi/threshold` | v1.9.4 | pinned v1.9.5 — same commit `0080201`, unmoved |
| `github.com/luxfi/pq` | v1.0.3 | resolved in place: move was content-neutral, `go.sum` carries the log hash |
| `github.com/hanzoai/base` | v1.1.0 | `go.sum` carries the log hash; **owner action** for a version host and log agree on |
| `github.com/hanzoai/kms/sdk/go` | v1.0.0 | graph-only, not in `go.sum` |
| `github.com/luxfi/mpc` | v1.14.13 | graph-only, not in `go.sum`; host and log disagree |
| `github.com/luxfi/precompile` | v0.5.37 | graph-only, not in `go.sum`; host and log disagree |

`luxfi/age` and `luxfi/threshold` are the pattern to copy: a successor tag cut at
the *identical commit*, so pinning it changes no code and restores corroboration.

Two entries needed more than a successor tag:

- **`luxfi/pq` v1.0.3** moved from `e16b004d` to `90d2223e`, but the two commits
  have byte-identical trees, so the zip hash never changed. The proxy, the log,
  and the git host all report `h1:pFlQm1+5...`; `go.sum` had recorded
  `h1:ksw1dmfT...`, which corresponds to nothing obtainable and made a
  cold-cache build fail outright. `go.sum` now carries the log hash. No
  successor tag is needed.
- **`hanzoai/base` v1.1.0** moved from `fe516fdc` to `a0b4a9f3`, and the content
  did change — in exactly three files, `README.md`, `docs/NETWORK.md`, and
  `docs/NETWORK_RED_REVIEW.md`. **No Go source and no `go.mod` differs**, so the
  two trees compile identically. `go.sum` carries the log hash
  (`h1:Mi4yRgR1...`, the `fe516fdc` tree). A machine whose module cache already
  holds the `a0b4a9f3` bits will report a mismatch until that entry is evicted;
  a clean cache resolves it from the proxy. The durable fix is for the owner to
  cut `v1.1.1` at `a0b4a9f3` so host, proxy, and log agree on one version.

## Third-party notices

The distributed artifacts carry `THIRD-PARTY-NOTICES`: the license, notice, and
patent-grant texts of every module the linker puts in `amld`, reproduced
verbatim. Apache-2.0 §4(d) requires the attribution notices of Apache-licensed
dependencies to travel with each distributed copy, and 10 of the linked modules
ship a `NOTICE` file; MIT/BSD/ISC require their copyright and permission notices
to travel the same way.

`go run ./internal/notice` generates it from the build's own module graph, so it
cannot describe a dependency set the artifact does not have and cannot go stale
when a dependency changes. Output is deterministic — modules sorted by path, no
timestamps — so it does not perturb a reproducible build.

It is generated, not committed (`.gitignore`), and produced on all three
distribution paths: `make build` (via the `notice` target), the goreleaser
archive (a `before` hook plus an `archives.files` entry), and the container image
(build stage, copied to `/app/THIRD-PARTY-NOTICES` beside `/app/LICENSE`).
Regenerate with `make notice`; verify by inspecting a built archive or the image
filesystem, never by reading the config.

## Durability

Three planes, all Base-backed, all proven across an instance boundary. Nothing
an obligation covers is held in memory: a rollout is not an event the
record-keeping rules make an exception for.

| Plane | Collections | Wired by | Restart test |
|-------|-------------|----------|--------------|
| Retained records | `aml_retention`, `aml_retention_parties` | `retention.Ensure` + `retention.NewBase` | `TestRetainedRecordsSurviveARestart` |
| Receipts | `aml_receipts` | `receipt.Ensure` + `receipt.NewBase` | `receipt.TestRestart` |
| Cases + timelines | `aml_cases`, `aml_case_events` | `cases.Ensure` + `cases.NewBase` | `TestCasesSurviveARestart` |
| Alerts | `aml_alerts` | `api.EnsureAlerts` + `api.NewAlertStoreBase` | `TestAlertsSurviveARestart` |
| Lists | `aml_lists`, `aml_list_entries` | `lists.Ensure` + `lists.NewBase` | `lists.TestRestart` |
| Suppressions | `aml_suppressions` | `suppress.Ensure` + `suppress.NewBase` | `suppress.TestRestart` |
| Activations + rungs | `aml_activations`, `aml_rungs` | `watch.Ensure` + `watch.NewBase` | `watch.TestRestart` |
| Field catalog | `aml_fields`, `aml_payloads` | `dictionary.Ensure` + `dictionary.NewBase` | `dictionary.TestRestart` |
| Model runs + fits | `aml_model_runs`, `aml_model_fits` | `models.Ensure` + `models.NewBase` | `models.TestRestart` |

Each test writes, copies the data directory as it stands, drops the instance,
opens a second one over those bytes, and asks again — including that the tenant
boundary still holds and that case numbering continues rather than restarting.

The memory implementations remain, and are for tests. `cases.NewStore()` and
`api.NewAlertStore()` are not what an instance serves from.

**What is deliberately in memory, and what brings it back.** The behavioural
model's learned state is a cache: its durable home is the adopted fit
(`aml_model_fits`), and `anomaly.Store` reloads it when it plants a tenant's model
(`models.Shelf.Adopted`), so a rollout of a Recreate-at-1-replica deployment or an
eviction to make room for another tenant costs a read and not a control.
`State.Planted` and `State.Restored` say which happened. The field catalog's
accumulator is in memory by design and `Catalog.Pending` publishes what a restart
would lose. Nothing else an obligation covers is held in memory at all.

## Deployment

- Single binary: `amld serve --http=0.0.0.0:8090`
- Docker: `ghcr.io/luxfi/aml:{tag}` (API), `ghcr.io/luxfi/aml-ui:{tag}` (console)
- Hanzo fleet: `charts/app/values/hanzo/aml.yaml` (no host of its own; reached at
  `api.hanzo.ai/v1/aml`, a path on the api Ingress in `hanzo-domains.yaml`) and
  `charts/app/values/hanzo/aml-ui.yaml` (the console at `aml.hanzo.ai`)
- K8s: Deployment, replicas=1 (SQLite single-writer), PVC for /data
- Replication: hanzoai/replicate sidecar for age-encrypted S3 WAL streaming

### What the release smoke has to know about the runner

Three facts, each learned from a release that produced no image at all. Every
v0.3.x tag before v0.3.6 is a tag with nothing behind it for these reasons.

- `amld` lives at `/usr/local/bin/amld`, on PATH. It was `/app/amld`, which
  alpine's PATH does not contain, so the smoke's `command -v amld` exited 127 and
  the release died one line into the check.
- A smoke container shares the job container's network namespace
  (`--network "container:$(hostname)"`) and is probed on its own port. It must
  not publish one: the step runs inside a job container while the docker daemon
  is the runner's, so `-p 127.0.0.1:…` binds in the runner's namespace and the
  loopback in the step reaches nothing.
- Hex comes from `od -An -tx1 | tr -d ' \n'`. `xxd` is not in the runner image.
  It failed quietly to an empty `AML_TOKEN_KEY` — an env prefix on a backgrounded
  command reports the async list's status, not the substitution's — so the CI
  smoke ran green for weeks against a daemon holding no key. The length is now
  asserted before use.

## Test Coverage

Go tests across 26 packages, all green under `-race`, plus 12 browser tests.
`pkg/receipt` and `pkg/roster` are the two new ones; both carry the full plane
suite (tenant isolation, bare org refused, restart over the first instance's
bytes).

- api: 76 · retention: 43 · cases: 40 · sanctions: 39 · engine: 38 · anomaly: 27
- measure: 26 · watch: 22 · dictionary: 17 · topology: 16 · screen: 15 · token: 14
- replay: 14 · models: 14 · suppress: 13 · rules: 13 · lists: 13 · velocity: 11
- brand: 11 · chain: 7 · workflows: 7 · webhook: 5 · store: 4 · history: 3
- lists · suppress · watch · dictionary · topology · models — each carries a
  `TestTenantIsolation` (the same org name under a second brand), a
  `TestBareOrgIsRefused` over every operation, a `TestNothingDeletes` that reads
  the package's own source, and a `TestRestart` that opens a second instance over
  the first one's bytes (`internal/instance`)

**Mutation harness.** `python3 tools/mutate.py` breaks one guard at a time and
reports whether a test noticed: ANCHOR MISS, COMPILE FAIL, SURVIVED, or KILLED. A
property with no mutation is a property nobody has seen fail, and a SURVIVED is a
test that cannot fail. Every bound and every gate above carries one — the study
gate, the worker clamp, the decider binding, the crowding refusal, the partial
cover marking, the firing identity, the record fingerprint, the rung bounds, the
custom-number moments, the vocabulary bound at both ends, and the adoption reload.

The browser suite is `ui/e2e`, run by `npm --prefix ui run e2e` and by CI. It
builds the bundle, serves it under `ui/csp.txt`, signs in before the first
script runs, and drives Chromium. See "The console and the CSP" and "The kit
reaches the screens" below for what each half of it establishes.