Decisions

The architecture decision records live in the repository at docs/adr, one number each. This page is the index; the record is the text there. Each decision also has a page here on one template (templates/decision.adoc in the documentation repository) with a map drawn from one shape: the decision, the mechanism that makes it true, the gate that keeps it true, and what was rejected.

ADR Title The decision in one sentence

ADR	Title	The decision in one sentence
0001	One repository	The kernel, the modules a reference architecture needs, the UI and the reference application live in one public repository; private catalogs and clients consume it by tag.
0002	Explicit wiring	An application is a list of `Module(Deps{…})` calls in `main`; the compiler checks the graph, and there is no dependency-injection container, registry or implication table.
0003	Tenancy by Postgres	Tenant isolation is `FORCE ROW LEVEL SECURITY` set per transaction, with `db.Tx[db.Tenant]` and `db.Tx[db.System]` as distinct types.
0004	Events are the job queue	One transactional outbox relayed to JetStream is the queue; `kit/jobs` is a schedule plus an advisory lock for the one thing an outbox cannot express.
0005	Roles and who migrates	One binary with `--role web\|worker\|all`; every role migrates behind an advisory lock at start.
0006	System access is a token	Cross-tenant access is a capability handed to a module at wiring time, so every crossing is visible in the composition.
0007	Screens are derived from schemas	A screen is generated from a resource’s schema, and a hand-written screen is an exception that has to earn itself.
0008	Prices are the operator’s	The price list is read by every tenant and written by the operator’s tenant alone, as an operator permission the kernel refuses elsewhere.
0009	What is public	The seam between the public repository and the private ones: what is never published, the `replace` lifecycle, and the ceilings as a commitment.
0010	A limit is a row	Rate limits are rows in Postgres shared by every replica, not per-process counters.
0011	Capabilities own migration progress	Each capability numbers its own SQL; one runner applies them in composition order, commits each file with its history row, and keeps no down files.

0001

One repository

The kernel, the modules a reference architecture needs, the UI and the reference application live in one public repository; private catalogs and clients consume it by tag.

0002

Explicit wiring

An application is a list of Module(Deps{…}) calls in main; the compiler checks the graph, and there is no dependency-injection container, registry or implication table.

0003

Tenancy by Postgres

Tenant isolation is FORCE ROW LEVEL SECURITY set per transaction, with db.Tx[db.Tenant] and db.Tx[db.System] as distinct types.

0004

Events are the job queue

One transactional outbox relayed to JetStream is the queue; kit/jobs is a schedule plus an advisory lock for the one thing an outbox cannot express.

0005

Roles and who migrates

One binary with --role web|worker|all; every role migrates behind an advisory lock at start.

0006

System access is a token

Cross-tenant access is a capability handed to a module at wiring time, so every crossing is visible in the composition.

0007

Screens are derived from schemas

A screen is generated from a resource’s schema, and a hand-written screen is an exception that has to earn itself.

0008

Prices are the operator’s

The price list is read by every tenant and written by the operator’s tenant alone, as an operator permission the kernel refuses elsewhere.

0009

What is public

The seam between the public repository and the private ones: what is never published, the replace lifecycle, and the ceilings as a commitment.

0010

A limit is a row

Rate limits are rows in Postgres shared by every replica, not per-process counters.

0011

Capabilities own migration progress

Each capability numbers its own SQL; one runner applies them in composition order, commits each file with its history row, and keeps no down files.

The design behind the UI composition layer and the native shell, written on 2026-09-05, is kept with the programme record rather than as an ADR: it is a plan that was executed, and the decisions it produced are the packages themselves.