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
- F1 — every bite edits or configures work not yet on
main. The clearing post, the refund command the posting commands copy and thecardPurchasetypes (ADR-836), the credit card and its grace-status row (ADR-838), the card fee (ADR-839), the revaluation cascade (ADR-837 bite 5). Every bite starts after ADR-836 and ADR-838 land; bite 4 after ADR-837 and ADR-839 too. - F2 — the raise reads the line from the clearing post’s own index. ADR-836’s purchase
posting carries the merchant as properties and the line reference as its source reference, not
the card; so the post step writes a
CardPostingIndexdocument per posting (bite 2 edits ADR-836’s post step) and the raise handler reads it. One writer: the post step. Shape only. - F3 — the processor’s dispute calls need request and reference shapes the ADR names only in
prose:
CardDisputeRequest,CardDisputeReference,CardDisputeUpdate(the door’s body),CardDisputeEvidence. Declared under## Interfaces; bags of fields. - F4 — the deadlines group. Decision 4 says “the disputes group”;
CardDisputeSettingscarriesDisputesGroup(aUserGroupId, optional — a tenant with none gets the task offered to nobody, as the suspense-case task does). The ADR’s call. - F5 — the simulator reads the trading date, as ADR-839 F25 made it do for a credential’s life, in a step of its own at 48; a move it makes on day D is seen by the deadlines step at 47 on D+1, which is harmless since a midpoint is never a due date.
- F6 —
AttachmentIdmoves to Contracts in bite 1. It is a four-line record struct with no dependencies, declared insidesrc/LedgerTM.Attachments/Files/Domain/Attachment.cs, used in nine files of one project; an evidence reference freezes into an event. - F9 — two
RevaluationEngineTestsclasses already exist (Accounts/Commands/,Accounts/Runtime/); the row-flag tests joinAccounts/Commands/RevaluationEngineTests.cs. - F7 —
PostTransactionReversalCommandis not used. It ignores its amount, reverses at the original’s value date and undoes one leg of several; both dispute postings are new postings through the dispatcher (D6). - F8 — the status-row flag edits
RevaluationEngine, whoseBrentmethod is at CRAP 812 with no coverage;RevaluationEngineTests.a_row_marked_as_recorded_replays_its_recorded_valueand…a_row_marked_keep_higher_posts_the_higher_and_keep_lower_the_lower_of_its_recorded_and_re_walked_valueis written first. The dispatcher’s characterisation test is ADR-836 F16’s.
Files touched
Bite 1 — contracts, settings, the integrations
src/LedgerTM.Contracts/Cards/CardDispute.cs— new;CardDisputeId,CardDisputeReasonCodeId,CardDisputeStage,CardDisputeOutcome,CardDisputeCategory,ProvisionalCreditRule,CardDisputePostingKind,EvidenceSource,CardDisputeRequest,CardDisputeReference,CardDisputeUpdate,CardDisputeEvidence(F3)src/LedgerTM.Contracts/Cards/CardReceipts.cs—CardDisputeUpdateId,CardDisputeUpdateOutcome,CardDisputeUpdateReceiptsrc/LedgerTM.Contracts/Cards/CardClearing.cs—CardClearingItem.DisputeReference(nullable)src/LedgerTM.Contracts/Cards/ICardProcessor.cs— the five dispute calls;src/LedgerTM.Cards/Application/Processor/PaymentologyProcessor.cs,CardProcessorClient.cs,src/LedgerTM.Cards/Simulation/PaymentologySimulator.cs,LedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.cs— implement them (the adapter’s real mapping and the simulator’s play are bite 3; the stub’s scripting lands here)src/LedgerTM.Contracts/Attachments/AttachmentId.cs— moved out ofsrc/LedgerTM.Attachments/Files/Domain/Attachment.cs(F6); its nine call sites gain ausingsrc/LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs—ProcessCardDisputeCreditCommand,ProcessCardDisputeClawbackCommandsrc/LedgerTM.Contracts/Accounts/Triggers/TransactionSource.cs—CardDisputeCredit,CardDisputeClawbacksrc/LedgerTM.Contracts/Tasks/RequestCardDisputeFollowUpTaskCommand.cs— newsrc/LedgerTM.Tasks/Application/Commands/RequestCardDisputeFollowUpTask.cs— new; the handler in the suspense-case shape;src/LedgerTM.Tasks/Domain/TaskSubjectTypes.cs—CardDisputesrc/LedgerTM.Accounts/Domain/Configuration/ExternalIntegrations.cs,src/LedgerTM.Accounts/Yaml/ExternalIntegrationsYamlConverter.cs,src/LedgerTM.Accounts/Application/Settings/ExternalIntegrationsValidator.cs—CardDisputeCredit,CardDisputeClawback(yamlcardDisputeCredit,cardDisputeClawback; parametersamount,disputeId,merchantCategory,merchantName,merchantCountry)src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.cs— the two handlers, in the refund handler’s shapesrc/LedgerTM.Accounts/Domain/Configuration/ScheduledTransaction.cs(or its home),src/LedgerTM.Accounts/Yaml/…—OnRevaluationon a scheduled row (D6); the type load refuses it on a row that is not aSet(ACCOUNT_TYPE_ON_REVALUATION_SET_ONLY);AccountTypeWriterexports itsrc/LedgerTM.Accounts/Application/Commands/RevalueAccount.cs— a marked row replays, or keeps the higher or lower of, its recorded value (F8);src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.cs—ProcessToDate’s re-walk honours it the same waysrc/LedgerTM.Cards/Domain/CardDisputeReasonCodeSettings.cs,CardDisputeSettings.cs— new; the rows and their validatorssrc/LedgerTM.Cards/Application/Settings/AmendCardDisputeReasonCodes.cs,AmendCardDisputeSettings.cs,GetCardDisputeReasonCodes.cs,GetCardDisputeSettings.cs— newsrc/LedgerTM.Infrastructure.Contracts/AccessControl/PermissionCatalog.cs— every new key;FeatureKeys—cards.disputessrc/LedgerTM.Seeding.Provisioning/PackageModel.cs,tenant-templates/packages/retail-bank/CardDisputeReasonCodeSettings.yaml,CardDisputeSettings.yaml— new files; the starter setsrc/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/AccountTypesSettings.yaml— the dispute-credit and clawback rows, operations and integrations on every type carryingcardPurchase;onRevaluation: KeepHigheron the credit card’s grace-status rowsrc/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PostingSettings.yaml— a chargeback receivable GL account; the credit rows Dr it, Cr the deposit liability or the card receivable; the clawback the reversesrc/LedgerTM.Seeding.Provisioning/tenant-templates/packages/retail-bank/PriceSettings.yaml—card-dispute-fee(250) and its price-list rowsrc/ui-apps/bank/src/features/entity-types/card-dispute-reason-codes.tsx,card-dispute-settings.tsx— new;settings-class-map.ts,category-taxonomy.ts,app.tsx,lib/api.tsLedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv— the two settings classesLedgerTM.Tests.Unit/Accounts/Commands/RevaluationEngineTests.cs— the row-flag tests, first (F8, F9)LedgerTM.Tests.Component/Cards/CardDisputeReasonCodeSettingsTests.cs— new
Bite 2 — the aggregate
src/LedgerTM.Cards/Domain/CardDispute.cs,CardDispute.Events.cs— new; the verbs, the invariants, the events;src/LedgerTM.Hosting/event-identity.tsvsrc/LedgerTM.Cards/Application/Disputes/RaiseCardDispute.cs,RecordCardDisputeEvidence.cs,EscalateCardDispute.cs,ConcedeCardDispute.cs,WithdrawCardDispute.cs— new; commands, validators, handlers, endpointssrc/LedgerTM.Cards/Application/Disputes/PostCardDisputeMoney.cs— new; the cascaded system command posting the credit or the clawback and recording posted or forgone (D9)src/LedgerTM.Cards/Application/Disputes/CardDisputeSummaryProjection.cs,CardDisputeByTransactionProjection.cs— new; the summary and the per-transaction index (open dispute, ordinal, won so far)src/LedgerTM.Cards/Application/Disputes/CardPostingIndex.cs— new; the document the post step writes per posting (F2);src/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cs— the post step writes it, a schemeReversaladds to its refunded amountssrc/LedgerTM.Cards/Application/Disputes/GetCardDispute.cs,ListCardDisputesForCard.cs— newsrc/LedgerTM.Cards/Application/Disputes/CardDisputeApproverViewReader.cs— new; andCardDisputeIsItsOwnHoldersrc/LedgerTM.Cards/Bootstrapper.cs— the projections, the reader, the holderLedgerTM.Tests.Component/Cards/CardsComponentFixture.cs—ZarCurrentAccount,UseCreditCardsAsync,GrantCreditCardFacilityAsync,OpenRevolvingAccountAsync,IssueCreditCardAsync(the names ADR-838’s tests assume), the dispute integrations on every fixture type, the fixture card types fundable from the current account too, and ADR-838’s full price list pluscard-dispute-feeLedgerTM.Tests.Component/Cards/CardDisputeTests.cs— new
Bite 3 — the door and the processor
src/LedgerTM.Cards/Application/Doors/RecordCardDisputeUpdate.cs— new; the door, its receipt, the handler moving the disputesrc/LedgerTM.Cards/Application/Processor/IInboundMapper.cs,PaymentologyInboundMapper.cs,PaymentologyProcessor.cs,CardProcessorClient.cs— the five calls andMapDisputeUpdatesrc/LedgerTM.Cards/Simulation/PaymentologySimulator.cs,SimulateCommands.cs,src/LedgerTM.Cards/Application/DayEnd/CardClearingSteps.cs— the scheme played:RaiseDisputeAsyncanswers a case reference;SimulateCardDisputesStep(48,RequiresSimulation) andSimulateCardDisputesCommandmove due disputes at their window midpoints through the doorsrc/LedgerTM.Cards/Domain/CardProcessorSettings.cs,Application/Settings/CardProcessorFacet.cs,AmendCardProcessor.cs—SimulatedDisputeOutcomeLedgerTM.Tests.Component/Cards/CardDisputeDoorTests.cs— new
Bite 4 — the outcome’s money
src/LedgerTM.Cards/Application/Disputes/CloseCardDispute.cs— new; the close’s cascade: theOnOutcomecredit (won or merchant-accepted), the clawback (lost or withdrawn),ProcessCardFeeCommand(card-dispute-fee, lost at arbitration) on the dispute’s account, the forgone posting and its tasksrc/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cs— aChargebackline carrying a dispute reference is recorded on that dispute as settlement, with its amount; one carrying none staysCHARGEBACK_NOT_HANDLED(ADR-836’s file)LedgerTM.Tests.Component/Cards/CardDisputeOutcomeTests.cs— new
Bite 5 — the clocks
src/LedgerTM.Cards/Application/DayEnd/CardDisputeDeadlinesStep.cs— new;CardDisputeDeadlinesStep(47),WatchCardDisputeDeadlinesCommandLedgerTM.Tests.Component/Cards/CardDisputeDeadlinesTests.cs— new
Bite 6 — the screens, the sample, the probe, the guide, the register
src/ui-apps/bank/src/features/cards/card-disputes-panel.tsx,card-dispute-viewer.tsx,card-dispute-dialogs.tsx— new;card-viewer.tsxgains the panel;hooks/cards.ts;app.tsx(routecard-disputes/{id})src/ui-apps/bank/src/features/accounts/generic/panels/transactions-panel.tsx— Dispute on a card postingsrc/ui-apps/shared/src/generated/api-types.ts— regeneratedsrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSampleCards.cs— a raised dispute on the demo card’s sample purchasesrc/ui-apps/bank/ui-review/adr-uat/flows/adr-840-server-probe.ts— newdocs/guide/features/card-disputes.md,card-dispute-reason-codes.md— new;cards.md— the paneldocs/standards/README.md— PSD2 Art. 73 and the scheme rules rows; ADR frontmatterstandards:in the same commitLedgerTM.Tests.Component/Cards/CardDisputeViewerTests.cs— new
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:
- No hits: no dispute surface exists. Bite 6 adds the Disputes panel on
card-viewer.tsx(itsViewerConfig.panels, where ADR-836 adds the Holds panel), the Dispute action beside Reverse ontransactions-panel.tsx:37-209(which already decides per row whether a reversal is offered), the dispute viewer route, and two settings pages in the entity-types pattern (card-types.tsx). - Permission keys: every new command and query lands in
permissions.generated.tsthrough the catalog; the user keys gate the dialogs.
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
LedgerTM.Accounts— 7 changed, 0 newLedgerTM.Attachments— 1 changed, 0 newLedgerTM.Cards— 19 changed, 0 newLedgerTM.Contracts— 8 changed, 0 newLedgerTM.Hosting— 1 changed, 0 newLedgerTM.Infrastructure.Contracts— 1 changed, 0 newLedgerTM.Seeding.Provisioning— 4 changed, 0 newLedgerTM.Seeding.ZaRetail.Samples— 1 changed, 0 newLedgerTM.Tasks— 2 changed, 0 newui-apps— 5 changed, 0 new Files: 93 named, 80 code, 5 config
Contracts types: 52 named, 49 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)TransactionSource— fan-in 6, changed (LedgerTM.Accounts, LedgerTM.Books, LedgerTM.Contracts, LedgerTM.Payments, LedgerTM.Tax, ui-apps)CardProcessorSettings— fan-in 4, changed (LedgerTM.Cards, LedgerTM.Seeding.Provisioning, LedgerTM.Seeding.ZaRetail.Samples, ui-apps)AttachmentId— fan-in 2, changed (LedgerTM.Attachments, _creditplus)CardClearingItem— fan-in 2, changed (LedgerTM.Cards, LedgerTM.Contracts)ICardProcessor— fan-in 2, changed (LedgerTM.Cards, LedgerTM.Contracts)IExternallyAuthenticatedCommand— fan-in 2, referenced (LedgerTM.Cards, LedgerTM.Infrastructure.Contracts)ExternalIntegrations— fan-in 1, changed (LedgerTM.Accounts)CardDispute— fan-in 0, changedCardDisputeApproverViewReader— fan-in 0, changedCardDisputeByTransaction— fan-in 0, changedCardDisputeCategory— fan-in 0, changedCardDisputeDeadlinesStep— fan-in 0, changedCardDisputeEvidence— fan-in 0, changedCardDisputeEvidenceSummary— fan-in 0, changedCardDisputeForgonePosting— fan-in 0, changedCardDisputeId— fan-in 0, changedCardDisputeIsItsOwnHolder— fan-in 0, changedCardDisputeOutcome— fan-in 0, changedCardDisputePostingKind— fan-in 0, changedCardDisputeReasonCode— fan-in 0, changedCardDisputeReasonCodeId— fan-in 0, changedCardDisputeReasonCodeSettings— fan-in 0, changedCardDisputeReference— fan-in 0, changedCardDisputeRequest— fan-in 0, changedCardDisputeSettings— fan-in 0, changedCardDisputeSettlement— fan-in 0, changedCardDisputeStage— fan-in 0, changedCardDisputeSummary— fan-in 0, changedCardDisputeTaskPurpose— fan-in 0, changedCardDisputeUpdate— fan-in 0, changedCardDisputeUpdateId— fan-in 0, changedCardDisputeUpdateOutcome— fan-in 0, changedCardDisputeUpdateReceipt— fan-in 0, changedConcedeCardDisputeCommand— fan-in 0, changedEscalateCardDisputeCommand— fan-in 0, changedEvidenceSource— fan-in 0, changedGetCardDisputeQuery— fan-in 0, changedListCardDisputesForCardQuery— fan-in 0, changedPostCardDisputeMoneyCommand— fan-in 0, changedProcessCardDisputeClawbackCommand— fan-in 0, changedProcessCardDisputeCreditCommand— fan-in 0, changedProvisionalCreditRule— fan-in 0, changedRaiseCardDisputeCommand— fan-in 0, changedRecordCardDisputeEvidenceCommand— fan-in 0, changedRecordCardDisputeUpdateCommand— fan-in 0, changedRequestCardDisputeFollowUpTaskCommand— fan-in 0, changedRevaluationBehaviour— fan-in 0, changedSimulateCardDisputesCommand— fan-in 0, changedWatchCardDisputeDeadlinesCommand— fan-in 0, changedWithdrawCardDisputeCommand— fan-in 0, changed
Files reading each changed type: 49 types
AttachmentId— 16 filesLedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsvLedgerTM.Tests.Component/Attachments/Attachments/DeleteAttachmentTests.csLedgerTM.Tests.Component/Attachments/Attachments/UpdateAttachmentTests.csLedgerTM.Tests.Unit/Attachments/Attachments/CreateAttachmentTests.cssrc/LedgerTM.Attachments/Bootstrapper.cssrc/LedgerTM.Attachments/Files/Application/AttachmentMembershipResolver.cssrc/LedgerTM.Attachments/Files/Application/Commands/CreateAttachment.cssrc/LedgerTM.Attachments/Files/Application/Commands/DeleteAttachment.cssrc/LedgerTM.Attachments/Files/Application/Commands/UpdateAttachment.cssrc/LedgerTM.Attachments/Files/Application/Projections/AttachmentReadModel.cssrc/LedgerTM.Attachments/Files/Application/Projections/AttachmentStagedReadProjector.cssrc/LedgerTM.Attachments/Files/Domain/Attachment.Events.cssrc/LedgerTM.Attachments/Files/Domain/Attachment.cssrc/_creditplus/docs/superpowers/plans/2026-03-14-rook-phase1-foundation.mdsrc/_creditplus/docs/superpowers/plans/2026-03-15-phase2-multitenancy-auth.mdsrc/_creditplus/docs/superpowers/specs/2026-03-14-rook-option1-design.md
CardClearingItem— 8 filesLedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.csLedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txtLedgerTM.Tests.Component/Cards/CardClearingTests.csLedgerTM.Tests.Unit/Cards/PaymentologyClearingMapperTests.cssrc/LedgerTM.Cards/Application/Processor/IClearingFileMapper.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyClearingMapper.cssrc/LedgerTM.Cards/Simulation/PaymentologySimulator.cssrc/LedgerTM.Contracts/Cards/CardClearing.cs
CardDispute— 0 filesCardDisputeApproverViewReader— 0 filesCardDisputeByTransaction— 0 filesCardDisputeCategory— 0 filesCardDisputeDeadlinesStep— 0 filesCardDisputeEvidence— 0 filesCardDisputeEvidenceSummary— 0 filesCardDisputeForgonePosting— 0 filesCardDisputeId— 0 filesCardDisputeIsItsOwnHolder— 0 filesCardDisputeOutcome— 0 filesCardDisputePostingKind— 0 filesCardDisputeReasonCode— 0 filesCardDisputeReasonCodeId— 0 filesCardDisputeReasonCodeSettings— 0 filesCardDisputeReference— 0 filesCardDisputeRequest— 0 filesCardDisputeSettings— 0 filesCardDisputeSettlement— 0 filesCardDisputeStage— 0 filesCardDisputeSummary— 0 filesCardDisputeTaskPurpose— 0 filesCardDisputeUpdate— 0 filesCardDisputeUpdateId— 0 filesCardDisputeUpdateOutcome— 0 filesCardDisputeUpdateReceipt— 0 filesCardProcessorSettings— 23 filesLedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsvLedgerTM.Tests.Architecture/TenantSettingsFolderTests.csLedgerTM.Tests.Component/Cards/CardProcessorClientTests.csLedgerTM.Tests.Component/Cards/CardProcessorSettingsTests.csLedgerTM.Tests.Component/Cards/CardsComponentFixture.cssrc/LedgerTM.Cards/Application/DayEnd/CardClearingCommands.cssrc/LedgerTM.Cards/Application/Doors/CardDoorClock.cssrc/LedgerTM.Cards/Application/Doors/DecideCardAuthorisation.cssrc/LedgerTM.Cards/Application/Doors/DecideCardTokenProvisioning.cssrc/LedgerTM.Cards/Application/Doors/ReverseCardAuthorisation.cssrc/LedgerTM.Cards/Application/Processor/CardProcessorClient.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyProcessor.cssrc/LedgerTM.Cards/Application/Queries/GetCardProcessor.cssrc/LedgerTM.Cards/Application/Settings/AmendCardProcessor.cssrc/LedgerTM.Cards/Application/Settings/CardProcessorFacet.cssrc/LedgerTM.Cards/Domain/CardProcessorSettings.cssrc/LedgerTM.Cards/Simulation/SimulateCommands.cssrc/LedgerTM.Seeding.Provisioning/PackageExporter.cssrc/LedgerTM.Seeding.Provisioning/PackageImporter.cssrc/LedgerTM.Seeding.Provisioning/PackageModel.cssrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSampleCards.cssrc/LedgerTM.Seeding.ZaRetail.Samples/Steps/SampleData/SeedSimulationCardProcessor.cssrc/ui-apps/bank/src/features/settings/settings-class-map.ts
ConcedeCardDisputeCommand— 0 filesEscalateCardDisputeCommand— 0 filesEvidenceSource— 0 filesExternalIntegrations— 12 filesLedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsvLedgerTM.Tests.Unit/Accounts/Configuration/CashOperationsSystemOnlyTests.csLedgerTM.Tests.Unit/Accounts/Operations/EvaluationContextParityTests.csLedgerTM.Tests.Unit/Accounts/Yaml/ExternalIntegrationsYamlTests.csLedgerTM.Tests/Integration.CreditPlus/Application/Features/OtherFundedOriginationTests.cssrc/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.cssrc/LedgerTM.Accounts/Application/Queries/ForecastAccount.cssrc/LedgerTM.Accounts/Application/Services/ExternalSourceCheck.cssrc/LedgerTM.Accounts/Application/Settings/ExternalIntegrationsValidator.cssrc/LedgerTM.Accounts/Domain/Configuration/AccountType.cssrc/LedgerTM.Accounts/Domain/Configuration/ExternalIntegrations.cssrc/LedgerTM.Accounts/Yaml/ExternalIntegrationsYamlConverter.cs
GetCardDisputeQuery— 0 filesICardProcessor— 13 filesLedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.csLedgerTM.Testing.Infrastructure/TestingEnvironment.csLedgerTM.Tests.Architecture/CardVocabularyTests.csLedgerTM.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/IssueCardTests.cssrc/LedgerTM.Cards/Application/Processor/CardProcessorClient.cssrc/LedgerTM.Cards/Application/Processor/PaymentologyProcessor.cssrc/LedgerTM.Cards/Bootstrapper.cssrc/LedgerTM.Cards/Simulation/PaymentologySimulator.cssrc/LedgerTM.Contracts/Cards/ICardProcessor.cs
ListCardDisputesForCardQuery— 0 filesPostCardDisputeMoneyCommand— 0 filesProcessCardDisputeClawbackCommand— 0 filesProcessCardDisputeCreditCommand— 0 filesProvisionalCreditRule— 0 filesRaiseCardDisputeCommand— 0 filesRecordCardDisputeEvidenceCommand— 0 filesRecordCardDisputeUpdateCommand— 0 filesRequestCardDisputeFollowUpTaskCommand— 0 filesRevaluationBehaviour— 0 filesSimulateCardDisputesCommand— 0 filesTransactionSource— 51 filesLedgerTM.Tests.Component/Accounts/Disbursements/CreditDisbursementTests.csLedgerTM.Tests.Component/Accounts/ReverseTransaction/ReverseTransactionEndpointTests.csLedgerTM.Tests.Component/Accounts/TransactionHistoryExternalAccountTests.csLedgerTM.Tests.Component/Accounts/TransactionHistoryOrderingTests.csLedgerTM.Tests.Component/Books/PostTransactionTests.csLedgerTM.Tests.Component/Books/SubLedgerTestHelper.csLedgerTM.Tests.Unit/Accounts/Application/TransactionHistoryProjectionTests.csLedgerTM.Tests.Unit/Accounts/Commands/RevaluationEngineTests.csLedgerTM.Tests.Unit/Accounts/Disbursements/CreditDisbursementOnTransactionPostedTests.csLedgerTM.Tests.Unit/Accounts/IntegrationEvents/AccountTriggerProjectionTests.csLedgerTM.Tests.Unit/Accounts/ReverseTransactionTests.csLedgerTM.Tests.Unit/Accounts/Runtime/OpenItemRestoreTests.csLedgerTM.Tests.Unit/Accounts/Runtime/ReverseOrCancelTests.csLedgerTM.Tests.Unit/Accounts/Scenarios/NoticeExpiryWalkTests.csLedgerTM.Tests.Unit/Accounts/Workflows/WorkflowInterpreterTests.csLedgerTM.Tests.Unit/Payments/DirectCredits/InitiateDirectCreditOnTransactionPostedTests.csLedgerTM.Tests.Unit/Payments/DirectDebits/InitiateDirectDebitOnTransactionPostedTests.csLedgerTM.Tests.Unit/Tax/PostTaxToLedgerTests.csLedgerTM.Tests.WorkerHost/TransactionPostedTriggerSeparatedDispatchTests.cssrc/LedgerTM.Accounts/Application/Commands/OpenTradingDay.cssrc/LedgerTM.Accounts/Application/Commands/PostRailFeeCommandHandler.cssrc/LedgerTM.Accounts/Application/Commands/PostTransaction.cssrc/LedgerTM.Accounts/Application/Commands/ProcessDayEnd.cssrc/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.cssrc/LedgerTM.Accounts/Application/Commands/ProcessToDate.cssrc/LedgerTM.Accounts/Application/Commands/ReverseTransactionCommandHandler.cssrc/LedgerTM.Accounts/Application/Commands/UnwindSettlementCommandHandler.cssrc/LedgerTM.Accounts/Application/DayEnd/NoticeExpiryStep.cssrc/LedgerTM.Accounts/Application/DayEnd/ProvisionRecomputeStep.cssrc/LedgerTM.Accounts/Application/DayEnd/SmallBalanceWriteOffStep.cssrc/LedgerTM.Accounts/Application/Designer/DesignerForecast.cssrc/LedgerTM.Accounts/Application/FixedDepositRollover.cssrc/LedgerTM.Accounts/Application/IntegrationEvents/AccountTriggerProjection.cssrc/LedgerTM.Accounts/Application/InternalTransferTarget.cssrc/LedgerTM.Accounts/Application/Operations/AccountOperationResolver.cssrc/LedgerTM.Accounts/Application/Projections/AccountStatementLinesReadModel.cssrc/LedgerTM.Accounts/Application/Projections/SuspenseItemReadModel.cssrc/LedgerTM.Accounts/Application/Projections/TransactionHistoryReadModel.cssrc/LedgerTM.Accounts/Application/Queries/ForecastAccount.cssrc/LedgerTM.Accounts/Application/Queries/TransactionHistoryQuery.cssrc/LedgerTM.Accounts/Application/Settlement/SettlementAcceptance.cssrc/LedgerTM.Accounts/Application/Workflows/WorkflowInterpreter.cssrc/LedgerTM.Accounts/Domain/Account.Events.cssrc/LedgerTM.Accounts/Domain/Account.Posting.cssrc/LedgerTM.Books/Application/Integrations/PostTransactionToBooks.cssrc/LedgerTM.Contracts/Accounts/OpenItemCommands.cssrc/LedgerTM.Contracts/Accounts/Triggers/TransactionSnapshot.cssrc/LedgerTM.Contracts/Accounts/Triggers/TransactionSource.cssrc/LedgerTM.Payments/DirectDebits/Application/Integrations/InitiateDirectDebitOnTransactionPosted.cssrc/LedgerTM.Tax/Application/Integrations/PostTaxToLedger.cssrc/ui-apps/bank/src/lib/api.ts
WatchCardDisputeDeadlinesCommand— 0 filesWithdrawCardDisputeCommand— 0 files Implementations of changed types: 6AttachmentId— 2:AttachmentMembershipResolver(src/LedgerTM.Attachments/Files/Application/AttachmentMembershipResolver.cs),AttachmentReadModelProjection(src/LedgerTM.Attachments/Files/Application/Projections/AttachmentReadModel.cs)CardProcessorSettings— 1:AmendCardProcessorCommand(src/LedgerTM.Cards/Application/Settings/AmendCardProcessor.cs)ICardProcessor— 3:CardProcessorClient(src/LedgerTM.Cards/Application/Processor/CardProcessorClient.cs),PaymentologyProcessor(src/LedgerTM.Cards/Application/Processor/PaymentologyProcessor.cs),StubCardProcessor(LedgerTM.Testing.Infrastructure/Cards/StubCardProcessor.cs) Files reading a touched file by path: 5app.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.tscard-viewer.tsx—src/ui-apps/bank/src/__tests__/standard-table-rowhref-guard.test.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.cslib/api.ts—LedgerTM.Tests.Component/Books/CostCentreOperationAvailabilityTests.cs,src/LedgerTM.Accounts/Application/Queries/GetAccountDetail.cs,src/_creditplus/docs/architecture-overview.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-18-ui-phase2-account-config-counterparties.md,src/_creditplus/docs/superpowers/plans/2026-03-20-accounttype-crud-complete-fields.md,src/_creditplus/docs/superpowers/plans/2026-03-20-ui-polish-crud-validation.md,src/_creditplus/docs/superpowers/specs/2026-03-19-openapi-typescript-pipeline-design.md,src/ui-apps/bank/src/__tests__/field-kind-coverage-guard.test.ts,src/ui-apps/bank/src/__tests__/lib/api-no-drift.test.ts,src/ui-apps/bank/src/__tests__/window-location-guard.test.ts,src/ui-apps/bank/src/lib/api.ts,src/ui-apps/bank/src/lib/dev-act-as.tssrc/LedgerTM.Accounts/Domain/Valuation/AccountValuation.cs—LedgerTM.Tests.Architecture/EvaluationContextConstructionSiteTests.cs
Domain events touched: 12 — CardDisputeCaseReferenceRecorded, CardDisputeClawbackPosted, CardDisputeClosed, CardDisputeCreditPosted, CardDisputeEscalated, CardDisputeEvidenceRecorded, CardDisputeFeeCharged, CardDisputeOverdue, CardDisputePostingForgone, CardDisputeRaised, CardDisputeRepresented, CardDisputeSettlementRecorded Aggregates touched: 1
Attachment—src/LedgerTM.Attachments/Files/Domain/Attachment.cs
Methods at CRAP 30+ in changed files: 7 (unit coverage at main 4b90dd253)
LedgerTM.Accounts.Domain.Valuation.AccountValuation.Brent— CRAP 812, complexity 28, 0% covered —src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.csLedgerTM.Accounts.Application.Commands.ExternalSourceDispatcher.BuildEvaluationContext— CRAP 506, complexity 22, 0% covered —src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.csExternalSourceDispatcher.DispatchAsync— CRAP 420, complexity 20, 0% covered —src/LedgerTM.Accounts/Application/Commands/ProcessExternalSourcePaymentHandlers.csLedgerTM.Accounts.Domain.Valuation.AccountValuation.RunSecant— CRAP 57, complexity 56, 95% covered —src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.csLedgerTM.Accounts.Domain.Valuation.AccountValuation.BuildContext— CRAP 46, complexity 46, 94% covered —src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.csLedgerTM.Accounts.Domain.Valuation.AccountValuation.SolveInstalment— CRAP 45, complexity 24, 67% covered —src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.csLedgerTM.Accounts.Domain.Valuation.AccountValuation.ProcessScheduledTransactions— CRAP 32, complexity 32, 100% covered —src/LedgerTM.Accounts/Domain/Valuation/AccountValuation.csPermission keys to add: 17 — concede-card-dispute, escalate-card-dispute, i, i-externally-authenticated, i-system, post-card-dispute-money, process-card-dispute-clawback, process-card-dispute-credit, raise-card-dispute, record-card-dispute-evidence, record-card-dispute-update, request-card-dispute-follow-up-task, simulate-card-disputes, watch-card-dispute-deadlines, withdraw-card-dispute, get-card-dispute-query, list-card-disputes-for-card-query
Warnings
TransactionSourceis changed and read by 6 projects — name the seam in the ADR.CardProcessorSettingsis changed and read by 4 projects — name the seam in the ADR.- A domain event is touched — set
reseed: trueand say so in the plan. LedgerTM.Accounts.Domain.Valuation.AccountValuation.Brentis at CRAP 812 (and 4 more in that file) — write its test before the bite edits it, and name the test in the plan.LedgerTM.Accounts.Application.Commands.ExternalSourceDispatcher.BuildEvaluationContextis at CRAP 506 (and 1 more in that file) — write its test before the bite edits it, and name the test in the plan.- 10 feature projects touched — say why this is not two ADRs.
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
- The amount disputed may be part of the line; the credit and the clawback follow the disputed amount, the processor’s amount is the remaining original amount or a part prorated on the original and rounded to its ISO 4217 minor unit, and the fee is the price row’s.
- The money is two postings, never a reversal. The credit is value-dated as the purchase whenever it posts, with fixed legs by merchant category; the clawback is value-dated today. Nothing is reversed through ADR-261 (F7).
- A chargeback clearing line (ADR-836’s
CardClearingItemKind.Chargeback) carries the processor’s dispute reference; the post step records it on that dispute as settlement with its amount, posts nothing itself, never moves the stage, and recordsCHARGEBACK_NOT_HANDLEDonly for a line carrying no reference or one matching no dispute. onRevaluationis generic engine configuration on anySetrow; this ADR adds it and marks the credit card’s grace-status rowKeepHigher. A forgone fee is recorded at the price row’s amount; a clawback and a fee forgone on one day share one task. The re-walk of an external posting is ADR-837 bite 5; both lanes build on whichever lands first (Landing notes).- Three feature projects (Accounts, Cards, Tasks) plus seeding, UI and hosting: Accounts
carries the two postings and the row flag, Tasks the follow-up task, Cards the rest. The
footprint’s CRAP 30+ methods:
RevaluationEngine(F8, test first) and the dispatcher (ADR-836 F16’s characterisation test). - The simulation’s clock is the trading date (ADR-839 F25); the simulation step at 48 moves disputes at their window midpoints through the real door, so a test needs no wall-clock wait.
- Fixtures. A stage reached only through the door (Represented, Closed) may be given in a
bite 2 test by appending the declared events to the dispute’s stream. The cards component
fixture gains the retail template’s
CreditCardtype and a current account beside its call deposits, each with the dispute integrations, and ADR-838’s price list pluscard-dispute-fee(an account with no plan prices it at 0, ADR-839 F22); a posting to dispute comes from ADR-836’s clearing post (store the batch, run the post step), which also writes the posting index; the stub processor scripts the five calls (next reference, refuse, calls made) and the door is driven over HTTP asCardReversalDoorTestsdrives its door. - The guide article names PSD2 Art. 73 and the scheme rules rows, the credit rule in every
worked example, and lifts its numbers from
CardDisputeOutcomeTests.
Landing notes
- ADR-837: the dispatcher’s revaluation cascade on a back-dated external posting (its bite 5) is what makes the dispute credit re-walk; whichever lane lands first builds it.
- ADR-838: the grace-status row carries
onRevaluation: KeepHigheronce ADR-840 bite 1 lands, so a re-walk may restore the interest-free period (D6 of this ADR refines ADR-838 D6: never removed, may be restored); the cards fixture gains theCreditCardtype and the helper names ADR-838’s tests assume when ADR-840 bite 2 starts. - ADR-838 / ADR-837 (observation, not this ADR’s): a purchase presented after its statement was
paid re-walks the due-date rows — catch-up, late fee, arrears — for a line the customer never
saw;
KeepHigherkeeps only the grace flag. F-1794 (P1), ruled by the operator on 2026-10-02: a late presentment is value-dated at presentation (recorded on ADR-838’s plan), soKeepHigherstays right and its “never remove” half is defensive only. The row flag as engine config is F-1795. - ADR-836:
CardClearingItemgains a nullableDisputeReference(the mapper fills it); the post step writesCardPostingIndexand records aChargebackline on its dispute once ADR-840 lands; a schemeReversaladds to the purchase row’s refunded amounts. - Attachments:
AttachmentIdmoves toLedgerTM.Contracts/Attachmentsin bite 1; nine call sites gain ausing. - Landing note (coordinator, 2026-10-03): ADR-840 (lane
cards-authorisation) sharesProcessExternalSourcePaymentHandlers.cs,ProcessExternalSourceCommands.cs,PackageModel.cs,event-identity.tsv,PermissionCatalog.cs,app.tsxandsettings-class-map.tswith ADR-845 (lanecashier-management). Built in parallel; the second to land resolves them. ADR-784 bite 4 (namespace move) waits for this lane and ADR-845 to land, then rebases onto both. - Decided: the
onRevaluationflag is honoured by the revaluation engine alone, through a recorded-outcomes overlay it sets onAccountValuation;ProcessToDatewalks forward from the day after the last processed day and never re-walks a recorded one · rests on: D6 · wrong if: a second caller ofInitAccountre-walks recorded days without the overlay. - Decided: each bite’s authored tests are copied in at the start of that bite and measured there, not all at once after bite 1. Bite 1’s files create the Contracts types; the Cards-side commands, events, queries and summary the later tests compile against are bite 2’s files and later, so a single pass after bite 1 cannot compile · rests on: the plan’s files-touched lists, ADR-787 D5 · wrong if: a bite’s test starts green and no probe was run on it.
- Decided: the dispute settings commands and reads are not bound to
cards.disputesin the feature catalog; their routes and tiles are, and bite 2 binds the operational keys · rests on: D9 (the screens and the step), ADR-363 D3 · wrong if: a tenant withcards.disputesoff can raise a dispute. - Decided:
IGroupPermissionsReadergainsGroupExists, which the disputes-group check reads; a feature project cannot read the group read model · rests on: F4, the dependency rule · wrong if:CARD_DISPUTE_SETTINGS_INVALIDrefuses a group the groups page lists. - Decided:
CardDisputeReasonCode.Idreadsdefaultfor a key that is not kebab-case, asCardType.Iddoes, so a blank key is the validator’s refusal and never a throw · rests on: ADR-422 · wrong if: a blank-key POST answers 500. - Decided: the card vocabulary rule exempts
ProvisionalCreditRule,EvidenceSourceandSimulatedDisputeOutcome, the names## Interfacesdeclares and the authored tests compile against · rests on: ADR-787 (never edit an authored test) · wrong if:CardVocabularyTestspasses with the exemptions removed. - Decided: the dispute GL leg is a new account 1008 “Chargeback receivable — card schemes”; the credit types carry BTC
PMNT/CCRD/CAJTand the clawbacksPMNT/CCRD/DAJT(ISO 20022 credit and debit adjustments);card-dispute-feeis 250.00 on the za lists and 15.00 on the gb lists · rests on: D5, D6 · wrong if: the za-retail trial balance shows a dispute credit against 2070. - Decided: the current account’s dispute posting types are neither postable nor reversible by a clerk, and the deposit operations declare only
amount, ascard-purchasedoes · rests on: D9 (system commands) · wrong if: the current account’s operations menu offers a dispute credit. - Note: the ADR’s
status:still readsAcceptedon the lane; the land advances it. - Decided: the raise targets the funding account (
AuthorisationTarget("Account", …)), as a card’s issue targets its owner; the dispute does not exist until the approved raise runs, and a target computed from the next ordinal reads as unreviewable on an uninitialised command · rests on: D9, ADR-780 D6 · wrong if: a captured raise cannot be read by its checker. - Decided: no
CardDisputeByTransactiondocument. The raise reads the transaction’s disputes fromCardDisputeSummary, filtered in memory as the house does for strong ids; a concurrent second raise still collides on the ordinal-derived stream id · rests on: D1 · wrong if: two open disputes ever share a transaction. - Decided:
ReasonLabelis filled from the reason-code row when a dispute is read, not stored;CardDisputeRaisedcarries the id only · rests on: D2 (the dispute holds the id) · wrong if: a relabelled row shows its old label on a dispute. - Decided: the money command catches the account’s own
ACCOUNT_NOT_ACTIVErefusal rather than reading availability first, asChargeCardFeeCommanddoes; a reader as a handler parameter opens its session before the tenant frame · rests on: D9, the untenanted-service gotcha · wrong if: a frozen account’s dispute credit posts. - Decided: a posting carries the dispute’s full id (
disputeId= the URN), the authored raise test’s reading · rests on: D5 · wrong if: a dispute credit’sdisputeIdproperty cannot be matched to its dispute. - Decided: the concede and withdraw keys are not bound to
cards.disputes; they run a dispute down, which ADR-363 D3 leaves open when a feature is off · rests on: ADR-363 D3 · wrong if: a tenant with disputes off is left with an open dispute it cannot close. - Decided: the door stores its receipt and appends the dispute’s events on one session, so a receipt never says Applied for a move that did not commit; a racing duplicate fails its commit rather than answering a second receipt · rests on: D3 · wrong if: a receipt reads Applied with no matching event on the dispute’s stream.
- Decided: the processor may report PreArbitration itself (a skipped stage applied as reported); it is recorded as the escalation event with no user and the update reference · rests on: D3 · wrong if: a processor-reported pre-arbitration lacks its due date.
- Decided: a close publishes one money message — the credit, the clawback, or the fee alone — and a lost arbitration’s fee rides behind its clawback in the same run, so two postings never race for one dispute’s stream; a clawback and a fee forgone together raise one task · rests on: D6, D9 · wrong if: a lost arbitration with a credit posted shows a clawback and no fee.
- Decided: the case fee is read from the funding account’s price row before it posts; a fee priced at nothing is neither charged nor forgone · rests on: D6, ADR-839 D4 · wrong if: a dispute shows a fee or a forgone fee on an account whose plan prices
card-dispute-feeat nothing. - Decided: the cards fixture’s credit-card type carries no active-card cap; the shared collection issues credit cards to one demo customer across tests, and no test relied on the cap of two · rests on: test isolation · wrong if: a credit-card cap test is added and passes against the fixture type.
- Decided: a represented dispute already past its due date still gets its one deadline task (the plan’s rule has no “not yet due” bound), and the overdue mark applies to every open stage · rests on: D4 · wrong if: a lapsed bank window raises no task.
- Decided: no sample dispute is seeded. The plan’s “raised dispute on the demo card’s sample purchase” has no purchase to stand on — no seed step posts a card purchase — and seeding one means a simulated authorisation and a clearing post at seed time, a bite of its own. The probe raises one on a posting the operator names · rests on: D9 (the screens), the demo seam · wrong if: the demo customer’s card shows a posted purchase after a reseed.
- Land: add
standards: [PSD2 (EU 2015/2366) Article 73, Card scheme dispute rules]to the ADR frontmatter and runmake adr-indexin the land commit; the register rows landed with bite 6, and a lane may not regenerate the index. - Decided: the card viewer and the transactions panel read the
cards.disputesfeature through registry resolvers (the viewer’s panel registry; a posting-actions registry), the house shape the feature read-site guard enforces · rests on: ADR-363 D7, ADR-411 D1 · wrong if: the Disputes panel or the Dispute action shows on a tenant with disputes off. - Box gate at 4c44fc726 (lane finished): script, docs, build, unit, integration (738 s), reachability and ui-build green;
uired on one test,account-actions-pay-out-suppression(“Unable to find the Pay Out button” after 1.6 s). It renders the transactions panel this lane changed. Locally it passes alone 5 of 5, and the full bank UI suite passes 1808 of 1808 on a rerun; a first local full run failed a different, untouched test (amend-collection-authority), so the pattern is a load-sensitive wait. The land gate’s UI stage is the authority; if it reds on the Pay Out test again, read it as this lane’s. - Correction (bite 4): the late-presentment test assumed a late line is value-dated as the purchase; F-1794 value-dates it at presentation. Re-dispatched to its author. The bite-4 test file also needed one missing
using(compile only). - Correction (bite 2): bite 2’s tests went in with its implementation, so no pre-implementation red was recorded for them. The bite-2 author fixed its own
TradingDateAsynchelper, which read the default tenant’s date; the bite-1 in-use tests needed one missingusing(compile only).