Twins, simulation & claims

The action layer.

TwinsService is the “actionable twin”. It reasons over the fetched estate, proposes action cards (outreach, claims, documents, route changes), and records the human decision on each card.
HypothesisService is the simulation lab. It proposes scenarios from the estate, simulates them on the sovereign model plane, validates them against the reconciled rules, and promotes them to the twin queue.
ClaimsAgentService triages returned items.

Nothing on this page executes an action without an explicit approval through ExecuteAction, and an approval is recorded against the verified identity of the session that made it.

Summary

Service	RPC	Kind	Purpose
TwinsService	StreamTwins	Server streaming	Ask the twin agent; stream its reasoning and analysis
TwinsService	ExecuteAction	Unary	Approve or reject an action card
TwinsService	GetActionQueue	Unary	List action cards by status and type
TwinsService	OptimizeRoute	Unary	Compute a route between two places
TwinsService	QuickAsk	Unary	Short retrieval-grounded answer
TwinsService	UploadAnalyze	Server streaming	Analyse an uploaded file with parallel agents
TwinsService	GenerateRoadmap	Unary	Phased maturity roadmap
TwinsService	GetSavingsSummary	Unary	Savings across action cards
TwinsService	SubmitFeedback	Unary	Record feedback on a response
HypothesisService	SimulateScenario	Server streaming	Simulate one scenario, streaming progress
HypothesisService	ValidateHypothesis	Unary	Check a scenario against reconciled rules
HypothesisService	GetHypothesisVariables	Unary	Scenarios proposed from the estate, with swarm results
HypothesisService	InteractiveSimulate	Bidirectional streaming	Re-simulate as variables change
HypothesisService	SendToTwins	Unary	Promote a scenario to the twin queue
HypothesisService	AnalyzeTelemetry	Unary	Decompose an equipment telemetry series
ClaimsAgentService	ProcessReverseLogistics	Unary	Not available: no claim records to ground it
ClaimsAgentService	TriageReturnItem	Unary	Disposition for a returned item

Several RPCs pass the caller’s text through the relevant agent’s guardrail rules first (see MetasearchService/EvaluateBias). A refusal from the guardrail is returned as an error.

TwinsService

Full name semantics.v1.TwinsService.

StreamTwins

rpc StreamTwins(StreamTwinsRequest) returns (stream StreamTwinsResponse);

Kind: Server streaming. Available over native gRPC and gRPC-web.
Auth: Bearer session. Tool use inside the agent loop follows the orchestrator’s tool gate.
Errors: The stream ends with an error (no specific code) if user_query trips the prompt-injection check, or if the agent loop fails before producing an answer.

Runs the twins agent (up to 3 turns) with a context built from:

the attached video_frames (the first 3 are shown to the vision model);
matching recognised rules;
the fetched domain knowledge (always when user_query is set, and narrowed by focus_domains);
scenario_context;
public research fetched for the query.

audio_input is not transcribed: the model is told that audio was attached and not processed. document_upload and document_filename are not read. Use UploadAnalyze for files.

The stream carries thought messages (progress), then zero or more simulation_result or error messages if the agent triggered a shadow simulation, then one final analysis message. The final message’s content is the analysis as JSON, with decisions, tools, metrics, time_series, shadow_search and spoken_response set from it. Identical requests may be answered from a cache with that single final message.

If the agent proposes new data connections, the server creates them through ConfigService.CreateConnection and reports each outcome in a thought message.

Request: StreamTwinsRequest

Field	Type	Description
`user_query`	`string`	The question or instruction.
`audio_input`	`bytes`	WAV/PCM audio. Not transcribed; the agent is told so.
`video_frames`	`repeated bytes`	JPEG/PNG frames for vision. The first 3 are used.
`document_upload`	`bytes`	Not read by this RPC.
`document_filename`	`string`	Not read by this RPC.
`ground_with_knowledge`	`bool`	Inject the latest posture snapshot and recognised rules into the context.
`focus_domains`	`repeated string`	Narrow that knowledge to these domains.
`scenario_context`	`string`	A hypothesis handed over from the lab.

Response: StreamTwinsResponse

Field	Type	Description
`content`	`string`	Text of this message. On the final `analysis` message, the analysis as JSON.
`type`	`string`	`thought`, `simulation_result`, `error` or `analysis`.
`decisions`	`repeated` `Decision`	The agent’s decisions. Final message only.
`tools`	`repeated` `ToolCall`	Tools the agent recommended. Final message only.
`metrics`	`EvaluationMetrics`	Quality figures as the agent reported them. See the message for how to read them.
`time_series`	`repeated` `TimeSeriesInsight`	Time-series insights.
`shadow_search`	`repeated` `ShadowSearchResult`	Public research findings used.
`spoken_response`	`string`	A short summary suitable for speech.
`audio_data`	`bytes`	Not populated by this RPC.

ExecuteAction

rpc ExecuteAction(ExecuteActionRequest) returns (ExecuteActionResponse);

Kind: Unary.
Auth: Bearer session. An approval is refused unless the session carries a verified subject, so that every approval names a principal. A rejection is recorded either way.
Errors: PERMISSION_DENIED for an approval that cannot be attributed. INVALID_ARGUMENT for a rejection with no reason, or a reason over 2,000 characters (refused, never truncated). FAILED_PRECONDITION if the instance has no action store. NOT_FOUND if action_id does not exist. INTERNAL if the card cannot be read or stored, or if sending the card’s email fails.

user_approval must be exactly approve to approve. Any other value is a rejection.

On approval, the server runs the card’s artefacts:

the email draft is sent through the tenant’s connected Google account;
calendar invites and ERP updates are not implemented and are reported in not_executed;
a success fee may be recorded when billing is configured;
an attached evidence document is sealed.

On rejection nothing runs, and the evidence document is not sealed. In both cases the decision is appended to the card’s decision_trail and the card’s status becomes Approved or Rejected. Re-sending the same decision is idempotent: the trail is unchanged and the original entry is returned.

Request: ExecuteActionRequest

Field	Type	Description
`action_id`	`string`	The card’s `id`.
`user_approval`	`string`	`approve` approves. Anything else rejects.
`sop_draft`	`string`	Not read by the server.
`suggested_providers`	`repeated string`	Not read by the server.
`reason`	`string`	Why, in the decider’s words. Required on a rejection, optional on an approval. Whitespace-only counts as empty. At most 2,000 characters.

Response: ExecuteActionResponse

Field	Type	Description
`success`	`bool`	`true` unless this was an approval that executed nothing. A rejection returns `true`. Not a receipt: read `transaction_id`.
`transaction_id`	`string`	Set only when `success` is `true`.
`decision_recorded`	`bool`	The decision was durably stored. `true` with `success: false` means stop: the card is decided, nothing was executable, and there is nothing to retry. Real failures arrive as gRPC errors instead.
`not_executed`	`repeated string`	`<artifact>:<reason>` for each requested artefact that did not run: `email:no_google_connector`, `calendar:not_implemented`, `erp:not_implemented`, `billing:charge_failed`. Empty does not mean everything ran.
`decision`	`ActionDecision`	The trail entry recorded, or the existing one on a retry.

GetActionQueue

rpc GetActionQueue(GetActionQueueRequest) returns (GetActionQueueResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNAVAILABLE if the action store cannot be read. The queue is then unknown, not empty.

With an empty status, returns the undecided cards: stored cards, the cards derived from the latest twin run when none are stored, and evidence-document cards derived from the tenant’s records. Cards already decided are left out. With status set to Approved or Rejected, returns only stored cards with that status, including their decision_trail.

Request: GetActionQueueRequest

Field	Type	Description
`workflow_type`	`string`	Keep cards whose `type` equals this, case-insensitively. Empty keeps all.
`status`	`string`	Keep cards whose `status` equals this, case-insensitively. Empty means undecided cards.

Response: GetActionQueueResponse

Field	Type	Description
`actions`	`repeated` `ActionCard`	The cards.

OptimizeRoute

rpc OptimizeRoute(OptimizeRouteRequest) returns (OptimizeRouteResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNAVAILABLE if the tenant has no Google Routes connector, or the routing provider returns no route.

Computes a route with the tenant’s connected Google Routes account. cost_savings is not computed.

Request: OptimizeRouteRequest

Field	Type	Description
`origin`	`string`	Start address or place.
`destination`	`string`	End address or place.
`preferences`	`repeated string`	Routing preferences, passed to the provider.

Response: OptimizeRouteResponse

Field	Type	Description
`distance`	`string`	For example `412.3 km`.
`duration`	`string`	Travel time, as a duration string.
`route_polyline`	`string`	Encoded polyline.
`cost_savings`	`string`	Not populated.
`route_card`	`RouteTwinCard`	The same route as a card.

QuickAsk

rpc QuickAsk(QuickAskRequest) returns (QuickAskResponse);

Kind: Unary.
Auth: Bearer session.
Errors: Returned without a specific code if the query trips the twin guardrail or the model call fails.

Answers in two or three sentences from the knowledge graph and the model. It also queues one S&OP card, “Deep Dive: …”, suggesting a full StreamTwins analysis.

Request: QuickAskRequest

Field	Type	Description
`query`	`string`	The question.
`context_hint`	`string`	`S&OP`, `INVENTORY`, `SPEND` or `WAREHOUSING`. Scopes the retrieval.

Response: QuickAskResponse

Field	Type	Description
`answer`	`string`	The answer.
`confidence`	`double`	A fixed value (0.75), not a measurement. Do not display it as a confidence.
`sources`	`repeated string`	`knowledge_graph` when retrieval found context. Otherwise empty.
`suggested_actions`	`repeated` `ActionCard`	The queued deep-dive card.

UploadAnalyze

rpc UploadAnalyze(UploadAnalyzeRequest) returns (stream UploadAnalyzeResponse);

Kind: Server streaming. Available over native gRPC and gRPC-web.
Auth: Bearer session.
Errors: The stream ends with an error (no specific code) for an invalid file name, a guardrail refusal of the name or content, or the first failing agent.

.csv, .tsv and .txt files are read as text. Any other file is described to the agents by name, size and a base64 sample of its first 4 KB, so the agents do not see its full content. Twelve agents then analyse it in parallel. Each streams a thought when it starts and when it answers. The stream ends with one action_card message holding all the analyses, and the server queues a Procurement card for the upload.

Request: UploadAnalyzeRequest

Field	Type	Description
`file_name`	`string`	File name. Only the base name is used.
`file_content`	`bytes`	The file.
`analysis_type`	`string`	`ROOT_CAUSE`, `SPEND`, `INVENTORY_HEALTH` or `GENERAL`. Shown in progress text only.

Response: UploadAnalyzeResponse

Field	Type	Description
`content`	`string`	Progress text, or on the final message all the analyses as Markdown.
`type`	`string`	`thought` or `action_card`.
`decisions`	`repeated` `Decision`	Final message only: one fixed “Review parallel agent analysis” decision. Its `confidence` is a constant, not a measurement.

GenerateRoadmap

rpc GenerateRoadmap(GenerateRoadmapRequest) returns (GenerateRoadmapResponse);

Kind: Unary.
Auth: Bearer session.
Errors: Returned without a specific code if industry trips the guardrail or the model call fails.

The model writes the executive summary. The phases are a fixed four-step template (Digitize, Connect, Analyze, Automate) with the timeline split evenly between them. Investment and ROI are not estimated. The server also queues the first action card.

Request: GenerateRoadmapRequest

Field	Type	Description
`current_scores`	`repeated` `MaturityDimension`	Current maturity per dimension.
`target_level`	`int32`	Target level, 1 to 5.
`timeline_months`	`int32`	Total months. 0 or negative means 18.
`industry`	`string`	Industry, for context.

Response: GenerateRoadmapResponse

Field	Type	Description
`executive_summary`	`string`	The model’s summary.
`phases`	`repeated` `RoadmapPhase`	The four phases. `estimated_investment_usd` and `expected_roi_percent` are 0: not estimated.
`first_actions`	`repeated` `ActionCard`	The queued “Begin Phase 1” card.

GetSavingsSummary

rpc GetSavingsSummary(GetSavingsSummaryRequest) returns (GetSavingsSummaryResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None.

Sums savings over all action cards, with operator decisions applied. Rejected cards are left out. A card counts when it carries a spend card (identified savings), a route card with a stated saving, or a reverse-logistics or freight-forwarding card (the card’s transaction_value). Neither figure is realised savings: the platform does not persist whether an approved action was carried out.

Request: GetSavingsSummaryRequest

Field	Type	Description
`time_range`	`string`	Not applied by the server.
`category_filter`	`string`	Filters `savings_by_category` only. `ALL` or empty keeps all. The totals are not filtered.

Response: GetSavingsSummaryResponse

Field	Type	Description
`total_savings_usd`	`double`	Pipeline: savings on approved and pending cards.
`savings_by_category`	`repeated` `SavingsCategory`	By category (`Procurement`, `Route`, `Reverse Logistics`, or the card type), largest first.
`savings_trend`	`repeated` `SavingsTrend`	A single entry for the current ISO week, holding the total.
`approved_savings_usd`	`double`	Savings on approved cards only. Never more than the total.

SubmitFeedback

rpc SubmitFeedback(SubmitFeedbackRequest) returns (SubmitFeedbackResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNAVAILABLE if no feedback store is configured. INTERNAL if it cannot be stored.

Request: SubmitFeedbackRequest

Field	Type	Description
`prompt`	`string`	The prompt the feedback is about.
`generated_response`	`string`	Not stored by the server.
`feedback_type`	`string`	`BAD_PROMPT`, `BAD_SUGGESTION` or `ADMIN_FLAG`.
`admin_notes`	`string`	Notes.

Response: SubmitFeedbackResponse

Field	Type	Description
`success`	`bool`	`true` once stored.
`message`	`string`	Outcome.

HypothesisService

Full name semantics.v1.HypothesisService.

SimulateScenario

rpc SimulateScenario(SimulateScenarioRequest) returns (stream SimulateScenarioResponse);

Kind: Server streaming. Available over native gRPC and gRPC-web.
Auth: Bearer session.
Errors: PERMISSION_DENIED if the scenario trips the hypothesis guardrail. Template, model and parse failures end the stream without a specific code.

Streams progress messages (only scenario_id and impact_summary set) through causal, Bayesian and context enrichment and the model’s reasoning, then one final message with the full result. confidence is the top scenario’s confidence as the model stated it. recommendation is Approve when that exceeds 0.8, Reject / More Evidence when it does not, and Review Needed when the model gave no number.

Request: SimulateScenarioRequest

Field	Type	Description
`scenario_id`	`string`	Scenario id.
`scenario_name`	`string`	Scenario name.
`variables`	`repeated` `Variable`	Scenario variables.
`reconciled_rules`	`repeated` `Rule`	Rules the scenario rests on.

Response: SimulateScenarioResponse

Field	Type	Description
`scenario_id`	`string`	Scenario id.
`impact_summary`	`string`	Progress text, or on the final message the simulated impacts and hypothesis.
`confidence`	`double`	The model’s stated confidence in the top scenario. 0 when none was stated.
`recommendation`	`string`	`Approve`, `Reject / More Evidence` or `Review Needed`. Empty when there were no scenarios.
`scenarios`	`repeated` `DecisionScenario`	Decision scenarios.
`impacts`	`repeated` `ImpactSimulation`	Simulated impacts.
`traces`	`repeated` `EvidenceTrace`	Evidence traces.
`metrics`	`EvaluationMetrics`	Quality figures as the model reported them.
`forecasts`	`repeated` `TimeSeriesForecast`	Forecasts.
`anomalies`	`repeated` `TimeSeriesAnomaly`	Anomalies, including decomposition anomalies over the forecasts.

ValidateHypothesis

rpc ValidateHypothesis(ValidateHypothesisRequest) returns (ValidateHypothesisResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None.

A deterministic check. No model is involved. valid_data is true when a fetch has produced rules or a posture snapshot. Each reconciled rule in Drift, Shadow, Missing or Conflict (stated in the request, or recognised by name) raises a risk flag. valid_logic needs valid data, no risk flags, and at least one rule.

Request: ValidateHypothesisRequest

Field	Type	Description
`hypothesis_id`	`string`	Hypothesis id. Not used by the check.
`scenario_name`	`string`	Scenario name, used in the rationale.
`reconciled_rules`	`repeated` `Rule`	Rules the scenario rests on.

Response: ValidateHypothesisResponse

Field	Type	Description
`valid_logic`	`bool`	Consistent with the rules, with nothing unresolved.
`valid_data`	`bool`	There is fetched knowledge to validate against.
`risk_flags`	`repeated string`	One sentence per unresolved rule.
`rationale`	`string`	Why.

GetHypothesisVariables

rpc GetHypothesisVariables(GetHypothesisVariablesRequest) returns (GetHypothesisVariablesResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None.

Returns the lab’s scenario groups, generated from the latest posture snapshot’s domains, with the latest swarm run’s results and census attached. Without a snapshot, only the default model variables are returned.

Request: GetHypothesisVariablesRequest

No fields.

Response: GetHypothesisVariablesResponse

Field	Type	Description
`variables`	`repeated` `Variable`	Default model knobs (temperature, top-p, top-k and so on).
`hypothesis_groups`	`repeated` `HypothesisGroup`	Scenario groups. Empty without a snapshot.
`swarm_census`	`HypothesisSwarmCensus`	Accounting for the last swarm run. Absent means no record here, not “never ran”.

InteractiveSimulate

rpc InteractiveSimulate(stream InteractiveSimulateRequest) returns (stream InteractiveSimulateResponse);

Kind: Bidirectional streaming. Native gRPC only.
Auth: Bearer session.
Errors: As for SimulateScenario. The first failure ends the stream.

For each request received, runs the same simulation as SimulateScenario, without progress messages, and sends one response. The stream ends when the client closes its side.

Request: InteractiveSimulateRequest

Field	Type	Description
`scenario_id`	`string`	Scenario id.
`scenario_name`	`string`	Scenario name.
`variables`	`repeated` `Variable`	Scenario variables.
`reconciled_rules`	`repeated` `Rule`	Rules the scenario rests on.

Response: InteractiveSimulateResponse

Same fields and meaning as SimulateScenarioResponse.

Field	Type	Description
`scenario_id`	`string`	Scenario id.
`impact_summary`	`string`	Simulated impacts and hypothesis.
`confidence`	`double`	The model’s stated confidence in the top scenario.
`recommendation`	`string`	`Approve`, `Reject / More Evidence` or `Review Needed`.
`scenarios`	`repeated` `DecisionScenario`	Decision scenarios.
`impacts`	`repeated` `ImpactSimulation`	Simulated impacts.
`traces`	`repeated` `EvidenceTrace`	Evidence traces.
`metrics`	`EvaluationMetrics`	Quality figures as the model reported them.
`forecasts`	`repeated` `TimeSeriesForecast`	Forecasts.
`anomalies`	`repeated` `TimeSeriesAnomaly`	Anomalies.

SendToTwins

rpc SendToTwins(SendToTwinsRequest) returns (SendToTwinsResponse);

Kind: Unary.
Auth: Bearer session.
Errors: None as gRPC status.

Queues an S&OP action card for the twin, with id twin-hyp-<scenario_id> (or a slug of the name) and origin stage simulate. Its priority is High when any reconciled rule is High or Critical severity, and Medium otherwise.

Request: SendToTwinsRequest

Field	Type	Description
`scenario_id`	`string`	Scenario id.
`scenario_name`	`string`	Card title. Empty means `Hypothesis <scenario_id>`.
`hypothesis`	`string`	The hypothesis. Used as the card’s impact when `impact_summary` is empty.
`reconciled_rules`	`repeated` `Rule`	Named on the card, and used for priority.
`variables`	`map<string, double>`	Scenario variables.
`domain`	`string`	Domain, noted on the card.
`impact_summary`	`string`	The card’s impact text.

Response: SendToTwinsResponse

Field	Type	Description
`success`	`bool`	Whether the card was queued.
`twin_action_id`	`string`	The queued card’s id.
`message`	`string`	Outcome.

AnalyzeTelemetry

rpc AnalyzeTelemetry(AnalyzeTelemetryRequest) returns (AnalyzeTelemetryResponse);

Kind: Unary.
Auth: Bearer session.
Errors: Returned without a specific code if the input trips the telemetry guardrail, there are fewer than 5 points, or the decomposition fails.

Runs a Prophet decomposition over the series. final_result_json holds anomaly_detected, anomaly_count, anomalies, trend (upward, downward or stable), forecast, changepoint_count, confidence_score (1 minus the anomaly share of the points) and equipment_id. When a model is available, impact_simulation holds its JSON impact assessment.

Request: AnalyzeTelemetryRequest

Field	Type	Description
`equipment_id`	`string`	Equipment id.
`time_series_data`	`repeated double`	The readings. At least 5.
`timestamp`	`string`	Not used by the server.

Response: AnalyzeTelemetryResponse

Field	Type	Description
`status`	`string`	`SUCCESS`.
`current_thought`	`string`	Not populated.
`action_attempted`	`string`	Not populated.
`observation_result`	`string`	Not populated.
`final_result_json`	`string`	The decomposition result, as above.
`fraud_patterns`	`repeated string`	Not populated.
`sops`	`repeated string`	Not populated.
`impact_simulation`	`string`	The model’s impact JSON, or `{}`.
`target_financial_value`	`double`	Always 0. Telemetry alone gives no basis for a dollar figure.

ClaimsAgentService

Full name semantics.v1.ClaimsAgentService.

ProcessReverseLogistics

rpc ProcessReverseLogistics(ProcessReverseLogisticsRequest) returns (ProcessReverseLogisticsResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INVALID_ARGUMENT if claim_id is empty. Otherwise always FAILED_PRECONDITION: FACE holds no record of the claim, return authorisation or receiving log, so any disposition or value would be invented. Evidence documents for returns reach the queue through GetActionQueue instead.

Request: ProcessReverseLogisticsRequest

Field	Type	Description
`claim_id`	`string`	Required. Claim id.
`return_authorization_id`	`string`	Return authorisation id.
`receiving_log_id`	`string`	Receiving log id.

Response: ProcessReverseLogisticsResponse

Never returned by the current server.

Field	Type	Description
`status`	`string`	Status.
`current_thought`	`string`	Reasoning.
`action_attempted`	`string`	Action.
`observation_result`	`string`	Observation.
`final_result_json`	`string`	Result as JSON.
`fraud_patterns`	`repeated string`	Fraud patterns.
`sops`	`repeated string`	Procedures.
`impact_simulation`	`string`	Impact.
`target_financial_value`	`double`	Value.

TriageReturnItem

rpc TriageReturnItem(TriageReturnItemRequest) returns (TriageReturnItemResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INVALID_ARGUMENT if return_id or condition_code is empty, the code is unknown, or original_value_usd is negative. A guardrail refusal is returned without a specific code.

The disposition is a fixed rule over the condition you state: PRISTINE/A restocks, DAMAGED/B refurbishes, DEFECTIVE/C recycles, EXPIRED/D goes to landfill. Nothing else is derived.

Request: TriageReturnItemRequest

Field	Type	Description
`return_id`	`string`	Required. Return id.
`barcode`	`string`	Barcode.
`condition_code`	`string`	Required. `PRISTINE`, `DAMAGED`, `DEFECTIVE`, `EXPIRED`, or `A` to `D`. Case-insensitive.
`original_value_usd`	`double`	Original value. Must not be negative.

Response: TriageReturnItemResponse

Field	Type	Description
`return_id`	`string`	The return id.
`optimal_disposition`	`DispositionTriage`	The disposition.
`estimated_recovery_yield_usd`	`double`	Not derived. Always 0: FACE holds no pricing data for returns.
`refurbishment_cost_usd`	`double`	Not derived. Always 0.
`routing_destination`	`string`	Not derived. Always empty.
`basis_note`	`string`	What the verdict rests on. Always set.

Messages

ActionCard

One proposed action. At most a few of the artefact fields are set on any card.

Field	Type	Description
`id`	`string`	Card id.
`title`	`string`	Title.
`type`	`string`	Business domain and queue routing key. Produced values: `Compliance`, `Finance`, `Operations`, `Procurement`, `S&OP`. Cards from the model may carry other strings: treat an unknown value as uncategorised.
`priority`	`string`	Priority.
`impact`	`string`	Impact, as text.
`status`	`string`	Pending status, or `Approved` / `Rejected` once decided.
`route_card`	`RouteTwinCard`	Route artefact.
`email_draft`	`EmailDraft`	Email sent on approval.
`calendar_invite`	`CalendarInvite`	Calendar artefact. Not executed.
`erp_update`	`ERPUpdate`	ERP artefact. Not executed.
`transaction_value`	`float`	Monetary value of the action.
`roadmap_card`	`RoadmapCard`	Roadmap artefact.
`spend_card`	`SpendAnalysisCard`	Spend artefact.
`rfp_card`	`RFPCard`	RFP artefact.
`sop_document`	`SOPDocument`	Orphaned. Never populated; kept for wire compatibility. Procedures come from `FetchService/GenerateSOP`.
`spo_card`	`SPOCard`	S&OP artefact.
`claims_card`	`ClaimsCard`	Claims artefact.
`fulfilment_card`	`FulfilmentCard`	Fulfilment artefact.
`reverse_logistics_card`	`ReverseLogisticsCard`	Reverse-logistics artefact.
`reactive_logistics_card`	`ReactiveLogisticsCard`	Reactive-logistics artefact.
`emissions_card`	`EmissionsCard`	Emissions artefact.
`cold_chain_card`	`ColdChainCard`	Cold-chain artefact.
`maintenance_card`	`MaintenanceCard`	Maintenance artefact.
`customs_clearance_card`	`CustomsClearanceCard`	Customs artefact.
`importer_of_record_card`	`ImporterOfRecordCard`	Importer-of-record artefact.
`freight_forwarding_card`	`FreightForwardingCard`	Freight-forwarding artefact.
`cross_border_trucking_card`	`CrossBorderTruckingCard`	Cross-border artefact.
`evidence_document`	`EvidenceDocument`	An evidence-bearing document (OS&D report, FNOL, subrogation demand and so on), with its citations. Sealed on approval.
`decision_trail`	`repeated` `ActionDecision`	Every decision on the card, oldest first. The last entry is the current decision. A decided card with an empty trail was decided before trails were recorded.
`origin`	`ActionOrigin`	Which stage produced the card. Absent means not recorded.
`judgement`	`Judgement`	The platform’s verdict on the card before it was accepted. Unset means not judged. A card that was dissented from is never served.

ActionDecision

One recorded decision. It shows that the decision was taken under a session this server signed and verified. It is a verified attribution, not a signature: it does not prove that a person rather than a script pressed the button. decided_by_role is what separates a service account from a person.

Field	Type	Description
`decision`	`string`	`Approved` or `Rejected`.
`decided_at`	`int64`	Unix seconds when it was recorded (server clock). A retry keeps the first value.
`decided_by`	`string`	The verified `sub` of the deciding session. Empty exactly when `attribution` is not verified.
`attribution`	`DeciderAttribution`	How well the decider could be named. Always `VERIFIED_SUBJECT` on an approval.
`decided_by_role`	`Role`	The verified role of the deciding session.
`reason`	`string`	The decider’s reason, trimmed.

ActionOrigin

Field	Type	Description
`stage`	`string`	`reconcile`, `fetch` or `simulate`. Show an unknown value verbatim.
`run_id`	`string`	The producing run, when recorded. Empty means not recorded.
`label`	`string`	What to show a person: a scenario title, schedule name or connection.

Decision

Field	Type	Description
`recommendation`	`string`	The recommendation.
`confidence`	`double`	The confidence the agent stated. Not a measurement.
`rationale`	`string`	Rationale.
`action_plan`	`string`	Action plan.
`risks`	`string`	Risks.
`judgement`	`Judgement`	The platform’s verdict on this decision. Unset means not judged. Dissented decisions do not appear.

ToolCall

Field	Type	Description
`name`	`string`	Tool name.
`arguments`	`string`	Arguments.
`reason`	`string`	Why the agent chose it.

EvaluationMetrics

Answer-quality figures. On this page they are the values the agent reported about its own answer, not the output of an evaluation harness, so read them as self-reports. When unmeasured_reason is set, no evaluation ran and every score is 0 because nothing measured it: do not display the scores as percentages.

Field	Type	Description
`context_precision`	`double`	Context precision.
`context_relevancy`	`double`	Context relevancy.
`context_recall`	`double`	Context recall.
`context_correctness`	`double`	Context correctness.
`contextual_faithfulness`	`double`	Faithfulness.
`contextual_relevance`	`double`	Relevance.
`contextual_completeness`	`double`	Completeness.
`contextual_accuracy`	`double`	Accuracy.
`contextual_clarity`	`double`	Clarity.
`contextual_consistency`	`double`	Consistency.
`answer_relevance`	`double`	Answer relevance.
`answer_completeness`	`double`	Answer completeness.
`answer_accuracy`	`double`	Answer accuracy.
`answer_clarity`	`double`	Answer clarity.
`answer_consistency`	`double`	Answer consistency.
`answer_correctness`	`double`	Answer correctness.
`unmeasured_reason`	`string`	Set when no evaluation ran, naming why.

TimeSeriesInsight

Field	Type	Description
`metric`	`string`	Metric.
`forecast_value`	`string`	Forecast value.
`anomaly_detected`	`string`	Anomaly description.
`confidence`	`double`	The agent’s stated confidence.

ShadowSearchResult

Field	Type	Description
`query`	`string`	Search query.
`source`	`string`	Source.
`finding`	`string`	Finding.
`relevance`	`string`	Relevance.

Variable

Field	Type	Description
`name`	`string`	Variable name.
`value`	`double`	Value.

DecisionScenario

Field	Type	Description
`template`	`string`	Scenario template.
`hypothesis`	`string`	Hypothesis.
`confidence`	`string`	The model’s stated confidence, as text.
`action_lever`	`string`	The lever the scenario pulls.

ImpactSimulation

Field	Type	Description
`metric`	`string`	Metric.
`change_pct`	`string`	Change, in percent.
`risk_level`	`string`	Risk level.
`time_horizon`	`string`	Time horizon.

EvidenceTrace

Field	Type	Description
`source_node`	`string`	Source node.
`relation`	`string`	Relation.
`target_node`	`string`	Target node.
`significance`	`string`	Significance.

TimeSeriesForecast

Field	Type	Description
`period`	`string`	Period.
`value`	`double`	Forecast value.
`confidence`	`double`	Stated confidence.
`interval_lower`	`double`	Interval lower bound.
`interval_upper`	`double`	Interval upper bound.

TimeSeriesAnomaly

Field	Type	Description
`timestamp`	`string`	When. For decomposition anomalies, `T+<n>`.
`value`	`double`	Value.
`type`	`string`	`Point`, `Contextual`, or `Prophet ML Anomaly`.
`confidence`	`double`	Confidence.
`explanation`	`string`	Explanation.
`cause`	`string`	Cause.

HypothesisGroup

Field	Type	Description
`id`	`string`	Group id.
`name`	`string`	Group name.
`description`	`string`	Description.
`category`	`string`	Category.
`scenarios`	`repeated` `HypothesisScenario`	Scenarios.

HypothesisScenario

Field	Type	Description
`id`	`string`	Scenario id.
`name`	`string`	Name.
`status`	`string`	The generator’s own lifecycle value, always `ready`. Not a result: read `simulation_state`.
`variables`	`repeated` `Variable`	Variables.
`simulation_result`	`InteractiveSimulateResponse`	The last swarm run’s result, when one was recorded.
`validation_result`	`ValidateHypothesisResponse`	Validation result.
`error`	`string`	Error.
`description`	`string`	Description.
`type`	`string`	`optimization`, `risk` or `compliance`.
`progress`	`double`	Progress.
`reconciled_rules`	`repeated` `Rule`	Rules the scenario rests on.
`origin`	`string`	Which part of the estate proposed it: `node`, `synapse` or `rule`. Empty on older scenarios: show them as unattributed.
`simulation_state`	`HypothesisScenarioState`	What the last recorded swarm did with this scenario.

HypothesisSwarmCensus

Accounting for one swarm run: what the estate proposed, what was simulated, and what was left out. It may describe a run on another process. Absence means no record here.

Field	Type	Description
`scenarios_inferred`	`int32`	Scenarios proposed before the cap.
`agents_dispatched`	`int32`	Agents started.
`agents_succeeded`	`int32`	Agents that produced a simulation.
`capped`	`bool`	Whether the cap limited the run.
`agent_cap`	`int32`	The cap at the time.
`source`	`string`	Where the scenarios came from, for example “this fetch’s posture”.
`computed_at`	`int64`	Unix seconds when the census was written.

MaturityDimension

Field	Type	Description
`dimension_name`	`string`	For example `data_and_architecture`.
`current_rating`	`int32`	1 to 5.
`description`	`string`	Description.

RoadmapPhase

Field	Type	Description
`phase_name`	`string`	`Digitize`, `Connect`, `Analyze` or `Automate`.
`phase_number`	`int32`	1 to 4.
`milestones`	`repeated string`	Milestones.
`estimated_investment_usd`	`double`	Investment estimate. 0 from `GenerateRoadmap`: not estimated.
`expected_roi_percent`	`double`	ROI estimate. 0 from `GenerateRoadmap`: not estimated.
`duration_months`	`int32`	Months.

SavingsCategory

Field	Type	Description
`category`	`string`	Category.
`amount_usd`	`double`	Savings in the category.
`action_count`	`int32`	Cards contributing.

SavingsTrend

Field	Type	Description
`period`	`string`	ISO week, for example `2026-W39`.
`amount_usd`	`double`	Savings.

RouteTwinCard

Field	Type	Description
`id`	`string`	Card id.
`title`	`string`	Title.
`origin`	`string`	Origin.
`destination`	`string`	Destination.
`distance`	`string`	Distance.
`duration`	`string`	Duration.
`cost_savings`	`string`	Stated saving, when a producer has one.
`route_polyline`	`string`	Encoded polyline.

EmailDraft

Field	Type	Description
`to`	`string`	Recipient.
`subject`	`string`	Subject.
`body`	`string`	Body.

CalendarInvite

Field	Type	Description
`title`	`string`	Title.
`description`	`string`	Description.
`start_time`	`string`	RFC 3339.
`end_time`	`string`	RFC 3339.
`attendees`	`repeated string`	Attendees.

ERPUpdate

Field	Type	Description
`system`	`string`	For example `SAP` or `Salesforce`.
`object_type`	`string`	For example `Inventory`, `Lead` or `Claim`.
`action`	`string`	`UPDATE` or `CREATE`.
`payload_json`	`string`	Payload.

RoadmapCard

Field	Type	Description
`current_level`	`string`	Current maturity level.
`target_level`	`string`	Target level.
`phases`	`repeated` `RoadmapPhase`	Phases.
`executive_summary`	`string`	Summary.

SpendAnalysisCard

Field	Type	Description
`total_spend_usd`	`double`	Total spend.
`identified_savings_usd`	`double`	Identified savings.
`top_categories`	`repeated string`	Top categories.
`consolidation_recommendation`	`string`	Recommendation.

RFPCard

Field	Type	Description
`rfp_title`	`string`	Title.
`rfp_content`	`string`	Content.
`evaluation_criteria`	`repeated string`	Criteria.
`recommended_vendors`	`repeated string`	Vendors.

SOPDocument

Field	Type	Description
`sop_id`	`string`	Id.
`title`	`string`	Title.
`content`	`string`	Content.
`process_name`	`string`	Process name.

SPOCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`forecast_accuracy`	`string`	Forecast accuracy.
`inventory_levels`	`string`	Inventory levels.
`recommendation`	`string`	Recommendation.

ClaimsCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`claim_number`	`string`	Claim number.
`status`	`string`	Status.
`amount`	`string`	Amount.
`reasoning`	`string`	Reasoning.

FulfilmentCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`order_number`	`string`	Order number.
`current_status`	`string`	Status.
`estimated_delivery`	`string`	Estimated delivery.
`issue`	`string`	Issue.

ReverseLogisticsCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`return_id`	`string`	Return id.
`item_condition`	`string`	Condition.
`refund_status`	`string`	Refund status.
`reasoning`	`string`	Reasoning.

ReactiveLogisticsCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`incident_id`	`string`	Incident id.
`disruption_type`	`string`	Disruption type.
`impacted_orders`	`string`	Impacted orders.
`resolution_plan`	`string`	Resolution plan.

EmissionsCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`scope`	`string`	What was measured, for example lanes and distance.
`total_co2e_kg`	`double`	Daily freight CO2e.
`annual_co2e_tonnes`	`double`	Annualised, on a working-day basis.
`highest_lane`	`string`	Worst-emitting lane.
`reduction_pct`	`double`	Achievable reduction.
`reduction_co2e_kg`	`double`	Daily CO2e abated.
`recommendation`	`string`	The abatement play.
`methodology`	`string`	Factor and basis, for the audit trail.

ColdChainCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`asset_id`	`string`	Refrigerated asset.
`breach_status`	`string`	Breach status.
`product_at_risk`	`string`	Load exposed.
`value_at_risk`	`double`	Value of the load exposed.
`excursion_detail`	`string`	Sensor reading or breach detail.
`corrective_action`	`string`	The dispatcher play.

MaintenanceCard

A channel’s measured trend against a limit the feed itself states. There is no model and no probability on this card.

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`equipment_id`	`string`	Equipment.
`failure_probability`	`double`	Always 0. Not a score and not a measured zero. Do not display it.
`predicted_failure`	`string`	The failure mode.
`recommended_action`	`string`	The intervention.
`downtime_impact`	`string`	Throughput or SLA at risk.

CustomsClearanceCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`entry_number`	`string`	Customs entry reference.
`shipment_id`	`string`	Shipment.
`port_of_entry`	`string`	Port of entry.
`clearance_status`	`string`	Status.
`hold_reason`	`string`	Hold reason.
`missing_documents`	`repeated string`	Missing documents.
`days_held`	`int32`	Days held.
`demurrage_exposure`	`double`	Demurrage exposure.
`recommended_action`	`string`	Recommended action.

ImporterOfRecordCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`shipment_id`	`string`	Shipment.
`country_of_import`	`string`	Country.
`declared_ior`	`string`	Declared importer of record. Empty when nobody is named.
`compliance_gap`	`string`	What is missing or wrong.
`duty_liability`	`double`	Duty and tax with no accountable party.
`hts_code`	`string`	HTS code.
`recommended_action`	`string`	Recommended action.

FreightForwardingCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`lane`	`string`	Lane.
`mode`	`string`	Mode, for example `OCEAN_LCL`.
`bookings`	`int32`	Separate bookings on the lane in the window.
`average_utilization_pct`	`double`	Average utilisation.
`current_spend`	`double`	Spend across those bookings.
`consolidation_saving`	`double`	Recoverable by consolidating.
`recommended_action`	`string`	Recommended action.

CrossBorderTruckingCard

Field	Type	Description
`id`	`string`	Id.
`title`	`string`	Title.
`crossing`	`string`	Crossing.
`carrier`	`string`	Carrier.
`border_dwell_hours`	`double`	Dwell at the border.
`scheduled_transit_hours`	`double`	Scheduled transit.
`actual_transit_hours`	`double`	Actual transit.
`loads_affected`	`int32`	Loads affected.
`detention_cost`	`double`	Detention accrued.
`root_cause`	`string`	Root cause.
`recommended_action`	`string`	Recommended action.

Enums

DeciderAttribution

Value	Meaning
`DECIDER_ATTRIBUTION_UNSPECIFIED`	Never written by `ExecuteAction`. On a stored entry it means the entry did not come from the decision path.
`DECIDER_ATTRIBUTION_VERIFIED_SUBJECT`	The session verified and named its subject. The only value an approval can carry.
`DECIDER_ATTRIBUTION_NO_SUBJECT_IN_TOKEN`	The session verified but carried no subject. Sign in again.
`DECIDER_ATTRIBUTION_NO_VERIFIED_IDENTITY`	No verified identity was attached to the call.

HypothesisScenarioState

Value	Meaning
`HYPOTHESIS_SCENARIO_STATE_UNSPECIFIED`	No census covers this scenario: unknown. Neither a failure nor a success.
`HYPOTHESIS_SCENARIO_STATE_SIMULATED`	Dispatched, and a simulation was produced.
`HYPOTHESIS_SCENARIO_STATE_FAILED`	Dispatched, and no simulation was produced.
`HYPOTHESIS_SCENARIO_STATE_CAPPED`	Proposed but not dispatched, because the swarm cap was reached.
`HYPOTHESIS_SCENARIO_STATE_NOT_IN_RUN`	Not proposed by that run at all: the scenario is newer than the census.

DispositionTriage

Value	Meaning
`DISPOSITION_TRIAGE_UNSPECIFIED`	Not set.
`DISPOSITION_TRIAGE_RESTOCK`	Restock.
`DISPOSITION_TRIAGE_REFURBISH`	Refurbish.
`DISPOSITION_TRIAGE_RECYCLE`	Recycle.
`DISPOSITION_TRIAGE_LANDFILL`	Landfill.

Fetch & traces Analysis, posture & rules