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

Findings for the ADR

Files touched

Bite 1 — the card fee

Bite 2 — renewal at day-end

Bite 3 — the demo, the guide, the probe

Prior art

Nothing changed since the grill. Two supporting shapes the signatures needed — RenewExpiringCardCredentialsCommand (the step’s tenant command, as every card step has one) and CardHandling.ChargeFeeAsync — carry no decision.

Interfaces

// src/LedgerTM.Contracts/Accounts/ProcessExternalSourceCommands.cs — new (D4), beside ProcessCardPurchaseCommand
[PermissionKey("accounts.process-card-fee")]
public record ProcessCardFeeCommand(AccountId AccountId, TransactionId TransactionId, PriceTypeId FeeType, DateOnly TradingDate, DateOnly ValueDate, string SourceRef) : ISystemCommand;
// SourceRef is the card's id. The handler: an account that is not Active → log, return nothing (F23); else run the type's cardFee integration with parameters amount = 0, feeType = FeeType.IdPart(),
// binding the account's price provider (IPriceProviderResolver.ResolveAsync(tenant, account); null → prices 0) and valueDate (F22), and supplying properties feeType, cardId through WorkflowDispatchContext.Properties (F24);
// the operation prices it: whenCondition price($feeType, valueDate) > 0 → postTransaction CardFeeCharged price($feeType, valueDate). Refused ACCOUNT_TYPE_DOES_NOT_ACCEPT_CARD_FEES without the integration;
// a price type with no price on the day is ADR-704's UnpricedOnDateException, dead-lettered (F23). No guard (F13). TransactionSource gains CardFee. TransactionId comes from the caller (F20).

// src/LedgerTM.Cards/Application/Commands/CardHandling.cs — changed (D4)
public static Task<object[]> MirroredAndChargedAsync(Card card, CardFee fee, IMessageBus bus);   // mirror as today, then publishes ChargeCardFeeCommand when the funding rule names an account; none → card.ForgoFee(fee, "no funding account") (F2, F21, F30)
// src/LedgerTM.Cards/Domain/Card.Events.cs — new (F30)
[MessageIdentity("cards.card-fee-forgone")] public record CardFeeForgone(CardId Id, PriceTypeId FeeType, string Reason, DateOnly On) : DomainEvent;
// ChargeCardFeeCommandHandler: an inactive funding account → the Accounts handler answers "forgone" and the Cards handler records CardFeeForgone(…, "funding account not active").
public readonly record struct CardFee(PriceTypeId Type, TransactionId Id, DateOnly On);        // Id from facts (F20): TransactionId.For($"{card.IdPart()}-card-issuance-fee"), For($"{newToken.IdPart()}-card-replacement-fee"), For($"{token.IdPart()}-{expiry}-card-renewal-fee")
// IssueCard publishes its own ChargeCardFeeCommand for a virtual card (no mirror there, F21).

// src/LedgerTM.Cards/Application/Commands/ChargeCardFee.cs — new (D4, F20, F21)
[PermissionKey("cards.charge-card-fee")]
public record ChargeCardFeeCommand(CardId Id, PriceTypeId FeeType, TransactionId Fee, DateOnly On) : ICommand, ISystemCommand { public AuthorisationTarget Target => new("Card", Id.Value); }
// Handler: reads the summary's funding rule; ProcessCardFeeCommand(fundingRule.Accounts[0], Fee, FeeType, On, On, SourceRef: Id.Value). A refusal dead-letters here, never in the card's own chain.

// src/LedgerTM.Cards/Domain/Card.cs — changed (D1, D3, F19)
public bool WasEverActive { get; }      // true from the first CardActivated or a virtual issue; IssueCard/ActivateCard charge card-issuance-fee only when it was false (F6)
public void Renew(CardCredential credential, DateOnly on);   // Require(CardVerb.Renew): Active or Suspended, a status-table row excluded from the menu; emits CardReissued(SameNumberNewExpiry, credential, on)
// Device credentials keep their own expiry (F26); ADR-836's decider does not check expiry on a device credential.

// src/LedgerTM.Cards/Application/Commands/RenewCardCredential.cs — new (D1)
[PermissionKey("cards.renew-card-credential")]
public record RenewCardCredentialCommand(CardId Id) : ICommand, ISystemCommand { public AuthorisationTarget Target => new("Card", Id.Value); }
// Handler: card.Require(CardVerb.Renew) (F19); processor.ReissueAsync(primary token, SameNumberNewExpiry); card.Renew(credential, on); OrderPlasticAsync for a plastic credential;
// MirroredAndChargedAsync(card, "card-renewal-fee", bus). A refusal from the processor surfaces as the DomainException the user's reissue raises. The expiry recorded is the processor's answer.

// src/LedgerTM.Cards/Application/DayEnd/CardRenewalStep.cs — new (D1, D2)
public sealed class RenewCardCredentialsStep(IMessageBus bus) : IDayEndStep   // Id "cards.renew-credentials", order 46, PreIncrement, NonCritical, FeatureKey "cards.issuing", RequiresSimulation false
[PermissionKey("cards.renew-expiring-card-credentials")]
public record RenewExpiringCardCredentialsCommand(DateOnly TradingDate) : ICommand, ISystemCommand { … }   // the tenant rides the envelope (F27); the handler takes IMessageBus
public sealed record CardRenewalStepResult(int Renewed, int Refused, string? Note);
// Handler: every CardSummary with Status Active or Suspended whose primary (non-device, open) credential's expiry month ends on or before TradingDate + the type's RenewalLeadDays (inclusive, no lower bound), read once per run;
// per card: bus.InvokeAsync(RenewCardCredentialCommand); any exception is counted as refused and the card named (display name, last four) in the note; never throws for a card.
// Outcome: Completed(renewed, note) when anything was attempted — the note carries the refused count and names (display name, or last four alone) — Skipped("nothing to renew") otherwise (F29). Each card's exception is caught before any retry policy (F33).
// [ReplaySafe(Guard = "a renewed credential leaves the selection; a re-run on the same date selects only what the first did not renew")] (F16).

// src/LedgerTM.Cards/Domain/CardTypesSettings.cs — changed (D1)
public int RenewalLeadDays { get; set; } = 45;   // yaml renewalLeadDays; validator (AmendCardTypes and provisioning): 1..365, below CredentialLifeYears * 365, and below the facet's SimulatedCredentialLifeMonths * 28 when set (F28)

// src/LedgerTM.Cards/Domain/CardProcessorSettings.cs — changed (D6)
public int? SimulatedCredentialLifeMonths { get; set; }   // set by SeedSimulationCardProcessor (two months); the simulator mints and reissues expiry = the tenant's trading date + months when set, else + the type's years (F4, F17, F25); refused when months × 28 does not clear the largest lead (F28); a live processor ignores it

// Configuration (D4, D5) — retail AccountTypesSettings.yaml, every type carrying cardPurchase:
//   transactionTypes: CardFeeCharged (Dr Current on a deposit type; Dr Fees, Dr Outstanding on CreditCard; costOfCreditCategory Fee where the type is regulated)
//   operations: card-fee → inputs amount (Decimal), feeType (String); steps: whenCondition price($feeType, valueDate) > 0 → postTransaction CardFeeCharged price($feeType, valueDate)
//   externalIntegrations: cardFee → card-fee
// PriceSettings.yaml: card-issuance-fee 0, card-replacement-fee 150, card-renewal-fee 0
// CardTypesSettings.yaml: renewalLeadDays: 45 on debit and virtual-debit (and credit, ADR-838)

Bites

Bite Description Acceptance criterion Status
1 ProcessCardFeeCommand, the cardFee integration and CardFeeCharged on the fundable types, the three price rows, the fee cascade on activation and on a new-number reissue, CardFeeForgone, the template test a replaced card is charged the replacement fee; a fee priced at nothing posts nothing; a fee on a closed funding account is forgone and recorded; a redelivered replacement fee posts once; CardFeeTemplateTests green Pending
2 RenewalLeadDays on the card type, the Renew verb, RenewCardCredentialCommand, RenewCardCredentialsStep at 46, the refusal note a credential about to expire is renewed at day-end; a refused renewal is tried again tomorrow; a lost card is not renewed; an already expired credential is renewed and an ordered or closed card is not; a renewed card is not renewed again the next day; a transport fault counts as a refusal and does not stop the next card; renewal is never offered on the operator’s menu; a renewal lead is one to 365 days and below the credential’s life Pending
3 The simulated life on the facet and its checks, the seed, the probe, the guide article, the day-end step in the operator’s step list an operator watches a renewal in the simulated tenant; a clerk’s reissue on the simulated tenant takes the simulated life; the facet refuses a simulated life that does not clear the largest lead; a live processor ignores the simulated life; the simulated tenant is seeded with a two-month life Pending

Scenarios

Feature: a card is renewed before it expires, and its fees are rows

# Bite 1
Scenario: a replaced card is charged the replacement fee
  Given an active card funded from a call deposit, and a replacement fee of 150
  When the card is reported stolen and reissued with a new number
  Then the old credential is closed and a new one minted
  And the call deposit is charged 150 as a card fee, naming the card
  # Seen at: route:/accounts/{id}

# Bite 1
Scenario: a fee priced at nothing posts nothing
  Given an issuance fee priced at 50 on one price list and at nothing on another, each list on a customer's funding account
  When a virtual card is issued for each customer, and a plastic card is activated for each
  Then the first list's funding accounts are charged 50 once per card, and the second's see no transaction
  And activating a replacement plastic on the first charges no second issuance fee
  # Seen at: route:/accounts/{id}

# Bite 1
Scenario: a fee on a closed funding account is forgone and recorded
  Given a lost card whose funding account has been closed
  When it is reissued with a new number
  Then the card is replaced, no fee posts, nothing dead-letters, and the card records the fee as forgone
  # Seen at: route:/cards/{id}

# Bite 1
Scenario: a redelivered replacement fee posts once
  Given a replaced card whose replacement fee has posted
  When the fee is delivered again
  Then the funding account still shows one card fee
  # Seen at: route:/accounts/{id}

# Bite 2
Scenario: a credential about to expire is renewed at day-end
  Given an active card with a wallet token whose credential's month ends exactly the lead days from the closing date
  When day-end runs
  Then the credential is reissued with the same number and the expiry the processor answered, and the wallet token keeps its own
  And a card with the same expiry on a type whose lead is a day shorter is left alone, and the step reports one renewal
  # Seen at: route:/cards/{id}

# Bite 2
Scenario: an already expired credential is renewed and an ordered or closed card is not
  Given cards in the window: one whose month has already ended, one plastic and active, one ordered and never activated, one closed
  When day-end runs
  Then the expired one and the plastic one are renewed, the plastic one ordering a new plastic on the same token, and the other two are untouched
  # Seen at: route:/cards/{id}

# Bite 2
Scenario: a renewed card is not renewed again the next day
  Given a card renewed last night whose wallet token still carries the old expiry month
  When the next day-end runs
  Then nothing is renewed and the step is skipped
  # Seen at: none

# Bite 2
Scenario: a transport fault counts as a refusal and does not stop the next card
  Given two cards due, one whose processor call faults
  When day-end runs
  Then the healthy card is renewed, the faulted one is unchanged and named in the note, and the step reports one renewal
  # Seen at: none

# Bite 2
Scenario: renewal is never offered on the operator's menu
  Given an active card and a suspended card
  When their menus are read
  Then each offers the clerk's reissue and neither offers a renewal
  # Seen at: route:/cards/{id}

# Bite 2
Scenario Outline: a renewal lead is one to 365 days and below the credential's life
  Given a card type with a life of <life> years
  When its lead is set to <lead> days
  Then it is <outcome>
  # Seen at: none

  Examples:
    | life | lead | outcome |
    | 1 | 364 | accepted |
    | 1 | 365 | refused |
    | 3 | 365 | accepted |
    | 3 | 366 | refused |
    | 3 | 0 | refused |

# Bite 2
Scenario: a refused renewal is tried again tomorrow
  Given an active card whose credential expires within the lead days and a processor that refuses the reissue
  When day-end runs
  Then the step completes, its note names the card, and the credential is unchanged
  And the next day-end, with the processor answering, renews it
  # Seen at: none

# Bite 2
Scenario: a lost card is not renewed
  Given a card reported lost or stolen and an active card, both with credentials expiring within the lead days
  When day-end runs
  Then the active card is renewed and the lost card's credential is unchanged
  And a suspended card in the same run is renewed too and stays suspended
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: an operator watches a renewal in the simulated tenant
  Given the simulated tenant, whose seed sets a simulated credential life of two months, and a lead of forty-five days
  When a card is issued and the trading date walks to forty-five days before its expiry month ends
  Then that day-end renews it to an expiry two months on, and the day-end log shows one renewal
  And the day before renews nothing, and the day after leaves the renewed card alone
  # Seen at: route:/cards/{id}

# Bite 3
Scenario: a clerk's reissue on the simulated tenant takes the simulated life
  Given the simulated tenant with a two-month life and two active cards
  When a clerk reissues one with the same number and the other with a new number
  Then both credentials expire two months from the trading date
  # Seen at: route:/cards/{id}

# Bite 3
Scenario Outline: the facet refuses a simulated life that does not clear the largest lead
  Given card types whose leads are <leads>
  When the processor facet is amended to a simulated life of <months> months
  Then it is <outcome>
  # Seen at: none

  Examples:
    | leads | months | outcome |
    | 45 | 1 | refused |
    | 45 | 2 | accepted |
    | 56 | 2 | refused |
    | 45, 60 | 2 | refused |
    | 45, 60 | 3 | accepted |

# Bite 3
Scenario: a live processor ignores the simulated life
  Given a processor facet naming a live processor that carries a simulated life of two months
  When a card is issued on a three-year type
  Then its expiry is three years on
  # Seen at: none

# Bite 3
Scenario: the simulated tenant is seeded with a two-month life
  Given the za-retail sample tenant
  When its seed has run
  Then its processor facet carries a simulated life of two months and every sample card's credential expires two months after its issue
  # Seen at: none

Scenario → test

Scenario Bite Project Class Method Probe
a replaced card is charged the replacement fee 1 LedgerTM.Tests.Component CardFeeTests a_replaced_card_is_charged_the_replacement_fee adr-839-server-probe.ts
a fee priced at nothing posts nothing 1 LedgerTM.Tests.Component CardFeeTests a_fee_priced_at_nothing_posts_nothing —
a fee on a closed funding account is forgone and recorded 1 LedgerTM.Tests.Component CardFeeTests a_fee_on_a_closed_funding_account_is_forgone_and_recorded —
a redelivered replacement fee posts once 1 LedgerTM.Tests.Component CardFeeTests a_redelivered_replacement_fee_posts_once —
every card-funding type carries the fee rows (F32) 1 LedgerTM.Tests.Unit CardFeeTemplateTests every_card_funding_type_carries_the_card_fee_rows_and_the_three_prices_exist — template
a credential about to expire is renewed at day-end 2 LedgerTM.Tests.Component CardRenewalTests a_credential_about_to_expire_is_renewed_at_day_end adr-839-server-probe.ts
a refused renewal is tried again tomorrow 2 LedgerTM.Tests.Component CardRenewalTests a_refused_renewal_is_tried_again_tomorrow —
a lost card is not renewed 2 LedgerTM.Tests.Component CardRenewalTests a_lost_card_is_not_renewed —
an already expired credential is renewed and an ordered or closed card is not 2 LedgerTM.Tests.Component CardRenewalTests an_already_expired_credential_is_renewed_and_an_ordered_or_closed_card_is_not —
a renewed card is not renewed again the next day 2 LedgerTM.Tests.Component CardRenewalTests a_renewed_card_is_not_renewed_again_the_next_day —
a transport fault counts as a refusal and does not stop the next card 2 LedgerTM.Tests.Component CardRenewalTests a_transport_fault_counts_as_a_refusal_and_does_not_stop_the_next_card —
renewal is never offered on the operator’s menu 2 LedgerTM.Tests.Component CardRenewalTests renewal_is_never_offered_on_the_operators_menu —
a renewal lead is one to 365 days and below the credential’s life — 5 rows 2 LedgerTM.Tests.Component CardRenewalTests a_renewal_lead_is_one_to_365_days_and_below_the_credentials_life (a [Theory], one row per example) — refusal
an operator watches a renewal in the simulated tenant 3 LedgerTM.Tests.Component CardRenewalSimulationTests the_simulated_tenant_renews_a_card_on_its_next_day_end adr-839-server-probe.ts
a clerk’s reissue on the simulated tenant takes the simulated life 3 LedgerTM.Tests.Component CardRenewalSimulationTests a_clerks_reissue_on_the_simulated_tenant_takes_the_simulated_life_from_the_trading_date —
the facet refuses a simulated life that does not clear the largest lead — 5 rows 3 LedgerTM.Tests.Component CardRenewalSimulationTests the_facet_refuses_a_simulated_life_that_does_not_clear_the_largest_lead (a [Theory]) — refusal
a live processor ignores the simulated life 3 LedgerTM.Tests.Component CardRenewalSimulationTests a_live_processor_ignores_the_simulated_life —
the simulated tenant is seeded with a two-month life 3 LedgerTM.Tests.Component CardRenewalSimulationSeedTests the_simulated_tenant_is_seeded_with_a_two_month_life_and_its_sample_card_carries_it — seed

UI-surface sweep

Swept src/ui-apps/bank/src for renewalLeadDays, credentialLifeYears, simulatedCredentialLifeMonths, cardFee, CardFeeCharged, renew:

Footprint

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

Contracts types: 20 named, 14 changed by this ADR

Files reading each changed type: 14 types

Domain events touched: 2 — CardReissued, SameNumberNewExpiry Aggregates touched: 1

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

Warnings

At land: 52 files touched, 46 predicted, 21 unplanned. LedgerTM.Testing.Builders/GenericAccountTestHelper.cs, LedgerTM.Tests.Architecture/ContractsClassificationPinTests.cs, LedgerTM.Tests.Architecture/MessageRoutingCatalogTests.cs, LedgerTM.Tests.Architecture/contracts-shared-surface-baseline.txt, LedgerTM.Tests.Architecture/replay-safe-outer-writes.txt, LedgerTM.Tests.Component/Cards/CardControlsAndFundingTests.cs, LedgerTM.Tests.Component/Cards/CardRenewalDispatchTests.cs, LedgerTM.Tests.Component/Cards/CurrentAccountExcessTests.cs, LedgerTM.Tests.Unit/AccessControl/PermissionKeyPinTests.cs, LedgerTM.Tests.Unit/Cards/CardOperationGuardParityTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, src/LedgerTM.Cards/Application/Commands/ActivateCard.cs, src/LedgerTM.Cards/Application/Commands/ReissueCard.cs, src/LedgerTM.Cards/Application/Queries/GetCardProcessor.cs, src/LedgerTM.Cards/Application/Settings/AmendCardProcessor.cs, src/LedgerTM.Cards/Bootstrapper.cs, src/LedgerTM.Cards/Simulation/SimulatorCard.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/ui-apps/bank/src/features/connectivity/card-processor-form.tsx, src/ui-apps/bank/src/features/entity-types/card-types.tsx

Land batches

One land, the whole ADR; reseed: true. Bite 1 starts after ADR-836 lands (the cardPurchase rows and ProcessCardPurchaseCommand it sits beside); bites 2 and 3 can start now.

Notes

Changed during the plan grill

Phase A (24 questions), the plan grill (12 press points) and three phase B authors ran 2026-10-02; F5–F33 record the rulings. The largest: Renew is a verb and a status-table row, not a second guard; fee ids derive from facts; the fee is published with its date and a typed fee type; the external-source path binds the price lookup and the value date, and an account with no pricing plan charges nothing; device tokens keep their own expiry and ADR-836’s decider skips the check on them; the simulator’s clock for a credential’s life is the trading date. Held: the three price rows, the step’s order and criticality, the lead’s default of 45.

Landing notes