Action cards & money
An action card (ActionCard) is a recommended action waiting for a person to
approve or reject it. You decide cards on Actionable Twins, where they sit in three
lanes:
- Waiting for you: cards that still need a decision.
- In flight: approved, with no final outcome recorded yet.
- Back: a final outcome is recorded (recovered in full or in part, or denied).
Each lane’s heading counts its items and adds up the money its cards state. Cards that state no amount are counted apart, never as $0. The same cards appear at their place on the page’s Map view. Play chips filter the list (claims, disruptions, routes, fulfilment and the other plays).
Cards come from three places:
- Deterministic derivers over the tenant’s records. These produce the twin cards and the evidence documents.
- The twins agent’s TOON output.
- An option a person sent for approval from Options (see Options sent for approval).
Every card is served through TwinsService.
Anatomy of a card
| Field | Meaning |
|---|---|
type | The business domain and routing key. The derivers and handlers emit Compliance, Finance, Operations, Procurement and S&OP. Model-produced cards may carry another string, which clients treat as uncategorised. |
priority, impact, status | status is Approved or Rejected once decided. Empty means pending. |
transaction_value | The card’s contribution to the dollar headline (see below). |
| Artifact fields | One typed payload per artifact family: route_card, email_draft, calendar_invite, erp_update, claims_card, cold_chain_card, customs_clearance_card, and others. |
evidence_document | One field for the whole evidence-document family. See Evidence documents. |
origin (ActionOrigin) | Which stage produced the card, as the wire spells it (reconcile, fetch or simulate), with a run_id and a label. If it’s absent, the stage wasn’t recorded. It’s never inferred. |
judgement | The judging ladder’s verdict, reached before the card was accepted. See Agents & oversight. |
authority (ActionAuthority) | The approval the decision-authority policy requires: its tier, how many distinct named approvals, the rule that decided it and why. See Auditability & lineage. |
execution (ActionExecution) | What approving will do on this instance, step by step, before anyone approves. records_only=true means approving records the decision and nothing else runs. |
decision_option | Set on a card that is an option sent for approval from Options (see below). |
decision_trail | Who decided the card, when, which way and why (see below). |
recovery_trail, latest_outcome | What happened after the approval, as named people recorded it, and the last outcome in the decision log. These move a card from In flight to Back. |
GetActionQueue returns the pending queue by default. Pass
status="Approved" or status="Rejected" to read back decided cards, and use
workflow_type to filter on type.
Options sent for approval
On Options, FACE compares the what-if options for one decision behind the selected
run’s checks (HypothesisService.CompareOptions). Every option is scored on one shared
measure with a 95% range. FACE marks one Recommended only when its range sits wholly
below the next option’s and below the figure as measured. Otherwise it says No clear
winner on this data and why. An option with no baseline is Not measured and is
never ranked.
Send for approval calls SendToTwins with the decision, the option and the run. The
server compares the options again and queues the option with the figures it computed
itself. The card lands in Waiting for you on Actionable Twins and carries
decision_option: the decision, the option’s lever and change, what it was measured to
do, the figure as measured, and whether it was the recommended one. The response names
the approval it needs: one named person, or two different named people.
Approving it records the decision and changes nothing by itself. It is never automatic.
Estimated and assumed effects are labelled apart. A lead-time option (for example, moving shipments to air) has its effect estimated from the shipments that took it, by regression adjustment, with its interval. A temperature option’s effect is the option’s own assumption: every reading is moved by the full change and checked again against its own limits, and the card states that how far the change really moves the readings is not estimated. An option the rows never took is Not measured, naming the data it needs.
Money: one headline, disjoint buckets
The money a lane’s heading shows on Actionable Twins is a sum of what its cards state. A sum can’t tell what the money is for, so FACE enforces a rule instead: two cards must never charge the same dollars.
A card contributes to a money total only if all three of these hold:
- It has not been rejected. A rejection is a decision not to take the saving. Approved and pending cards both count.
- It carries a dollar value. An emissions card sets its value in kilograms of CO2e, so it contributes nothing to a money total.
- It is in a named charging bucket. A test (
TestOnlyTheNamedCardFamiliesChargeTheHeadline) lists the closed set of buckets allowed to charge and says why each one owns its money. A new producer that charges without being added to that list fails the build. Adding it is where someone has to write down whose dollars they are.
The charging buckets
Four evidence-document kinds charge:
| Kind | The money it owns |
|---|---|
OSD_REPORT | The cargo itself: units short plus units damaged, at the cited unit price. This is a loss already incurred. |
FNOL | The reserve on a newly reported loss, only for claim numbers no claims card already charges. |
RATE_CON_ACCESSORIAL_AUDIT | Accessorials invoiced above the signed rate confirmation. |
MSA_SLA_COMPLIANCE_AUDIT | Service credits owed back under an SLA clause. |
Five twin-card families charge:
| Card family | The money it owns |
|---|---|
cold_chain_card | Value at risk of the load on a reefer whose own readings broke a stated band. |
claims_card | The reserve on an open claim. For billing alerts, the invoice amount due on an account. |
customs_clearance_card | Demurrage or per-diem accrued by a hold. Never the duty and never the cargo. |
importer_of_record_card | Duty and tax with no accountable party. |
cross_border_trucking_card | Detention accrued at a crossing. |
Why other documents keep their money out of totals
Most evidence documents are about money another bucket already owns. A cargo loss survey, a notice of intent, a statement of position and a subrogation demand all concern the same cargo the OS&D report charges. A temperature excursion and a warranty audit concern the same load the cold-chain card charges. If they charged too, one loss would be counted several times, and the error would look like better news.
So those documents state their money in claimed_amount (what the document asks
for) or exposure_amount (value at risk, not yet lost), and no total reads those
fields. The reader still sees the figure; the headline just doesn’t add it up twice.
Value ledger
TwinsService.GetValueLedger returns, for the tenant and a period, the money FACE
identified, what people approved and filed, what was recovered, and what expired
unfiled. Recovered money is kept in two figures: what people entered, and what the
operator’s own claims system states. Every figure names its basis, and a figure with no
basis is “not measured”, never zero. The ledger bills nothing.
Where you see it: the line above the lanes on Actionable Twins (recovered this quarter against FACE’s fee, with the full ledger folded under it), and the Recovered this quarter tile of the money line on Why.
The money line is on Why only, not on Ask (owner, 2026-11-02: the money tiles “are
under Why page not Ask”). Its seven tiles are At risk, Owed to you, Claim windows
closing in 14 days, Waiting for your approval, Recovered this quarter, Shipments at risk
and OTIF fines, led by what the run’s persona reads first. Only Recovered this quarter
reads the ledger. Waiting for your approval reads the run’s pending decisions
(TwinsService.GetActionQueue), and the board tiles come from the selected run’s
operations board (FetchService.GetOperationsBoard), computed from the rows that run
read. A tile with no basis says Not measured and why, never $0. See
Why.
Savings summary
GetSavingsSummary returns two separate figures:
total_savings_usd: the pipeline. It counts savings on cards nobody has rejected.approved_savings_usd: the subset the operator has committed to. It’s always less than or equal to the total.
Neither figure is “realised.” These figures do not record whether an approved
action was carried out in the world, so no client may label either figure that way.
What a person recorded after an approval is in the card’s recovery_trail and shows in
the Back lane. The FACE app does not display GetSavingsSummary today; it is an API
call.
Deciding a card
ExecuteAction is the one place a person decides a card:
- The decider is identified from the verified session. An approval is refused unless the session token’s subject can be verified. A rejection is recorded whatever the attribution says.
- A reason is required on rejection and optional on approval. Whitespace-only counts as empty. The limit is 2000 characters, and a longer reason is refused rather than truncated.
- On approval, the evidence document is sealed (see Sealing), and any executable artifacts run.
- The response reports what happened:
decision_recorded: the decision was durably written.success: false only when an approval executed nothing.transaction_id: minted only on success.not_executed: tokens such asemail:no_google_connector,calendar:not_implemented,erp:not_implementedorbilling:charge_failed, one for each artifact that didn’t run.
How a client should read the response. decision_recorded=true with
success=false means the card is decided but nothing was executable. The client
should stop, and must not retry. Genuine failures arrive as gRPC status errors
instead.
The decision trail
ActionCard.decision_trail is a list of ActionDecision entries, and the last entry
is the current decision. Each entry records:
decision:ApprovedorRejected.decided_at: the server’s clock when the decision was recorded.decided_by: the verifiedsubclaim of the deciding session, never a value the caller supplied.attribution(DeciderAttribution): how well the decider could be named.decided_by_role: the verified role.reason.
A retried decision with the same content doesn’t add a new entry. The original entry is kept, including its original time. An operator who changes their mind gets a second entry.
Reading the results
- The headline is a sum of claims about money, not money received. It’s only as good as the cited records behind each card.
decided_bydoesn’t prove a human pressed a button. A person’s token driven by a script looks the same.decided_by_roleseparates a service account from a person’s session.- The trail is a verified attribution, not a signature. It is written by the instance into a store the instance owns.
- A required reason proves someone typed something, not that it’s true or complete.
- An approval is not an execution receipt. Read
transaction_idandnot_executed. - A recommended option is the clear winner on the rows read, not a guarantee. Read whether its effect was estimated or assumed before approving it.