disbursement_funding

Archive an orphaned FA anchor. Unknown id -> success with empty data.

Code
An absent row is not an error (same as ``disbursements.get_detail``), so a
stale row the operator dismisses twice does not fail the page. Returning
``None`` here renders as ``data: []`` -- ``standard_response`` defaults
``data_type`` to list -- not as a JSON null.

One funding source's advisory available balance -- the Check balance action.

Code
Returns ``{available}``, and ``available`` is **null when the peek was
UNAVAILABLE** -- the vendor was unreachable or the integration is not
connected. Null is not zero, and the two must not render the same way:
showing $0.00 for an unreachable vendor tells an operator their funding
source is empty when it may be full. Render null as "Unavailable".

Advisory by design. The vendor marks this balance non-authoritative, so the
service swallows a transport failure rather than failing the page; a real
shortfall surfaces later as a rejected top-up. Gated 'r' -- it reads, and it
moves nothing.

Takes the BriteCore source row id, not a vendor reference; the stored handle
is resolved in the service. A source the vendor lists but BC has never
linked has no row id yet, so it cannot be checked -- link it first.

Is funding configured on this site, under which instance, and what may this caller do.

Code
Returns ``{connected, integration_instance_id, instance_count,
can_configure, can_move_money}``. The console reads this first:
``connected`` false with ``instance_count`` 0 is the not-configured state,
and greater than 1 is an ambiguous configuration the operator has to fix --
no instance id is returned for either, so no other endpoint here can be
called against a guess.

The two capability flags exist so the screens can DISABLE an action they
know will be refused, and say why, instead of letting the operator click it
and read an error. They are the page-load half of the rule this console
follows for permissions: render from the page-load read, re-check fresh on
the action, and always say why. Nothing is trusted to them -- every write
is still gated independently by its own ``@requires_permission`` at the
gateway and, for money, re-checked in the service. A caller who forges
``can_move_money`` gains exactly nothing.

Read at the API layer rather than in the service on purpose: this is an
authorization question about the *request*, and the service is also driven
by the ``bin/`` money drivers, which have no session and must not start
consulting one. The shared ``core.permissions.caller_may`` reports False without a
session rather than raising, mirroring ``_require_money_action_permission``:
no session means a trusted caller, which is not a browser, so the flags do
not pretend to know.

The FA's live balance, in dollars -- the overview's balance card.

Code
Returns ``available`` / ``incoming`` / ``outbound_pending``. The vendor is
the source of truth and nothing is stored, so this is what **Refresh**
re-reads.

Two limits the rendered figure inherits, both deliberate MVP positions from
BC-23640 and worth knowing before anyone treats ``incoming`` as exact: the
computed incoming does not follow pagination (one call, limit 100) and does
not count the payments-balance payout rail.

First-time link of a live vendor source into BC's waterfall.

Code
``priority`` defaults to 1 and is validated in the service against the
funding schema, so a non-waterfall position never reaches the column.

One page of the FA's live ledger -- the overview's Account activity card.

Code
Money is re-denominated to dollars at the service boundary. Pass the
previous response's ``next_pagination_cursor`` to fetch the next page, omit
it for the first (this is a user-paged "Load more", not a background sweep).

A row is credit, debit, trailing_balance, description and -- when the
integration system supplies it (BC-24754) -- ``posted_at``, the vendor's own
entry timestamp, passed through verbatim and null until the IS emits it.
There is still no entry id, type or status, so the mock's Type / Status
columns and its row menu cannot be rendered from this feed; see the plan's
D1.

BC's money-IN log for one FA, newest first -- the "Money added" card.

Code
Returns ``{items, has_more}``. Each row carries when / how much / from which
source / the outcome, plus the error context behind a non-success: outcome
``succeeded`` renders as Submitted (the bank accepted the pull), ``settled``
as Funded (the money arrived), ``returned`` as Returned (the bank sent it
back, before or after settlement -- code / reason in ``error_code`` /
``error``), ``vendor_rejected`` as Declined, and ``transport_failed`` as
Needs review -- the last meaning the response was lost and **money may have
moved**, never a clean failure. The settlement sweep (BC-24754) is what
advances ``succeeded`` to the two terminal states.

Takes no ``integration_instance_id``: this reads BC's own append-only log by
FA id and makes no vendor call, so there is no instance to dispatch against.
It is also why this card can disagree with the balance and activity cards
while a pull settles -- a row appears here at once, the vendor may take
hours to reflect it.

``limit`` is clamped in the service; a missing or non-positive value gets
the default page rather than an error.

The live vendor source set, left-joined with BC's stored waterfall state.

Code
Returns ``{items: [...]}`` in the engine's waterfall order -- (priority,
dateAdded, id), so ties come back the way the auto top-up reads them --
with never-linked sources last.
Each row carries the vendor payload plus ``source_id`` and ``priority``,
both null when the source has never been linked in BC -- that is the
``link_funding_source`` case, where a linked row re-prioritizes through
``set_source_priority`` instead.

Onboard a discoverable vendor FA as a BC anchor; returns the anchor.

Diff the live vendor FA set against BC's stored anchors; persists nothing.

Code
Returns ``{matched, discoverable, orphaned}``. ``matched`` rows carry both
sides (``stored`` anchor + live ``vendor`` payload) because the vendor owns
display / status / features and BC owns only the anchor; ``discoverable`` is
a vendor account the operator can onboard via ``manage_account``;
``orphaned`` is a stored anchor the vendor no longer returns, which
``archive_account`` clears. There is deliberately no ``drifted`` state.

Mint a vendor source-entry session and return the embed payload verbatim.

Code
The payload is vendor-shaped and modeled nowhere in BC; mounting it is
BC-23257 (S5). Gated 'rw' because it opens an add-a-source flow, not because
it moves money -- it does not.

Re-position an already-linked source in the waterfall by BC row id.

Code
Unknown id -> success with empty data (``data: []``, as in
``archive_account``). ``priority`` is required here and its
value is validated in the service -- unlike ``link_funding_source``, which
defaults an omitted position to 1: a first link has an obvious default, a
deliberate re-position does not. Use ``link_funding_source`` for a source BC
has never stored.

Pull amount dollars from a source into the FA -- this moves money.

Code
Backs Add money. With auto top-up and JIT both out of the MVP, this is the
only way money enters the funding account.

Three things about this endpoint are deliberate and should not be
"simplified" away:

1. **``request_id`` is caller-supplied and is the vendor Idempotency-Key.**
   The console mints it when the modal OPENS, not on submit -- that is what
   makes a double-click dedupe to one pull rather than two. A reused id
   describing different money is rejected outright.
2. **No ``initiated_by_contact_id`` parameter.** The service pins the
   initiator to the authenticated session (``_resolve_initiator``). Taking
   one from the body would let a permitted user attribute a real pull to
   another contact, and the permission gate proves only that the caller MAY
   move money, not that they ARE the submitted initiator.
3. **``commit_attempt=db.safe_commit`` -- the one place this module does not
   leave its write to the decorator.** The audit row must be durable INSIDE
   the service's per-FA lock: ``api_request``'s generic error handler rolls
   the session back, so without this hook any failure after the vendor pull
   would discard the row while the money had already moved. Committing
   early is also what lets a concurrent auto evaluation see the row it must
   debounce against. The decorator's own commit afterwards is a harmless
   no-op.

Gated on ``britecore/payments/funding/topUp`` (rw), NOT on the console's
config permission -- config rights must not imply moving money. The service
re-checks the same path independently.

Two service exceptions are allowed to propagate rather than being folded
into a tidy response, because both carry meaning a caller must not lose:
``FundingAuditIntegrityError`` (a pull was attempted and the row did not
persist -- money may have moved) and ``FundingLockUnavailableError`` (Redis
down; fail-closed, no money moved). Their messages reach the caller through
the decorator's error envelope.