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-836 — Implementation Plan

Findings for the ADR

Files touched

Bite 1 — contract types, the changes to ADR-820’s types, the expiry settings and page

Bite 2 — the hold on the card, the projections, the reductions seam, Accounts reads it

Bite 3 — the decider (F6)

Bite 4 — release on reversal, closure and expiry at day-end

Bite 5 — the clearing post

Bite 6 — the UI, the guide, the probe

Prior art

Re-checked 2026-10-02 after the grill: no new candidate for any declared name. Supporting names the signatures needed: IFacilityAvailableReader (F1, back to the ADR), CardHoldSummary (the hold as the list shows it), MoveTradingDateAsync (test only).

Interfaces

// src/LedgerTM.Contracts/Cards/CardHold.cs
public readonly record struct CardHoldId(string Value) : IStrongId<CardHoldId>
{ public static CardHoldId Of(CardAuthorisationId authorisation) => new(authorisation.Value); }   // one hold per authorisation
public enum CardHoldReleaseReason { Reversed, Cleared, Expired, CardClosed }
public enum CardHoldStatus { Open, Released }
// One inline document per hold (F12); the reductions reader sums Open by FundingAccount, expiry queries ExpiresOn, spend sums by Card and PlacedOn.
public sealed class CardHold
{
    public CardHoldId Id { get; set; } public CardId Card { get; set; } public CardAuthorisationId Authorisation { get; set; } public AccountId FundingAccount { get; set; }
    public decimal OriginalAmount { get; set; } public decimal Amount { get; set; } /* remaining */ public CurrencyId Currency { get; set; }
    public MerchantCategoryCode Mcc { get; set; } public string MerchantName { get; set; } = ""; public DateOnly PlacedOn { get; set; } public DateOnly ExpiresOn { get; set; }
    public CardHoldStatus Status { get; set; } public CardHoldReleaseReason? Released { get; set; } public DateOnly? ReleasedOn { get; set; } public string? ReleasedBy { get; set; }
    // ReleasedBy: the processor's reversal reference or clearing reference (F24); null for expiry and closure. Amount reads 0 once released.
}
public sealed record CardClearingItemOutcome(string ProcessorReference, CardClearingItemKind Kind, TransactionId? Posted, AccountId? Account, string? ExceptionCode, string? Message);
public sealed record CardClearingException(string ProcessorReference, CardClearingItemKind Kind, string Code, string Message);   // the view of an outcome with a code

// src/LedgerTM.Contracts/Cards/CardAuthorisation.cs — changed
public enum CardDeclineReason { IssuerNotReady, CardNotActive, ControlBreached, InsufficientFunds, NoFundingAccount, DecisionFailed, UnknownToken,
    DeviceTokensNotAllowed, DeviceTokenMissing, CredentialExpired, ChannelNotAllowed, CountryNotAllowed, CeilingExceeded }   // ControlBreached kept, never produced (F25)
public sealed record CardAuthorisationRequest(/* ADR-820's members */ …, DateTimeOffset RequestedAt, bool PartialApprovalAllowed = false);
// src/LedgerTM.Contracts/Cards/CardClearing.cs — changed
public sealed record CardClearingBatch(/* ADR-820's members */ …, DateTimeOffset ImportedAt, IReadOnlyList<CardClearingItemOutcome>? Outcomes = null);   // an item with no outcome is unposted
// src/LedgerTM.Cards/Domain/CardProcessorSettings.cs — changed (F7): public IsoCountryCode? DomesticCountry { get; set; }  (optional; null: the country check is skipped, F20)
// src/LedgerTM.Accounts/Application/Queries/GetAccountDetail.cs — PositionDto gains decimal HeldExternally (per position; the card holds sit on Current)
// src/LedgerTM.Cards/Simulation/SimulateCommands.cs — SimulateCardAuthorisationCommand(…, string? ProcessorReference = null, bool PartialApprovalAllowed = false, bool Clears = true)

// src/LedgerTM.Contracts/Accounts/IAvailableBalanceReductionsReader.cs — Cards implements; Accounts injects IEnumerable<> and sums (D3, F14)
public interface IAvailableBalanceReductionsReader
{ Task<IReadOnlyDictionary<AccountId, decimal>> ReductionsAsync(IReadOnlyCollection<AccountId> accounts, DateOnly asOf, CancellationToken ct = default); }
// Every requested account is a key (0 when nothing is held); every Open hold counts whatever asOf says; opens its tenant session per call.
// src/LedgerTM.Contracts/Accounts/IAccountAvailabilityReader.cs — Accounts implements, Cards reads (D4); the facility joins with the current account ADR (F1)
public sealed record AccountAvailability(AccountId Account, CurrencyId Currency, decimal Available, decimal Ledger, decimal Claims, decimal ExternalReductions);
public interface IAccountAvailabilityReader { Task<AccountAvailability?> AvailableAsync(AccountId account, DateOnly asOf, CancellationToken ct = default); }   // null: unknown or not Active; the walk skips it

// src/LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs — beside ProcessBankDepositCommand (F2)
[PermissionKey("accounts.process-card-purchase")]
public record ProcessCardPurchaseCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate,
    string SourceRef, string MerchantName, MerchantCategoryCode Mcc, IsoCountryCode? MerchantCountry) : ISystemCommand;
[PermissionKey("accounts.process-card-refund")]
public record ProcessCardRefundCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate,
    string SourceRef, string MerchantName, MerchantCategoryCode Mcc, IsoCountryCode? MerchantCountry) : ISystemCommand;
// WorkflowDispatchContext gains Properties; TransactionPosted.Properties carries merchantName, merchantCategoryCode, merchantCountry (F16).
// PostingSettings: CardPurchase Dr deposit liability / Cr card-settlement-payable; CardRefund the reverse (F17).
// TransactionSource gains CardPurchase, CardRefund. ExternalIntegrations gains CardPurchase and CardRefund entries (YAML cardPurchase, cardRefund),
// each naming an operation on the type; a type without one refuses ACCOUNT_TYPE_DOES_NOT_ACCEPT_CARD_PURCHASES / _REFUNDS.

// src/LedgerTM.Cards/Domain/Card.Events.cs — frozen once shipped
[MessageIdentity("cards.card-hold-placed")]  public record CardHoldPlaced(CardId Id, CardHoldId Hold, CardAuthorisationId Authorisation, AccountId FundingAccount,
    decimal Amount, CurrencyId Currency, MerchantCategoryCode Mcc, string MerchantName, DateOnly On, DateOnly ExpiresOn) : DomainEvent;
[MessageIdentity("cards.card-hold-reduced")] public record CardHoldReduced(CardId Id, CardHoldId Hold, AccountId FundingAccount, decimal By, decimal Remaining, string ReleasedBy /* the reversal's processor reference */, DateOnly On) : DomainEvent;
[MessageIdentity("cards.card-hold-released")] public record CardHoldReleased(CardId Id, CardHoldId Hold, AccountId FundingAccount, decimal Amount /* freed */, CardHoldReleaseReason Reason,
    string? ReleasedBy /* the reversal's or clearing line's processor reference, null for expiry and closure */, DateOnly On) : DomainEvent;   // Amount is what was freed: the remainder, never the reversal's figure

// src/LedgerTM.Cards/Domain/Card.cs — verbs; every Apply public
// PlaceHold(authorisation, account, amount, currency, mcc, merchantName, on, expiresOn): refused CARD_HOLD_EXISTS on a repeat, CARD_STATUS_FORBIDS unless Active
// ReduceHold(hold, by, releasedBy, on): refused CARD_HOLD_NOT_OPEN, CARD_HOLD_REDUCTION_INVALID (by ≤ 0, or a reduction with a reason other than Reversed,
// or no releasedBy); `by` is a reduction, not a replacement; at or above the remainder releases as Reversed
// ReleaseHold(hold, reason, on): refused CARD_HOLD_NOT_OPEN · ReleaseAllHolds(on): on Close, reason CardClosed

// src/LedgerTM.Cards/Domain/CardHoldExpirySettings.cs
public class CardHoldExpirySettings : Settings { public int DefaultDays { get; set; } = 7; public List<CardHoldExpiryRule> Rules { get; set; } = []; }
public sealed class CardHoldExpiryRule { public string Label { get; set; } = ""; public MerchantCategoryCode From { get; set; } public MerchantCategoryCode To { get; set; } public int Days { get; set; } }
// src/LedgerTM.Cards/Application/Settings/AmendCardHoldExpiry.cs — POST /api/settings/card-hold-expiry
[PermissionKey("cards.amend-hold-expiry")] public record AmendCardHoldExpiryCommand(int DefaultDays, IReadOnlyList<CardHoldExpiryRule> Rules) : ISettingsCommand<CardHoldExpirySettings>;
// Validator (400, every row's faults in one answer): CARD_HOLD_EXPIRY_RANGE_INVERTED, CARD_HOLD_EXPIRY_DAYS_BELOW_ONE (rows and the default),
// CARD_HOLD_EXPIRY_DAYS_ABOVE_THIRTY_ONE, CARD_HOLD_EXPIRY_RANGES_OVERLAP (inclusive ranges, disjoint; a narrower exception is a split band),
// CARD_HOLD_EXPIRY_MCC_REQUIRED; Label optional. An absent document reads as DefaultDays 7 and no rules (GET answers 200 with them).
// The command is four-eyes eligible through SettingsApproverViewReader.
[PermissionKey("cards.view-hold-expiry")]  public record GetCardHoldExpiryQuery : IQuery<CardHoldExpirySettings>;   // GET /api/settings/card-hold-expiry

// src/LedgerTM.Cards/Application/Holds/ReleaseCardHold.cs — system-internal; cascaded by the reversal door, the clearing post, the expiry command
[PermissionKey("cards.release-card-hold")]
public record ReleaseCardHoldCommand(CardHoldId Hold, CardHoldReleaseReason Reason, string? ReleasedBy = null, decimal? ReduceBy = null) : ICommand, ISystemCommand { … }   // the CardHold document names the card; ReleasedBy required for Reversed and Cleared
// src/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cs
[PermissionKey("cards.expire-card-holds")]        public record ExpireCardHoldsCommand(TenantId Tenant, DateOnly TradingDate) : ICommand, ISystemCommand { … }   // releases ExpiresOn <= TradingDate (F18)
[PermissionKey("cards.post-card-clearing-batch")] public record PostCardClearingBatchCommand(TenantId Tenant, CardClearingBatchId Batch) : ICommand, ISystemCommand { … }   // invoked for the tenant (F14)
public sealed class PostCardClearingStep : IDayEndStep   // order 44, NonCritical, PreIncrement, id "cards.post-clearing": every batch with an unsettled item — no outcome,
                                                         // an exception outcome, or a Posted outcome whose hold is still Open (F13, F23)
public sealed class ExpireCardHoldsStep : IDayEndStep    // order 45, NonCritical, PreIncrement, id "cards.expire-holds"

// src/LedgerTM.Cards/Application/Queries/ListCardHolds.cs — GET /api/cards/{id}/holds
[PermissionKey("cards.list-card-holds")] public record ListCardHoldsQuery(CardId Card) : IQuery<IReadOnlyList<CardHold>>;   // 403 FEATURE_DISABLED without cards.issuing, as the other reads

// src/LedgerTM.Cards/Application/Doors/CardAuthorisationDecider.cs — implements ICardAuthorisationDecider (ADR-820)
// Order: UnknownToken (the index holds only open credentials, so a closed one is unknown) · CardNotActive · CredentialExpired (the credential's
// expiry month is before the trading date's month; good through the last day of its month) · DecisionFailed when the request's billing currency
// is not the card's (a processor fault, logged) · ChannelNotAllowed: the request's CardPresent flag decides presence (F27); Atm needs AtmAllowed
// and nothing else; a card-present tap needs InStoreAllowed, and Contactless entry (a phone tap included) also ContactlessAllowed; a
// card-not-present tap (Ecommerce, MailOrTelephone, Recurring, a remote wallet) needs OnlineAllowed · CountryNotAllowed: card present only (an
// ATM abroad included), merchant country (normalised to upper-case alpha-2 by the mapper; anything else reads as foreign) ≠ the facet's
// DomesticCountry, unless InStoreAbroadAllowed or the travel window covers the trading date and lists the country · CeilingExceeded: amount >
// per-transaction, or today's spend + amount > daily, or this calendar month's + amount > monthly, where today is the trading date and spend is
// by PlacedOn; equal passes; a ceiling breach is final even with partial approval allowed · NoFundingAccount: no account
// in the rule is open and Active · the walk (D4): for each account in order, IAccountAvailabilityReader (null skipped); the first whose Available
// ≥ amount takes PlaceHold(amount); none and PartialApprovalAllowed: the first with Available > 0 takes PlaceHold(Available), PartiallyApproved;
// none: InsufficientFunds. The decider captures tenant and trading date before its first await; its reads run under the door's budget and its
// save under CancellationToken.None, in its own IDocumentSession (store + current tenant), before the decision returns; a ConcurrencyException
// retries the whole decision once, a second is DecisionFailed. Writes nothing into the door's unit of work. Expiry: trading date + the first
// CardHoldExpiryRule whose range covers the MCC, else DefaultDays, in calendar days from the trading date. Spend (F4): sum over the card's
// CardHold documents by PlacedOn of OriginalAmount less reductions — NotAnswered, expired and closed holds count, declined taps do not. Two
// cards on one account may overcommit it between two reads; accepted (ADR Consequences). A null DomesticCountry skips the country check (F20).

// src/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cs — PostCardClearingBatchCommandHandler (D6)
// PostCardClearingStep (44) dispatches PostCardClearingBatchCommand for the tenant, per batch with an item lacking an outcome (F13). Per such item
// in file order: the authorisation's CardHold, open or released, names the account (a reissued card's old token still matches); else token →
// card (none: outcome UNKNOWN_TOKEN). Purchase with an open hold → ProcessCardPurchaseCommand to the hold's account for FinalAmount, ValueDate =
// TransactionDate (a live file publishes D on D+1, so a live post is back-valued a day and accrues from it), TransactionId = Uuid5(connection
// namespace, ProcessorReference), outcome recorded, then ReleaseCardHold(Cleared, ReleasedBy = reference); an item whose outcome says Posted
// but whose hold is still Open is released on a re-run. Purchase with a released hold → that hold's account, no release; Purchase with no hold →
// the first funding account; Refund → the account its authorisation's hold names, else the first funding account; Reversal → ProcessCardRefund
// to the account its purchase posted to (the purchase found by authorisation across batches), releasing the hold as Reversed if still open,
// else outcome REVERSAL_UNMATCHED (F19); Chargeback → outcome CHARGEBACK_NOT_HANDLED; a DomainException from Accounts → outcome with its code,
// the hold untouched, retried at the next day-end (F23). Never throws for an item. A Posted item is skipped on a re-run, by item; Accounts
// also skips a transaction id it has posted, so a re-import that merges outcomes by reference posts nothing twice. TransactionPosted.Properties carry merchantName, merchantCategoryCode, merchantCountry, read back through
// the account's transactions read (GET /api/accounts/{id}/transactions) (F16).

// LedgerTM.Tests.Component/Cards/CardsComponentFixture.cs (F5) — the fixture type: CallDeposit with cash-out guarded `Current >= $amount`,
// cardPurchase/cardRefund integrations and transaction types; hold-expiry rows (7 default, 7011 → 30, 7512 → 30, 5541–5542 → 3); DomesticCountry ZA
protected Task FundAsync(AccountId account, decimal amount);                      // ProcessCashDepositCommand
protected AccountId ThirdZarCallDeposit { get; }                                  // the demo customer's, unfunded until a test funds it
protected Task<CardHoldId> PlaceHoldAsync(CardSummary card, AccountId account, decimal amount, string mcc = "5411");   // appends CardHoldPlaced (bite 2 only)
protected Task CloseAccountAsync(AccountId account);                              // appends AccountClosed, as other tests do
protected Task<IReadOnlyList<CardHold>> HoldsOfAsync(CardId card);
protected Task<CardAuthorisationReceipt> SimulateAuthorisationAsync(CardSummary card, decimal amount, string mcc = "5411", CardChannel channel = CardChannel.CardPresent,
    CardEntryMode entry = CardEntryMode.Chip, string country = "ZA", bool partial = false, string? reference = null);   // SimulateCardAuthorisationCommand through the bus
protected Task<CardReversalReceipt> SimulateReversalAsync(CardAuthorisationId authorisation, decimal? amount = null);
protected Task RunDayEndThroughAsync(DateOnly closes);                            // run-forward to closes + 1, waits for the run; from CardClearingTests
protected Task<CardClearingBatch> StoreBatchAsync(DateOnly businessDate, params CardClearingItem[] items);   // a batch the post can be invoked on
// LedgerTM.Testing.Infrastructure/Cards/ScriptedDeciders.cs — the authorisation half decorates the real decider: script when set, else inner;
// Around(tenant, (inner, request, ct) => …) wraps the real one (a late answer, a pause between the availability read and the append) and
// exposes the inner task (LastInner(tenant)) so a test awaits the abandoned decision before asserting its hold (F21).
// SimulateCardAuthorisationCommand gains `bool PartialApprovalAllowed = false` after ProcessorReference.

Bites

Bite Description Acceptance criterion Status
1 Contract types: CardHoldId, the values, the three card events, the system commands, the two Accounts postings, the two readers, the hold document, the changes to ADR-820’s reason, request, facet, simulate command and converter; CardHoldExpirySettings with validator, amend and read, template rows, settings page A hold expiry rule is banded by merchant category Pending
2 The hold on the card: PlaceHold, ReduceHold, ReleaseHold; CardHold inline; IAvailableBalanceReductionsReader; the holds read; Accounts reads the reductions at every available-balance site A card hold reduces the account’s available balance wherever a claim does Pending
3 The decider: token, status, credential, channel, country and travel window, ceilings; IAccountAvailabilityReader in Accounts; the funding walk; partial approval; the hold placed in the decider’s own unit of work with one retry; the new reasons mapped in the adapter Every control refusal names its cause; A suspended card and an expired credential are declined naming each; An approval places the whole hold on the first account that covers it; A partial approval holds what the first account has; Two taps on one card serialise on the card Pending
4 The reversal door cascades the release; closing a card releases its holds; ExpireCardHoldsStep (45) and its command A reversal releases the hold in real time; A hold expires at day-end by its merchant category; Closing a card releases its holds Pending
5 PostCardClearingStep (44) and PostCardClearingBatchCommand: matching, the two Accounts postings with their transaction types, GL rules and the merchant on the posting, outcomes on the batch, retried until settled A cleared purchase posts to the funding account and releases its hold; An unmatched item posts to the first funding account and a chargeback is an exception Pending
6 The holds panel, held-by-cards on the account, the guide, the probe An operator sees a hold on the card and on the account Pending

Scenarios

Feature: A card processor's question is answered from the ledger, and the answer holds the money until the line clears

# Bite 1
Scenario: A hold expiry rule is banded by merchant category
  Given the za-retail tenant's hold expiry settings hold a default of 7 days and a row for 7011 to 7011 of 30 days
  When an operator adds a row for 7512 to 7512 of 30 days and a row for 5541 to 5542 of 3 days
  Then the rules read back and a row whose range is inverted or whose days are below one is refused naming the fault
  # Seen at: route:/settings/card-hold-expiry

# Bite 2
Scenario: A card hold reduces the account's available balance wherever a claim does
  Given a call deposit holding 4,200.00 ZAR and an active card funded from it
  When a hold of 1,200.00 is placed on the card against that account
  Then the account's available balance reads 3,000.00 on its detail and through the balance resolver, its ledger balance still reads 4,200.00 and its own claims are unchanged
  And a cash withdrawal of 3,500.00 against the account is refused for want of available balance
  And a withdrawal of 2,900.00 is accepted and the ledger then reads 1,300.00
  # Seen at: route:/accounts/{id}

# Bite 3
Scenario Outline: Every control refusal names its cause
  Given an active card with online off, in-store abroad off, a per-transaction ceiling of 2,000.00 and a daily ceiling of 5,000.00, and a travel window for GB
  When the processor asks to authorise <amount> at <channel> in <country>
  Then the reply is <outcome> with reason <reason>, and no hold is placed on a decline
  # Seen at: panel:cardProcessorReceipts

  Examples:
    | amount   | channel              | country | outcome  | reason            |
    | 200.00   | online               | ZA      | Declined | ChannelNotAllowed |
    | 200.00   | card present, chip   | FR      | Declined | CountryNotAllowed |
    | 200.00   | card present, chip   | GB      | Approved |                   |
    | 2,500.00 | card present, chip   | ZA      | Declined | CeilingExceeded   |
    | 1,900.00 twice then 1,900.00 | card present, chip | ZA | Declined on the third | CeilingExceeded |

# Bite 3
Scenario: A suspended card and an expired credential are declined naming each
  Given a suspended card, and an active card whose credential expired last month
  When the processor asks to authorise 100.00 on each
  Then the first is Declined CardNotActive and the second Declined CredentialExpired
  # Seen at: panel:cardProcessorReceipts

# Bite 3
Scenario: An approval places the whole hold on the first account that covers it
  Given an active card whose funding rule names a call deposit holding 3,000.00 then a call deposit holding 5,000.00
  When the processor asks to authorise 4,000.00 at merchant category 7011
  Then the reply is Approved
  And one hold of 4,000.00 sits on the card against the second account, expiring thirty days on
  And the first account's available is unchanged and the second's reads 1,000.00
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: A partial approval holds what the first account has
  Given an active card whose funding rule names a call deposit holding 3,000.00 then a call deposit holding 500.00
  When the processor asks to authorise 5,000.00 with partial approval allowed
  Then the reply is PartiallyApproved for 3,000.00 and a hold of 3,000.00 sits against the first account
  And the same request without partial approval allowed is Declined InsufficientFunds and places no hold
  And a request on a card whose only funding account has been closed is Declined NoFundingAccount
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: Two taps on one card serialise on the card
  Given an active card funded from a call deposit holding 1,500.00
  When the processor asks to authorise 1,000.00 twice at once under two references
  Then exactly one is Approved and the other is Declined InsufficientFunds
  And one hold sits on the card and the account's available reads 500.00
  # Seen at: route:/cards/{id}

# Bite 4
Scenario: A reversal releases the hold in real time
  Given an approved authorisation holding 3,000.00 against a call deposit
  When the processor reverses it in full at 14:00
  Then the hold is released as Reversed at once and the account's available is restored
  When the processor reverses a different approved authorisation of 1,200.00 by 400.00
  Then that hold reads 800.00 remaining of 1,200.00
  And a further reversal of 900.00 releases it as Reversed
  # Seen at: route:/cards/{id}

# Bite 4
Scenario: A hold expires at day-end by its merchant category
  Given a hold placed today at merchant category 5411 and a hold placed today at 7011, with a default expiry of seven days and thirty for 7011
  When day-end closes every trading date up to and including the seventh day after today
  Then the first hold is released as Expired at that close and not at the sixth, and the second is still open
  And a hold placed by a decision the door could not answer in time stays open until it clears or expires
  # Seen at: route:/cards/{id}

# Bite 4
Scenario: Closing a card releases its holds
  Given an active card with two open holds against a call deposit
  When the card is closed
  Then both holds are released as CardClosed and the account's available equals its ledger balance
  # Seen at: route:/cards/{id}

# Bite 5
Scenario: A cleared purchase posts to the funding account and releases its hold
  Given a hold of 1,200.00 on a card against a call deposit, placed by an approved authorisation
  When a clearing batch whose item names that authorisation with a final amount of 1,150.00 dated today is posted
  Then a card purchase of 1,150.00 is posted to the call deposit, value-dated today, naming the merchant, its category and country
  And the books debit the deposit liability and credit card settlement payable by 1,150.00
  And the hold is released as Cleared naming the clearing reference, and the account's available equals its ledger balance
  And posting the same batch again posts nothing twice
  And a line dated yesterday posts value-dated yesterday
  And at day-end the clearing is posted before holds expire
  # Seen at: route:/accounts/{id}

# Bite 5
Scenario: An unmatched item posts to the first funding account and a chargeback is an exception
  Given an active card whose funding rule names a call deposit first, and an expired hold on it
  When a clearing batch with a purchase naming an authorisation the ledger never saw, a purchase naming the expired hold, a refund, and a chargeback is posted
  Then the first purchase posts to the first funding account and the second to the expired hold's account, and the refund posts as a credit
  And a reversal item for a purchase already posted credits the account that purchase posted to
  And the chargeback is recorded as an exception on the batch, naming its kind
  And a purchase for a card whose funding account is closed is recorded as an exception naming the refusal
  And the batch records an outcome for every item, and a re-run posts none of them again
  # Seen at: route:/connectivity/card-processor

# Bite 6
Scenario: An operator sees a hold on the card and on the account
  Given the demo customer's card holds 1,200.00 against their call deposit
  When an operator opens the card viewer's holds panel and the account's detail
  Then the hold shows its merchant, amount, placed-on and expires-on dates on the card
  And the account's available breakdown shows 1,200.00 held by cards
  # Seen at: route:/cards/{id}

Scenario → test

Scenario Bite Project Class Method Probe
A hold expiry rule is banded by merchant category 1 LedgerTM.Tests.Component CardHoldExpirySettingsTests expiry_rules_are_banded_by_merchant_category_and_refuse_a_bad_band adr-836-server-probe.ts
A card hold reduces the account’s available balance wherever a claim does 2 LedgerTM.Tests.Component CardHoldTests a_card_hold_reduces_available_on_the_detail_the_resolver_and_the_guard adr-836-server-probe.ts
Every control refusal names its cause — online with online off 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_control_refusal_names_its_cause (theory) adr-836-server-probe.ts
Every control refusal names its cause — card present in FR 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_control_refusal_names_its_cause (theory) adr-836-server-probe.ts
Every control refusal names its cause — card present in GB inside the window 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_control_refusal_names_its_cause (theory) adr-836-server-probe.ts
Every control refusal names its cause — 2,500.00 over the per-transaction ceiling 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_control_refusal_names_its_cause (theory) adr-836-server-probe.ts
Every control refusal names its cause — the third 1,900.00 over the daily ceiling 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests the_daily_ceiling_counts_todays_approvals — timing, no surface
A suspended card and an expired credential are declined naming each 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_suspended_card_and_an_expired_credential_are_declined_naming_each adr-836-server-probe.ts
An approval places the whole hold on the first account that covers it 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests an_approval_holds_the_whole_amount_on_the_first_account_that_covers_it adr-836-server-probe.ts
A partial approval holds what the first account has 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests a_partial_approval_holds_what_the_first_account_has adr-836-server-probe.ts
Two taps on one card serialise on the card 3 LedgerTM.Tests.Component CardAuthorisationDeciderTests two_taps_on_one_card_serialise_on_the_card — timing, no surface
A reversal releases the hold in real time 4 LedgerTM.Tests.Component CardHoldReleaseTests a_reversal_releases_the_hold_at_once_and_a_partial_one_reduces_it adr-836-server-probe.ts
A hold expires at day-end by its merchant category 4 LedgerTM.Tests.Component CardHoldReleaseTests a_hold_expires_at_day_end_by_its_merchant_category adr-836-server-probe.ts
Closing a card releases its holds 4 LedgerTM.Tests.Component CardHoldReleaseTests closing_a_card_releases_its_holds adr-836-server-probe.ts
A cleared purchase posts to the funding account and releases its hold 5 LedgerTM.Tests.Component CardClearingPostTests a_cleared_purchase_posts_to_the_funding_account_and_releases_its_hold adr-836-server-probe.ts
An unmatched item posts to the first funding account and a chargeback is an exception 5 LedgerTM.Tests.Component CardClearingPostTests an_unmatched_item_posts_to_the_first_funding_account_and_a_chargeback_is_an_exception adr-836-server-probe.ts
An operator sees a hold on the card and on the account 6 LedgerTM.Tests.Component CardHoldsPanelTests a_hold_is_listed_on_the_card_and_counted_on_the_account adr-836-server-probe.ts

UI-surface sweep

Swept src/ui-apps/bank and src/ui-apps/shared for ControlBreached, holds, CardHold, heldBy, held-by, card-hold-expiry, /holds, PartialApproval: no hits outside the generated unions. The card viewer, the account viewer’s held-available tiles (generic-account-viewer.tsx already renders a position’s available beside its amount) and the settings taxonomy are the surfaces this ADR adds to:

No existing UI surface is deleted, renamed or repointed.

Footprint

Feature projects touched: 7 — LedgerTM.Accounts, LedgerTM.Cards, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Seeding.Provisioning, ui-apps

Contracts types: 42 named, 35 changed by this ADR

Files reading each changed type: 35 types

Domain events touched: 3 — CardHoldPlaced, CardHoldReduced, CardHoldReleased Aggregates touched: 1

Methods at CRAP 30+ in changed files: 2 (unit coverage, cached at main 442243a39)

Warnings

Land batches

One land — the whole ADR. Reseed at the land (reseed: true: the hold-expiry rows, the two transaction types and operations on CallDeposit, the permission keys). The current account ADR lands after this one.

Notes

Changed during the plan grill

Phase A (26 questions) and the plan grill (15 points), 2026-10-02. The ADR’s own section carries the decision-level changes; what the plan changed on its own: bites 3 and 4 merged; the fixture’s account type guarded and integrated, funded through FundAsync, with a third call deposit and the expiry rows; PlaceHoldAsync for bite 2; ScriptedDeciders.Around exposing the inner task; the day-end helpers moved into the context; the guard context’s five callers listed; the characterisation test of the dispatcher named before it is edited; PostingSettings.yaml and the chart named; F1 reversed and F12–F22 added; CardHoldsByAccount and CardSpendByPeriod dropped for one CardHold document. Phase B (six authors, 2026-10-02): F23–F28 — the post step revisits a batch until every item is settled and retries exceptions; what released a hold is the processor’s reference; ControlBreached stays plain; the simulator can leave an approval uncleared; presence is the request’s flag; bands disjoint and capped; PositionDto.HeldExternally declared; closure moved to bite 4’s files.

Landing notes

(appended by /ltm-partition and by lanes)