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

Findings for the ADR

Files touched

Bite 1 — contracts, settings, the integrations

Bite 2 — the aggregate

Bite 3 — the door and the processor

Bite 4 — the outcome’s money

Bite 5 — the clocks

Bite 6 — the screens, the sample, the probe, the guide, the register

Prior art

Nothing changed since the grill. Four supporting shapes the signatures needed — CardDisputeRequest, CardDisputeReference, CardDisputeUpdate, CardDisputeEvidence (F3) — and PlayCardDisputesCommand (the simulator’s, in SimulateCardClearingFileCommand’s shape) carry no decision.

Interfaces

// src/LedgerTM.Contracts/Cards/CardDispute.cs — new (D1, D2, D3)
public readonly record struct CardDisputeId(string Value) : IStrongId<CardDisputeId> { … }   // For(TransactionId purchase, int ordinal): "{purchase}-dispute-{n}"; a concurrent second raise collides on the stream (D1)
public readonly record struct CardDisputeReasonCodeId(string Value) : IStrongId<CardDisputeReasonCodeId> { … }   // StrongId.SlugFor: "{scheme}-{code}", e.g. visa-10-4
public enum CardDisputeStage { Raised, Represented, PreArbitration, Arbitration, Closed }
public enum CardDisputeOutcome { Won, Lost, MerchantAccepted, Withdrawn }
public enum CardDisputeCategory { Fraud, Authorisation, ProcessingError, ConsumerDispute }   // the schemes' word
public enum ProvisionalCreditRule { OnRaise, OnOutcome }
public enum CardDisputePostingKind { Credit, Clawback, Fee }
public enum EvidenceSource { Bank, Merchant }
public sealed record CardDisputeRequest(CardTokenReference Token, string ProcessorReference, decimal Amount, CurrencyId Currency, decimal OriginalAmount, CurrencyId OriginalCurrency, string SchemeReasonCode, string Narrative);
public sealed record CardDisputeReference(string ProcessorDisputeReference, string? SchemeCaseReference);
public sealed record CardDisputeEvidence(string Description, AttachmentId? File, string? ProcessorReference);
public sealed record CardDisputeUpdate(CardDisputeUpdateId Id, string ProcessorDisputeReference, CardDisputeStage Stage, CardDisputeOutcome? Outcome, string? SchemeCaseReference, CardDisputeEvidence? MerchantEvidence, DateOnly On, string UpdateReference);

// src/LedgerTM.Contracts/Cards/CardReceipts.cs — beside CardReversalReceipt (D3)
public readonly record struct CardDisputeUpdateId(string Value) : IStrongId<CardDisputeUpdateId> { … }   // For(processorDisputeReference, updateReference), as CardClearingBatchId composes
public enum CardDisputeUpdateOutcome { Applied, Stale, UnknownDispute, Refused }   // a repeated Id returns the stored receipt verbatim
public sealed record CardDisputeUpdateReceipt(CardDisputeUpdateId Id, InstitutionConnectionId Connection, DateOnly TradingDate, CardDisputeId? Dispute, CardDisputeUpdateOutcome Outcome, DateTimeOffset ReceivedAt);

// src/LedgerTM.Contracts/Cards/CardClearing.cs — changed (D6)
public sealed record CardClearingItem(…, string? DisputeReference = null);   // a Chargeback line names the processor's dispute reference; defaulted so no caller breaks

// src/LedgerTM.Contracts/Attachments/AttachmentId.cs — moved from LedgerTM.Attachments (F6); unchanged

// src/LedgerTM.Contracts/Cards/ICardProcessor.cs — changed (D8)
Task<CardDisputeReference> RaiseDisputeAsync(CardDisputeRequest request, CancellationToken ct = default);
Task EscalateDisputeAsync(string processorDisputeReference, CancellationToken ct = default);
Task ConcedeDisputeAsync(string processorDisputeReference, CancellationToken ct = default);
Task WithdrawDisputeAsync(string processorDisputeReference, CancellationToken ct = default);
Task SubmitDisputeEvidenceAsync(string processorDisputeReference, CardDisputeEvidence evidence, CancellationToken ct = default);

// src/LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs — new (D5, D6); ProcessCardRefundCommand's shape plus the dispute
[PermissionKey("accounts.process-card-dispute-credit")]
public record ProcessCardDisputeCreditCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate,
    CardDisputeId Dispute, string MerchantName, MerchantCategoryCode Mcc, IsoCountryCode? MerchantCountry) : ISystemCommand;
[PermissionKey("accounts.process-card-dispute-clawback")]
public record ProcessCardDisputeClawbackCommand(AccountId AccountId, TransactionId TransactionId, decimal Amount, DateOnly TradingDate, DateOnly ValueDate,
    CardDisputeId Dispute, string MerchantName, MerchantCategoryCode Mcc, IsoCountryCode? MerchantCountry) : ISystemCommand;
// Each handler runs the type's cardDisputeCredit / cardDisputeClawback integration (parameters amount, disputeId, merchantCategory, merchantName, merchantCountry; properties disputeId, merchant…; sourceRef = the dispute id); no guard;
//   an account that is not Active refuses ACCOUNT_NOT_ACTIVE and the caller records the posting forgone.
// Credit: ValueDate = the purchase's value date (from the index), TransactionId.For($"{dispute.IdPart()}-dispute-credit"); the revaluation cascade re-walks (ADR-837 bite 5).
// Clawback: ValueDate = TradingDate, TransactionId.For($"{dispute.IdPart()}-dispute-clawback"). Each id is minted once per dispute: a dispute credits at most once and claws back at most once.

// src/LedgerTM.Contracts/Tasks/RequestCardDisputeFollowUpTaskCommand.cs — new (D4)
public enum CardDisputeTaskPurpose { Deadline, ForgonePosting }
public record RequestCardDisputeFollowUpTaskCommand(CardDisputeId DisputeId, CardDisputeTaskPurpose Purpose, string Title, string Description, UserGroupId? OfferedToGroupId, DateOnly DueOn) : ISystemCommand;
//   the task id derives from (dispute, purpose, DueOn), so a repeat is idempotent and a deadline and a forgone posting on one day do not collide.

// src/LedgerTM.Accounts — the scheduled-row flag (D6, F8)
public enum RevaluationBehaviour { Reevaluate, AsRecorded, KeepHigher, KeepLower }   // ScheduledTransaction.OnRevaluation; YAML `onRevaluation:`; default Reevaluate; Set rows only
//   AsRecorded replays the row's recorded outcome for that day (nothing, where nothing was recorded); KeepHigher/KeepLower post the higher/lower of the recorded and the re-evaluated value; a day with nothing recorded evaluates as normal.
//   RevaluationEngine and ProcessToDate honour it alike; the credit card's GraceStatusUpdate row carries KeepHigher (D6).

// src/LedgerTM.Cards/Domain/CardDisputeReasonCodeSettings.cs — new (D2)
public sealed class CardDisputeReasonCodeSettings : Settings { public List<CardDisputeReasonCode> Codes { get; set; } = []; }
public sealed class CardDisputeReasonCode { public string Key { get; set; } = ""; public CardDisputeReasonCodeId Id { get => CardDisputeReasonCodeId.FromKey(Key); init { } }
    public string Scheme { get; set; } = ""; public string Code { get; set; } = ""; public string Label { get; set; } = ""; public CardDisputeCategory Category { get; set; }
    public ProvisionalCreditRule ProvisionalCredit { get; set; } public int FilingDays { get; set; } public int RepresentmentDays { get; set; } public int ResponseDays { get; set; } public int PreArbitrationDays { get; set; } public int ArbitrationDays { get; set; } }
// Calendar days. FilingDays: raise allowed while TradingDate <= TransactionDate + FilingDays (the limit day inside). RepresentmentDays: the merchant's window at Raised; ResponseDays: the bank's at Represented; PreArbitrationDays: the merchant's; ArbitrationDays: the scheme's.
// Validator: Key == CardDisputeReasonCodeId.FromKey($"{Scheme}-{Code}").IdPart() and VocabularyKey.Pattern (CARD_DISPUTE_REASON_CODE_KEY); Scheme and Code required and unique together by id (CARD_DISPUTE_REASON_CODE_DUPLICATE); every days 1..720 (CARD_DISPUTE_REASON_CODE_INVALID);
//   a row removed or re-keyed while an open dispute holds its id → CARD_DISPUTE_REASON_CODE_IN_USE (as CARD_TYPE_IN_USE; reads CardDisputeSummary, so the rule and its tests land with bite 2); a blank scheme or code → CARD_DISPUTE_REASON_CODE_INVALID; a DisputesGroup naming no group → CARD_DISPUTE_SETTINGS_INVALID.
//   KeepHigher/KeepLower: a walked day where the row recorded nothing evaluates as normal; a keep row whose re-walk would post nothing keeps its recorded value and books no adjustment. "Set row": a row whose generated type's position rules are all Set. The refusal is AccountTypesSettingsValidator's, which every write path calls. Code is stored as the scheme writes it ("10.4"); the key is its slug ("visa-10-4").
// AmendCardDisputeReasonCodesCommand(IReadOnlyList<CardDisputeReasonCode> Codes) : ISettingsCommand<CardDisputeReasonCodeSettings>, POST /api/settings/card-dispute-reason-codes; [PermissionKey("cards.view-card-dispute-reason-codes")] GetCardDisputeReasonCodesQuery : IQuery<CardDisputeReasonCodeSettings>, GET /api/settings/card-dispute-reason-codes.
// Template (filing, representment, response, pre-arbitration, arbitration): visa-10-4 (fraud, OnRaise, 120, 30, 30, 30, 45), visa-11-3 (authorisation, OnOutcome, 75, 30, 30, 30, 45),
//   visa-12-6 (processing error, OnOutcome, 120, 30, 30, 30, 45), visa-13-1 (consumer dispute, OnOutcome, 120, 30, 30, 30, 45), mastercard-4837 (fraud, OnRaise, 120, 45, 30, 30, 45), mastercard-4853 (consumer dispute, OnOutcome, 120, 45, 30, 30, 45).

// src/LedgerTM.Cards/Domain/CardDisputeSettings.cs — new (D4, F4)
public sealed class CardDisputeSettings : Settings { public int WarnDaysBeforeDeadline { get; set; } = 5; public UserGroupId? DisputesGroup { get; set; } }
// AmendCardDisputeSettingsCommand(int WarnDaysBeforeDeadline, UserGroupId? DisputesGroup) : ISettingsCommand<CardDisputeSettings>, POST /api/settings/card-disputes (1..90 days, CARD_DISPUTE_SETTINGS_INVALID); [PermissionKey("cards.view-card-dispute-settings")] GetCardDisputeSettingsQuery : IQuery<CardDisputeSettings>, GET /api/settings/card-disputes. Template: 5 days, no group.

// src/LedgerTM.Cards/Domain/CardDispute.cs — new (D1, D3, D5, D6, D7)
public sealed class CardDispute : EventSourcedAggregate
{
    public void Raise(CardId card, AccountId account, TransactionId transaction, int ordinal, string processorReference, decimal amount, CurrencyId currency, decimal schemeAmount, CurrencyId schemeCurrency,
                      MerchantCategoryCode mcc, string merchantName, IsoCountryCode? merchantCountry, DateOnly purchaseValueDate, CardDisputeReasonCodeId reason, ProvisionalCreditRule creditRule, CardDisputeReference reference, DateOnly dueOn, string narrative, UserId by, DateOnly on);
    public void RecordEvidence(CardDisputeEvidence evidence, EvidenceSource source, UserId? by, DateOnly on);
    public void RecordRepresentment(CardDisputeEvidence? merchantEvidence, DateOnly dueOn, string updateReference, DateOnly on, DateOnly receivedOn);
    public void Escalate(DateOnly dueOn, UserId by, DateOnly on);                     // Represented → PreArbitration, the bank's call
    public void RecordArbitration(DateOnly dueOn, string updateReference, DateOnly on, DateOnly receivedOn);   // PreArbitration → Arbitration, the processor's report
    public void RecordCaseReference(string schemeCaseReference, string updateReference, DateOnly on);
    public void RecordPosting(CardDisputePostingKind kind, TransactionId transaction, DateOnly valueDate, DateOnly on);   // CreditPosted / ClawbackPosted
    public void RecordPostingForgone(CardDisputePostingKind kind, decimal amount, DateOnly on);
    public void RecordFee(TransactionId fee, DateOnly on);                           // only when it posted
    public void MarkOverdue(DateOnly on);                                            // cleared by the next stage
    public void RecordSettlement(string settlementReference, decimal amount, CurrencyId currency, DateOnly on);   // a Chargeback clearing line; never moves the stage
    public void Close(CardDisputeOutcome outcome, string? reason, UserId? by, string? updateReference, DateOnly on);   // from any open stage; the bank's Concede → Lost; Withdraw → Withdrawn with its reason
    // Refusals: CARD_DISPUTE_NOT_OPEN, CARD_DISPUTE_STAGE_FORBIDS (escalate and concede need Represented; withdraw any open stage), CARD_DISPUTE_UPDATE_INVALID (Closed without an outcome, an outcome on an open stage)
}
// Events (Card.Events shape, [MessageIdentity("cards.card-dispute-…")]):
//   CardDisputeRaised(Id, Card, Account, Transaction, Ordinal, ProcessorReference, Amount, Currency, SchemeAmount, SchemeCurrency, Mcc, MerchantName, MerchantCountry, PurchaseValueDate, Reason, CreditRule, ProcessorDisputeReference, SchemeCaseReference?, DueOn, Narrative, By, On),
//   CardDisputeEvidenceRecorded(Id, Evidence, Source, By?, On), CardDisputeRepresented(Id, MerchantEvidence, DueOn, UpdateReference, On, ReceivedOn), CardDisputeEscalated(Id, Stage, DueOn, By?, UpdateReference?, On, ReceivedOn),
//   CardDisputeCaseReferenceRecorded(Id, SchemeCaseReference, UpdateReference, On), CardDisputeCreditPosted(Id, Credit, ValueDate, On), CardDisputeClawbackPosted(Id, Clawback, ValueDate, On), CardDisputeFeeCharged(Id, Fee, On),
//   CardDisputePostingForgone(Id, Kind, Amount, On), CardDisputeOverdue(Id, Stage, On), CardDisputeClosed(Id, Outcome, Reason?, By?, UpdateReference?, On), CardDisputeSettlementRecorded(Id, SettlementReference, Amount, Currency, On).

// src/LedgerTM.Cards/Application/Disputes/CardPostingIndex.cs — new (F2): a document keyed by TransactionId, one writer (the post step)
//   { Card, Token, Account, ProcessorReference, Authorisation?, CardClearingItemKind Kind, Amount, Currency, OriginalAmount, OriginalCurrency, Mcc, MerchantName, MerchantCountry, TransactionDate, ValueDate, RefundedAmount, RefundedOriginalAmount };
//   a scheme Reversal adds to its purchase row's refunded amounts. Disputable = Amount − RefundedAmount − Σ (Won | MerchantAccepted) disputes on the transaction, read from CardDisputeByTransaction.

// src/LedgerTM.Cards/Application/Disputes/… — new (D9)
[PermissionKey("cards.raise-card-dispute")] public record RaiseCardDisputeCommand(AccountId Account, TransactionId Transaction, decimal Amount, CardDisputeReasonCodeId Reason, string Narrative) : ICommand { Target "Account", Account }   // as shipped: the funding account is what a checker reviews (landing notes)
//   Handler: reads CardPostingIndex (absent, or Refund/Reversal/Chargeback → CARD_DISPUTE_POSTING_NOT_DISPUTABLE; Account not the row's → CARD_DISPUTE_ACCOUNT_MISMATCH; Amount <= 0 or beyond the currency's minor unit → CARD_DISPUTE_AMOUNT_INVALID; > disputable → CARD_DISPUTE_AMOUNT_EXCEEDS_LINE; unknown code → CARD_DISPUTE_REASON_UNKNOWN);
//   through CardDisputeByTransaction: CARD_DISPUTE_OPEN_FOR_TRANSACTION (the message names the open id), CARD_DISPUTE_ALREADY_DECIDED (a Lost/Withdrawn under the same code on this transaction), the ordinal (from 1); CARD_DISPUTE_FILING_WINDOW_PASSED when TradingDate > TransactionDate + FilingDays; the ledger refuses before the processor is called;
//   then processor.RaiseDisputeAsync (CARD_PROCESSOR_REFUSED, ADR-835 D3); dispute.Raise (a stream that exists → CARD_DISPUTE_EXISTS, the concurrent second raise); OnRaise → publishes PostCardDisputeMoneyCommand(Id, Credit) after commit. The card's status does not gate. The endpoint answers the new CardDisputeId (or the capture answer); refusals are 400 with the code; the stream key is CardDisputeId.Value.
[PermissionKey("cards.post-card-dispute-money")] public record PostCardDisputeMoneyCommand(CardDisputeId Id, CardDisputePostingKind Kind) : ICommand, ISystemCommand { Target "CardDispute" }   // ChargeCardFeeCommand's shape (ADR-839)
//   Handler: reads IAccountAvailabilityReader for the dispute's account (null → not Active → RecordPostingForgone + RequestCardDisputeFollowUpTaskCommand(ForgonePosting, DueOn = TradingDate), nothing posted); else builds ProcessCardDisputeCreditCommand / ProcessCardDisputeClawbackCommand / ProcessCardFeeCommand (Kind Fee: ADR-839's command on the dispute's account, TransactionId.For($"{dispute.IdPart()}-card-dispute-fee"), value-dated TradingDate), bus.InvokeAsync, RecordPosting / RecordFee.
//   Any other refusal dead-letters by design. Bite 2's Close emits the stage event only; the cascade is bite 4.
[PermissionKey("cards.record-card-dispute-evidence")] public record RecordCardDisputeEvidenceCommand(CardDisputeId Id, CardDisputeEvidence Evidence) : ICommand, INotFourEyesGated { … }   // submits to the processor, records with Source = Bank
[PermissionKey("cards.escalate-card-dispute")] public record EscalateCardDisputeCommand(CardDisputeId Id) : ICommand { … }
[PermissionKey("cards.concede-card-dispute")] public record ConcedeCardDisputeCommand(CardDisputeId Id) : ICommand { … }          // the bank concedes to the merchant's evidence: processor.ConcedeDisputeAsync, then Close(Lost) — the clawback, no fee
[PermissionKey("cards.withdraw-card-dispute")] public record WithdrawCardDisputeCommand(CardDisputeId Id, string Reason) : ICommand { … }
public sealed class CardDisputeApproverViewReader() : DocumentApproverViewReader<CardDisputeSummary, CardDisputeId>("CardDispute");
public sealed class CardDisputeIsItsOwnHolder() : SelfHoldingAggregate("CardDispute");
public sealed class CardDisputeSummary { CardDisputeId Id; CardId Card; AccountId Account; TransactionId Transaction; decimal Amount; CurrencyId Currency; MerchantCategoryCode Mcc; string MerchantName; CardDisputeReasonCodeId Reason; ProvisionalCreditRule CreditRule; CardDisputeStage Stage; CardDisputeOutcome? Outcome;
    DateOnly RaisedOn; DateOnly? DueOn; bool Overdue; string? SchemeCaseReference; string ProcessorDisputeReference; TransactionId? Credit; DateOnly? CreditValueDate; TransactionId? Clawback; TransactionId? Fee; List<CardDisputeForgonePosting> Forgone;
    List<CardDisputeSettlement> Settlements; List<CardDisputeEvidenceSummary> Evidence; string? WithdrawReason; DateOnly? ClosedOn }
public sealed record CardDisputeEvidenceSummary(string Description, AttachmentId? File, string? ProcessorReference, EvidenceSource Source, UserId? By, DateOnly On);
public sealed record CardDisputeForgonePosting(CardDisputePostingKind Kind, decimal Amount, DateOnly On);  public sealed record CardDisputeSettlement(string Reference, decimal Amount, CurrencyId Currency, DateOnly On);
// As shipped: no CardDisputeByTransaction document — the raise reads the transaction's disputes from CardDisputeSummary (landing notes).
// CardDisputeSummary as shipped also carries SchemeAmount, SchemeCurrency, StageEnteredOn and PurchaseValueDate; CardDispute carries ClosedFrom, OwesCaseFee and PostingOwedOnClose.
// A close publishes one PostCardDisputeMoneyCommand; a lost arbitration's fee rides behind its clawback in the same handler run.
[PermissionKey("cards.view-card-dispute")] public record GetCardDisputeQuery(CardDisputeId Id) : IQuery<CardDisputeSummary?>;  [PermissionKey("cards.list-card-disputes-for-card")] public record ListCardDisputesForCardQuery(CardId Card) : IQuery<IReadOnlyList<CardDisputeSummary>>;   // 404 for an unknown dispute or card
// CardDisputeSummary also carries string ReasonLabel (from the row at the raise) and DueOn clears on Close; the summary projection is Inline. Namespaces: LedgerTM.Cards.Application.Disputes; settings in LedgerTM.Cards.Domain.
// Routes: POST /api/card-disputes (raise), POST /api/card-disputes/{id}/{evidence|escalate|concede|withdraw}, GET /api/card-disputes/{id}, GET /api/cards/{cardId}/disputes. Feature key cards.disputes (child of cards.issuing) on every endpoint, the panel and the steps.

// src/LedgerTM.Cards/Application/Doors/RecordCardDisputeUpdate.cs — new (D3); the ReverseCardAuthorisation shape
[PermissionKey("cards.record-card-dispute-update")] public record RecordCardDisputeUpdateCommand(CardDisputeUpdate Update, InstitutionConnectionId Connection) : ICommand, IExternallyAuthenticatedCommand, IConnectionScoped { Target "CardDisputeUpdate", Update.Id }
// [WolverinePost("/api/cards/disputes/update")]; the mapper mints Update.Id; CardDoorGuard.RequireTheProcessorsConnection as the other doors.
// Handler: finds the dispute by processor reference (unknown → UnknownDispute; a stage behind the current → Stale; a repeated Id → the stored receipt; nothing moves); applies as reported, skipped stages included:
//   Represented → RecordRepresentment with ResponseDays; Arbitration → RecordArbitration with ArbitrationDays; the same stage with a new case reference → RecordCaseReference; Closed with an outcome → Close, then the cascade (bite 4); Closed without one, or an outcome on an open stage → Refused (CARD_DISPUTE_UPDATE_INVALID).

// src/LedgerTM.Cards/Application/DayEnd/CardDisputeDeadlinesStep.cs — new (D4, F5)
public sealed class CardDisputeDeadlinesStep(IMessageBus bus) : IDayEndStep   // "cards.dispute-deadlines", 47, PreIncrement, NonCritical, FeatureKey "cards.disputes"
[PermissionKey("cards.watch-card-dispute-deadlines")] public record WatchCardDisputeDeadlinesCommand(DateOnly TradingDate) : ICommand, ISystemCommand { Target "CardDisputeDeadlines" }   // takes ADR-836's landed step-command shape
// Handler: for every open dispute: Stage == Represented (the bank's window) and DueOn − WarnDaysBeforeDeadline <= TradingDate → RequestCardDisputeFollowUpTaskCommand(Deadline, DueOn); DueOn < TradingDate and not Overdue → MarkOverdue. Outcome Completed(tasks + overdue, note).

// src/LedgerTM.Cards/Application/DayEnd/CardClearingSteps.cs — SimulateCardDisputesStep ("cards.simulate-disputes", 48, PreIncrement, RequiresSimulation => true, FeatureKey "cards.disputes") (D8); AmendCardProcessorCommand gains SimulatedDisputeOutcome
[PermissionKey("cards.simulate-card-disputes")] public record SimulateCardDisputesCommand(DateOnly TradingDate) : ICommand, ISystemCommand { Target "CardProcessorSimulation" }
// Handler: through the real door (AsTheProcessorAsync): a Raised dispute at floor(RepresentmentDays/2) days is represented with scripted evidence ("merchant-evidence-{ref}"); a PreArbitration dispute at floor(PreArbitrationDays/2) moves to Arbitration with a case reference;
//   an Arbitration dispute at floor(ArbitrationDays/2) is ruled: Won, Lost, or ByAmountParity on floor(the disputed Amount) — 12 000 wins, 12 001 loses. Each move fires once per stage, on the first close at or after stage entry (On) + the midpoint. Lapses are never simulated.
// The door's wire body for the simulated processor is CardDisputeUpdate itself in camelCase without Id (the mapper mints it); the door answers 200 with the receipt for every outcome, Refused included. ClosedOn is the update's On. A Raised update on a Raised dispute is Stale; RecordSettlement is allowed on a closed dispute.
// src/LedgerTM.Cards/Domain/CardProcessorSettings.cs — changed (D8)
public SimulatedDisputeOutcome? SimulatedDisputeOutcome { get; set; }   // enum { Won, Lost, ByAmountParity } (Contracts/Cards); the simulator alone reads it; null → ByAmountParity

// Configuration (D5, D6) — AccountTypesSettings.yaml, every type carrying cardPurchase:
//   a deposit type: CardDisputeCredit (Cr Current), CardDisputeClawback (Dr Current); operations card-dispute-credit / card-dispute-clawback → inputs amount, disputeId, merchantCategory, merchantName, merchantCountry; postTransaction $amount
//   CreditCard: PurchaseDisputeCredit (Cr PurchaseBalance, Cr Outstanding, Cr CyclePurchases), CashAdvanceDisputeCredit (Cr CashAdvanceBalance, Cr Outstanding); PurchaseDisputeClawback / CashAdvanceDisputeClawback the reverse, costOfCreditCategory None;
//     the workflows branch on $merchantCategory exactly as card-purchase does (6010/6011 → cash advance) — fixed legs, no min() split; the clawback lands in today's cycle with normal grace
//   externalIntegrations cardDisputeCredit → card-dispute-credit, cardDisputeClawback → card-dispute-clawback; the credit card's GraceStatusUpdate row: onRevaluation: KeepHigher
// PostingSettings.yaml: GL account "Chargeback receivable — card schemes" (balance sheet); the credit rows Dr it, Cr the deposit liability / the card receivable; the clawback rows the reverse. The receivable clears in the merchant settlement ADR.
// The close cascade (bite 4): Won/MerchantAccepted under OnOutcome → PostCardDisputeMoneyCommand(Credit); under OnRaise nothing. Lost/Withdrawn with a credit posted → PostCardDisputeMoneyCommand(Clawback).
//   Lost at Arbitration → PostCardDisputeMoneyCommand(Fee), whatever the credit rule; RecordFee on success, RecordPostingForgone(Fee) on an inactive account. A Withdrawn OnRaise dispute claws back. A settlement line's amount is recorded as reported.
//   A Chargeback line's settlement never closes; the processor's Closed update does.

Bites

Bite Description Acceptance criterion Status
1 Contracts: the ids, the commands, the events, the queries, the processor seam’s five calls, the two Accounts posting commands, the task command, AttachmentId moved; the reason-code and dispute settings with their validators, reads, settings pages and template rows; the dispute-credit and clawback rows and integrations on the fundable types; the onRevaluation row flag (AsRecorded, KeepHigher, KeepLower, Set rows only) with its unit tests a reason code names its category, its credit rule and its clocks; a row marked as recorded replays its recorded value Done
2 The aggregate and its verbs: raise (with the credit when the rule says so, cascaded), evidence, escalate, concede, withdraw; the one-open-per-transaction invariant and the ordinal id; the posting index; the summary and the card’s disputes read raising a fraud dispute credits the cardholder at once, value-dated as the purchase; a merchandise dispute credits on outcome; a transaction has one open dispute at a time; the bank concedes a represented dispute Done
3 The door and the processor: CardDisputeUpdate with its receipt, the adapter’s five calls, the simulation step playing the scheme the merchant’s representment moves the dispute and starts its clock; the simulator rules by amount parity Done
4 The outcome’s money: the OnOutcome credit, the clawback, the case fee, the forgone posting and its task; the grace status restored where the purchase alone cost it, never removed; the chargeback clearing line recorded on its dispute a won dispute credits on outcome and a won credit is final; a lost dispute claws back the credit and charges the case fee; a dispute credit reprices the interest and may restore the interest-free period but never remove it; the scheme’s chargeback line is recorded and moves nothing Done
5 The deadlines step at 47: the warning task, Overdue a deadline raises a task and passes into overdue Done
6 The Disputes panel, the Dispute action on a card posting, the dispute viewer, the sample dispute, the probe, the guide article, the register rows an operator raises and follows a dispute on the screens Done

Scenarios

Feature: a cardholder's dispute runs the scheme's stages inside the ledger

# Bite 1
Scenario: a reason code names its category, its credit rule and its clocks
  Given the retail tenant's dispute reason codes
  When Visa 10.4 and Visa 13.1 are read
  Then 10.4 is a fraud code that credits the cardholder on raising, filed within 120 days, with 30-day windows at the three contested stages and 45 days at arbitration
  And 13.1 is a consumer-dispute code that credits on outcome
  And a row whose key is not its scheme and code, or whose window is outside a day and two years, is refused
  # Seen at: route:/settings/card-dispute-reason-codes

# Bite 1
Scenario: a row marked as recorded replays its recorded value
  Given an account whose scheduled row sets a status from a balance and is marked as recorded
  When a back-dated posting re-walks the account so the balance on that day differs
  Then every amount row re-evaluates and the status row replays the value it recorded
  And a row marked keep-higher posts the higher of its recorded and its re-walked value, and a row marked keep-lower the lower
  And the mark is refused on a row that is not a set row
  # Seen at: none

# Bite 2
Scenario: raising a fraud dispute credits the cardholder at once, value-dated as the purchase
  Given a card purchase of 12 000 value-dated 10 September posted to the demo customer's credit card
  When a clerk raises a dispute on it on 20 September under a fraud code that credits on raising
  Then the dispute is raised with the next move due in the code's window
  And the account is credited 12 000 as a dispute credit value-dated 10 September, naming the dispute
  And when the funding account is not active, the dispute is still raised and the credit is recorded as forgone with a task to the disputes group
  # Seen at: route:/card-disputes/{id}

# Bite 2
Scenario: a merchandise dispute credits on outcome
  Given a card purchase of 3 000 posted to the demo customer's current account
  When a clerk raises a dispute on it under a consumer-dispute code
  Then the dispute is raised and nothing is credited
  And the dispute reads that its credit waits for the outcome
  # Seen at: route:/card-disputes/{id}

# Bite 2
Scenario: a transaction has one open dispute at a time
  Given a card purchase with an open dispute
  When a clerk raises a second dispute on it
  Then the second is refused, naming the open one
  And after the first closes, a second may be raised while the code's filing window allows
  And a dispute for more than the line less the scheme's reversals already posted against it and the disputes already won is refused
  And a dispute on a refund, on a reversal, or on a posting no clearing line made is refused
  # Seen at: route:/card-disputes/{id}

# Bite 2
Scenario: the bank concedes a represented dispute
  Given a represented fraud dispute for 12 000 with the credit posted
  When a clerk concedes to the merchant's evidence
  Then the dispute closes lost on the processor's word, with no case fee
  And the bank's own evidence recorded before conceding is on the trail and was sent to the processor
  # Seen at: route:/card-disputes/{id}

# Bite 3
Scenario: the merchant's representment moves the dispute and starts its clock
  Given a raised dispute with a 30-day window
  When the processor reports the merchant's representment with an evidence reference
  Then the dispute is represented, the evidence is on its trail, and the next move is due 30 days on
  And the processor reporting the same update again changes nothing
  And the processor reporting a stage the dispute has passed, or a dispute the ledger never raised, changes nothing and says so in its receipt
  # Seen at: route:/card-disputes/{id}

# Bite 3
Scenario: the simulator rules by amount parity
  Given the simulated tenant set to rule by amount parity
  When a dispute for 12 000 and a dispute for 12 001 reach arbitration and the scheme's window reaches its midpoint
  Then the first closes won and the second closes lost
  # Seen at: route:/card-disputes/{id}

# Bite 4
Scenario: a won dispute credits on outcome and a won credit is final
  Given a consumer dispute for 3 000 on a purchase of 10 September, under a code that credits on outcome
  When the dispute closes as won on 12 November
  Then the disputed 3 000 is credited to the account value-dated 10 September
  And the customer's balance is what it would have been had the purchase never posted
  And a won fraud dispute whose credit posted at the raise posts nothing further
  # Seen at: route:/accounts/{id}

# Bite 4
Scenario: a lost dispute claws back the credit and charges the case fee
  Given a fraud dispute for 12 001 with the credit posted, and a case fee of 250
  When the dispute closes as lost at arbitration on 12 November
  Then the credit is clawed back by a debit of 12 001 value-dated 12 November, in that day's cycle
  And the case fee of 250 posts to the funding account as a card fee
  And a dispute withdrawn by the bank charges no fee
  And when the funding account is not active at the loss, the clawback is recorded as forgone and a task goes to the disputes group
  # Seen at: route:/accounts/{id}

# Bite 4
Scenario: a dispute credit reprices the interest and may restore the interest-free period but never remove it
  Given a credit card that lost its interest-free period at the due date only because of a purchase later disputed
  When the disputed amount is credited value-dated as the purchase
  Then the deferred and catch-up interest on that purchase re-walks to nothing
  And the interest-free period is restored, as it would have been had the purchase never posted
  And a card that would have lost it anyway keeps it lost, and a re-walk never takes away a grace the due date granted
  # Seen at: route:/accounts/{id}

# Bite 4
Scenario: the scheme's chargeback line is recorded and moves nothing
  Given a raised dispute for 12 000
  When the next clearing file carries a chargeback line naming the dispute for 12 000
  Then the settlement is recorded on the dispute with its amount
  And the dispute's stage is unchanged and nothing posts to the account
  And a chargeback line naming no dispute is recorded as an exception
  # Seen at: route:/card-disputes/{id}

# Bite 5
Scenario: a deadline raises a task and passes into overdue
  Given a represented dispute due in five days and warning days of five
  When day-end runs
  Then a follow-up task is raised to the disputes group naming the dispute and the date
  And when day-end runs the day after the due date the dispute reads overdue
  # Seen at: route:/card-disputes/{id}

# Bite 6
Scenario: an operator raises and follows a dispute on the screens
  Given the demo customer's card with a posted purchase
  When an operator raises a dispute from the posting and opens the card's Disputes panel
  Then the dispute shows its stage, its reason, its next due date and the credit posted
  # Seen at: panel:cardDisputes

Scenario → test

Scenario Bite Project Class Method Probe
a reason code names its category, its credit rule and its clocks 1 LedgerTM.Tests.Component CardDisputeReasonCodeSettingsTests a_reason_code_names_its_category_its_credit_rule_and_its_clocks — settings
a row marked as recorded replays its recorded value 1 LedgerTM.Tests.Unit RevaluationEngineTests a_row_marked_as_recorded_replays_its_recorded_value —
raising a fraud dispute credits the cardholder at once, value-dated as the purchase 2 LedgerTM.Tests.Component CardDisputeTests raising_a_fraud_dispute_credits_the_cardholder_at_once_value_dated_as_the_purchase adr-840-server-probe.ts
a merchandise dispute credits on outcome 2 LedgerTM.Tests.Component CardDisputeTests a_merchandise_dispute_credits_on_outcome adr-840-server-probe.ts
a transaction has one open dispute at a time 2 LedgerTM.Tests.Component CardDisputeTests a_transaction_has_one_open_dispute_at_a_time — refusal
the bank concedes a represented dispute 2 LedgerTM.Tests.Component CardDisputeTests the_bank_concedes_a_represented_dispute adr-840-server-probe.ts
the merchant’s representment moves the dispute and starts its clock 3 LedgerTM.Tests.Component CardDisputeDoorTests the_merchants_representment_moves_the_dispute_and_starts_its_clock adr-840-server-probe.ts
the simulator rules by amount parity 3 LedgerTM.Tests.Component CardDisputeDoorTests the_simulator_rules_by_amount_parity adr-840-server-probe.ts
a won dispute credits on outcome and a won credit is final 4 LedgerTM.Tests.Component CardDisputeOutcomeTests a_won_dispute_credits_on_outcome_and_a_won_credit_is_final adr-840-server-probe.ts
a lost dispute claws back the credit and charges the case fee 4 LedgerTM.Tests.Component CardDisputeOutcomeTests a_lost_dispute_claws_back_the_credit_and_charges_the_case_fee adr-840-server-probe.ts
a dispute credit reprices the interest and may restore the interest-free period but never remove it 4 LedgerTM.Tests.Component CardDisputeOutcomeTests a_dispute_credit_reprices_the_interest_and_may_restore_the_interest_free_period_but_never_remove_it —
the scheme’s chargeback line is recorded and moves nothing 4 LedgerTM.Tests.Component CardDisputeOutcomeTests the_schemes_chargeback_line_is_recorded_and_moves_nothing —
a deadline raises a task and passes into overdue 5 LedgerTM.Tests.Component CardDisputeDeadlinesTests a_deadline_raises_a_task_and_passes_into_overdue adr-840-server-probe.ts
an operator raises and follows a dispute on the screens 6 LedgerTM.Tests.Component CardDisputeViewerTests the_dispute_summary_and_the_cards_disputes_read_carry_the_stage_the_reason_the_due_date_and_the_credit adr-840-server-probe.ts

Reachability: EscalateCardDispute and WithdrawCardDispute are dispatched over HTTP by the one-open-dispute scenario, the GET endpoints by the viewer scenario; RecordCardDisputeEvidence is dispatched by the concession scenario; AmendCardDisputeSettings and the two settings reads by the reason-code settings test; PostCardDisputeMoney by the raise and outcome scenarios; SimulateCardDisputes by the parity scenario.

UI-surface sweep

Swept src/ui-apps/bank/src for dispute, Dispute, chargeback, cardDisputes, card-disputes, reasonCode:

Footprint

Feature projects touched: 10 — LedgerTM.Accounts, LedgerTM.Attachments, LedgerTM.Cards, LedgerTM.Contracts, LedgerTM.Hosting, LedgerTM.Infrastructure.Contracts, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, LedgerTM.Tasks, ui-apps

Contracts types: 52 named, 49 changed by this ADR

Files reading each changed type: 49 types

Domain events touched: 12 — CardDisputeCaseReferenceRecorded, CardDisputeClawbackPosted, CardDisputeClosed, CardDisputeCreditPosted, CardDisputeEscalated, CardDisputeEvidenceRecorded, CardDisputeFeeCharged, CardDisputeOverdue, CardDisputePostingForgone, CardDisputeRaised, CardDisputeRepresented, CardDisputeSettlementRecorded Aggregates touched: 1

Methods at CRAP 30+ in changed files: 7 (unit coverage at main 4b90dd253)

Warnings

At land: 124 files touched, 93 predicted, 70 unplanned. LedgerTM.Testing.Builders/GenericAccountTestHelper.cs, LedgerTM.Tests.Architecture/CardVocabularyTests.cs, LedgerTM.Tests.Architecture/CascadedMoneyMoveTests.cs, LedgerTM.Tests.Architecture/MessageRoutingCatalogTests.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.Architecture/replay-safe-outer-writes.txt, LedgerTM.Tests.Component/Attachments/Attachments/DeleteAttachmentTests.cs, LedgerTM.Tests.Component/Attachments/Attachments/UpdateAttachmentTests.cs, LedgerTM.Tests.Component/Cards/CardDisputeReasonCodeInUseTests.cs, LedgerTM.Tests.Unit/AccessControl/PermissionKeyPinTests.cs, LedgerTM.Tests.Unit/Attachments/Attachments/CreateAttachmentTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Accounts/Application/Settings/AccountTypesSettingsValidator.cs, src/LedgerTM.Accounts/Application/Settings/OnRevaluationValidator.cs, src/LedgerTM.Accounts/Domain/Configuration/RevaluationBehaviour.cs, src/LedgerTM.Accounts/Domain/Valuation/RecordedRowOutcomes.cs, src/LedgerTM.Attachments/Bootstrapper.cs, src/LedgerTM.Attachments/Files/Application/AttachmentMembershipResolver.cs, src/LedgerTM.Attachments/Files/Application/Commands/CreateAttachment.cs, src/LedgerTM.Attachments/Files/Application/Commands/DeleteAttachment.cs, src/LedgerTM.Attachments/Files/Application/Commands/UpdateAttachment.cs, src/LedgerTM.Attachments/Files/Application/Projections/AttachmentReadModel.cs, src/LedgerTM.Attachments/Files/Application/Projections/AttachmentStagedReadProjector.cs, src/LedgerTM.Attachments/Files/Domain/Attachment.Events.cs, src/LedgerTM.Cards/Application/DayEnd/PostCardClearingBatch.cs, src/LedgerTM.Cards/Application/Disputes/CardDisputeHandling.cs, src/LedgerTM.Cards/Application/Disputes/CardDisputeSummary.cs, src/LedgerTM.Cards/Application/Disputes/CardPostingEventLabelResolver.cs, src/LedgerTM.Cards/Application/Disputes/ConcedeCardDispute.cs, src/LedgerTM.Cards/Application/Disputes/EscalateCardDispute.cs, src/LedgerTM.Cards/Application/Disputes/ListCardDisputesForCard.cs, src/LedgerTM.Cards/Application/Disputes/RecordCardDisputeEvidence.cs, src/LedgerTM.Cards/Application/Disputes/WithdrawCardDispute.cs, src/LedgerTM.Cards/Application/Processor/CardProcessorClient.cs, src/LedgerTM.Cards/Application/Processor/PaymentologyInboundMapper.cs, src/LedgerTM.Cards/Application/Processor/PaymentologyOutboundMapper.cs, src/LedgerTM.Cards/Application/Queries/GetCardProcessor.cs, src/LedgerTM.Cards/Application/Settings/AmendCardDisputeSettings.cs, src/LedgerTM.Cards/Application/Settings/AmendCardProcessor.cs, src/LedgerTM.Cards/Application/Settings/GetCardDisputeReasonCodes.cs, src/LedgerTM.Cards/Application/Settings/GetCardDisputeSettings.cs, src/LedgerTM.Cards/Domain/CardDispute.Events.cs, src/LedgerTM.Cards/Domain/CardDisputeSettings.cs, src/LedgerTM.Cards/Simulation/SimulateCardDisputes.cs, src/LedgerTM.Cards/Simulation/SimulateCommands.cs, src/LedgerTM.Infrastructure.Contracts/AccessControl/IGroupPermissionsReader.cs, src/LedgerTM.Infrastructure.Contracts/Features/FeatureCatalog.cs, src/LedgerTM.Infrastructure/AccessControl/GroupPermissionsReader.cs, src/LedgerTM.Seeding.Provisioning/PackageExporter.cs, src/LedgerTM.Seeding.Provisioning/PackageImporter.cs, src/LedgerTM.Seeding.Provisioning/tenant-templates/countries/gb/retail-bank/PriceSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/countries/za/retail-bank/PriceSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/CardDisputeReasonCodeSettings.yaml, src/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/CardDisputeSettings.yaml, src/ui-apps/bank/src/__tests__/feature-read-site-guard.test.ts, 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/accounts/generic/posting-actions.ts, src/ui-apps/bank/src/features/cards/card-dispute-dialogs.tsx, src/ui-apps/bank/src/features/cards/card-dispute-viewer.tsx, src/ui-apps/bank/src/features/cards/card-viewer.tsx, src/ui-apps/bank/src/features/cards/hooks/card-dispute-settings.ts, src/ui-apps/bank/src/features/cards/hooks/card-disputes.ts, src/ui-apps/bank/src/features/entity-types/card-dispute-settings.tsx, 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. Every bite starts after ADR-836 and ADR-838 land; bite 4 after ADR-837 and ADR-839 too (F1).

Notes

Landing notes