[Ledger::Item] Route all custom_memo writes through HcbCode#update_custom_memo!

[garyhtou]

Summary of the problem

custom_memo is stored in three places: canonical_transactions, canonical_pending_transactions, and ledger_items. Ledger::Item#memo — the memo the ledger renders and searches — is a cached column computed in Ledger::Item#refresh! from the ledger item's own copy:

self.memo = self.custom_memo.presence || self.system_memo.presence || fallback_memo

HcbCode#update_custom_memo! is the only writer that keeps all three in sync, but five paths wrote the canonical transactions directly and left ledger_items.custom_memo NULL:

Path
CanonicalTransactionsController#set_custom_memo	organizer rename form
CanonicalPendingTransactionsController#update	organizer rename form
CanonicalPendingTransactionService::Settle	pending → settled memo copy
StripeCardService::Nightly	update_all, skips every callback
HcbCode#update_custom_memo! itself	fallback when hcb_codes.ledger_item_id is NULL

The first two are reachable from the ✏️ icons in hcb_codes/_transaction_history, hcb_codes/_pending_transaction_history and transactions/show.

A direct write does still fire ledger_item.refresh!, but refresh! reads the ledger item's own (still-NULL) custom_memo, so:

• linked-object transactions (donations, ACH transfers, card charges…) have a system_memo, so the rename is silently discarded — and refresh! cannot recover it;
• raw bank transactions have no system_memo and fall through to fallback_memo → ct.smart_memo, which is why calling refresh! looks like a fix for those. ledger_items.custom_memo stays NULL even then.

Since pg_search_scope :search_memo runs against ledger_items.memo, renamed transactions were also unfindable by their new name in the ledger.

The fifth path is why the others can't simply be re-pointed: hcb_codes.ledger_item_id is only back-linked when the transaction engine creates the item, so it is NULL for any transaction that adopted an existing one — and update_custom_memo! then fell back to writing the canonical transactions only.

Describe your changes

Every custom_memo write on CanonicalTransaction/CanonicalPendingTransaction now goes through HcbCode#update_custom_memo!.

• HcbCode#update_custom_memo! resolves ledger items through its transactions as well as its own ledger_item_id, then writes the canonical transactions, the pending transactions and every resolved ledger item — no early return, so a transaction with no ledger item is still renamed. It short-circuits when nothing would change, since each write cascades into Ledger::Item#map! and #refresh! per record.
• Ledger::Item#update_custom_memo! owns just its own transactions (keyed by ledger_item_id); group renames are HcbCode's job.
• Both rename controllers route through the HCB code, falling back to the ledger item and only writing the column directly when the transaction has neither. The pending-transaction controller keeps fronted/fee_waived as a normal update, and both only touch the memo when the param is submitted, so an absent field no longer clears it.
• Settle copies through the HCB code, and only when the pending transaction actually has a memo — routing a nil through update_custom_memo! would clear the memo on every record in the group. It also writes the pending transaction's ledger item: CanonicalPendingSettledMapping hands the canonical transaction over to that item after the transaction commits, and several settle paths (Settle::Donation, AdminController#set_wire) pair a pending transaction with a still-ungrouped HCB-000 canonical transaction, so the two HCB codes differ and the destination item would keep its old memo.
• StripeCardService::Nightly replaces update_all (which fired no callbacks at all) with a batched per-transaction rename, skipping any group where a transaction already carries an organizer's memo — the group write would otherwise stamp the default over it.
• Both rename forms prefill from the HCB code's memo rather than the record's own column, which is empty for transactions renamed before the group write existed. Submitting that blank field would have cleared the whole group.

Behaviour change worth a look

Renaming from the per-transaction ✏️ now renames the whole HCB code group instead of the single canonical transaction, matching what the HCB code page and the v4 API already did. Two consequences:

• Per-transaction memos within one group can no longer differ, and the surrounding copy ("Rename transaction") is now about the group.
• HCB-900-<year>_<week> groups every fee reimbursement for a week onto one HCB code and one ledger item, across organizations — so a group rename there is cross-org, and the write is wider than the single-event policy these two endpoints authorize against. HcbCodesController#update already had this reach; these endpoints didn't. Flagging rather than changing authorization in a bugfix — happy to split that out either way.

Remediation

Already-desynced rows are not repaired here. Maintenance::BackfillLedgerItemCustomMemosTask keys off ledger_item.hcb_code&.custom_memo, which is NULL for exactly the un-back-linked population above, so it needs to resolve the memo through the item's own transactions before it is re-run.

Test plan

bundle exec rspec spec/models spec/services spec/controllers spec/jobs spec/mailboxes — 1691 examples, the only failures being 4 that need the wkhtmltopdf binary and 2 that need Redis, neither available locally and neither memo-related. rubocop and erb_lint clean.

New specs cover each path (rename and clear) and pin the regressions worth guarding: settling must not clear a memo an organizer already set and must reach the item the transaction is handed to; the nightly must not stamp over a group that already has a memo; a rename must reach the ledger item when the HCB code is not back-linked; and a transaction with no ledger item must still be renamed alongside one that has it. Assertions are on custom_memo rather than memo, since fallback_memo reads the canonical transaction and masks a desynced item.

---

Generated by Claude Code