Simulation & twins
After a run answers your question on Ask, two pages carry it forward:
- Options answers “what could we do, and what is each option worth?”. It leads with the options for the decision behind the run’s checks, scored and sendable for approval. Below them is what FACE tested: the run’s scenarios as a list, with a Graph view, and a New Simulation action. The status counts, what went to the twins and the run step by step sit in the folded How FACE knows this.
- Actionable Twins holds the decision cards in three lanes (Waiting for you, In flight, Back), with a Map view on the same page that places each card where your own data says it is.
This page covers the services behind both, and the claims and reverse-logistics service.
Options and scenarios (HypothesisService)
| RPC | What it does | Where you see it |
|---|---|---|
CompareOptions | Scores the what-if options for one decision on one shared measure over a run’s measured rows, each with a 95% range, and names a recommended one only when it is the clear winner. Reads what the run stored; never re-reads a source. | Options, at the top |
SendToTwins | With decision_key, option_key and run_id: compares the options again and queues the named one for approval. Without them: turns a validated scenario into an action card. | The card waits on Actionable Twins |
GetHypothesisVariables | Scenario groups inferred from the estate, with each scenario’s simulation_state and the run-level swarm_census. | Options |
InteractiveSimulate / SimulateScenario | Runs one scenario through the agentic ReAct loop and returns SimulateScenarioResponse. The app uses InteractiveSimulate. | Options |
ValidateHypothesis | Checks a scenario against the recognised rules and data. | Options |
GetTwinsHandoff / SetTwinsHandoffExclusion | The scenarios a run’s analysis handed to the twins agent, with each verdict and impact, and whether a person removed one from the next twins analyses. | Options, How FACE knows this |
GetScenarioBuilder, SaveCustomScenario, AddScenarioItem, AddScenarioTerm | One run’s scenarios with their business categories, the items each tests and the market terms each watches, plus what your team added. | Options, New Simulation |
AnalyzeTelemetry | Agentic analysis of an equipment time series. The FACE app does not call it. | API only |
The scenario list and its Graph view read FetchService.GetScenarioGraph: the run’s
scenarios and what each one tested, computed from the run’s stored records only, with
no model call. Anything the run did not record is shown as a gap, never as an invented
node.
Comparing options
How the options are scored, recommended and sent for approval is covered in Action cards & money. In short: one measure for every option, a range for each, a recommendation only when the best range clears both the next option and the figure as measured, and nothing runs until a named person approves.
Scenarios and the swarm
Scenarios are generated from the estate’s domains, synapses and rules.
HypothesisScenario.origin records which one proposed each scenario: node,
synapse or rule. In a full fetch, Phase 2 runs a bounded-parallel swarm with one
agent per scenario. The cap is derived from the time budget rather than chosen:
- Inside a fetch, the plan comes from the time left for the phase. Up to three agents run at once. Each agent gets as many reasoning turns as fit, the number of waves is the time left divided by one agent’s turns, and the cap is waves times agents at once. The roster is ranked first, so when not every scenario fits, the ones that run are a measured cross-domain correlation first, then an open rule, then a domain node.
- Outside a fetch (the swarm a session starts), the limits are fixed: three agents at once, 6 minutes per agent, a 25-minute budget, so at most 12 agents.
A scenario the cap left out is marked, not hidden. HypothesisScenarioState takes one
of these values:
| State | Meaning |
|---|---|
SIMULATED | Dispatched, and the agent produced a result. |
FAILED | Dispatched, but the agent produced no result. Causes include a guardrail block, a TOON parse failure, the per-agent ceiling, or the budget running out. |
CAPPED | Inferred, but never dispatched because of the cap. |
NOT_IN_RUN | Newer than the recorded run. |
UNSPECIFIED | No result recorded. This is neither a success nor a failure. |
HypothesisSwarmCensus records scenarios_inferred, agents_dispatched,
agents_succeeded, capped, agent_cap, the source of the roster, and
computed_at. Options shows the counts as “N scenarios tested, M succeeded”.
A simulation returns:
- Decision scenarios.
- Impacts (metric, change percentage, risk level and horizon).
- Evidence traces (
source_node → relation → target_node). - Forecasts with intervals.
- Anomalies.
The swarm’s aggregate is a union of independent answers, not a consensus: nothing votes, no agent is scored against another, and two agents that disagree are not reconciled.
Validation
ValidateHypothesis is a deterministic check, not a model call:
valid_datais true when a fetch has grounded the instance, meaning a rules or posture snapshot exists.valid_logicalso requires that none of the scenario’s rules is indrift,shadow,missing,conflictorviolated. Each such rule becomes arisk_flagsentry.rationaleexplains the verdict.
Digital twins (TwinsService)
| RPC | What it does | Where you see it |
|---|---|---|
GetActionQueue / ExecuteAction | The action queue and the human decision. See Action cards & money. | Actionable Twins lanes, and each card’s place on the Map view |
GetValueLedger | Money identified, approved, filed, recovered and expired for a period, each figure with its basis. | Actionable Twins (above the lanes) and the money line on Why |
ListDecisionLog | The hash-chained decision log. Admins only. | Settings › Account, Admin |
ProposeStandingRule, ApproveStandingRule, RevokeStandingRule, ListStandingRules | Turn an approved decision into a decision-authority rule. Proposing needs a writer; approving needs an org admin who is not the proposer. Every step is chained onto the decision log first. | A decided card on Actionable Twins |
ListAssetLocations | Where each asset in FACE’s fetched data is: a position only where a source stated one, and every other asset listed with the reason it has none. | Map view |
ListRunRoutes | The routes and destinations one run inferred from the rows it read, each proposal with its judging state, and what is missing when no destination has a position. | Map view |
ListLiveTraffic / AnalyseRoutesLive | Public transit and road feeds found from the run’s towns and regions, read only while someone watches the map, and each route against the live events near it. | Map view |
ListRunProviders | Service providers one run looked for on the public web near the sites in trouble (disposal, alternate warehousing, fleet repair, cold storage), with the queries sent. | Map view |
OptimizeRoute | Computes a route through the session’s Google Routes connector and returns distance, duration and polyline. | Map view, fleet plan |
StreamTwins, QuickAsk, UploadAnalyze | Interactive twin reasoning over text, audio, frames or a document; retrieval-based Q&A for S&OP and inventory questions; root-cause or savings analysis of an uploaded CSV, Excel or PDF file. The query is screened before it reaches a model. | The assistant, opened from its floating button on every page |
GetSavingsSummary | Pipeline savings and approved savings. The FACE app does not display it. | API only |
GenerateRoadmap | A phased roadmap (Digitize, Connect, Analyze, Automate) from maturity scores. The FACE app does not call it. | API only |
SubmitFeedback | Records feedback on a generated response to the durable record store. |
From Actionable Twins you also open:
- Follow-ups, which run on the cards selected on the list or the map.
- The Compliance, Finance and Operations remediation views, from the page’s Remediation links. See Compliance, finance, operations.
- The site plans and the twin entities, as panels over the Map view.
Refusals are errors, not empty cards.
OptimizeRoutereturnsUnavailablewhen there’s no routing connector or no route, rather than a card with blank measurements.cost_savingsis left empty, because the routing provider returns no cost.GenerateRoadmapleavesestimated_investment_usdandexpected_roi_percentat zero, which means “not estimated”: the roadmap describes a plan, not a measurement.
Claims and reverse logistics (ClaimsAgentService)
TriageReturnItem is a fixed rule over the condition grade the caller states:
condition_code | Disposition |
|---|---|
PRISTINE / A | RESTOCK |
DAMAGED / B | REFURBISH |
DEFECTIVE / C | RECYCLE |
EXPIRED / D | LANDFILL |
- A missing
return_idorcondition_code, an unknown grade, or a negative value is refused withInvalidArgument. An unknown grade is never a decision to destroy stock. estimated_recovery_yield_usd,refurbishment_cost_usdandrouting_destinationaren’t derived, because FACE holds no pricing, cost or facility data for returns.basis_notesays so on every response.
Reverse-logistics outcomes that rest on records are produced as
RETURN_DISPOSITION evidence documents. See
Evidence documents.
Reading the results
- A simulation is a model’s reasoning over grounded context. It isn’t a measured
outcome, and its
confidenceis the model’s own. - The swarm results cover only the scenarios that ran. Read the census before treating the results as covering the estate.
- Passing validation means the rules are consistent. It doesn’t mean the scenario will happen.
- A compared option is scored over the rows the run read. A recommendation means its range cleared the others on that sample, not that it will work.
- A triage disposition follows the stated grade, not an inspection. It’s only as good as the grade the caller supplied.