Skip to content

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)

RPCWhat it doesWhere you see it
CompareOptionsScores 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
SendToTwinsWith 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
GetHypothesisVariablesScenario groups inferred from the estate, with each scenario’s simulation_state and the run-level swarm_census.Options
InteractiveSimulate / SimulateScenarioRuns one scenario through the agentic ReAct loop and returns SimulateScenarioResponse. The app uses InteractiveSimulate.Options
ValidateHypothesisChecks a scenario against the recognised rules and data.Options
GetTwinsHandoff / SetTwinsHandoffExclusionThe 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, AddScenarioTermOne 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
AnalyzeTelemetryAgentic 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:

StateMeaning
SIMULATEDDispatched, and the agent produced a result.
FAILEDDispatched, but the agent produced no result. Causes include a guardrail block, a TOON parse failure, the per-agent ceiling, or the budget running out.
CAPPEDInferred, but never dispatched because of the cap.
NOT_IN_RUNNewer than the recorded run.
UNSPECIFIEDNo 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_data is true when a fetch has grounded the instance, meaning a rules or posture snapshot exists.
  • valid_logic also requires that none of the scenario’s rules is in drift, shadow, missing, conflict or violated. Each such rule becomes a risk_flags entry.
  • rationale explains the verdict.

Digital twins (TwinsService)

RPCWhat it doesWhere you see it
GetActionQueue / ExecuteActionThe action queue and the human decision. See Action cards & money.Actionable Twins lanes, and each card’s place on the Map view
GetValueLedgerMoney 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
ListDecisionLogThe hash-chained decision log. Admins only.Settings › Account, Admin
ProposeStandingRule, ApproveStandingRule, RevokeStandingRule, ListStandingRulesTurn 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
ListAssetLocationsWhere 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
ListRunRoutesThe 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 / AnalyseRoutesLivePublic 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
ListRunProvidersService 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
OptimizeRouteComputes a route through the session’s Google Routes connector and returns distance, duration and polyline.Map view, fleet plan
StreamTwins, QuickAsk, UploadAnalyzeInteractive 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
GetSavingsSummaryPipeline savings and approved savings. The FACE app does not display it.API only
GenerateRoadmapA phased roadmap (Digitize, Connect, Analyze, Automate) from maturity scores. The FACE app does not call it.API only
SubmitFeedbackRecords 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.

  • OptimizeRoute returns Unavailable when there’s no routing connector or no route, rather than a card with blank measurements. cost_savings is left empty, because the routing provider returns no cost.
  • GenerateRoadmap leaves estimated_investment_usd and expected_roi_percent at 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_codeDisposition
PRISTINE / ARESTOCK
DAMAGED / BREFURBISH
DEFECTIVE / CRECYCLE
EXPIRED / DLANDFILL
  • A missing return_id or condition_code, an unknown grade, or a negative value is refused with InvalidArgument. An unknown grade is never a decision to destroy stock.
  • estimated_recovery_yield_usd, refurbishment_cost_usd and routing_destination aren’t derived, because FACE holds no pricing, cost or facility data for returns. basis_note says 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 confidence is 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.