Simulation & twins

The cockpit’s pipeline has three stages:

Reconcile grounds the data.
Simulate tests what-if scenarios. This is the Hypothesis Lab.
Twins prepares the actions that act on the results.

This page covers the services behind Simulate and Twins, and the claims and reverse-logistics service.

Hypothesis Lab (`HypothesisService`)

RPC	What it does
`GetHypothesisVariables`	Scenario groups inferred from the estate, with each scenario’s `simulation_state` and the run-level `swarm_census`.
`SimulateScenario` / `InteractiveSimulate`	Runs one scenario (or a stream of them) through the agentic ReAct loop. Returns `SimulateScenarioResponse`.
`ValidateHypothesis`	Checks a scenario against the recognised rules and data.
`SendToTwins`	Turns a validated scenario into an action card in the Twins queue.
`AnalyzeTelemetry`	Agentic analysis of an equipment time series.

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:

Three agents run concurrently.
Each agent has a ceiling of 6 minutes.
The swarm’s budget is 25 minutes.
That gives 4 waves of 3, so at most 12 agents per run.

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`	Unknown. 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.

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.

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 reconciled rules is in drift, shadow, missing or conflict. Each such rule becomes a risk_flags entry.
rationale explains the verdict.

Digital twins (`TwinsService`)

RPC	What it does
`StreamTwins`	Interactive twin reasoning. It takes text, audio, video frames or a document, and can ground itself in the posture snapshot and recognised rules (`ground_with_knowledge`, `focus_domains`, `scenario_context`). Streams thoughts, `Decision`s and tool calls. The query is checked by `ai.SanitizePrompt` first.
`GetActionQueue` / `ExecuteAction`	The action queue and the human decision. See Action cards & money.
`OptimizeRoute`	Computes a route through the session’s Google Routes connector and returns distance, duration and polyline.
`QuickAsk`	Retrieval-based Q&A for S&OP and inventory questions.
`UploadAnalyze`	Root-cause or savings analysis of an uploaded CSV, Excel or PDF file.
`GenerateRoadmap`	A phased transformation roadmap (Digitize, Connect, Analyze, Automate) from maturity scores.
`GetSavingsSummary`	Pipeline savings and approved savings.
`SubmitFeedback`	Records feedback on a generated response to the durable record store.

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”. Nothing derives those figures, so 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_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.

ProcessReverseLogistics refuses without a record. It needs a record behind the claim, the return authorisation and the receiving log. Without one it answers FailedPrecondition rather than inventing dispositions or fraud patterns from identifiers alone.

Reverse-logistics outcomes that rest on records are produced as RETURN_DISPOSITION evidence documents. See Evidence documents.

What this does not establish

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 triage disposition follows the stated grade, not an inspection. It’s only as good as the grade the caller supplied.

Posture & maturity Compliance, finance, operations