This is the decision record as it was written, grilled and shipped. It’s copied from our repository unedited, apart from customer, partner and bank names, which read [redacted]. It was written for the people and agents building the product, so expect internal shorthand, and the mistakes are left in.

ADR-820: Card Connectivity — the processor contracts and the Paymentology simulator

Status: Shipped — 2026-09-30

The first ADR of the cards series seeded by Cards, Inside the Ledger (sections 7, 8 and 11). It builds the seam every later card ADR stands on, and nothing above it.


Outcome

A card processor now connects as a configured facet: authorisation, reversal and token-provisioning doors answer inside the budget from insert-once receipts, and a Paymentology adapter and simulator carry the outbound seam and the clearing-file import. Landed as designed across seven bites, plus a Worker that starts without a secret store and the card seam’s reachability reason relabelled (F-1577).

Context

The Problem

LedgerTM has no card of any kind. The proposal decides that it never will have a switch: the issuer processor owns real-time authorisation, the PAN vault, tokenisation, the scheme connections and card production, and LedgerTM is the system of record behind it. What LedgerTM needs is the seam to that processor, and it needs it before a card aggregate, an authorisation oracle or a card product can be designed, because those three compile against the names this seam declares and a contract name cannot be renamed once shipped.

Four things cross the seam, in two tempos. In real time, the processor asks whether to approve an authorisation and whether a card may be provisioned to a device wallet, and it tells us when a merchant reverses an authorisation. In request and reply, we tell the processor to create, reissue, block, control and close a card, and it hands back a credential. Daily, the processor delivers a clearing file, one line per cleared item, which is the fact the ledger posts from.

Nothing above the seam may learn the processor’s field names, and nothing on either side may carry a primary account number, because a system that stores, processes or transmits a PAN is in PCI DSS scope and a system holding a token reference, the BIN and the last four is not.

What Already Exists

Scope

This ADR covers:

Out of scope: the card aggregate, its lifecycle and controls (next ADR); the oracle’s decision logic, the hold and the per-account holds projection (the ADR after); any account type; disputes; the acquiring feed and merchant settlement; stand-in balance push; a second processor; Amex.


Decisions

1. The seam is a boundary in LedgerTM.Contracts/Cards, and nothing above it names Paymentology

Every type a later card ADR compiles against lives in LedgerTM.Contracts/Cards, named in the scheme’s vocabulary and not the processor’s. The Paymentology adapter maps in both directions and is the only code that knows a Paymentology field name: outbound, our card commands into its API; inbound, its authorisation, reversal, provisioning and clearing shapes into ours. The inbound doors therefore bind a processor-kind body chosen by the connection’s kind, and the mapper mints our ids from the processor’s references, so one authorisation has one id whichever way it arrived. A second processor is a second adapter behind the same types.

The corporate proposal set the rule for Connectivity, and ADR-694 D1 applies it to statements: a consumer above the boundary cannot tell which institution spoke. The same property here is what makes the simulator honest: it implements the same seam the adapter does, so a test that passes against the simulator exercises the code a bank will run.

2. The scheme’s authorisation is a CardAuthorisation, never an Authorisation

Authorisation is taken: it means a four-eyes approval of a change (ADR-197, ADR-780). A purchase authorisation is a different thing with a different lifecycle, and giving it the bare word would make every later event and permission key ambiguous to the reader and to the PermissionKey.For derivation. Every type here carries the Card prefix: CardAuthorisationRequest, CardAuthorisationDecision, CardAuthorisationReversal.

3. The processor is an InstitutionConnection with a ProcessorApi transport

ADR-821 D1 declares one settings row per institution we exchange with, carrying its transport, and says a feature attaches its own facet keyed by the connection. A card processor is such an institution. This ADR uses the ProcessorApi transport ADR-821 seeds, and adds a CardProcessorSettings facet keyed by the connection that carries what a processor needs beyond identity: the processor kind (Paymentology, Simulator), its environment, its base address, the credential it presents outbound (a secret reference, ADR-811), the settlement account and operating entity its clearing is a statement of, and the decision budget.

One connection per tenant, nothing shared. BINs are not here: they are rows on the card product, which the next ADR owns, and this ADR places no ceiling on how many a tenant has.

Why not a settings row of its own, unrelated to InstitutionConnection. Because ADR-821 D1 says every feature attaches a facet to the one row, and a card processor that is not an institution connection would be the second mechanism the corporate proposal refused. The cost is a dependency: ADR-821’s bite 2 lands before this ADR’s bite 2 starts. That is a design-time sequencing, recorded in the plan, not a cross-lane choreography.

Kind Simulator is valid only on a tenant whose simulation is enabled, as the capability provider decides it, which also refuses simulation in a Production environment. The settings validator refuses the kind otherwise, and the simulation facet is never a template row: it is seeded in the simulation phase beside the simulation principal, so a production tenant provisioned from the same package never carries it. The adapter for a tenant is resolved from the facet’s kind at call time, because kind is per-tenant settings and a registration cannot choose it.

4. Inbound calls authenticate as ADR-821’s machine principal, and run as the connection

The processor calls three endpoints: decide an authorisation, reverse an authorisation, decide a token provisioning. Each arrives in ADR-821’s connection frame: the gateway validated the processor’s client-credentials token, resolved its machine principal to the tenant and the connection, and minted the identity token that names both. Each dispatches a command marked IExternallyAuthenticatedCommand running as that connection. None is [PublicEndpoint]; none is ISystemCommand, because the caller is not UserId.System. The day-end lock passes the external origin (ADR-821 D4), which is what lets an authorisation be answered while day-end runs.

None is four-eyes eligible, and the derivation says so, not this ADR. ADR-821 D5 adds the marker as a fifth term: eligible iff ICommand && !ISystemCommand && !IFourEyesControlCommand && !IExternallyAuthenticatedCommand. A command carrying the marker is excluded by the rule, not by assertion.

How a client id resolves to a tenant is ADR-821 D2’s, not decided here. It was ADR-694’s gap (F-1562): a token must resolve its tenant before any tenant settings can be read. ADR-821 binds a machine principal to one tenant and one connection at platform level; this ADR assumes only that the identity token carries tenant_id and the connection, which ADR-821 D3 mints.

Permission keys are stated, not derived (ADR-766 D7): cards.decide-authorisation, cards.reverse-authorisation, cards.decide-token-provisioning, held by the connection’s identity and grantable to no human; each carries an // externally-authenticated: note in the catalogue in the style of the existing // system-internal: ones.

5. Every inbound door answers once, inside a budget, and never late

The processor’s own reference is the idempotency key, and a pending receipt is committed before anything decides. An authorisation request keys a CardAuthorisationReceipt by the processor’s authorisation reference; a token provisioning request keys a CardTokenProvisioningReceipt by its provisioning reference. The door commits the receipt as Pending in its own unit of work before it consults the decider, so two identical requests in flight serialise on that insert: the loser finds a pending receipt and waits for the outcome, up to the budget, then answers NotAnswered. A repeat of an answered receipt is answered from it without consulting the decider, whatever body the repeat carries; a repeat of a NotAnswered one is answered NotAnswered again, because the processor has already stood in for it. A body with no reference, or a value that cannot be read, is refused as a bad request and no receipt is written; a decider that throws or answers nonsense yields Declined with DecisionFailed.

A decision that misses the budget is refused, recorded, and discarded. The connection’s decision budget (default two seconds) bounds the decider through a cancellation token. At the budget the door marks the receipt NotAnswered, then replies HTTP 503 with no decision body, so the processor stands in at once rather than at its own timeout; a decision that arrives later is discarded. The decider returns a decision and writes nothing into the door’s unit of work, so a late decision cannot commit a hold the processor never saw. The receipt is what tomorrow’s reconciliation matches a stand-in clearing line against.

The request carries what the cardholder saw as well as what the account pays. The processor converts a foreign transaction to the card’s billing currency before it asks us, so CardAuthorisationRequest carries the billing amount and currency, and beside them the original amount and currency, the merchant category code, merchant name and country, channel, entry mode, whether the card was present, the card’s token reference, the processor’s authorisation reference and the transaction’s local date.

A reversal is its own receipt naming the authorisation it reverses; an unknown one is accepted. A reversal records a CardReversalReceipt keyed by the processor’s reversal reference, naming the authorisation, the amount reversed and the connection that sent it; the authorisation receipt is never rewritten. A reversal of an authorisation never seen is recorded with outcome UnknownAuthorisation and accepted, because the processor’s record outranks ours and a refusal would leave the processor holding a reversal we will meet in the clearing file anyway. A second reversal of the same authorisation is a second receipt.

The deciders are seams, ICardAuthorisationDecider and ICardTokenProvisioningDecider in LedgerTM.Contracts/Cards. This ADR ships neither: with none registered, the authorisation door declines every request with reason IssuerNotReady and the provisioning door answers Decline. The oracle ADR registers the real ones. The component tests here register scripted ones.

6. Outbound card commands go through ICardProcessor, and the reply is a credential without a PAN

ICardProcessor in LedgerTM.Contracts/Cards carries the request-and-reply crossings: create a card, reissue it (same number with a new expiry, or a new number after loss), set its status, set its controls, order plastic, close it, and fetch the clearing file for a business date. It is resolved per tenant from the facet’s kind, and every caller lives in the cards feature projects until a Contracts resolver is declared. Each card reply is a CardCredential: the processor’s token reference, the BIN, the last four, the expiry month, and the credential kind (Plastic, Virtual, DeviceToken). The adapter maps the Paymentology response and drops everything else; a PAN in a response is never deserialised into a field, because no field exists to hold it.

The controls the processor is told about are the ones it enforces at its switch (channel switches, per-transaction ceiling) so that a declined transaction never reaches us; the oracle still evaluates them, because a processor’s controls are a copy and ours are the record.

7. The clearing file becomes a clearing batch that Cards owns

The processor’s daily clearing file is a statement of what it did on our behalf, and the draft put it through the bank-statement file door. That does not hold: a bank statement demands an opening and closing balance the file does not carry, its import fires matching into Suspense, and the settlement account would carry two statements a day, its bank’s and the processor’s. So the file is received exactly as every other inbound file is (ADR-337, ADR-766 D4), and what it becomes is Cards’ own.

A common fetch step, run at day-end for every business date since the last file, asks ICardProcessor for the file and receives it into the inbound file store under purpose cards.clearing and the business date of the items it reports, skipping a date whose file already exists. A common import step resolves the day’s file, maps it through the processor’s adapter into CardClearingItems, and writes one CardClearingBatch document per connection and business date, keyed deterministically, carrying the file’s id and version, the items, and whether it was simulated. A repeat run of the same day rewrites the same batch from the same file. An empty day is an empty batch. Matching items to holds is the oracle ADR’s, and it reads the batch.

A real processor publishes the file for business date D on the morning of D+1, so the run for D+1 fetches and imports D’s file, and a Monday run fetches Saturday’s and Sunday’s, because cards clear on days the ledger does not open. The file is keyed by D, because a reconciliation that matches items to holds by business date must not read a run date.

The processor’s real-time transaction stream is not ingested here or anywhere: Paymentology itself says it cannot be used for financial reconciliation. The clearing batch is the ledger’s source.

8. The simulator is the processor, in-process, both directions, and it writes a real file

PaymentologySimulator implements ICardProcessor and is resolved as the adapter when the tenant’s facet says kind Simulator. It allocates a token reference, a BIN and a last four for every card it is asked to create, and it keeps its own record of what it authorised.

Its inbound half is four system-internal commands, dispatched by the component tests and never routed over HTTP: simulate a card’s creation, an authorisation, a reversal, a provisioning. Each refuses to run unless the tenant’s kind is Simulator and simulation is enabled, and each dispatches the real inbound command in IdentityFrame.ForConnection as the tenant’s simulation principal (ADR-821’s seed step). The demo drives the real HTTP doors with a development machine token, as the processor would.

At day-end, SimulateCardClearingStep (RequiresSimulation => true) writes the day’s clearing file from the simulator’s record into the inbound file store, named with the SIMULATED- prefix ADR-727 and ADR-766 established, for the business date being closed; the common fetch step then finds a file already present and skips, and the common import step reads it. One import path, one difference: where the bytes came from. Formatting is the adapter’s mapping run backwards, so the round trip is the mapper’s own test. On the simulation tenant the run for D imports D’s own file rather than D−1’s, because the simulator has no overnight to wait for.

The simulator never stands in for a human control (ADR-728 D3). There is none here to stand in for.

9. No PAN, enforced at build time

NoPrimaryAccountNumberTests in the architecture suite walks every type in LedgerTM.Contracts/Cards, every event and document in the cards feature projects as they arrive, and the cards fixtures and card settings templates, and fails the build on a member, parameter or property whose name has a whole segment Pan, CardNumber or PrimaryAccountNumber other than Bin and LastFour, or on a string constant of sixteen to nineteen digits that starts with a scheme digit and passes the Luhn check. Its walker takes a set of types and files, so its own test plants a failing type and proves the failure. It does not walk the whole template tree: a thousand account, deal and identity numbers there pass Luhn by construction, and they are not card numbers.

The adapter has a runtime counterpart: any inbound payload field on an explicit list of free-text fields (merchant name, device description, embossed name) carrying more than twelve digits in total, separators ignored, is dropped before mapping, and a dropped field is a warning in the request log with its field name and never its value. References, tokens and amounts are not on that list, because a processor’s references and a payment token are long numerics and the reference is the idempotency key. The guard is for the doors’ bodies only, never the clearing file, whose merchant names round-trip through the simulator.

10. cards.issuing is the feature key

A tenant that has not bought cards has no processor facet, no doors and no page. The feature catalogue binds the seven cards.* keys to cards.issuing, so a processor calling a door on a tenant without the feature is refused, not declined, and the two read endpoints check the feature themselves because the gate binds command keys. A tenant with no feature manifest has every feature on, as the platform already behaves; a manifest that omits the key has it off. Whether the tenant is simulated is the facet kind’s to say (Decision 3), guarded by the capability provider.


Contracts

Ids — CardAuthorisationId, CardReversalId, CardTokenProvisioningId (each name-derived from the processor’s reference, minted by the inbound mapper), CardTokenReference (the processor’s surrogate for a PAN), CardClearingBatchId (derived from connection and business date). InstitutionConnectionId is reused from ADR-821.

Contract types (LedgerTM.Contracts/Cards) — CardAuthorisationRequest, CardAuthorisationDecision, CardAuthorisationOutcome (Approved, PartiallyApproved, Declined), CardDeclineReason (a closed vocabulary: IssuerNotReady, CardNotActive, ControlBreached, InsufficientFunds, NoFundingAccount, DecisionFailed), CardReceiptOutcome (Pending, Approved, PartiallyApproved, Declined, NotAnswered, UnknownAuthorisation, StepUp), CardAuthorisationReversal, CardCredential, CardExpiry, CardCredentialKind, CardReissueKind, CardStatus, CardControls, CardChannel, CardEntryMode, MerchantCategoryCode, CardTokenProvisioningRequest, CardTokenProvisioningDecision (Approve, StepUp, Decline), CardClearingItem, CardClearingItemKind (Purchase, Reversal, Refund, Chargeback), CardClearingBatch, CardProcessorKind (None, Paymentology, Simulator), CardClearingPurposes, CardCreationRequest (what ICardProcessor is asked to create), and the JSON converters MerchantCategoryCodeJsonConverter and CardExpiryJsonConverter, so the code travels as "7011" and the expiry as "2029-09".

Interfaces — ICardProcessor (outbound: create, reissue, set status, set controls, order plastic, close, fetch clearing file for a business date), ICardAuthorisationDecider, ICardTokenProvisioningDecider (inbound seams, implemented by the oracle ADR).

Commands — DecideCardAuthorisationCommand, ReverseCardAuthorisationCommand, DecideCardTokenProvisioningCommand — each IExternallyAuthenticatedCommand and IConnectionScoped (ADR-821 D4, D5), permission keys cards.decide-authorisation, cards.reverse-authorisation, cards.decide-token-provisioning, of the externally authenticated kind, bound to cards.issuing. AmendCardProcessorCommand — ISettingsCommand<CardProcessorSettings>, key cards.amend-processor. SimulateCardCreationCommand, SimulateCardAuthorisationCommand, SimulateCardAuthorisationReversalCommand, SimulateCardTokenProvisioningCommand — ISystemCommand, no HTTP route, keys cards.simulate-card-creation, cards.simulate-authorisation, cards.simulate-authorisation-reversal, cards.simulate-token-provisioning (system-internal), refused unless the tenant’s kind is Simulator and simulation is enabled.

Settings — CardProcessorSettings (keyed by InstitutionConnectionId: kind, environment, base address, credential, settlement account, operating entity, decision budget).

Read documents — CardAuthorisationReceipt (keyed by CardAuthorisationId: request, outcome, reason, approved amount, decided at, connection), CardReversalReceipt (keyed by CardReversalId: the authorisation, amount, outcome, received at, connection), CardTokenProvisioningReceipt (keyed by CardTokenProvisioningId: request, outcome, reason, decided at, connection), CardClearingBatch (keyed by CardClearingBatchId: connection, business date, file id and version, simulated, items).

Events — none. This ADR has no aggregate (ADR-766 D6 precedent); the first card event is the next ADR’s.

Queries — GetCardProcessorQuery (key cards.view-processor), ListCardProcessorReceiptsQuery (key cards.list-receipts; every kind of receipt a tenant answered in a period of trading dates, newest first), ListCardClearingBatchesQuery (key cards.list-clearing; the batches by business date with their file and item count).

Consumed from LedgerTM.Infrastructure.Contracts — InstitutionConnection, ConnectionTransport, IInstitutionConnectionFacet, IInstitutionConnectionReader, IMachinePrincipalReader, IExternallyAuthenticatedCommand, IConnectionScoped, IdentityFrame.ForConnection, ICurrentConnection (ADR-821); ICapabilityProvider (moved here by this ADR from LedgerTM.Infrastructure, a namespace change); SecretReference and ISecretStore (ADR-811).

Consumed from LedgerTM.Contracts — IInboundFileStore (ADR-337), ExternalAccountId, OperatingEntityId.

Changed — FeatureCatalog gains cards.issuing, binding the seven cards.* keys; ICapabilityProvider moves to LedgerTM.Infrastructure.Contracts; ADR-821’s plan gains IInstitutionConnectionReader and IMachinePrincipalReader.ActorForAsync (additive, before it builds).

Removed — none.


Prior art

python3 scripts/adr/prior_art.py --concept "card connectivity processor authorisation hold token clearing feed simulator Paymentology" was run before the title existed. The three proposal documents matched; the cards proposal’s sections 7, 8 and 11 name every concept here.

Declared Search returned Verdict
CardAuthorisationRequest, CardAuthorisationDecision, CardAuthorisationReversal, CardAuthorisationId RequestAuthorisation, AuthorisationTargetRef (Contracts/Authorisations): four-eyes approval of a change. The bare name is taken and means something else genuinely new — a purchase authorisation, prefixed Card so it can never be read as a four-eyes record (Decision 2)
InstitutionConnectionId, InstitutionConnection, ConnectionTransport ADR-821 D1 (carved out of ADR-694 D13), Proposed, not yet built extend — one new transport value and one facet; the row is reused as is
the statement import path (ImportStatementCommand, FormatProfile) and ADR-694’s canonical delivery ADR-094 (built), ADR-694 (unbuilt) not reused — pressed at the plan grill and refused: a bank statement carries balances, fires matching and belongs to one bank; the clearing batch is Cards’ own document (Decision 7)
IExternallyAuthenticatedCommand ADR-821 D5 (carved out of ADR-694 bite 14): the marker for an authenticated non-human principal reuse unchanged — the three inbound commands carry it
CardClearingItem, CardClearingBatch, CardClearingBatchId ExpectedItem (BankStatements matching), AccountStatementLine (a line on a statement we issue), BankStatement (a statement of an account, with balances and matching) genuinely new — a processor’s cleared items for a business date, with no balances and no matching; a bank statement’s invariants and cascades are the wrong shape for it
CardCredential, CardTokenReference ExternalAccountProxy, ProxyKinds (ADR-412): a proxy address for a beneficiary genuinely new — a proxy names an account someone pays; a credential names an instrument that spends
CardControls, CardChannel, CardEntryMode HoldAuthorityBasis (Collections), ChannelParticipant (ADR-739): a person’s channel genuinely new — a card’s switches and ceilings; ADR-739’s channel is a client-channel concept and the word is qualified here as CardChannel to keep them apart
MerchantCategoryCode nothing genuinely new — ISO 18245; a standards-register row
ICardProcessor ISubmissionChannel (Payments): an outbound rail with file generation genuinely new — request and reply over an API, not a file; a rail has no reply
ICardAuthorisationDecider, ICardTokenProvisioningDecider IAuthorisationApprover (ADR-728: a Contracts seam into four-eyes) genuinely new — the same seam into a feature project shape, a different subject
CardProcessorSettings, AmendCardProcessorCommand InstitutionConnectionSettings (ADR-821), MarketDataSettings and FeedDefinition (ADR-766) extend — the facet ADR-821 D1 invites, keyed by the connection, holding what a processor needs beyond identity
PaymentologySimulator, SimulateCardClearingStep, the four Simulate* commands ADR-727 D7 return simulator, ADR-766 D4 feed simulation (DeliverFeedObservationsCommand), SimulateExchangeRateDeliveryStep, RequiresSimulation on IDayEndStep reuse the pattern — capability-gated step, real file, SIMULATED- prefix; system-internal commands with no route
CardAuthorisationReceipt, CardReversalReceipt, CardTokenProvisioningReceipt, CardReceiptOutcome, CardReversalId, CardTokenProvisioningId InboundFileDescriptor (ADR-766), the request record of scripts/ltm (ADR-793) genuinely new — an idempotency and audit record for a real-time decision; neither existing record is keyed by a caller’s reference
CardClearingItemKind ClearOpenItemCommand, OpenItemCleared, ReverseOpenItemClearingCommand (Suspense): clearing an open item in a suspense account genuinely new — clearing here is the scheme’s word for a presented card item; the enum names what kind of item was presented, not what happened to a suspense item
CardTokenProvisioningRequest, CardTokenProvisioningDecision CollateralProvisionRequest (Securities): provisioning collateral on activation genuinely new — a device wallet asking to hold a card token; the shared word is a coincidence of English
CardDeclineReason.IssuerNotReady FeatureNotReadyException (a feature switched on but unconfigured) genuinely new — a scheme-facing decline reason answered to a processor, not an exception raised to an operator; the two are mapped in the door, never merged
IInboundFileStore, InboundFileDescriptor ADR-337’s inbound file store, used by ADR-766’s feed simulation and ADR-727’s return files reuse unchanged — the clearing file is one more purpose, cards.clearing, keyed by business date
ICapabilityProvider (moved) LedgerTM.Infrastructure/Capabilities/CapabilityProvider.cs, read by DayEndStepRegistry and hosting only extend — a namespace move to Infrastructure.Contracts so a feature project may ask whether simulation is enabled
IInstitutionConnectionReader, IMachinePrincipalReader.ActorForAsync ADR-821’s IMachinePrincipalReader (ids only), InstitutionConnectionSettings in LedgerTM.Infrastructure extend — a feature project cannot read the connection row or a principal’s actor otherwise; additive to ADR-821’s plan before it builds
ExternalAccountId, OperatingEntityId (on CardProcessorSettings) ExternalAccountId (ADR-348), OperatingEntityId; the same pair ImportStatementCommand takes reuse unchanged — the settlement account the clearing is of, and the operating entity that owns it
SecretReference (on CardProcessorSettings) SecretReference, ISecretStore (ADR-811); EmailGatewaysSettings.Credential (ADR-810) reuse unchanged — the outbound credential named by purpose, never stored
NoPrimaryAccountNumberTests VocabularyRowIdTests, StringVocabularyReferenceTests (ADR-422): build-time walkers over the contract surface reuse the pattern — a Cecil walker with an allowlist of two names
IInstitutionConnectionFacet built by ADR-821 (D1): the seam a feature registers so a connection cannot be removed while the feature holds settings for it reuse — the processor settings row registers a facet; nothing new is declared

Relies on

Symbol What it does today What this ADR assumes
ICapabilityProvider Whether simulation is enabled for the tenant, refusing it in Production The facet validator and the simulate commands ask it
IInboundFileStore (ADR-337) Receives a file keyed by purpose and business date; a day-end step resolves it The fetch step receives the clearing file; the import step resolves it
IDayEndStep (its default member RequiresSimulation) A step that runs only on a simulation tenant SimulateCardClearingStep
ISettingsCommand<T> and SettingsCommandMiddleware Loads and saves a settings root around a handler AmendCardProcessorCommand
FeatureSettings (ADR-363) Absent key means off cards.issuing
InstitutionConnection (ADR-821 D1) A tenant settings row naming an institution, with its transport A card processor is one row with a ProcessorApi transport and a CardProcessorSettings facet
IdentityFrame.ForConnection (ADR-821 D4) Enters a frame whose origin is external, acting as the principal’s own actor The three inbound doors run in it; the simulate commands run the real inbound command in it as the simulation principal
ICurrentConnection (ADR-821 D4) The principal and connection of the current frame, empty after the first hop The inbound handlers read the connection from it
IExternallyAuthenticatedCommand (ADR-821 D5) Keeps a command out of four-eyes and away from any person frame The three inbound commands carry it
IMachinePrincipalReader (ADR-821, ActorForAsync) The actor and client id an enabled principal runs as The simulate commands enter the connection frame as the simulation principal
IInstitutionConnectionReader (ADR-821) Reads a connection row by id without referencing LedgerTM.Infrastructure The processor facet validates its connection

Worked example

Fixture: the za-retail tenant (package retail-bank), simulation on, cards.issuing licensed, one InstitutionConnection of kind Simulator. A counterparty and a card are created by the scenario’s Given; no card exists in seeded data yet. Amounts in ZAR.

Row Before After
Create card for the counterparty no credential CardCredential(token ref SIM-000001, BIN 400000, last four 0001, expiry 2029-09, Plastic); no field holds sixteen digits
Authorisation AUTH-1: 5,000.00 ZAR, MCC 7011, card present, scripted decider says approve no receipt receipt AUTH-1 → Approved, answered in under the two-second budget
Authorisation AUTH-1 again, same id one receipt same decision returned from the receipt; the decider is not called a second time
Two AUTH-4 requests in flight at once — one pending receipt; one decider call; both replies carry the same decision
Authorisation AUTH-2, no decider registered — Declined, IssuerNotReady; a receipt exists
Authorisation AUTH-3, decider sleeps past the budget — receipt AUTH-3 → NotAnswered written at two seconds, then HTTP 503 with no decision; the late decision is discarded
Reversal of AUTH-1 receipt Approved a reversal receipt REV-1 → AUTH-1, 5,000.00, from the connection; the authorisation receipt is unchanged
Reversal of AUTH-9, never seen no receipt reversal receipt REV-2 → AUTH-9, UnknownAuthorisation; accepted
Day-end for 29 September 2026 on the simulation tenant no clearing file SIMULATED-cards-clearing-2026-09-29.csv written into the inbound store for purpose cards.clearing, business date 29 September; the fetch step skips it, the import step writes batch sim-processor/2026-09-29 with one item AUTH-1, 5,000.00 ZAR, MCC 7011, kind Purchase, simulated
Day-end for 29 September runs again one batch the same batch rewritten from the same file version; still one item
Token provisioning PROV-1 from a device, scripted decider says step up — StepUp returned; provisioning receipt PROV-1 → StepUp; PROV-1 again is answered from it
A contract type gains string Pan build green NoPrimaryAccountNumberTests fails naming the member; a member named Company or Participant does not

Model

Generated from docs/model/model.json (ADR-773 D8): the shape the model knows today, <<new>> for what ## Contracts declares and the model does not know, relies-on for ## Relies on. Regenerate with python3 scripts/model/adr_model.py ADR-NNN --write; frozen at Shipped.

classDiagram
  class FeatureSettings {
    <<settings, relies-on>>
  }
  class Approve {
    <<new>>
  }
  class Approved {
    <<new>>
  }
  class CardNotActive {
    <<new>>
  }
  class Chargeback {
    <<new>>
  }
  class ControlBreached {
    <<new>>
  }
  class DecisionFailed {
    <<new>>
  }
  class Decline {
    <<new>>
  }
  class Declined {
    <<new>>
  }
  class InsufficientFunds {
    <<new>>
  }
  class IssuerNotReady {
    <<new>>
  }
  class NoFundingAccount {
    <<new>>
  }
  class NotAnswered {
    <<new>>
  }
  class PartiallyApproved {
    <<new>>
  }
  class Paymentology {
    <<new>>
  }
  class Pending {
    <<new>>
  }
  class Purchase {
    <<new>>
  }
  class Refund {
    <<new>>
  }
  class Reversal {
    <<new>>
  }
  class Simulator {
    <<new>>
  }
  class StepUp {
    <<new>>
  }
  class UnknownAuthorisation {
    <<new>>
  }
  class ICapabilityProvider {
    <<relies-on>>
  }
  class ICurrentConnection {
    <<relies-on>>
  }
  class IDayEndStep {
    <<relies-on>>
  }
  class IExternallyAuthenticatedCommand {
    <<relies-on>>
  }
  class IInboundFileStore {
    <<relies-on>>
  }
  class IInstitutionConnectionReader {
    <<relies-on>>
  }
  class IMachinePrincipalReader {
    <<relies-on>>
  }
  class IdentityFrame {
    <<relies-on>>
  }
  class InstitutionConnection {
    <<relies-on>>
  }
  class SettingsCommandMiddleware {
    <<relies-on>>
  }

Consequences

Positive

Negative / Trade-offs

The cheaper option, and why not

Skip the doors and the simulator: build the contract types and the clearing reader only, and let the oracle ADR add real-time later. About two sessions fewer. Refused because the oracle over batch is the proposal’s first decision, the doors are where the timeout and idempotency rules live, and a simulator that cannot drive an authorisation cannot demonstrate the product.

Neutral


Implementation Plan

Seven bites, one land. Bites, acceptance criteria, files touched, interfaces, scenarios and status live in ADR-820-plan.md.

Notes


Changed during the grill

Grilled 2026-09-30 against the code, one day after drafting. What the draft said, what it says now, and why.

Pressed and held without change: the boundary in LedgerTM.Contracts/Cards with no processor name above it; the Card prefix over the bare Authorisation; the processor as an InstitutionConnection and the sequencing on ADR-694 that follows; ADR-694 D18’s machine identity; ICardProcessor returning a credential with no field for a PAN; the build-time no-PAN test; no aggregate and no events; and the out-of-scope list, each item of which is the next ADR’s by name.

Contradiction press: 8 pairs, resolved as listed above. Run by a fresh agent given the decisions and the worked example only. Its returned block, condensed:

  1. Token provisioning has no receipt, idempotency or outcome vocabulary — resolved: its own receipt and id, same rules.
  2. UnknownAuthorisation is not in the closed outcome list — resolved: CardReceiptOutcome.
  3. Connection kind and simulation flag both decide simulation — resolved: kind decides, flag guards the validator.
  4. A receipt is inserted once, yet gains reversed at — resolved: the one permitted update, stated.
  5. Timeout path replies before it records — resolved: receipt first, then 503, like every other outcome.
  6. “One BIN set per tenant” constrains what the ADR disclaims — resolved: dropped.
  7. The clearing file is named for the run date while keyed by business date — resolved: business date, worked example corrected.
  8. Four-eyes ineligibility asserted rather than derived — resolved: the fourth term named.

Corrected after the grill, 2026-09-30: the dependency on ADR-694 was replaced by a dependency on ADR-821, the platform half carved out of ADR-694 so that neither series waits on the other. F-1562 closes inside ADR-821. The clearing reader named here was itself replaced at the plan grill by the Cards-owned clearing batch; the design-grill entries above that mention a reversal stamping its receipt or the connectivity deliveries area are history, superseded by the plan-grill record below.

Changed during the plan grill

Plan grill 2026-09-30 (phase A questions from the test author, then a fresh reader over the signatures). What the ADR said after the design grill, what it says now, and why.