This is the build plan for this decision record, bite by bite, as it was grilled and built. 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-835 — Implementation Plan

Findings for the ADR

Files touched

Bite 1 — contract types, the card type vocabulary, its page

Bite 2 — the aggregate, issue, activate, close, the read side, four-eyes

Bite 3 — the lifecycle verbs and the mirror

Bite 4 — controls, travel window, rename, the funding rule

Bite 5 — the provisioning decider, device credentials, reveal

Bite 6 — the UI, the guide, the sample card, the probe

Prior art

Re-checked 2026-10-01 after the grill: no new candidate for any declared name. Two supporting names the signatures needed, both plan-level: CardCredentialSummary (the credential as the summary shows it, with Expired and Closed) and MirrorCardToProcessorCommand (F1). The full table lives in the ADR.

Interfaces

// src/LedgerTM.Contracts/Cards/CardIds.cs
public readonly record struct CardId(string Value) : IStrongId<CardId>
{ public static CardId Generate() => new(StrongId.UrnFor<CardId>(Guid.NewGuid().ToString())); }
public readonly record struct CardTypeId(string Value) : IStrongId<CardTypeId>
{ public static CardTypeId FromKey(string key) => new(StrongId.SlugFor<CardTypeId>(key)); }

// src/LedgerTM.Contracts/Cards/CardValues.cs
public sealed record CardholderReference(string EmbossedName, CounterpartyId? Counterparty);
public sealed record CardFundingRule(IReadOnlyList<AccountId> Accounts);
public enum CardFundingShape { OrderedList, SingleAccount }
public enum DeviceProvisioningRule { Approve, StepUp }
public sealed record CardTravelWindow(DateOnly From, DateOnly To, IReadOnlyList<IsoCountryCode> Countries);   // LedgerTM.Contracts.Countries
public enum CardRevealKind { CardDetails, Pin }
public sealed record CardRevealSession(Uri HostedView, DateTimeOffset ExpiresAt);

// src/LedgerTM.Contracts/Cards/CardCredential.cs — changed (ADR-835 D6)
public sealed record CardControls(
    bool OnlineAllowed, bool InStoreAllowed, bool InStoreAbroadAllowed, bool AtmAllowed, bool ContactlessAllowed,
    decimal? PerTransactionCeiling, decimal? DailyCeiling, decimal? MonthlyCeiling);

// src/LedgerTM.Contracts/Cards/CardTokenProvisioning.cs — changed (ADR-835 D7)
public sealed record CardTokenProvisioningRequest(
    CardTokenProvisioningId Id, string ProcessorReference, CardTokenReference Token, string WalletProvider, string DeviceDescription,
    DateTimeOffset RequestedAt, CardTokenReference? DeviceTokenReference = null);
// src/LedgerTM.Contracts/Cards/ICardTokenProvisioningDecider.cs — changed (F12)
public sealed record CardTokenProvisioningAnswer(CardTokenProvisioningDecision Decision, CardDeclineReason? Reason);
public interface ICardTokenProvisioningDecider { Task<CardTokenProvisioningAnswer> DecideAsync(CardTokenProvisioningRequest request, CancellationToken ct); }
// CardDeclineReason gains DeviceTokenMissing, DeviceTokensNotAllowed, UnknownToken.

// src/LedgerTM.Contracts/Cards/ICardProcessor.cs — changed (ADR-835 D8, F9)
Task<CardRevealSession> RequestRevealAsync(CardTokenReference token, CardRevealKind kind, CancellationToken ct = default);
public sealed record CardCreationRequest(CounterpartyId Holder, string EmbossedName, CardCredentialKind Kind, CardControls Controls,
    CardId Reference, int CredentialLifeYears);   // Reference is the processor's idempotency key where it takes one
// src/LedgerTM.Contracts/Cards/CardProcessorException.cs (F10)
public sealed class CardProcessorException(string code, string message) : Exception(message) { public string Code { get; } = code; }

// src/LedgerTM.Cards/Domain/Card.Events.cs — each `: DomainEvent` with [MessageIdentity("cards.<kebab-name>")] and a row in event-identity.tsv;
// frozen once shipped; On is the tenant's trading date
[MessageIdentity("cards.card-issued")] public record CardIssued(CardId Id, CounterpartyId Owner, CardholderReference Cardholder, CardTypeId Type,
    CurrencyId BillingCurrency, string DisplayName, CardCredential Credential, CardControls Controls, CardFundingRule FundingRule, CardStatus Status, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-activated")] public record CardActivated(CardId Id, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-suspended")] public record CardSuspended(CardId Id, string Reason, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-reinstated")] public record CardReinstated(CardId Id, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-reported-lost-or-stolen")] public record CardReportedLostOrStolen(CardId Id, string Reason, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-reissued")] public record CardReissued(CardId Id, CardReissueKind Kind, CardCredential Credential, IReadOnlyList<CardTokenReference> ClosedTokens, CardStatus Status, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-closed")] public record CardClosed(CardId Id, string Reason, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-renamed")] public record CardRenamed(CardId Id, string DisplayName, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-controls-set")] public record CardControlsSet(CardId Id, CardControls Controls, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-travel-window-set")] public record CardTravelWindowSet(CardId Id, CardTravelWindow? Window, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-funding-rule-set")] public record CardFundingRuleSet(CardId Id, CardFundingRule FundingRule, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-device-credential-added")] public record CardDeviceCredentialAdded(CardId Id, CardTokenReference DeviceToken, string WalletProvider, string DeviceDescription, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-credential-removed")] public record CardCredentialRemoved(CardId Id, CardTokenReference Token, string Reason, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-details-revealed")] public record CardDetailsRevealed(CardId Id, CardRevealKind Kind, DateOnly On) : DomainEvent;   // never the address

// src/LedgerTM.Cards/Application/Commands/*.cs (F8) — every Target is ("Card", Id.Value) except IssueCard's; POST /api/cards answers { id }, 200
[PermissionKey("cards.issue-card")]
public record IssueCardCommand(CardId Id, CounterpartyId Owner, CardholderReference Cardholder, CardTypeId Type, CurrencyId BillingCurrency,
    string DisplayName, CardCredentialKind FirstCredential, CardControls? Controls, CardFundingRule FundingRule) : ICommand
{ public AuthorisationTarget Target => new("Counterparty", Owner.Value); }
// Validator refusals (400, format only): CARD_EMBOSSED_NAME_INVALID (1–26 chars of A–Z, space, hyphen, apostrophe, full stop after upper-casing;
// never empty), CARD_FIRST_CREDENTIAL_NOT_ALLOWED (a device token as first credential), CARD_DISPLAY_NAME_TOO_LONG (60; empty or
// whitespace defaults to the type's label), CARD_CONTROLS_INVALID (as for SetCardControls), CARD_TEXT_HOLDS_A_CARD_NUMBER (a display name
// or reason carrying thirteen or more digits, separators ignored). Handler refusals (422, DomainException, before the processor is
// called): CARD_ALREADY_ISSUED (the id already has a stream), CARD_TYPE_UNKNOWN, CARD_FIRST_CREDENTIAL_NOT_ALLOWED (a kind the type
// lacks), CARD_ACTIVE_CAP_REACHED (Ordered, Active and Suspended cards of the type and owner count), CARD_CARDHOLDER_MUST_BE_OWNER (a
// cardholder counterparty other than the owner on a type that forbids it; none means the owner), the funding codes CARD_FUNDING_RULE_EMPTY,
// CARD_FUNDING_RULE_DUPLICATE, CARD_FUNDING_ACCOUNT_NOT_HELD (an unknown id counts as not held), CARD_FUNDING_CURRENCY_MISMATCH,
// CARD_FUNDING_TYPE_NOT_FUNDABLE, CARD_FUNDING_SHAPE_SINGLE_ACCOUNT — each check over the whole list before the next, each naming the
// account id and, for currency, the account's currency — and CARD_PROCESSOR_REFUSED (the processor's code and message). A validator
// refusal is 400 with FluentValidation's errors body; a DomainException is 422 { code, message } (CustomExceptionHandler).
[PermissionKey("cards.activate-card")]              public record ActivateCardCommand(CardId Id) : ICommand { … }
[PermissionKey("cards.suspend-card")]               public record SuspendCardCommand(CardId Id, string Reason) : ICommand, INotFourEyesGated { … }   // protective: delay is the risk
[PermissionKey("cards.reinstate-card")]             public record ReinstateCardCommand(CardId Id) : ICommand { … }
[PermissionKey("cards.report-card-lost-or-stolen")] public record ReportCardLostOrStolenCommand(CardId Id, string Reason) : ICommand, INotFourEyesGated { … }
[PermissionKey("cards.reissue-card")]               public record ReissueCardCommand(CardId Id, CardReissueKind Kind) : ICommand { … }
[PermissionKey("cards.close-card")]                 public record CloseCardCommand(CardId Id, string Reason) : ICommand { … }
[PermissionKey("cards.rename-card")]                public record RenameCardCommand(CardId Id, string DisplayName) : ICommand { … }
[PermissionKey("cards.set-card-controls")]          public record SetCardControlsCommand(CardId Id, CardControls Controls) : ICommand { … }
[PermissionKey("cards.set-card-travel-window")]     public record SetCardTravelWindowCommand(CardId Id, CardTravelWindow? Window) : ICommand { … }
[PermissionKey("cards.set-card-funding-rule")]      public record SetCardFundingRuleCommand(CardId Id, CardFundingRule FundingRule) : ICommand { … }
[PermissionKey("cards.remove-card-credential")]     public record RemoveCardCredentialCommand(CardId Id, CardTokenReference Token, string Reason) : ICommand { … }   // cascades the mirror
[PermissionKey("cards.reveal-card")]                public record RevealCardCommand(CardId Id, CardRevealKind Kind) : ICommand, INotFourEyesGated { … }   // POST /api/cards/{id}/reveal → CardRevealSession; CardDetailsRevealed on the stream; statuses per the status table (Ordered, Active)
// Routes: POST /api/cards/{id}/activate | suspend | reinstate | report-lost-or-stolen | reissue | close | rename | controls |
// travel-window | funding-rule | credentials/remove | reveal; each takes its whole command as the body, the id in both; 2xx on success;
// an unknown id is 404. CARD_CONTROLS_INVALID (400): a negative ceiling, or a ceiling below one declared earlier in the order
// per-transaction ≤ daily ≤ monthly, gaps skipped; zero and equal ceilings are allowed; the day is the tenant's trading date, the month its
// calendar month. CARD_TRAVEL_WINDOW_INVALID (400): from after to, to before today's trading date, an empty country list, a country that
// is not alpha-2; a window already begun is fine. Rename to empty or whitespace reads back the type's label; a reason or display name
// with thirteen or more digits is CARD_TEXT_HOLDS_A_CARD_NUMBER. The status table (F19) — the aggregate's guards and DispatchedOperations.ForCard are one table:
//   activate: Ordered · suspend: Active · reinstate: Suspended · report-lost-or-stolen: Ordered, Active, Suspended
//   reissue NewNumber: Active, Suspended, LostOrStolen · reissue SameNumberNewExpiry: Active (a plastic card stays Active and its plastic is ordered)
//   close: every status but Closed · rename, set-controls, set-travel-window, set-funding-rule: Ordered, Active, Suspended
//   remove-credential: Active, Suspended · reveal: Ordered, Active
// Anything else is CARD_STATUS_FORBIDS (422; the message names the status in enum casing and the verb), refused before the processor is
// called, so a refused reissue mints nothing. After a NewNumber reissue from Active or LostOrStolen a plastic card is Ordered and a
// virtual card Active; a Suspended card stays Suspended whatever its kind (a new number does not end a review), and a plastic one still has
// its plastic ordered. Close leaves the card's tokens in the index: the oracle resolves them and declines on status, never as unknown.
// The embossing line is ASCII A–Z: an accented letter is refused, not folded.
// CARD_CREDENTIAL_NOT_REMOVABLE (422): not a device credential, or not this card's. Removing a closed device credential is a no-op; adding
// the same open device token twice is a no-op; a removed device token that provisions again is a new credential. Lifecycle, controls, reissue and remove handlers
// return DequeueEvents() plus an outgoing MirrorCardToProcessorCommand(Id); the mirror tells every open token the current status and
// controls, and calls CloseAsync for every token the card has closed. A NewNumber reissue closes the device tokens with the old number.
[PermissionKey("cards.add-card-device-credential")]   // system-internal: cascaded by the provisioning door after it commits an Approved receipt (F12)
public record AddCardDeviceCredentialCommand(CardId Id, CardTokenReference DeviceToken, string WalletProvider, string DeviceDescription) : ICommand, ISystemCommand { … }
[PermissionKey("cards.mirror-card-to-processor")]     // system-internal: cascaded after commit (F1)
public record MirrorCardToProcessorCommand(CardId Id) : ICommand, ISystemCommand { … }

// src/LedgerTM.Cards/Domain/CardTypesSettings.cs — the vocabulary (ADR-422, slug-derived)
public class CardTypesSettings : Settings { public List<CardType> Types { get; set; } = []; }
public sealed class CardType
{
    public CardTypeId Id { get => VocabularyKey.Pattern.IsMatch(Key ?? "") ? CardTypeId.FromKey(Key) : default; init { } }   // a bad key is the validator's, never a throw
    public string Key { get; set; } = "";
    public string Label { get; set; } = "";
    public List<CardCredentialKind> CredentialKinds { get; set; } = [];
    public CardControls DefaultControls { get; set; } = new(true, true, false, true, true, null, null, null);
    public CardFundingShape FundingShape { get; set; }
    public List<AccountTypeId> FundableAccountTypes { get; set; } = [];   // typed, as PropertyType.AllowedAccountTypes (F16)
    public bool CardholderMayDifferFromOwner { get; set; }
    public DeviceProvisioningRule DeviceProvisioning { get; set; } = DeviceProvisioningRule.StepUp;
    public int CredentialLifeYears { get; set; } = 3;
    public int? MaxActivePerOwner { get; set; }
}
// src/LedgerTM.Cards/Application/Settings/AmendCardTypes.cs — POST /api/settings/card-types
[PermissionKey("cards.amend-card-types")]
public record AmendCardTypesCommand(IReadOnlyList<CardType> Types) : ISettingsCommand<CardTypesSettings>;
// Validator (400, every row's faults in one answer): CARD_TYPE_KEY_INVALID (VocabularyKey.Pattern, no trimming), CARD_TYPE_KEY_DUPLICATE,
// CARD_TYPE_NO_CREDENTIAL_KIND, CARD_TYPE_NO_FIRST_CREDENTIAL_KIND (device token only), CARD_TYPE_NO_FUNDABLE_TYPE, CARD_TYPE_LIFE_OUT_OF_RANGE
// (1–5 inclusive), CARD_TYPE_CAP_BELOW_ONE. Handler (422): CARD_TYPE_IN_USE. Reviewable through SettingsApproverViewReader, as every settings command.

// src/LedgerTM.Cards/Application/Queries/*.cs (F8)
[PermissionKey("cards.view-card-types")] public record GetCardTypesQuery : IQuery<IReadOnlyList<CardType>>;          // GET /api/settings/card-types
[PermissionKey("cards.view-cards")]      public record ListCardsQuery(CounterpartyId Owner) : IQuery<IReadOnlyList<CardSummary>>;  // GET /api/counterparties/{id}/cards
[PermissionKey("cards.view-card")]       public record GetCardQuery(CardId Id) : IQuery<CardSummary?>;                // GET /api/cards/{id}
// GET /api/cards/{id}/operations — [RequiresPermission("cards.view-card")], the engine's verdicts over DispatchedOperations.ForCard (F2)

// src/LedgerTM.Contracts/Cards/CardSummary.cs — inline documents, tenant-scoped
// A device credential shows the card's primary BIN, last four and expiry. Expiry is stored; "expired" is the reader's comparison with
// the trading date (the oracle's and the UI's), never a stored flag.
public sealed record CardCredentialSummary(CardTokenReference Token, CardCredentialKind Kind, string Bin, string LastFour, CardExpiry Expiry,
    bool Closed, string? WalletProvider, string? DeviceDescription);
public sealed class CardSummary
{
    public CardId Id { get; set; } public CounterpartyId Owner { get; set; } public CardholderReference Cardholder { get; set; } = null!;
    public CardTypeId Type { get; set; } public CurrencyId BillingCurrency { get; set; } public string DisplayName { get; set; } = "";
    public CardStatus Status { get; set; } public List<CardCredentialSummary> Credentials { get; set; } = [];
    public CardControls Controls { get; set; } = null!; public CardTravelWindow? TravelWindow { get; set; }
    public CardFundingRule FundingRule { get; set; } = null!; public DateOnly IssuedOn { get; set; } public DateOnly? ClosedOn { get; set; }
}
public sealed class CardByToken { public string Id { get; set; } = ""; /* the token urn */ public CardId CardId { get; set; } }
public interface ICardByTokenReader { Task<CardId?> FindAsync(CardTokenReference token, CancellationToken ct = default); }

// src/LedgerTM.Cards/Domain/Card.cs — EventSourcedAggregate; verbs Issue, Activate, Suspend, Reinstate, ReportLostOrStolen, Reissue, Close,
// Rename, SetControls, SetTravelWindow, SetFundingRule, AddDeviceCredential, RemoveCredential; every Apply public; SelfHoldingAggregate("Card").
// src/LedgerTM.Cards/Application/Authorisations/CardApproverViewReader.cs
public sealed class CardApproverViewReader() : DocumentApproverViewReader<CardSummary, CardId>("Card", typeof(CardTokenReference));

// src/LedgerTM.Cards/Application/Doors/CardTokenProvisioningDecider.cs — implements ICardTokenProvisioningDecider (ADR-820)
// Decline(UnknownToken): no card for the token. Decline(CardNotActive): status != Active. Decline(DeviceTokensNotAllowed): the type lacks
// DeviceToken. Decline(DeviceTokenMissing): the request names no device token (F14). StepUp: the type says StepUp and no receipt on this
// tenant's trading date, later than the token's last removal from this card, already answered StepUp for this device token (F15). Approve: otherwise. StepUp and Approve carry no reason; a
// decline's reason is on the receipt, the wire reply stays ADR-820's bare decision. Reads the card and the receipts through IDocumentStore
// under ICurrentUser.TenantId; writes and publishes nothing — the door cascades the credential command after its Approved receipt
// commits, and only when the token resolves to a card, so a scripted Approve for an unknown token cascades nothing (F12).
// Wire: the Paymentology provisioning body gains `deviceTokenReference` (raw reference); the first request names it too.

// src/LedgerTM.Operations/DispatchedOperations.cs
public static IReadOnlyList<OperationDefinition> ForCard { get; }   // activate, suspend, reinstate, report-lost-or-stolen, reissue, close, rename,
                                                                     // set-controls, set-travel-window, set-funding-rule, remove-credential, reveal — statuses per ADR-835 D12

// LedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.cs (F5) — kind Paymentology; every verb answers; tenant-keyed
public sealed class StubCardProcessor : ICardProcessor
{
    public void RefuseCreation(string tenantSlug, bool refuse = true);   // CreateCardAsync throws CardProcessorException("PROCESSOR_SAYS_NO", "…")
    public void RefuseReissue(string tenantSlug, bool refuse = true);    // ReissueAsync likewise
    public IReadOnlyList<StubCardProcessorCall> Calls(string tenantSlug);
    public void NextExpiry(string tenantSlug, CardExpiry expiry);        // the next credential minted (created or reissued) for the tenant carries this expiry
    // credentials: BIN 400000, last four from a per-tenant sequence, expiry = trading date + CredentialLifeYears unless overridden;
    // reveal: https://stub.invalid/reveal/{guid}, expiring ten minutes after the tenant's clock
}
public sealed record StubCardProcessorCall(string Method, CardTokenReference? Token, object? Argument);   // Method = nameof(ICardProcessor.SetStatusAsync) etc.
// LedgerTM.Testing.Infrastructure/Cards/ScriptedDeciders.cs — the provisioning half decorates the real decider: script when set, else inner.

// LedgerTM.Tests.Component/Cards/CardsComponentFixture.cs (F5) — seeded per test tenant in InitializeAsync
// card types (CardholderMayDifferFromOwner false on all): debit (Plastic, DeviceToken; OrderedList; CallDeposit; cap 1; StepUp; 3y),
// virtual-debit (Virtual, DeviceToken; OrderedList; CallDeposit; no cap; StepUp; 3y), single-account (Virtual; SingleAccount; CallDeposit);
// a revealer actor group holding cards.reveal-card
protected Task UseStubProcessorAsync();                              // facet kind Paymentology, the shipped host's stub
protected Task<CardSummary> IssueVirtualCardAsync(CounterpartyId owner, params AccountId[] funding);   // virtual-debit, Active
protected Task<CardSummary> IssuePlasticCardAsync(CounterpartyId owner, params AccountId[] funding);   // debit, Ordered
protected Task<CardSummary> ActivateAsync(CardId id);
protected HttpClient ClientAsRevealer();
protected CounterpartyId DemoCustomer { get; }  protected AccountId ZarCallDeposit { get; }  protected AccountId SecondZarCallDeposit { get; }
protected AccountId UsdCallDeposit { get; }     protected AccountId ZarFixedDeposit { get; }   // held, not fundable
protected CounterpartyId OtherCustomer { get; } protected AccountId OtherZarCallDeposit { get; }

Bites

Bite Description Acceptance criterion Status
1 Contract types: CardId, CardTypeId, the values, the events, the command and query records, ICardByTokenReader, CardSummary, CardByToken, the three changes to ADR-820’s types; CardTypesSettings with its validator, AmendCardTypesCommand, GetCardTypesQuery, the template rows for retail-bank, the settings page A card type is a vocabulary row with a derived id Pending
2 The Card aggregate with Issue, Activate, Close; IssueCardCommand running the funding-rule check and calling the processor first; the mirror command; the two inline read models; ListCardsQuery, GetCardQuery; the approver view reader, holder and label resolvers; keys and feature binding for this bite A virtual card is issued active and a plastic card is issued ordered; Issuing a card is refused when the processor refuses; A plastic card is activated and a card is closed, and the processor hears both Pending
3 Suspend, Reinstate, ReportLostOrStolen, Reissue; every status handler cascading the mirror, which tells the current status A suspended card is reinstated and the processor hears both; A card reported lost is reissued with a new number; An expired credential leaves the card active; Two mirrors after a suspension and a reinstatement leave the processor on Active Pending
4 SetCardControls, SetCardTravelWindow, RenameCard, SetCardFundingRule reusing bite 2’s rule check; the mirror of controls A funding rule may name only accounts the owner holds, in the billing currency; A single-account card type refuses a list of two Pending
5 CardTokenProvisioningDecider answering with a reason, the door cascading AddCardDeviceCredentialCommand, RemoveCardCredentialCommand; RequestRevealAsync on the adapter and the simulator, RevealCardCommand A first device steps up and the second request adds the credential; A lost phone’s credential is removed and closed at the processor; A reveal is the processor’s hosted view and never a number Pending
6 The cards panel on the counterparty viewer, the card viewer with DispatchedOperations.ForCard driving its operations menu, the guide articles, SeedSampleCards on the simulation tenant, the probe The demo customer has one active virtual card on a fresh simulation tenant; A card’s operations menu offers only the verbs its status allows Pending

Scenarios

Feature: A card is a record of its own under the customer, and the processor is told what we decided

# Bite 1
Scenario: A card type is a vocabulary row with a derived id
  Given the za-retail tenant's card types hold a row keyed debit with funding shape ordered list and fundable type CallDeposit
  When an operator adds a row keyed "Travel Card"
  Then the add is refused naming the key
  And adding a row keyed travel-card is accepted and reads back with an id derived from that key
  # Seen at: route:/settings/card-types

# Bite 2
Scenario: A virtual card is issued active and a plastic card is issued ordered
  Given the demo customer holds a call deposit in ZAR and the tenant's processor is a stub that records every call
  When an operator issues a virtual debit card to the customer funded from the call deposit
  Then the card reads back Active with the display name given, one virtual credential showing a BIN, a last four and an expiry, and never sixteen digits
  And the token the processor returned resolves to that card
  When an operator issues a plastic debit card to the same customer
  Then the second card reads back Ordered and the processor was asked to order plastic
  And the customer's card list shows both
  And issuing a second card of the plastic type, which caps at one card per owner, is refused naming the cap
  # Seen at: route:/cards/{id}

# Bite 2
Scenario: Issuing a card is refused when the processor refuses
  Given the tenant's processor is a stub told to refuse creation
  When an operator issues a card
  Then the issue is refused naming the processor's code
  And the customer's card list is empty and no card exists under the id the request carried
  # Seen at: none

# Bite 2
Scenario: A plastic card is activated and a card is closed, and the processor hears both
  Given an ordered plastic card and an active virtual card, on the stub processor
  When an operator activates the plastic card and closes the virtual card
  Then the plastic card reads back Active and the virtual card Closed
  And the processor was told Active for the plastic card's token and asked to close the virtual card's token
  And every later command on the closed card is refused naming its status
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: A suspended card is reinstated and the processor hears both
  Given an active virtual card on the stub processor
  When an operator suspends it and then reinstates it
  Then the card reads back Active with both changes in its history
  And the processor was told Suspended and then Active, in that order
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: A card reported lost is reissued with a new number
  Given an active plastic card on the stub processor
  When the card is reported lost or stolen
  Then it reads back LostOrStolen and the processor was told LostOrStolen
  And suspending it is refused, and reissuing it with the same number is refused, and the processor was asked nothing for either
  When an operator reissues it with a new number
  Then it reads back Ordered with a new credential, its first credential closed, and the processor was asked to order plastic again and to close the old token
  And the old token no longer resolves to the card and the new one does
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: An expired credential leaves the card active
  Given the stub processor will mint the next credential with an expiry last month
  When a virtual card is issued
  Then the card reads back Active and its credential's expiry is before today's trading date
  And suspending and reinstating it are accepted as for any active card
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: Two mirrors after a suspension and a reinstatement leave the processor on Active
  Given an active virtual card on the stub processor
  When the card is suspended, then reinstated, and the card's mirror to the processor is delivered once more afterwards
  Then the processor's last word for the card's token is Active
  # Seen at: none

# Bite 4
Scenario: A funding rule may name only accounts the owner holds, in the billing currency
  Given an active debit card in ZAR on the stub processor, whose owner holds a ZAR call deposit and a USD call deposit, and another customer holds a ZAR call deposit
  When an operator sets the funding rule to the owner's ZAR call deposit then the other customer's call deposit
  Then the change is refused naming the account the owner does not hold
  When an operator sets the funding rule to the owner's USD call deposit
  Then the change is refused naming the currency
  When an operator sets the funding rule to the owner's ZAR call deposit alone
  Then the card reads back with that rule
  And setting controls to online off, in-store abroad off, a per-transaction ceiling of 2,000.00 and a daily ceiling of 5,000.00 reads back and the processor was told
  And setting a travel window of 10 to 24 October 2026 for GB and FR reads back, and clearing it reads back empty
  And renaming the card reads back and the processor received no call for it
  # Seen at: route:/cards/{id}

# Bite 4
Scenario: A single-account card type refuses a list of two
  Given a card type whose funding shape is single account
  When an operator sets a card of that type's funding rule to two accounts the owner holds
  Then the change is refused naming the shape
  # Seen at: none

# Bite 5
Scenario: A first device steps up and the second request adds the credential
  Given an active virtual card whose type steps up a first device
  When the processor asks whether the card may be provisioned to a first device, naming the device token it will mint
  Then the reply is StepUp and the card has no device credential
  When the processor asks again under a new provisioning reference for the same device token
  Then the reply is Approve
  And the card reads back with a device credential naming the wallet provider, the device and that token
  And the device token resolves to the card
  And asking to provision a suspended card is answered Decline naming the card as not active, where the active card was approved
  And a request naming no device token is answered Decline naming the missing token
  # Seen at: route:/cards/{id}

# Bite 5
Scenario: A lost phone's credential is removed and closed at the processor
  Given an active virtual card with a device credential, on the stub processor
  When an operator removes the device credential for a lost phone
  Then the card reads back with the device credential closed and its primary credential untouched
  And the device token no longer resolves to the card
  And the processor was asked to close the device token
  And removing the primary credential is refused
  # Seen at: route:/cards/{id}

# Bite 5
Scenario: A reveal is the processor's hosted view and never a number
  Given an active virtual card and a member of a group holding the reveal key, and a member without it
  When the holder requests a reveal of the card's details, and then of its PIN
  Then each answer is a hosted-view address with an expiry after the tenant's clock
  And the card's history records both reveals, by kind and date, and never the address
  And neither answer, the card's summary nor the processor's record of the card holds a run of thirteen or more digits
  And the member without the key is refused
  And a reveal of a closed card is refused
  # Seen at: route:/cards/{id}

# Bite 6
Scenario: The demo customer has one active virtual card on a fresh simulation tenant
  Given a freshly provisioned za-retail tenant with simulation enabled
  When the sample data has been seeded
  Then the demo customer's card list shows one active virtual debit card funded from their call deposit
  And the card was issued through the same command an operator uses
  # Seen at: route:/cards/{id}

# Bite 6
Scenario: A card's operations menu offers only the verbs its status allows
  Given an ordered plastic card and a suspended virtual card
  When an operator reads each card's available operations
  Then the ordered card offers activate and close but not suspend
  And the suspended card offers reinstate, report lost or stolen and close but not activate or suspend
  # Seen at: route:/cards/{id}

Scenario → test

Scenario Bite Project Class Method Probe
A card type is a vocabulary row with a derived id 1 LedgerTM.Tests.Component CardTypesSettingsTests a_card_type_key_is_kebab_case_and_its_id_derives_from_it adr-835-server-probe.ts
A virtual card is issued active and a plastic card is issued ordered 2 LedgerTM.Tests.Component IssueCardTests a_virtual_card_is_active_on_issue_and_a_plastic_card_is_ordered adr-835-server-probe.ts
Issuing a card is refused when the processor refuses 2 LedgerTM.Tests.Component IssueCardTests a_processor_refusal_refuses_the_issue_and_leaves_no_card — refusal, nothing to look at
A plastic card is activated and a card is closed, and the processor hears both 2 LedgerTM.Tests.Component IssueCardTests activating_and_closing_reach_the_processor_and_a_closed_card_refuses_everything adr-835-server-probe.ts
A suspended card is reinstated and the processor hears both 3 LedgerTM.Tests.Component CardLifecycleTests a_suspended_card_is_reinstated_and_the_processor_hears_both adr-835-server-probe.ts
A card reported lost is reissued with a new number 3 LedgerTM.Tests.Component CardLifecycleTests a_lost_card_is_reissued_with_a_new_number_and_the_old_token_leaves_the_index adr-835-server-probe.ts
An expired credential leaves the card active 3 LedgerTM.Tests.Component CardLifecycleTests an_expired_credential_leaves_the_card_active adr-835-server-probe.ts
Two mirrors after a suspension and a reinstatement leave the processor on Active 3 LedgerTM.Tests.Component CardLifecycleTests a_second_mirror_after_reinstatement_tells_the_processor_active — a stub’s call log, no surface
A funding rule may name only accounts the owner holds, in the billing currency 4 LedgerTM.Tests.Component CardControlsAndFundingTests a_funding_rule_names_only_held_accounts_in_the_billing_currency adr-835-server-probe.ts
A single-account card type refuses a list of two 4 LedgerTM.Tests.Component CardControlsAndFundingTests a_single_account_type_refuses_two_funding_accounts — refusal, nothing to look at
A first device steps up and the second request adds the credential 5 LedgerTM.Tests.Component CardDeviceCredentialTests a_first_device_steps_up_and_the_second_request_adds_the_credential adr-835-server-probe.ts
A lost phone’s credential is removed and closed at the processor 5 LedgerTM.Tests.Component CardDeviceCredentialTests removing_a_device_credential_closes_it_at_the_processor adr-835-server-probe.ts
A reveal is the processor’s hosted view and never a number 5 LedgerTM.Tests.Component CardRevealTests a_reveal_is_a_hosted_view_address_and_never_a_number adr-835-server-probe.ts
The demo customer has one active virtual card on a fresh simulation tenant 6 LedgerTM.Tests.Component SampleCardsSeedTests the_demo_customer_has_one_active_virtual_card_after_seeding adr-835-server-probe.ts
A card’s operations menu offers only the verbs its status allows 6 LedgerTM.Tests.Component CardOperationsTests the_operations_offered_follow_the_cards_status adr-835-server-probe.ts

UI-surface sweep

Swept src/ui-apps/bank and src/ui-apps/shared for cards., CardControls, ListCards, GetCard, CardSummary, /cards/, card-types, AbroadAllowed: no hits outside ADR-820’s card-processor files and the generated unions (cards in positions-cards.tsx, staged-change-list.tsx and matrix-shape.ts is the position-card and approval-card sense, unrelated). What this ADR adds or changes:

No existing UI surface is deleted, renamed or repointed.

Footprint

Feature projects touched: 8 — LedgerTM.Cards, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Operations, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, ui-apps

Contracts types: 74 named, 63 changed by this ADR

Files reading each changed type: 63 types

Domain events touched: 14 — CardActivated, CardClosed, CardControlsSet, CardCredentialRemoved, CardDetailsRevealed, CardDeviceCredentialAdded, CardFundingRuleSet, CardIssued, CardReinstated, CardReissued, CardRenamed, CardReportedLostOrStolen, CardSuspended, CardTravelWindowSet Aggregates touched: 0

Methods at CRAP 30+ in changed files: 0 (unit coverage, cached at main d0ec6de46) Permission keys to add: 22 — activate-card, add-card-device-credential, amend-card-types, close-card, i, i-system, issue-card, reinstate-card, reissue-card, remove-card-credential, rename-card, report-card-lost-or-stolen, set-card-controls, set-card-funding-rule, set-card-travel-window, suspend-card, card-reveal-session, card-summary, get-card-query, get-card-types-query, list-cards-query, reveal-card

Warnings

At land: 108 files touched, 99 predicted, 36 unplanned. LedgerTM.Tests.Architecture/CardVocabularyTests.cs, LedgerTM.Tests.Architecture/MessageRoutingCatalogTests.cs, LedgerTM.Tests.Architecture/SessionAcquisitionConfinementTests.cs, LedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv, LedgerTM.Tests.Architecture/TenantSettingsFolderTests.cs, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Component/Cards/CardClearingTests.cs, LedgerTM.Tests.Component/Cards/CardOperationsTests.cs, LedgerTM.Tests.Unit/Cards/PaymentologyInboundMapperTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Api/Diagnostics/CardNumberRedaction.cs, src/LedgerTM.Cards/Application/Commands/CardHandling.cs, src/LedgerTM.Cards/Application/Commands/CloseCard.cs, src/LedgerTM.Cards/Application/Commands/ReinstateCard.cs, src/LedgerTM.Cards/Application/Commands/ReissueCard.cs, src/LedgerTM.Cards/Application/Commands/RemoveCardCredential.cs, src/LedgerTM.Cards/Application/Commands/RenameCard.cs, src/LedgerTM.Cards/Application/Commands/ReportCardLostOrStolen.cs, src/LedgerTM.Cards/Application/Commands/SetCardFundingRule.cs, src/LedgerTM.Cards/Application/Commands/SetCardTravelWindow.cs, src/LedgerTM.Cards/Application/Processor/CardProcessorCalls.cs, src/LedgerTM.Cards/Application/Processor/CardProcessorClient.cs, src/LedgerTM.Cards/Application/Queries/GetCard.cs, src/LedgerTM.Cards/Domain/CardRules.cs, src/LedgerTM.Cards/Simulation/SimulateCommands.cs, src/LedgerTM.Seeding.Provisioning/PackageModel.cs, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/investment-house/CounterpartyTypesSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/microlender/CounterpartyTypesSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/personal-lender/CounterpartyTypesSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/CounterpartyTypesSettings.yaml, src/ui-apps/bank/src/__tests__/features/counterparties/shared/counterparty-rail-groups.test.ts, src/ui-apps/bank/src/features/cards/card-operation-dialogs.tsx, src/ui-apps/bank/src/features/cards/hooks/card-types.ts, src/ui-apps/bank/src/features/cards/hooks/cards.ts, src/ui-apps/bank/src/features/counterparties/shared/counterparty-viewer.tsx, tools/LedgerTM.ShapeSnapshot/SyntheticInstanceFactory.cs

Land batches

One land — the whole ADR. Reseed at the land (reseed: true: the card type rows, the permission keys, the sample card). The oracle ADR and the current account ADR land after this one, each in its own lane; those are dependencies between lands, not a reason to split this.

Notes

Changed during the plan grill

Phase A (27 questions), the plan grill (15 points) and phase B (six authors), 2026-10-01. The ADR’s own section carries the decision-level changes; what the plan changed on its own: tests run on a tenant-keyed stub processor with a call log (the simulator shows nothing of the mirror); commands, queries and events moved into LedgerTM.Cards; CardCreationRequest carries the card id and the credential life; the mirror is a cascaded system command; the funding check is bite 2’s; the operations endpoint, its project reference and its seam-test allowlist are listed; the feature-catalog path corrected; NextExpiry on the stub; CardProcessorException added; F4, F6, F7 and F8 withdrawn or corrected as F12–F17 say. Phase B: refusal statuses as the host maps them (F18), one status table with a parity test (F19), the travel window not mirrored (F20), IsoCountryCode’s JSON converter (F21), a re-sent issue refused before the processor is called, the free-text card-number guard, duplicate funding entries refused, three more vocabulary refusals, the fixture’s extra accounts, RefuseReissue, the seed’s skips, and the door cascading only for a known card.

Landing notes

(appended by /ltm-partition and by lanes)