Decision records
42 engineering decision records for Marque. An EDR records a decision that has already been made — the context that forced it, the choice, and the consequences we accepted. Discussion happens in pull requests; this is the outcome.
The architecture page is a synthesis of these
records. Where the two disagree, the records win. Marque's design also cites
Field Notes (ZFN-N) — the standing engineering
positions these decisions are derived from.
- 0001
Broker production data access as reviewed, signed, expiring grants Status: accepted Implementation: none
Marque replaces ad-hoc production database access with a reviewed workflow: a submitted statement is analysed, approved by a human with authority over that target, and executed under a named role inside a signed validity window.
- 0002
One bootstrap URL is the only client configuration Status: accepted Implementation: none
A Marque deployment publishes its own configuration at a well-known path. A client is configured with one URL and discovers issuers, audiences, endpoints, relays and capabilities from the server.
- 0003
Every principal is federated, and every token is bound to a key Status: accepted Implementation: none
Marque has no local accounts and no long-lived keys. Humans authenticate through any configured OIDC issuer, workloads through their cloud's own identity, and every token is DPoP-bound so a stolen one is useless.
- 0004
A marque is a doubly-signed lease, verified by computation Status: accepted Implementation: none
A marque is a JWS carrying both the approver's signature and the control plane's, binding one statement digest to a role, a window and an execution budget. The Pilot verifies it locally; only revocations are looked up.
- 0005
The control plane never holds a target credential Status: accepted Implementation: none
Target credentials live only where connections are made. The Harbourmaster stores a reference; the Pilot dereferences it at connect time using its own workload identity and never returns it.
- 0006
Every statement names a role, and the role is the real limit Status: accepted Implementation: none
A request must name a target role, and the database's own grants on that role bound what any marque can do. Marque's policy narrows what the role could do; it never widens it.
- 0007
Prove object scope, fence row scope, and escalate anything unprovable Status: accepted Implementation: none
A delegation is checked in three ways: object scope by static proof over a restricted statement grammar, row scope by a transactional fence that aborts loudly rather than narrowing silently, and magnitude by an affected-row assertion.
- 0008
Approve routine work once, as a parameterised standing order Status: accepted Implementation: none
A standing order is a statement template approved once, invoked with parameters that must satisfy declared constraints. Invocation mints a marque with no human in the loop, and every invocation is still logged.
- 0009
The Leadsman advises and can never decide Status: accepted Implementation: none
The analyst reads a request and reports what it touches, but has no authority to approve, deny, alter or execute anything. Its output is data attached to a request, and the approval path does not consult it.
- 0010
Rehearse the statement in a transaction that never commits Status: accepted Implementation: none
Before approval, the Pilot runs the request inside a transaction it always rolls back, capturing affected rows, duration and plan. The approver sees measured numbers rather than a guess.
- 0011
Execution is idempotent, fenced, and budgeted Status: accepted Implementation: none
Every execution carries a caller-supplied nonce recorded before the statement runs. A repeat returns the first outcome instead of applying the change twice, and the marque's budget is consumed by the nonce, not by success.
- 0012
The logbook is an append-only hash-chained journal Status: accepted Implementation: none
Every request, analysis, approval, execution and revocation is appended to a hash-chained journal that Marque's own role cannot update or delete. Resubmission cites the prior entry rather than reopening it.
- 0013
Async work rides the write-ahead log, not a job table Status: accepted Implementation: none
Notifications, analysis dispatch and reaping are emitted transactionally into PostgreSQL's WAL and consumed by a replication listener, so an event cannot exist without its state change or be lost after it.
- 0014
Reach isolated targets through a relay the Pilot dials out to Status: accepted Implementation: none
A Pilot inside a private network reaches the control plane by dialling out to a Tender relay and serving over that connection. No inbound port, no bastion credential, and the relay never terminates the session.
- 0015
Who may approve what is reviewed configuration, not a console setting Status: accepted Implementation: none
Targets, roles, approval policy and standing orders live in a versioned repository, are applied by a signed change, and every applied version is recorded in the logbook. Delegation is the runtime path.
- 0016
Compile a written delegation, and have the human sign the compilation Status: accepted Implementation: none
A delegation may be written in plain language. A model compiles it into a structured scope, the grantor reads and signs the compiled form, and enforcement runs entirely on the compilation — never on the sentence.
- 0017
A model may choose a route, never widen a bound Status: accepted Implementation: none
Where a written delegation will not fully compile, a Surveyor judges whether a request conforms to it — but only inside a deterministic bound a human signed, with two possible outcomes: take the fast path, or refer to a human.
- 0018
An agent's authority is the intersection of three scopes, including its own Status: accepted Implementation: none
An agent submits as itself, on behalf of a named human. What it may do without asking is the intersection of operator policy, its human's delegation, and the narrower scope the agent declared for its own task.
- 0019
Escalation is a chain of named stages, and every stage is a person Status: accepted Implementation: none
A request outside its submitter's scope escalates to a defined sequence of approvers — an agent's human first, then whoever policy additionally requires — with each stage timed, notified, and recorded.
- 0020
One schema generates every client, and annotates what may be retried Status: accepted Implementation: partial
A single protobuf definition is the source of truth for the API. Server stubs, CLI and console clients are generated from it, every method declares whether it is read-only or idempotent, and CI fails on a breaking change.
- 0021
Connect as the operator where the database can, and never let a driver retry a write Status: accepted Implementation: partial
Pilots use pooled, dynamically-credentialled connections. Where the engine allows, a session authenticates as the individual operator via IAM so the database's own audit names them; reads may route to replicas.
- 0022
Speak the PostgreSQL wire protocol locally, and broker every statement across it Status: accepted Implementation: none
Marque runs a loopback proxy that emulates PostgreSQL so psql and existing tools work unchanged. It parses and brokers every statement rather than forwarding bytes — it is an interface onto the control, not a tunnel around it.
- 0023
Enrol approver keys in hardware, and require an existing approver to enrol the next Status: accepted Implementation: none
An approver signs with a non-extractable hardware key — WebAuthn in the browser, the platform key store in the CLI. Enrolling an additional key needs a second enrolled approver, so a stolen session cannot mint its own authority.
- 0024
The console is for deciding, and it has no bulk approve Status: accepted Implementation: none
A static, same-origin web app for reviewing and signing marques, supervising agents and reading the logbook. It cannot author policy, cannot run ad-hoc SQL, and deliberately offers no way to approve many things at once.
- 0025
Partition every tenant from day one, including its logbook chain and its signing key Status: accepted Implementation: partial
Tenancy is in the model from the first migration: the tenant comes from the authenticated principal, never a request field, and each tenant gets its own hash chain and its own control-plane signing key.
- 0026
Publish what each engine can actually enforce, and disable what it cannot Status: accepted Implementation: none
Adding an engine is not a driver swap: the fence, the rehearsal and the timeout are all engine-specific. Where an engine cannot support a control, that control is marked unavailable rather than silently weakened.
- 0027
Be psql first, then be better than psql Status: accepted Implementation: none
`marque psql` accepts psql's flags, meta-commands and output formats so it can be aliased in place. Catalog introspection is a named statement class that runs under the role without approval, logged in aggregate.
- 0028
Open the statement pipeline to providers that may narrow or veto, never widen Status: accepted Implementation: none
A staged pipeline lets configured out-of-process providers transform and verify a statement, possibly asynchronously. The digest is taken after transformation so a human signs what will run, and no provider can grant authority.
- 0029
On a fast path the human signed the shape, and the Pilot verifies that artefact Status: accepted Implementation: none
A marque minted without a human present carries the standing order or compiled delegation that authorised it, with its own approver signature, so the Pilot verifies offline that some human signed the shape of what it is about to run.
- 0030
A marque states how many approvers it needs, inside what every signature covers Status: accepted Implementation: none
JWS signature entries are independent, so a two-approver marque could be stripped to one and still verify. The required count and eligible approvers move into the signed payload, making a stripped marque invalid rather than downgraded.
- 0031
Anchor the approver key set outside the control plane, or the second signature is theatre Status: accepted Implementation: none
A Pilot must not learn which keys are approvers from the Harbourmaster. The enrolled set is a co-signed, epoch-chained roster verified back to a root configured out of band at Pilot deployment.
- 0032
Bind the executor, the tenant and the Pilot into the marque Status: accepted Implementation: none
Three bindings other records already assume had no payload field: the caller's key, the tenant, and the Pilot. Adding them makes offline execution work for the caller, makes tenant confusion fail closed, and makes the budget fence real.
- 0033
Assert the transaction's whole write set, not just the named relation Status: accepted Implementation: none
A cascading delete returns one row and destroys millions in a table no delegation names. A fourth fence check reads the transaction's per-relation write counts before commit and aborts if anything outside the declared scope was touched.
- 0034
Give the whole Pilot API an authorisation model, not just Execute Status: accepted Implementation: none
Rehearse and Introspect are statement-execution paths with no stated caller check, so a compromised control plane has an exact-count oracle over every target. Every Pilot method now verifies a submitter signature.
- 0035
Execution freshness belongs to the approval, not to the executing principal Status: accepted Implementation: none
Requiring a fresh interactive authentication to execute against a critical target broke offline execution, locked agents out of the flow escalation exists for, and keyed on a different criticality than another record. It is resolved here.
- 0036
Anchor what is signed and what it claims, not only who may sign Status: accepted Implementation: none
A compromised control plane can render one payload and obtain a signature over another. Policy becomes an anchored artefact, the payload carries a signed rendering, and critical signing leaves the browser.
- 0037
An emergency changes who is asked and how loudly, not what is checked Status: accepted Implementation: none
Urgency reroutes and pages without widening scope. Break-glass is a pre-granted, dormant scope that activates only on an explicit act with a bound justification, mints an ordinary fast-path marque, and is very loud.
- 0038
A request is a shareable, watchable object with a live status Status: accepted Implementation: partial
Every request has a reference an operator can paste into chat, a status block naming the chain and who is being waited on, and a queue command that lists pending and approved work so it can be run without hunting.
- 0039
The checkable grammar is parsed by PostgreSQL's own parser Status: accepted Implementation: none
Every component that parses a statement uses libpg_query — PostgreSQL's real grammar — not a re-implementation. cgo is accepted in every binary, including the CLI, rather than maintain a second grammar that can disagree with the server.
- 0040
Declare a method's behaviour in one annotation, and never weaken it Status: accepted Implementation: shipped
A method's retry behaviour travels as a single MethodBehaviour extension rather than three, and once declared it may only strengthen. buf breaking ignores custom options, so a separate check compares every method against the base branch.
- 0041
Spell a scope the same way in every artefact Status: accepted Implementation: partial
A fence is an array of conjuncts in every artefact that carries one, a relation is a schema field and a relation field, and an operation is lowercase. Conjuncts compare as decoded strings, so canonicalisation normalises nothing.
- 0042
Give the control plane's store a schema, a migrator, and a driver rule that survives PostgreSQL Status: accepted Implementation: partial
The store was already fixed to PostgreSQL. What M1 owed was the schema, a forward-only digest-checked migrator, and a replacement for EDR-0005's no-driver-linked rule, which PostgreSQL for Marque's own state makes unachievable.