Skip to content

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

FieldMeaning
typeThe 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, statusstatus is Approved or Rejected once decided. Empty means pending.
transaction_valueThe card’s contribution to the dollar headline (see below).
Artifact fieldsOne typed payload per artifact family: route_card, email_draft, calendar_invite, erp_update, claims_card, cold_chain_card, customs_clearance_card, and others.
evidence_documentOne 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.
judgementThe 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_optionSet on a card that is an option sent for approval from Options (see below).
decision_trailWho decided the card, when, which way and why (see below).
recovery_trail, latest_outcomeWhat 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:

KindThe money it owns
OSD_REPORTThe cargo itself: units short plus units damaged, at the cited unit price. This is a loss already incurred.
FNOLThe reserve on a newly reported loss, only for claim numbers no claims card already charges.
RATE_CON_ACCESSORIAL_AUDITAccessorials invoiced above the signed rate confirmation.
MSA_SLA_COMPLIANCE_AUDITService credits owed back under an SLA clause.

Five twin-card families charge:

Card familyThe money it owns
cold_chain_cardValue at risk of the load on a reefer whose own readings broke a stated band.
claims_cardThe reserve on an open claim. For billing alerts, the invoice amount due on an account.
customs_clearance_cardDemurrage or per-diem accrued by a hold. Never the duty and never the cargo.
importer_of_record_cardDuty and tax with no accountable party.
cross_border_trucking_cardDetention 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:

  1. 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.
  2. 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.
  3. On approval, the evidence document is sealed (see Sealing), and any executable artifacts run.
  4. 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 as email:no_google_connector, calendar:not_implemented, erp:not_implemented or billing: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: Approved or Rejected.
  • decided_at: the server’s clock when the decision was recorded.
  • decided_by: the verified sub claim 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_by doesn’t prove a human pressed a button. A person’s token driven by a script looks the same. decided_by_role separates 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_id and not_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.