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-844 — Implementation Plan
Findings for the ADR
- F1 — the hold must carry the channel. A limit scoped to a channel filters spend by channel
(D1), and ADR-836’s
CardHoldrecords the merchant category but not the channel. The hold gainsChannelbeside the category groups D1 stamps. Proceeded on that; it is the ADR’s call only in that D1 names the stamp and not the channel. - F2 — every bite depends on ADR-836, which is In Progress on the cards lane: its decider,
hold document, hold projection and expiry step are rewritten or extended here. Nothing starts on
main. ADR-837 (also on that lane) addsFacilityAvailableto availability; this ADR does not touch it. - F3 — closed-list calls taken on the operator’s standing instruction:
CardActoris frozen onCardSuspended; two members,BankandClientChannel.- The five control types and
CardControlBoundslive inLedgerTM.Contracts/Cards, becauseCardType(Cards) and the channel commands (Cards) both carry them and a test must build them. MerchantCategoryGroupIdis slug-derived (ADR-422), its validator applyingVocabularyKey.Pattern.- The eight channel commands are new commands in Cards, not the bank’s commands catalogued, as the ADR’s prior-art verdict says.
- F4 — the lapsed-card step is wind-down and carries no feature key (ADR-363 D3).
- F5 — supporting types added at phase A:
CardSpendChannel,CardLimitUse(Contracts),GetCardLimitUseQuery, and two channel commands; the ADR’s Contracts and Prior art carry them. - F6 — ADR-836 lane defect, F-1807: the decider loads every
CardHoldin the tenant on every tap, before the status check. This ADR rewrites it to load the card’s own holds after the rules. - F7 — ADR-836 lane defect, F-1806 (P1): the decider reads spend before
FetchForWriting, in another session, so two racing taps both pass a limit. Bite 2 reorders it. - F8 — ADR-836 lane cost, F-1808:
CardHoldReductionsReaderloads every open hold in the tenant for each availability call. - F9 — eight commands, two reads, ten catalog rows, everywhere.
Files touched
Bite 1 — contracts, settings and validation
src/LedgerTM.Contracts/Cards/CardSpendControls.cs— new;MerchantCategoryGroupId,CardSpendPeriod,CardSpendScope,CardSpendLimit,CardRuleMode,CardCategoryRule,CardCountryRule,CardControlBounds,CardActorsrc/LedgerTM.Contracts/Cards/CardCredential.cs—CardControlsloses three ceilings, gainsLimits,Categories,Countriessrc/LedgerTM.Contracts/Cards/CardAuthorisation.cs—CardDeclineReasongainsMerchantCategoryNotAllowed,FrequencyExceeded,CardLapsedsrc/LedgerTM.Contracts/Cards/CardReceipts.cs—CardAuthorisationReceipt.DeclinedRule;CardAuthorisation.cs—CardAuthorisationDecision.DeclinedRulesrc/LedgerTM.Contracts/Cards/CardSummary.cs,src/LedgerTM.Cards/Application/Projections/CardSummaryProjection.cs—ValidUntil,SuspendedBysrc/LedgerTM.Cards/Simulation/SimulateCommands.cs—CardSimulation.OpenControlsin the new shapeLedgerTM.Tests.Component/Cards/CardsComponentFixture.cs—PlaceHoldAsyncwith the channel and groups; a corporate type, the category groups, the cards tenant’s channel agreement and entitlement over a ZAR pooled account,client-channelandcards.corporateon;CardControlsAndFundingTests.cs— the limit shapesrc/LedgerTM.Contracts/Cards/CardHold.cs(ADR-836’s) —Channel,CategoryGroupssrc/LedgerTM.Cards/Domain/CardRules.cs—CardControlsRulegeneralised over limits, rules and bounds (CARD_CONTROLS_INVALID,CARD_CONTROLS_OUT_OF_BOUNDS)src/LedgerTM.Cards/Domain/CardTypesSettings.cs—CardType.Bounds,IssuableFromChannel;DefaultControlsin the new shapesrc/LedgerTM.Cards/Domain/MerchantCategoryGroupsSettings.cs— newsrc/LedgerTM.Cards/Domain/Card.cs,Card.Events.cs—CardStatusTablegainsSetValidUntil;ValidUntilonCardIssued,SetValidUntil,CardValidUntilSet;CardHoldPlacedandPlaceHoldgain the channel and groups;Suspend(reason, by, on),CardSuspended.By;Reinstaterefuses a channel act on a bank suspension (CARD_SUSPENDED_BY_BANK)src/LedgerTM.Cards/Application/Settings/AmendMerchantCategoryGroups.cs— new; command, handler, validator (MERCHANT_CATEGORY_GROUP_IN_USE, keys fixed, ranges not inverted, a group never empty)src/LedgerTM.Cards/Application/Queries/GetMerchantCategoryGroups.cs— newsrc/LedgerTM.Cards/Application/Settings/AmendCardTypes.cs— bounds validated; a channel-issuable type bounds an all-spend monthsrc/LedgerTM.Cards/Application/Commands/IssueCard.cs,SetCardControls.cs,SuspendCard.cs— the new shape;ValidUntil; bounds checked only on added or raised limitssrc/LedgerTM.Cards/Application/Commands/SetCardValidUntil.cs— newsrc/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/MerchantCategoryGroupsSettings.yaml— new; the nine seeded groups;CardTypesSettings.yaml— limits in the new shape, bounds, a corporate type issuable from the channel always blocking gamblingsrc/LedgerTM.Seeding.Provisioning/PackageModel.cs—MerchantCategoryGroupEntry;CardTypeEntrygains bounds, issuable from the channel, default controls;PackageImporter.cs,PackageExporter.cs— both waysLedgerTM.Tests.Component/Seeding/PackageImporterFolderTests.cs— the real template’s corporate type blocks gambling and bounds a monthsrc/LedgerTM.Cards/Application/Doors/CardAuthorisationDecider.cs(ADR-836’s) — the three-ceiling check becomes all-spend limits (mechanical; bite 2 does the rest);Application/Processor/PaymentologyOutboundMapper.cs— the limits’ mirrorLedgerTM.Tests.Component/Cards/CardAuthorisationDeciderTests.cs(ADR-836’s),IssueCardTests.cs,LedgerTM.Tests.Unit/Cards/PaymentologyOutboundMapperTests.cs— the limit shape;src/ui-apps/bank/ui-review/adr-uat/flows/adr-835-server-probe.ts— the limit shapesrc/ui-apps/bank/src/features/cards/card-viewer.tsx,card-operation-dialogs.tsx,card-issue-dialog.tsx— read and send the limit list so the UI builds (bite 5 adds the editor)src/LedgerTM.Cards/Bootstrapper.cs—Schema.For<CardHold>().Index(x => x.Card)src/LedgerTM.Cards/Application/Commands/ReinstateCard.cs—Reinstate(by, on);LedgerTM.Tests.Component/Cards/CardClearingPostTests.cs— positionalCardHoldPlacedsrc/LedgerTM.Infrastructure.Contracts/AccessControl/PermissionCatalog.cs— every key;src/LedgerTM.Infrastructure.Contracts/Features/FeatureCatalog.cs—cards.corporatesrc/LedgerTM.Hosting/event-identity.tsv—CardValidUntilSet;LedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv— the changed recordsLedgerTM.Tests.Component/Cards/CardSpendControlsSettingsTests.cs— new
Bite 2 — the oracle
src/LedgerTM.Cards/Application/Doors/CardAuthorisationDecider.cs(ADR-836’s) — the total order; valid-until; type block; category, domestic and country rules; limits by scope and period, amount then count; the type’s bounds as limits;DeclinedRulesrc/LedgerTM.Cards/Application/Projections/CardHoldProjection.cs(ADR-836’s) — the stamp and the channelsrc/LedgerTM.Cards/Application/Processor/PaymentologyOutboundMapper.cs— 57, 65, 54 for the new reasons; the three ceilings’ mirror becomes the limits’src/LedgerTM.Cards/Application/Doors/(ADR-836’s authorisation door) — copiesDeclinedRuleto the receiptLedgerTM.Tests.Unit/Cards/PaymentologyOutboundMapperTests.cs— rows for 57, 65 and 54src/LedgerTM.Cards/Domain/CardSpend.cs— new; the one spend computation;CardSpendChannels.Classifysrc/LedgerTM.Cards/Application/Queries/GetCardLimitUse.cs,ListCardAuthorisations.cs— new;ListCardProcessorReceipts.cs—DeclinedRuleon the rowLedgerTM.Tests.Component/Cards/CardSpendControlsDecisionTests.cs— new
Bite 3 — the lapsed card
src/LedgerTM.Cards/Application/DayEnd/CloseLapsedCardsStep.cs— new; step 46 PreIncrement, no feature key;CloseLapsedCardsCommand;Bootstrapper.cs— registers the stepsrc/LedgerTM.Operations/DispatchedOperations.cs,LedgerTM.Tests.Unit/Cards/CardOperationGuardParityTests.cs—set-card-valid-untilon the menu for Ordered, Active and SuspendedLedgerTM.Tests.Component/Cards/CardLapseTests.cs— new
Bite 4 — the corporate administrator
src/LedgerTM.Cards/Application/Corporate/CorporateCardCommands.cs— new; the eight channel commands, validators, handlers dispatching to the card’s verbs;CORPORATE_CARD_ACCOUNT_MISMATCH,CARD_TYPE_NOT_CHANNEL_ISSUABLEsrc/LedgerTM.Cards/Application/Corporate/CorporateCardQueries.cs— new;ListCorporateCardsQuery,GetCorporateCardQuerywith spend usedsrc/LedgerTM.ClientChannel/Application/ChannelCatalog.cs— ten rows by keyLedgerTM.Tests.Component/Cards/CorporateCardChannelTests.cs— new
Bite 5 — the screens, the guide, the probe
src/ui-apps/bank/src/features/cards/card-viewer.tsx,card-operation-dialogs.tsx,card-issue-dialog.tsx— the limits editor with use this period, the rules, valid-until, who suspended, the declining rule on authorisations;card-controls-editor.tsx— newsrc/ui-apps/bank/src/features/entity-types/card-types.tsx— bounds, issuable from the channel;merchant-category-groups.tsx— new;settings-class-map.ts,category-taxonomy.ts,app.tsx(routesettings/merchant-category-groups)docs/guide/features/card-spend-controls.md,merchant-category-groups.md,corporate-cards.md— newsrc/ui-apps/bank/ui-review/adr-uat/flows/adr-844-server-probe.ts— newdocs/standards/README.md— ISO 8583 row gains 65; ISO 18245 row names the groupsLedgerTM.Tests.Component/Cards/CardSpendControlsReadTests.cs— new
Prior art
Unchanged since the grill, apart from F1’s CardHold.Channel and the supporting
CorporateCardView, CardLimitUse read records, which carry no decision.
Interfaces
// LedgerTM.Contracts/Cards/CardSpendControls.cs — new (D1–D4)
public readonly record struct MerchantCategoryGroupId(string Value) : IStrongId<MerchantCategoryGroupId> { public static MerchantCategoryGroupId FromKey(string key) => StrongId.SlugFor<MerchantCategoryGroupId>(key); … }
public enum CardSpendPeriod { Transaction, Day, Month, Life }
public enum CardSpendChannel { Atm, InStore, Online } // one classifier, CardSpendChannels.Classify(CardAuthorisationRequest), used by the switch check and the stamp: ATM; card present; card not present
public sealed record CardSpendScope(CardSpendChannel? Channel = null, MerchantCategoryGroupId? CategoryGroup = null) { public static CardSpendScope AllSpend { get; } = new(); } // at most one set
public sealed record CardSpendLimit(CardSpendScope Scope, CardSpendPeriod Period, decimal? Amount, int? Count); // billing currency
public enum CardRuleMode { AllowOnly, Block }
public sealed record CardCategoryRule(CardRuleMode Mode, IReadOnlyList<MerchantCategoryGroupId> Groups);
public sealed record CardCountryRule(CardRuleMode Mode, IReadOnlyList<IsoCountryCode> Countries);
public sealed record CardControlBounds(IReadOnlyList<CardSpendLimit> MaxLimits, IReadOnlyList<MerchantCategoryGroupId> AlwaysBlocked);
public enum CardActor { Bank, ClientChannel } // stored as a string; bank handlers pass Bank, channel handlers ClientChannel
public sealed record CardLimitUse(CardSpendScope Scope, CardSpendPeriod Period, CardSpendLimit? Limit, CardSpendLimit? Bound, decimal Spent, int Count, DateOnly PeriodFrom);
// one row per scope and period where the card's limit or the type's bound is set; Bound = the tightest type bound capping the row at the oracle (its own, a longer period of its scope, or all spend at its period or longer), shown when lower than the card's limit or the card has none; PeriodFrom: trading date (Transaction and Day), month start, issue date; a Transaction row reports Spent 0, Count 0
public sealed record CardAuthorisationLine(CardAuthorisationId Id, DateTimeOffset ReceivedAt, decimal Amount, string MerchantName, CardReceiptOutcome Outcome, CardDeclineReason? Reason, string? DeclinedRule);
// LedgerTM.Contracts/Cards/CardCredential.cs — changed (D1, D3)
public sealed record CardControls(bool OnlineAllowed, bool InStoreAllowed, bool InStoreAbroadAllowed, bool AtmAllowed, bool ContactlessAllowed,
IReadOnlyList<CardSpendLimit> Limits, CardCategoryRule? Categories = null, CardCountryRule? Countries = null);
// CARD_CONTROLS_INVALID: an allow-only rule with an empty list; amount < 0; count < 1; neither amount nor count; scope with both members; a group id the tenant does not define; scope+period twice; a count on Transaction;
// within one scope Transaction <= Day <= Month <= Life for amounts and for counts. Cross-scope combinations are accepted and bind at the oracle.
// CARD_CONTROLS_OUT_OF_BOUNDS, only for what an edit adds or raises: a limit above any type bound that would cap it at the oracle (its scope's bound for its period or a longer one, or an
// all-spend bound for its period or a longer one); an allow-only category rule gaining a group the type always blocks. Removing a limit is never raising. AmendCardTypes validates
// DefaultControls against Bounds the same way, and refuses a type IssuableFromChannel with no all-spend month bound carrying an amount (CARD_TYPE_BOUNDS_INVALID). A type's own faults — duplicate scope and period, negative,
// a count on a Transaction bound, a group the tenant does not define in Bounds, AlwaysBlocked or DefaultControls — are CARD_TYPE_BOUNDS_INVALID. "In use" = any card not Closed.
// LedgerTM.Contracts/Cards/CardAuthorisation.cs, CardReceipts.cs, CardSummary.cs, CardHold.cs — changed (D1, D5, D6, D7)
// CardDeclineReason gains MerchantCategoryNotAllowed (57), FrequencyExceeded (65), CardLapsed (54).
// CardAuthorisationDecision gains trailing string? DeclinedRule = null; CardAuthorisationReceipt gains trailing string? DeclinedRule = null; the door copies it.
// CardSummary gains DateOnly? ValidUntil and CardActor? SuspendedBy. CardHold gains CardSpendChannel Channel and List<MerchantCategoryGroupId> CategoryGroups, copied from the event.
// CardProcessorReceiptRow (ListCardProcessorReceipts) gains string? DeclinedRule.
// LedgerTM.Cards/Domain/CardTypesSettings.cs, MerchantCategoryGroupsSettings.cs — changed / new (D2, D4)
public sealed class CardType { …; public CardControlBounds Bounds { get; set; } = new([], []); public bool IssuableFromChannel { get; set; } }
public class MerchantCategoryGroupsSettings : Settings { public List<MerchantCategoryGroup> Groups { get; set; } = []; }
public sealed class MerchantCategoryGroup { public MerchantCategoryGroupId Id { get => Regex.IsMatch(Key, VocabularyKey.Pattern) ? MerchantCategoryGroupId.FromKey(Key) : default; init { } } public string Key { get; set; } = ""; public string Label { get; set; } = ""; public List<MerchantCategoryRange> Ranges { get; set; } = []; }
public sealed record MerchantCategoryRange(MerchantCategoryCode From, MerchantCategoryCode To); // inclusive
[PermissionKey("cards.amend-merchant-category-groups")] public record AmendMerchantCategoryGroupsCommand(IReadOnlyList<MerchantCategoryGroup> Groups) : ISettingsCommand<MerchantCategoryGroupsSettings>; // POST /api/settings/merchant-category-groups, whole list
[PermissionKey("cards.view-merchant-category-groups")] public record GetMerchantCategoryGroupsQuery : IQuery<IReadOnlyList<MerchantCategoryGroup>>; // GET same route
// The key is the identity: a changed key is a removed group and an added one. MERCHANT_CATEGORY_GROUP_IN_USE (async validator, only when a key is removed: the card types document through
// ISettingsProvider — Bounds and DefaultControls — then open CardSummary documents prefiltered by MatchesSql on the group id and confirmed in memory; closed cards do not count),
// MERCHANT_CATEGORY_GROUP_KEY_INVALID (naming the key), MERCHANT_CATEGORY_GROUP_DUPLICATE, MERCHANT_CATEGORY_GROUP_EMPTY, MERCHANT_CATEGORY_RANGE_INVERTED; keys VocabularyKey.Pattern. The handler stays void Handle(cmd, settings).
// Seeded: cash 6010–6011; quasi-cash 4829, 6050–6051, 6540; gambling 7800–7802, 7995; airlines 3000–3350, 4511; lodging 3501–3999, 7011; car-hire 3351–3500, 7512; fuel 5541–5542, 5983;
// dining 5811–5814; groceries 5411, 5422, 5451, 5462, 5499. PackageModel gains MerchantCategoryGroupEntry; CardTypeEntry gains Bounds, IssuableFromChannel, DefaultControls.
// LedgerTM.Cards/Domain/Card.cs, Card.Events.cs — changed (D1, D5, D6)
// Issue(…, DateOnly? validUntil, …); CardIssued gains trailing DateOnly? ValidUntil = null; a ValidUntil before the issue date → CARD_VALID_UNTIL_IN_PAST.
public void SetValidUntil(DateOnly? validUntil, DateOnly on); // CardVerb.SetValidUntil: Ordered, Active, Suspended (a Live verb, as SetControls); otherwise CARD_STATUS_FORBIDS; before on → CARD_VALID_UNTIL_IN_PAST; null clears
// → [MessageIdentity("cards.card-valid-until-set")] CardValidUntilSet(CardId Id, DateOnly? ValidUntil, DateOnly On)
public void Suspend(string reason, CardActor by, DateOnly on); // CardSuspended(CardId Id, string Reason, CardActor By, DateOnly On)
public void Reinstate(CardActor by, DateOnly on); // ClientChannel on a Bank suspension → CARD_SUSPENDED_BY_BANK; the bank may lift either; SuspendedBy cleared
// PlaceHold — ADR-836's signature on its branch, (authorisation, account, amount, currency, mcc, merchantName, on, expiresOn), plus CardSpendChannel channel and
// IReadOnlyList<MerchantCategoryGroupId> categoryGroups last and required; CardHoldPlaced likewise gains Channel and CategoryGroups last, no defaults.
// IssueCardCommand gains trailing DateOnly? ValidUntil = null.
[PermissionKey("cards.set-card-valid-until")] public record SetCardValidUntilCommand(CardId Id, DateOnly? ValidUntil) : ICommand { Target ("Card", Id) } // POST /api/cards/{id}/valid-until
// LedgerTM.Cards/Domain/CardSpend.cs — new (bite 2): the one spend computation
public static class CardSpend { public static IReadOnlyList<CardLimitUse> Use(CardControls controls, CardControlBounds bounds, IReadOnlyList<CardHold> holds, DateOnly tradingDate, DateOnly issuedOn); }
// Σ (OriginalAmount − Reversed) over holds placed in the period whose stamp matches the scope; count = those not fully reversed. The decider, GetCardLimitUse and CorporateCardView call it.
// LedgerTM.Cards/Application/Doors/CardAuthorisationDecider.cs — changed (D3)
// Spend = Σ (CardHold.OriginalAmount — the approved billing amount — less Reversed); a limit breach is final (no partial approval up to the remainder); a bound equal to the card's
// limit names the card's limit (a bound binds only when strictly lower); contactless with both switches off names the in-store switch; an empty country on a card-present tap is
// foreign to the domestic check (ADR-836); the authorisations read breaks ties by receipt id.
// Unit of work: open the write session, FetchForWriting<Card>, then load that card's CardHold documents in the same session (Where(h => h.Card == id), PlacedOn >= the earliest period start
// unless a life limit or bound applies), decide, append; a ConcurrencyException reruns once (RetryingOnce) against fresh spend.
// Order: token, status, valid-until (trading date > ValidUntil → CardLapsed), credential, currency, channel, type's AlwaysBlocked, card's category rule, domestic-country check (skipped under an AllowOnly
// country rule), card's country rule, then limits by period (Transaction, Day, Month, Life), within a period by scope (all spend, channel, category groups in the tenant's list order), amount
// before count; the type's bounds bind as limits, the effective limit the lower; funding. A merchant country "" is absent; a category in no group and an absent country pass Block, fail AllowOnly.
// DeclinedRule, invariant culture, ASCII space as thousands separator, '.' decimal, group by key: "{period}, {scope}, {amount}" or "{period}, {scope}, count {n}", with ", the card type's bound"
// when the bound binds; period: transaction | day | month | life; scope: all spend | channel atm|in store|online | category {key}. Others: "category {key}, blocked by the card type",
// "category {key}, blocked", "category {mcc}, not in the allow list", "country {cc}, blocked", "country {cc|unknown}, not in the allow list", "in store abroad, not allowed",
// "channel {online|in store|atm|contactless}, switched off", "valid until {yyyy-MM-dd}, lapsed". Every other decline carries null.
// Worked example: step 4 "transaction, all spend, 2 000.00"; 5 "category gambling, blocked by the card type"; 7 "country US, not in the allow list"; 9 "life, all spend, count 1".
// LedgerTM.Cards/Application/Queries/GetCardLimitUse.cs, ListCardAuthorisations.cs — new (D6, D7; bite 2)
[PermissionKey("cards.view-card-limit-use")] public record GetCardLimitUseQuery(CardId Id) : IQuery<IReadOnlyList<CardLimitUse>>; // GET /api/cards/{id}/limit-use
[PermissionKey("cards.list-card-authorisations")] public record ListCardAuthorisationsQuery(CardId Id, int Take = 50) : IQuery<IReadOnlyList<CardAuthorisationLine>>; // GET /api/cards/{id}/authorisations; resolved through the card's tokens, newest first
// LedgerTM.Cards/Application/DayEnd/CloseLapsedCardsStep.cs — new (D5)
public sealed class CloseLapsedCardsStep(IMessageBus bus) : IDayEndStep // "cards.close-lapsed-cards", 46, PreIncrement, NonCritical, FeatureKey null; after clearing (44) and expiry (45); [ReplaySafe]
[PermissionKey("cards.close-lapsed-cards")] public record CloseLapsedCardsCommand(TenantId Tenant, DateOnly TradingDate) : ICommand, ISystemCommand { Target ("Cards", Tenant) }
// ValidUntil < TradingDate and no open hold → Close("valid-until passed"), mirrored to the processor; the day-end whose clearing or expiry frees the last hold closes it.
// LedgerTM.Cards/Application/Corporate/CorporateCardCommands.cs — new (D6); bus only, no endpoints (as every ADR-695 channel operation); each IChannelOperation, ICommand
[PermissionKey("cards.issue-corporate-card")] public record IssueCorporateCardCommand(CardId Id, AccountId FundingAccount, CardholderReference Cardholder, CardTypeId Type, string DisplayName, CardCredentialKind FirstCredential, CardControls Controls, DateOnly? ValidUntil); // Target ("Account", FundingAccount); returns CardId
[PermissionKey("cards.set-corporate-card-controls")] public record SetCorporateCardControlsCommand(CardId Id, AccountId FundingAccount, CardControls Controls); // whole-list replace
[PermissionKey("cards.set-corporate-card-valid-until")] public record SetCorporateCardValidUntilCommand(CardId Id, AccountId FundingAccount, DateOnly? ValidUntil); // null clears
[PermissionKey("cards.activate-corporate-card")] public record ActivateCorporateCardCommand(CardId Id, AccountId FundingAccount);
[PermissionKey("cards.suspend-corporate-card")] public record SuspendCorporateCardCommand(CardId Id, AccountId FundingAccount, string Reason) : INotFourEyesGated; // a stolen card is never held for approval
[PermissionKey("cards.reinstate-corporate-card")] public record ReinstateCorporateCardCommand(CardId Id, AccountId FundingAccount);
[PermissionKey("cards.close-corporate-card")] public record CloseCorporateCardCommand(CardId Id, AccountId FundingAccount, string Reason);
[PermissionKey("cards.reveal-corporate-card")] public record RevealCorporateCardCommand(CardId Id, AccountId FundingAccount) : INotFourEyesGated; // CardRevealKind.CardDetails; non-virtual → CARD_REVEAL_VIRTUAL_ONLY
// All but issue Target ("Card", Id). ResolveChannelScope: Asserts([FundingAccount], amount) — issue and set: the card's own monthly exposure = min(all-spend Month, all-spend Day × 31, all-spend Life);
// controls with none of the three → CORPORATE_CARD_EXPOSURE_UNBOUNDED (validator); the rest: null. The command's own figure is never below the effective one, so an error refuses, never leaks.
// Handlers: IChannelUserDirectory.IsActingOnChannelAsync false → CORPORATE_CARD_CHANNEL_ONLY; the owner is the funding account's single owner (IAccountOwningPartiesReader; not exactly one → refused);
// the type IssuableFromChannel (CARD_TYPE_NOT_CHANNEL_ISSUABLE); FundingAccount is the card's whole funding rule (CORPORATE_CARD_ACCOUNT_MISMATCH); the card's verbs directly with
// CardActor.ClientChannel, never the bank's commands; every change mirrored to the processor as the bank verbs do.
// cards.corporate binds every command but suspend and close, which are run-down (ADR-363 D3); unlicensed, both reads are refused. A card of a type not issuable from the channel →
// CARD_TYPE_NOT_CHANNEL_ISSUABLE on every operation; a count-only month is unbounded; the asserted account is ScopedAccount.Owned; reveal returns CardRevealSession.
// LedgerTM.Cards/Application/Corporate/CorporateCardQueries.cs — new (D6); IChannelOperation, Asserts([FundingAccount], null); each checks cards.corporate itself
public sealed record CorporateCardView(CardId Id, string DisplayName, CardholderReference Cardholder, CardStatus Status, CardActor? SuspendedBy, AccountId FundingAccount, CardControls Controls, DateOnly? ValidUntil,
IReadOnlyList<CardLimitUse> Use, IReadOnlyList<CardAuthorisationLine> RecentAuthorisations /* last 20 */);
[PermissionKey("cards.list-corporate-cards")] public record ListCorporateCardsQuery(AccountId FundingAccount) : IQuery<IReadOnlyList<CorporateCardView>>;
[PermissionKey("cards.view-corporate-card")] public record GetCorporateCardQuery(CardId Id, AccountId FundingAccount) : IQuery<CorporateCardView?>;
// An account outside the entitlement is refused by the gate (NotEntitled); a card outside the account or not of an IssuableFromChannel type reads empty or null. ChannelCatalog: ten rows by key.
Bites
| Bite | Description | Acceptance criterion | Status |
|---|---|---|---|
| 1 | Contracts and settings: the limit, rule and bounds types, the controls’ new shape and its validation everywhere it is built, category groups as settings with their seeded rows through the package model, the decline reasons, the receipt’s rule, valid-until, who suspended | a card’s controls are set and refused by the limit rules and the type’s bounds; the bank maintains its category groups | Done |
| 2 | The oracle and its reads: the card locked before spend is read, one spend computation, the total order, category and country rules, limits by scope and period with amount and count, the type’s bounds and always-blocked groups, the hold’s group stamp, CardLapsed, the declining rule, limit use and the card’s authorisations |
each rule declines with its reason and names itself; a clerk reads a card’s limit use and its authorisations | Done |
| 3 | The lapsed card: the valid-until verb and the day-end close | a virtual card lapses and closes once its holds are gone | Done |
| 4 | The corporate administrator: the eight channel operations, the two reads, the monthly exposure against the entitlement ceiling, who suspended, cards.corporate |
an administrator issues and caps a staff card within the entitlement’s ceiling | Done |
| 5 | The screens and the guide: the controls editor, the category groups page, the card type’s bounds, the declining rule on the authorisation list | a clerk sets a card’s limits and rules and reads why a tap was declined | Done |
Scenarios
Feature: a bank and a corporate's administrator control where and how much a card may spend
# Bite 1
Scenario: a card's controls are set and refused by the limit rules and the type's bounds
Given a card on a type bounding a month at 50 000.00
When a clerk sets 2 000.00 a transaction, 5 000.00 a day and 20 000.00 a month, and a cash limit of 2 000.00 a day with a count of 3
Then the card reads those limits
And a day limit above the month's, two limits on one scope and period, a count on a transaction limit, and a month of 60 000.00 are each refused
# Seen at: route:/cards/{id}
# Bite 1
Scenario: the bank maintains its category groups
Given the template's nine groups and a card blocking cash
When a clerk adds a group for toll roads, removes an unused group, and tries to remove cash
Then the groups read back with the new one and without the unused one, and removing cash is refused while the card names it
# Seen at: route:/settings/merchant-category-groups
# Bite 2
Scenario: each rule declines with its reason and names itself
Given the worked example's card for J SMITH
When the worked example's taps arrive
Then each is approved or declined with the worked example's reason and declining rule
# Seen at: route:/cards/{id}
# Bite 2
Scenario: a clerk reads a card's limit use and its authorisations
Given the worked example's card after its taps on 2026-11-02
When a clerk reads the card's limit use and its authorisations
Then the day and month read 2 300.00 spent over 2 taps against 5 000.00 and 20 000.00, and each declined tap reads its reason and rule
# Seen at: route:/cards/{id}
# Bite 3
Scenario: a virtual card lapses and closes once its holds are gone
Given the worked example's virtual supplier card with an open hold of 11 500.00
When a tap arrives on 2026-12-01, and day-end runs before and after the hold clears
Then the tap is declined as lapsed, the card stays open while the hold is open, and closes in the day-end that clears it
And a clerk moving its valid-until later before it closes revives it
# Seen at: route:/cards/{id}
# Bite 4
Scenario: an administrator issues and caps a staff card within the entitlement's ceiling
Given Thandi's entitlement with a ceiling of 25 000.00 over the pooled account
When she issues J SMITH a card, then raises its month to 30 000.00, then suspends it
Then the card is issued and suspended, the raise is refused, and a card funded by another account cannot be touched
And a card the bank suspended cannot be reinstated by her, and she can open the hosted view of a virtual card's details
And she activates a plastic card on arrival, moves a card's valid-until, closes a card, and reads her cards with each limit's use and recent declines
# Seen at: route:/cards/{id}
# Bite 5
Scenario: a clerk sets a card's limits and rules and reads why a tap was declined
Given the worked example's card
When a clerk opens it, edits its limits and category rule, and opens a declined authorisation
Then the editor shows each limit with its use this period, and the authorisation shows its declining rule
# Seen at: route:/cards/{id}
Scenario → test
| Scenario | Bite | Project | Class | Method | Probe |
|---|---|---|---|---|---|
| a card’s controls are set and refused by the limit rules and the type’s bounds | 1 | LedgerTM.Tests.Component |
CardSpendControlsSettingsTests |
a_cards_controls_are_set_and_refused_by_the_limit_rules_and_the_types_bounds |
adr-844-server-probe.ts |
| the bank maintains its category groups | 1 | LedgerTM.Tests.Component |
CardSpendControlsSettingsTests |
the_bank_maintains_its_category_groups_and_cannot_remove_one_in_use |
adr-844-server-probe.ts |
| each rule declines with its reason and names itself | 2 | LedgerTM.Tests.Component |
CardSpendControlsDecisionTests |
each_rule_declines_with_its_reason_and_names_itself |
adr-844-server-probe.ts |
| a clerk reads a card’s limit use and its authorisations | 2 | LedgerTM.Tests.Component |
CardSpendControlsDecisionTests |
a_clerk_reads_a_cards_limit_use_and_its_authorisations |
adr-844-server-probe.ts |
| a virtual card lapses and closes once its holds are gone | 3 | LedgerTM.Tests.Component |
CardLapseTests |
a_virtual_card_lapses_and_closes_once_its_holds_are_gone |
adr-844-server-probe.ts |
| an administrator issues and caps a staff card within the entitlement’s ceiling | 4 | LedgerTM.Tests.Component |
CorporateCardChannelTests |
an_administrator_issues_and_caps_a_staff_card_within_the_entitlements_ceiling |
adr-844-server-probe.ts |
| a clerk sets a card’s limits and rules and reads why a tap was declined | 5 | LedgerTM.Tests.Component |
CardSpendControlsReadTests |
the_card_and_authorisation_reads_carry_each_limits_use_and_the_declining_rule |
adr-844-server-probe.ts |
UI-surface sweep
Swept src/ui-apps/bank/src for CardControls, perTransactionCeiling, dailyCeiling,
monthlyCeiling, controls, card-types, cards., suspend:
features/cards/card-viewer.tsx,card-operation-dialogs.tsx,card-issue-dialog.tsx— read and write the three ceilings; all move to the limits editor.features/entity-types/card-types.tsx,features/cards/hooks/card-types.ts—DefaultControlsin the old shape; gain bounds and issuable-from-channel.features/settings/settings-class-map.ts,category-taxonomy.ts,app.tsx— the new settings page.src/ui-apps/shared/generated/permissions.generated.ts— every new key andcards.corporate.- No client-channel UI exists (ADR scope).
Footprint
Feature projects touched: 8 — LedgerTM.Cards, LedgerTM.ClientChannel, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Operations, LedgerTM.Seeding.Provisioning, ui-apps
LedgerTM.Cards— 21 changed, 0 newLedgerTM.ClientChannel— 1 changed, 0 newLedgerTM.Contracts— 6 changed, 0 newLedgerTM.Hosting— 1 changed, 0 newLedgerTM.Infrastructure.Contracts— 2 changed, 0 newLedgerTM.Operations— 1 changed, 0 newLedgerTM.Seeding.Provisioning— 2 changed, 0 newui-apps— 4 changed, 0 new Files: 81 named, 66 code, 2 config
Contracts types: 48 named, 41 changed by this ADR
ICommand— fan-in 38, referenced (LedgerTM.Accounts, LedgerTM.Attachments, LedgerTM.Audit, LedgerTM.Authorisation, LedgerTM.BankStatements, LedgerTM.Books, LedgerTM.Cards, LedgerTM.ClientChannel, LedgerTM.Collections, LedgerTM.Compliance, LedgerTM.Contracts, LedgerTM.Correspondence, LedgerTM.Counterparties, LedgerTM.Currencies, LedgerTM.DayEnd, LedgerTM.DocumentTemplates, LedgerTM.Identifications, LedgerTM.Import, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Limits, LedgerTM.Metering, LedgerTM.OperatingEntities, LedgerTM.Payments, LedgerTM.Pricing, LedgerTM.[redacted], LedgerTM.Regulatory, LedgerTM.Securities, LedgerTM.Seeding.[redacted].Conversion, LedgerTM.ServiceEnrolment, LedgerTM.Signing, LedgerTM.Statements, LedgerTM.Structures, LedgerTM.Suspense, LedgerTM.Tasks, LedgerTM.Tax, LedgerTM.Warehouse, ui-apps)ISystemCommand— fan-in 31, referenced (LedgerTM.Accounts, LedgerTM.BankStatements, LedgerTM.Books, LedgerTM.Cards, LedgerTM.ClientChannel, LedgerTM.Collections, LedgerTM.Compliance, LedgerTM.Contracts, LedgerTM.Correspondence, LedgerTM.Counterparties, LedgerTM.DayEnd, LedgerTM.Identifications, LedgerTM.Identity, LedgerTM.Import, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Limits, LedgerTM.Metering, LedgerTM.OperatingEntities, LedgerTM.Payments, LedgerTM.Pricing, LedgerTM.Regulatory, LedgerTM.Scheduling, LedgerTM.Seeding.[redacted].Conversion, LedgerTM.ServiceEnrolment, LedgerTM.Signing, LedgerTM.Statements, LedgerTM.Suspense, LedgerTM.Tasks, LedgerTM.Tax, LedgerTM.Warehouse)Bank— fan-in 13, referenced (LedgerTM.Accounts, LedgerTM.BankStatements, LedgerTM.Counterparties, LedgerTM.Infrastructure.Contracts, LedgerTM.Payments, LedgerTM.Regulatory, LedgerTM.Seeding, LedgerTM.Seeding.Corporate.Samples, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, LedgerTM.Statements, _creditplus, ui-apps)CardSummary— fan-in 4, changed (LedgerTM.Cards, LedgerTM.Contracts, LedgerTM.Seeding.ZaRetail.Samples, ui-apps)IChannelOperation— fan-in 4, referenced (LedgerTM.ClientChannel, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Payments)CardControls— fan-in 3, changed (LedgerTM.Cards, LedgerTM.Contracts, ui-apps)CardSuspended— fan-in 3, referenced (LedgerTM.Cards, LedgerTM.Hosting, LedgerTM.Operations)CardType— fan-in 3, changed (LedgerTM.Cards, LedgerTM.Seeding.Provisioning, ui-apps)IssueCardCommand— fan-in 3, changed (LedgerTM.Cards, LedgerTM.Seeding.ZaRetail.Samples, ui-apps)CardAuthorisationDecision— fan-in 2, changed (LedgerTM.Cards, LedgerTM.Contracts)CardAuthorisationReceipt— fan-in 2, changed (LedgerTM.Cards, LedgerTM.Contracts)CardControlsSet— fan-in 2, referenced (LedgerTM.Cards, LedgerTM.Hosting)CardDeclineReason— fan-in 2, changed (LedgerTM.Cards, LedgerTM.Contracts)CardIssued— fan-in 2, referenced (LedgerTM.Cards, LedgerTM.Hosting)ActivateCorporateCardCommand— fan-in 0, changedAmendMerchantCategoryGroupsCommand— fan-in 0, changedCardActor— fan-in 0, changedCardAuthorisationLine— fan-in 0, changedCardCategoryRule— fan-in 0, changedCardControlBounds— fan-in 0, changedCardCountryRule— fan-in 0, changedCardLimitUse— fan-in 0, changedCardRuleMode— fan-in 0, changedCardSpend— fan-in 0, changedCardSpendChannel— fan-in 0, changedCardSpendLimit— fan-in 0, changedCardSpendPeriod— fan-in 0, changedCardSpendScope— fan-in 0, changedCloseCorporateCardCommand— fan-in 0, changedCloseLapsedCardsCommand— fan-in 0, changedCloseLapsedCardsStep— fan-in 0, changedCorporateCardView— fan-in 0, changedGetCardLimitUseQuery— fan-in 0, changedGetCorporateCardQuery— fan-in 0, changedGetMerchantCategoryGroupsQuery— fan-in 0, changedIssueCorporateCardCommand— fan-in 0, changedListCardAuthorisationsQuery— fan-in 0, changedListCorporateCardsQuery— fan-in 0, changedMerchantCategoryGroup— fan-in 0, changedMerchantCategoryGroupId— fan-in 0, changedMerchantCategoryGroupsSettings— fan-in 0, changedMerchantCategoryRange— fan-in 0, changedReinstateCorporateCardCommand— fan-in 0, changedRevealCorporateCardCommand— fan-in 0, changedSetCardValidUntilCommand— fan-in 0, changedSetCorporateCardControlsCommand— fan-in 0, changedSetCorporateCardValidUntilCommand— fan-in 0, changedSuspendCorporateCardCommand— fan-in 0, changed
Files reading each changed type: 41 types
ActivateCorporateCardCommand— 0 filesAmendMerchantCategoryGroupsCommand— 0 filesCardActor— 0 filesCardAuthorisationDecision— 11 filesLedgerTM.Testing.Infrastructure/Cards/ScriptedDeciders.csLedgerTM.Tests.Architecture/CardVocabularyTests.csLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardAuthorisationDoorTests.csLedgerTM.Tests.Component/Cards/CardClearingTests.csLedgerTM.Tests.Component/Cards/CardProcessorReceiptsTests.csLedgerTM.Tests.Component/Cards/CardReversalDoorTests.cssrc/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cssrc/LedgerTM.Cards/Simulation/SimulateCommands.cssrc/LedgerTM.Contracts/Cards/CardAuthorisation.cssrc/LedgerTM.Contracts/Cards/ICardAuthorisationDecider.cs
CardAuthorisationLine— 0 filesCardAuthorisationReceipt— 9 filesLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardAuthorisationDoorTests.csLedgerTM.Tests.Component/Cards/CardProcessorClientTests.csLedgerTM.Tests.Component/Cards/CardReversalDoorTests.cssrc/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cssrc/LedgerTM.Cards/Application/Doors/ReverseCardAuthorisation.cssrc/LedgerTM.Cards/Application/Queries/ListCardProcessorReceipts.cssrc/LedgerTM.Cards/Bootstrapper.cssrc/LedgerTM.Contracts/Cards/CardReceipts.cs
CardCategoryRule— 0 filesCardControlBounds— 0 filesCardControls— 23 filesLedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.csLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.csLedgerTM.Tests.Component/Cards/CardTypesSettingsTests.csLedgerTM.Tests.Component/Cards/IssueCardTests.csLedgerTM.Tests.Unit/Cards/PaymentologyOutboundMapperTests.cssrc/LedgerTM.Cards/Application/Commands/IssueCard.cssrc/LedgerTM.Cards/Application/Commands/SetCardControls.cssrc/LedgerTM.Cards/Application/Processor/CardProcessorClient.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyOutboundMapper.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyProcessor.cssrc/LedgerTM.Cards/Domain/Card.Events.cssrc/LedgerTM.Cards/Domain/Card.cssrc/LedgerTM.Cards/Domain/CardRules.cssrc/LedgerTM.Cards/Domain/CardTypesSettings.cssrc/LedgerTM.Cards/Simulation/PaymentologySimulator.cssrc/LedgerTM.Cards/Simulation/SimulateCommands.cssrc/LedgerTM.Cards/Simulation/SimulatorCard.cssrc/LedgerTM.Contracts/Cards/CardCredential.cssrc/LedgerTM.Contracts/Cards/CardSummary.cssrc/LedgerTM.Contracts/Cards/ICardProcessor.cssrc/ui-apps/bank/src/features/cards/card-operation-dialogs.tsxsrc/ui-apps/bank/src/lib/api.ts
CardCountryRule— 0 filesCardDeclineReason— 15 filesLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardAuthorisationDoorTests.csLedgerTM.Tests.Component/Cards/CardClearingTests.csLedgerTM.Tests.Component/Cards/CardDeviceCredentialTests.csLedgerTM.Tests.Component/Cards/CardProcessorReceiptsTests.csLedgerTM.Tests.Component/Cards/CardTokenProvisioningDoorTests.csLedgerTM.Tests.Unit/Cards/PaymentologyOutboundMapperTests.cssrc/LedgerTM.Cards/Application/Doors/CardTokenProvisioningDecider.cssrc/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cssrc/LedgerTM.Cards/Application/Doors/DecideCardTokenProvisioning.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyOutboundMapper.cssrc/LedgerTM.Cards/Application/Queries/ListCardProcessorReceipts.cssrc/LedgerTM.Contracts/Cards/CardAuthorisation.cssrc/LedgerTM.Contracts/Cards/CardReceipts.cssrc/LedgerTM.Contracts/Cards/ICardTokenProvisioningDecider.cs
CardLimitUse— 0 filesCardRuleMode— 0 filesCardSpend— 0 filesCardSpendChannel— 0 filesCardSpendLimit— 0 filesCardSpendPeriod— 0 filesCardSpendScope— 0 filesCardSummary— 26 filesLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.csLedgerTM.Tests.Component/Cards/CardDeviceCredentialTests.csLedgerTM.Tests.Component/Cards/CardLifecycleTests.csLedgerTM.Tests.Component/Cards/CardsComponentFixture.csLedgerTM.Tests.Component/Cards/IssueCardTests.csLedgerTM.Tests.Component/Seeding/SampleCardsSeedTests.cssrc/LedgerTM.Cards/Application/Authorisations/CardApproverViewReader.cssrc/LedgerTM.Cards/Application/Commands/CardHandling.cssrc/LedgerTM.Cards/Application/Commands/IssueCard.cssrc/LedgerTM.Cards/Application/Commands/MirrorCardToProcessor.cssrc/LedgerTM.Cards/Application/Commands/RevealCard.cssrc/LedgerTM.Cards/Application/Doors/CardTokenProvisioningDecider.cssrc/LedgerTM.Cards/Application/Operations/CardOperationAvailabilityEndpoint.cssrc/LedgerTM.Cards/Application/Projections/CardSummaryProjection.cssrc/LedgerTM.Cards/Application/Queries/GetCard.cssrc/LedgerTM.Cards/Application/Queries/ListCards.cssrc/LedgerTM.Cards/Application/Settings/AmendCardTypes.cssrc/LedgerTM.Cards/Bootstrapper.cssrc/LedgerTM.Contracts/Cards/CardSummary.cssrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSampleCards.cssrc/ui-apps/bank/src/features/cards/card-operation-dialogs.tsxsrc/ui-apps/bank/src/features/cards/card-viewer.tsxsrc/ui-apps/bank/src/features/cards/hooks/cards.tssrc/ui-apps/bank/src/features/counterparties/persons/panels/person-cards-panel.tsxsrc/ui-apps/bank/src/lib/api.ts
CardType— 12 filesLedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.csLedgerTM.Tests.Component/Cards/CardTypesSettingsTests.csLedgerTM.Tests.Component/Cards/CardsComponentFixture.csLedgerTM.Tests.Component/Cards/IssueCardTests.cssrc/LedgerTM.Cards/Application/Queries/GetCardTypes.cssrc/LedgerTM.Cards/Application/Settings/AmendCardTypes.cssrc/LedgerTM.Cards/Domain/CardFundingRuleCheck.cssrc/LedgerTM.Cards/Domain/CardTypesSettings.cssrc/LedgerTM.Seeding.Provisioning/PackageImporter.cssrc/ui-apps/bank/src/features/cards/hooks/card-types.tssrc/ui-apps/bank/src/features/entity-types/card-types.tsxsrc/ui-apps/bank/src/lib/api.ts
CloseCorporateCardCommand— 0 filesCloseLapsedCardsCommand— 0 filesCloseLapsedCardsStep— 0 filesCorporateCardView— 0 filesGetCardLimitUseQuery— 0 filesGetCorporateCardQuery— 0 filesGetMerchantCategoryGroupsQuery— 0 filesIssueCardCommand— 10 filesLedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.csLedgerTM.Tests.Component/Cards/CardDeviceCredentialTests.csLedgerTM.Tests.Component/Cards/CardsComponentFixture.csLedgerTM.Tests.Component/Cards/IssueCardTests.csLedgerTM.Tests.Component/Seeding/SampleCardsSeedTests.cssrc/LedgerTM.Cards/Application/Commands/IssueCard.cssrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSampleCards.cssrc/ui-apps/bank/src/features/cards/card-issue-dialog.tsxsrc/ui-apps/bank/src/features/cards/hooks/cards.tssrc/ui-apps/bank/src/lib/api.ts
IssueCorporateCardCommand— 0 filesListCardAuthorisationsQuery— 0 filesListCorporateCardsQuery— 0 filesMerchantCategoryGroup— 0 filesMerchantCategoryGroupId— 0 filesMerchantCategoryGroupsSettings— 0 filesMerchantCategoryRange— 0 filesReinstateCorporateCardCommand— 0 filesRevealCorporateCardCommand— 0 filesSetCardValidUntilCommand— 0 filesSetCorporateCardControlsCommand— 0 filesSetCorporateCardValidUntilCommand— 0 filesSuspendCorporateCardCommand— 0 files Implementations of changed types: 6CardSummary— 4:CardApproverViewReader(src/LedgerTM.Cards/Application/Authorisations/CardApproverViewReader.cs),CardSummaryProjection(src/LedgerTM.Cards/Application/Projections/CardSummaryProjection.cs),GetCardQuery(src/LedgerTM.Cards/Application/Queries/GetCard.cs),ListCardsQuery(src/LedgerTM.Cards/Application/Queries/ListCards.cs)CardType— 1:GetCardTypesQuery(src/LedgerTM.Cards/Application/Queries/GetCardTypes.cs)IssueCardCommand— 1:IssueCardCommandValidator(src/LedgerTM.Cards/Application/Commands/IssueCard.cs) Files reading a touched file by path: 6Bootstrapper.cs—src/LedgerTM.Accounts/Application/Commands/ProcessDayEnd.cs,src/LedgerTM.Books/Application/Commands/PostTransaction.cs,src/LedgerTM.Infrastructure.Contracts/LedgerTM.Infrastructure.Contracts.csproj,src/_creditplus/docs/superpowers/plans/2026-03-14-rook-phase1-foundation.md,src/_creditplus/docs/superpowers/plans/2026-03-15-multitenant-bootstrap.md,src/_creditplus/docs/superpowers/plans/2026-03-15-phase2-multitenancy-auth.md,src/_creditplus/docs/superpowers/plans/2026-03-15-phase3-ui-commands-batch.md,src/_creditplus/docs/superpowers/plans/2026-03-17-data-init-saga-workers.md,src/_creditplus/docs/superpowers/plans/2026-03-20-ui-polish-crud-validation.md,src/_creditplus/docs/superpowers/specs/2026-03-14-rook-option1-design.md,src/_creditplus/docs/superpowers/specs/2026-03-15-multitenant-bootstrap-design.md,src/_creditplus/docs/superpowers/specs/2026-03-17-data-init-saga-workers-design.mdCardSimulation.OpenControls—src/LedgerTM.Cards/Simulation/SimulateCommands.csCardTypesSettings.yaml—LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt,src/LedgerTM.Seeding.Provisioning/PackageImporter.cs,src/LedgerTM.Seeding.Provisioning/PackageModel.csPackageExporter.cs—LedgerTM.Tests.Component/Currencies/ExchangeRateProvisioningTests.csapp.tsx—src/ui-apps/bank/index.html,src/ui-apps/bank/src/__tests__/features/account-types/account-types-tabs.test.tsx,src/ui-apps/bank/src/__tests__/features/settings/settings-list-tabs.test.tsx,src/ui-apps/bank/src/__tests__/route-guard-helpers.ts,src/ui-apps/bank/src/__tests__/route-tree.ts,src/ui-apps/bank/src/__tests__/theme-boot-script.test.ts,src/ui-apps/bank/src/__tests__/window-location-guard.test.ts,src/ui-apps/bank/src/components/layout/rail-nav.tsx,src/ui-apps/bank/src/features/counterparties/flyout-config.ts,src/ui-apps/bank/src/lib/api.ts,src/ui-apps/bank/ui-review/targets/resolve-targets.ts,src/ui-apps/shared/lib/theme-key.tsdocs/standards/README.md—LedgerTM.Tests.Component/Seeding/StandardsRegisterPinTests.cs,LedgerTM.Tests.Unit/Payments/ExternalAccounts/ExternalAccountProxyTests.cs,src/LedgerTM.Payments/ExternalAccounts/Domain/ProxyKinds.cs,src/LedgerTM.Payments/Submissions/Channels/Bacs/Format/BacsAdviceFileFormat.cs,src/LedgerTM.Payments/Submissions/Channels/Bacs/Format/Standard18FileFormat.cs,src/LedgerTM.Payments/Submissions/Channels/Bacs/README.md,src/LedgerTM.Payments/Submissions/Channels/BankservAfrica/BankservAfricaReturnReasons.cs,src/LedgerTM.Payments/Submissions/Channels/BankservAfrica/Format/BankservAfricaReturnFileFormat.cs
Domain events touched: 1 — CardValidUntilSet Aggregates touched: 1
Card—src/LedgerTM.Cards/Domain/Card.cs
Methods at CRAP 30+ in changed files: 0 (unit coverage at main f43a82cc0)
Permission keys to add: 18 — activate-corporate-card, amend-merchant-category-groups, close-corporate-card, close-lapsed-cards, i, i-system, issue-corporate-card, reinstate-corporate-card, reveal-corporate-card, set-card-valid-until, set-corporate-card-controls, set-corporate-card-valid-until, suspend-corporate-card, get-card-limit-use-query, get-corporate-card-query, get-merchant-category-groups-query, list-card-authorisations-query, list-corporate-cards-query
Warnings
CardSummaryis changed and read by 4 projects — name the seam in the ADR.CardTypeis changed and read by 3 projects — name the seam in the ADR.CardControlsis changed and read by 3 projects — name the seam in the ADR.IssueCardCommandis changed and read by 3 projects — name the seam in the ADR.- A domain event is touched — set
reseed: trueand say so in the plan. - 8 feature projects touched — say why this is not two ADRs.
At land: 87 files touched, 81 predicted, 38 unplanned. LedgerTM.Testing.Infrastructure/Cards/CardTestLimits.cs, LedgerTM.Tests.Architecture/CardVocabularyTests.cs, LedgerTM.Tests.Architecture/TenantSettingsFolderTests.cs, LedgerTM.Tests.Architecture/UnitOfWorkTests.cs, LedgerTM.Tests.Architecture/commands-whose-caller-reads-the-record.txt, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Component/Accounts/AccountsComponentFixture.cs, LedgerTM.Tests.Component/Cards/CardAuthorisationRaceTests.cs, LedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.cs, LedgerTM.Tests.Component/Cards/CardOperationsTests.cs, LedgerTM.Tests.Component/Cards/IssueCardTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Cards/Application/Commands/CardHandling.cs, src/LedgerTM.Cards/Application/Commands/MirrorCardToProcessor.cs, src/LedgerTM.Cards/Application/Commands/SetCardControls.cs, src/LedgerTM.Cards/Application/Commands/SuspendCard.cs, src/LedgerTM.Cards/Application/Corporate/CorporateCardHandlers.cs, src/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cs, src/LedgerTM.Cards/Application/Processor/PaymentologyInboundMapper.cs, src/LedgerTM.Cards/Application/Queries/ListCardAuthorisations.cs, src/LedgerTM.Cards/Application/Queries/ListCardProcessorReceipts.cs, src/LedgerTM.Cards/Domain/Card.Events.cs, src/LedgerTM.Seeding.Provisioning/CardSpendControlsPackage.cs, src/LedgerTM.Seeding.Provisioning/PackageExporter.cs, src/LedgerTM.Seeding.Provisioning/PackageImporter.cs, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/CardTypesSettings.yaml, src/ui-apps/bank/src/__tests__/standard-table-rowhref-guard.test.ts, src/ui-apps/bank/src/app.tsx, src/ui-apps/bank/src/features/cards/card-controls-editor.tsx, src/ui-apps/bank/src/features/cards/card-issue-dialog.tsx, src/ui-apps/bank/src/features/cards/card-operation-dialogs.tsx, src/ui-apps/bank/src/features/cards/hooks/cards.ts, src/ui-apps/bank/src/features/cards/hooks/merchant-category-groups.ts, src/ui-apps/bank/src/features/entity-types/merchant-category-groups.tsx, src/ui-apps/bank/src/features/operations/dispatched-homes.ts, src/ui-apps/bank/src/features/settings/category-taxonomy.ts, src/ui-apps/bank/src/features/settings/settings-class-map.ts, src/ui-apps/bank/src/lib/api.ts
Land batches
One land, the whole ADR; reseed: true (the controls’ shape). It starts after ADR-836 lands.
Notes
- Fixtures. ADR-836’s card and oracle fixtures; the corporate administrator from ADR-695’s channel fixtures (an agreement, a channel user, an entitlement with a ceiling).
- The guide articles name ISO 18245 and ISO 8583, and lift their numbers from
CardSpendControlsDecisionTests. - The three-ceiling
CardControlsis built by ADR-836’s lane tests,docs/adr/ADR-835-tests/bite-2.cs.txtandbite-4.cs.txt(shipped asCardControlsAndFundingTests),docs/adr/ADR-837-tests/bite-4.cs.txtand the simulator’sOpenControls; all move to the limit shape in bite 1. - Channel tests act over the bus inside
ChannelScopeFrame.Enter, as ADR-695’s do; the probe covers the bank’s half only. - Hold retention: a card’s hold documents are kept while it is open; any retention job skips open cards.
- Test both refusals for a foreign card: an account outside the entitlement (the gate,
NotEntitled) and the pooled account naming a card funded elsewhere (CORPORATE_CARD_ACCOUNT_MISMATCH).
Landing notes
-
ADR-835:
CardControlsAndFundingTests’ two.Be(controls)assertions compare by reference onceCardControlsholds lists; bite 1 rewrites them member by member. -
ADR-838:
docs/adr/ADR-838-tests/bite-4.cs.txtbuilds the three-ceilingCardControls; whichever lands second moves it. -
ADR-837: its bite-4 tests build the three-ceiling
CardControls; whichever lands second moves them. -
ADR-836:
CardHoldandCardHoldPlacedgainChannelandCategoryGroups; the decider loads the card’s own holds; the decider’s ceiling check becomes the limit check;CardControlschanges shape under its tests. -
Landing note (coordinator, 2026-10-03): ADR-844 builds beside ADR-840 (lane
cards-authorisation) and ADR-845 (lanecashier-management). With ADR-840 it shares the Cards bootstrapper,CardsComponentFixture.cs,CardReceipts.csand the category taxonomy; with ADR-845, the package model, importer and exporter. The second to land resolves them. -
Decided: the valid-until menu entry, its parity row and its dialog land in bite 1, not bite 3 · rests on:
CardVerb.SetValidUntillands in bite 1 andCardOperationGuardParityTestsholds the menu equal to the verbs · wrong if: bite 3 adds a secondset-card-valid-untilentry. -
Decided: the bounds check at edit lives in
Card.SetControls(controls, bounds, on), against the card’s own current controls · rests on: CLAUDE.md, no business logic in handlers · wrong if: a corporate command in bite 4 sets controls without passing the type’s bounds. -
Decided: the decline codes 57, 65 and 54 are mapped in bite 1 · rests on: the reasons land in bite 1 and
PaymentologyOutboundMapperTestsmaps every reason · wrong if: bite 2’s mapper rows find them unmapped. -
Decided:
CardSpendChannels.Classifylands in bite 1 · rests on:PlaceHoldtakes the channel from bite 1 (plan Interfaces) · wrong if: bite 2 needs a second classifier. -
Decided: an amount newly set on a limit that held only a count is an added amount and is checked against the bounds · rests on: D4 phase A, “a limit an edit adds or raises” · wrong if: a count-only limit gaining an amount below every bound is refused.
-
Decided: the exporter writes
CardTypesSettings.yaml, andCardTypeEntrygainsRenewalLeadDays, which the importer had dropped · rests on: D2 plan grill, the seed proved both ways · wrong if:CardSpendControlsSeedTests.the_groups_and_bounds_survive_export_and_reimportreads a type the template does not. -
Decided: the eleven merchant-category-group types join
CardVocabularyTests’ named exceptions, and the ten new Contracts types join the shared-surface baseline · rests on: F3 and the ADR’s Contracts naming them · wrong if: an operator reads a category group as a four-eyes authorisation. -
Decided:
cards.corporateis added to the feature catalog in bite 4, with the keys it gates · rests on: a feature with no key gates nothing · wrong if: bite 1’s tests need the feature on. -
Measure: bite 4’s test file was re-authored for one stale call (ADR-807 added
NametoRecordChannelServiceAgreementCommand); the corrected file replacesADR-844-tests/bite-4.cs.txt. -
Measure:
the_limit_use_and_authorisations_reads_are_404_for_an_unknown_cardis a scaffold green, because a route that does not exist answers 404 too. The bite stands, and the test cannot tell a missing route from a handled refusal. -
Decided: bite 1 also declares the later bites’ contract types (the corporate commands and reads, the two card reads,
CloseLapsedCardsCommand) with their catalog keys and ChannelCatalog rows, and no handlers · rests on: ADR-692, bite 1 creates the types so later tests compile · wrong if: a channel operation is dispatchable before bite 4 lands. -
Decided: the Paymentology inbound mapper reads an empty or missing merchant country as absent, and still refuses any other value that is not two letters · rests on: D3 phase A and the plan’s Interfaces, “a merchant country “” is absent” · wrong if: a tap with no merchant country is refused at the door rather than by an allow-only rule.
-
Decided: the channel issue calls the bank’s issue handler directly, not over the bus, so the act meets the channel’s gates and never the bank’s · rests on: D6, “never the bank’s commands” · wrong if: a channel issue is captured for a bank four-eyes approval.
-
Decided: the corporate card’s owner is the funding account’s single owning party, or the account’s own owner where it records no owning role; two or more owners are refused
CORPORATE_CARD_OWNER_AMBIGUOUS· rests on: D6 plan grill, “the funding account’s single owner” · wrong if: a jointly owned pooled account issues a channel card. -
Decided:
IssueCorporateCardCommandjoinscommands-whose-caller-reads-the-record.txt; its caller names the card’s id · rests on: ADR-780 D3 · wrong if: a caller reads the returned id after a captured issue. -
Measure: bite 4’s test file was re-authored a second time for one assertion that compared
ChannelScopeby its member-less base type. -
Decided: the authorisations route reads
?take=; the bite-5 test that seemed to rely on a tie was right, the route ignoredtake· rests on: Interfaces,ListCardAuthorisationsQuery(CardId Id, int Take = 50)· wrong if:the_authorisations_read_lists_only_the_cards_own_taps_newest_first_and_honours_takegoes red. -
Decided: the controls and valid-until sheets carry
sheet:card-controlsandsheet:card-valid-until, replacing the unattachedcards.controlshelp key · rests on: ADR-407, a sheet key is named when an article first attaches · wrong if: an article attaches tocards.controls. -
As built (Interfaces reconcile at land):
Card.SetControls(controls, bounds, on)holds an edit to the type’s bounds on the card;Card.Lapse(tradingDate)is the day-end close;Card.RequireFundedOnlyBy(account)andCard.RequireVirtual()carryCORPORATE_CARD_ACCOUNT_MISMATCHandCARD_REVEAL_VIRTUAL_ONLY;CardControlsRule.MonthlyExposure(controls)is the channel’s asserted amount;CardSpendChannels.Classifylives inCardSpend.cs;GET /api/cards/{id}/authorisationsreads?take=; the corporate handlers live inCorporate/CorporateCardHandlers.cs, beside the records.