World Model

Event-sourced data layer that accepts supported healthcare inputs, preserves provenance and confidence, and projects current entity state.

The Health World Model is the platform's persistent, time-aware representation of patients, other entities, relationships, observations, and current state. Connectors, specialized applications, agent tools, and analytics contribute or consume workspace-scoped data through supported interfaces. Agents receive a bounded amount of selected context automatically and use tools for facts that are not already present.

This creates a feedback loop between data and agent activity without making every observation automatically available or writable. Session construction selects ambient context, tools perform explicit reads and writes, and accepted observations can become inputs to later projections and analytics.

The world model preserves supported observations with provenance and a source-class confidence value. Current entity state is a computed projection over retained relevant events rather than an in-place record update. Projection rules can therefore resolve conflicting inputs without discarding their retained history.

Supported observations are recorded as events. Current entity state is derived from the relevant retained events. Recording an observation preserves what its source reported; it does not independently verify the observation.

Place in the System

Follow One Patient, Two Workflows to see a prescription, patient report, measurements, and a reviewed note support a follow-up application. The case includes source evidence, separate completion signals, and a downloadable record.

The world model supplies shared context to several consumers. It is distinct from the Context Graph, which describes how an agent should work, and from memory, which can supply generated context from prior interactions. An external system still determines whether it accepted a requested change.

Read this page in three parts: how source evidence is retained, how projections select current values, and how a conversation reads or contributes observations. Core Concepts introduces the relationships; How It Works follows them through an appointment change.

Data Pipeline

The broader liquid world-model perspective treats SQL transformations, bounded classifications, and model-generated interpretations as different ways to derive task-relevant views. Each derivation retains its own evidence, uncertainty, and freshness requirements. The term does not imply an automatically evolving schema, a learned simulator, or synchronous visibility for every observation.

For the surrounding architecture, see Shared Context and Applications. Applications own their sessions, tasks, decisions, and transactions; the world model supplies shared evidence and views, not a universal application state machine.

Projection and external delivery are separate paths. Verify queryability and destination outcomes independently.

Data enters from external systems through connectors, passes through unification into the event store, and resolves into entity projections. Agent conversations add source-attributed observations to the same model. Metrics and analytics read the resulting state and history. Outbound policies separately decide which events are eligible for delivery. Where connector review is enabled, an eligible mutation is staged as a proposal before an authorized reviewer decides whether to approve it. That decision does not change the source event's confidence.

Evidence, Facts, and Application Views

These layers answer different questions: what was reported, what is selected now, and what this application is allowed to use.

A source assertion records what a source reported, not independent proof of that claim. A selected fact is the value chosen by the relevant projection rules. An application view selects or derives information for a particular reader and task. Selection does not remove the need to inspect source quality, contradictory evidence, or missing coverage.

Time and Corrections

Distinguish when something happened or became effective, when the source observed it, when it was received, and when a consumer could read the resulting view. Those times need not match. Verify each connector's timestamp meaning; a recent receipt can contain an old observation.

A correction adds evidence with its own source and supersession relationship where supported. The affected projection can change without rewriting the earlier retained observation. Applications must decide what to do with pending work that used the older view. A changed projection does not automatically cancel a booking or undo another external transaction.

An absent value means the required information was not found in the available view. It does not prove that the event never happened or the condition is absent. Likewise, a prescription, reported medication use, symptoms, and measurements can be connected without inferring a causal relationship between them.

To test those distinctions across applications, use Connect Another Workflow.

Why Event Sourcing for Healthcare

Healthcare data varies widely in structure, freshness, and authority. The world model is designed to make those differences explicit instead of treating every input as equally reliable.

Source records can be incomplete or stale. Clinical notes, copied templates, structured records, and operational systems capture different parts of a patient's history. Retaining source and effective time lets consumers distinguish a recent observation from an older record instead of assuming that every field is current.

Patient observations and verified records serve different purposes. A caller can report a new symptom or correct an old address while also being uncertain about a medication name or appointment date. Record the observation with its source, then use the workflow's verification rules before acting on it. A lower-ranked observation can remain in the retained history even when it does not become the projected value.

External systems have uneven reliability and throughput. EHRs, FHIR stores, practice management systems, and insurance verification services all behave differently. Response times vary, timeouts occur, and some sources can return stale data. Integrations should therefore expose failure and freshness rather than assume constant availability.

An overwritten value is not enough evidence. A current-value record alone cannot explain which source contributed the value, what it replaced, or what change was intended when a downstream operation failed. Conflict handling needs an explicit policy. World-model observations instead carry source and confidence, with supersession data where applicable. Current state is projected without rewriting the contributing events. Historical availability remains subject to explicit lifecycle actions, retention, and the bounds of each read surface.

Four Invariants

The world model follows four core rules, with the lifecycle exceptions called out below.

1. World-Model Writes Become Events

Supported world-model write paths add events rather than editing the projected entity row. The serving state is recomputed asynchronously from the retained events relevant to that entity.

Under normal retention, competing observations remain separate events. Supported projections apply their own source-based precedence and recency rules rather than blindly applying global last-write-wins behavior. Some compare numeric source-class confidence directly; enrichment groups those values into precedence tiers.

2. Events Are Append-Only and Immutable

An accepted event is not updated in place. If new information contradicts an earlier event, a new event can supersede it while both remain available under normal retention. Authorized retention, erasure, and workspace-lifecycle operations remain separate exceptions.

Corrections retain their own provenance. While the contributing events remain available, a reviewer can inspect the earlier observation and the correction selected by the projection. Source validation and correction procedures remain necessary before using that data for an operational decision.

This matters for healthcare operations because it provides:

• Projection evidence - Retained source events can explain which observations contributed to modeled state.
• Temporal analysis - Historical event reads can support point-in-time reconstruction where the required events and projection logic remain available.
• Correction without in-place mutation - A new event can supersede an earlier observation instead of editing it.

3. Entity State Uses Explicit Projection Rules

Entity-state projections use explicit rules to select and derive values from retained evidence. Reproducing a deterministic derivation requires the same complete inputs, configuration, and projection logic, including evaluation time for time-relative values. An upcoming-appointment indicator can change when recomputed after an appointment's start without any change to the appointment events. Retained events and a projection version alone therefore do not guarantee identical replay; this is not a promise of a general as-of query or replay API. Projection runs asynchronously from event acceptance, so a successful write can precede the updated serving view. Time-relative fields describe their evaluation point, not a guarantee of continuous freshness between projection runs.

Source-linked rules make selected values inspectable. Outbound delivery is a separate path: a published event is evaluated against destination policy, and the connector sends that eligible event payload without rebuilding the entity projection at delivery time. A patient's phone number might still project from a higher-confidence EHR observation instead of a lower-confidence conversational observation, but only an event selected by outbound policy is considered for external delivery.

Multi-Level Projections

Entity state is one derived view, but not the only one. Different derived products use different methods. Deterministic folds and structured connector transformations depend on their complete input and evaluation context. Episodic memory extraction and semantic user-model consolidation are model-generated, bounded processes that retain lineage to their supporting observations; identical inputs do not guarantee identical narrative text.

Level	What It Projects	Derived From
Entity state	Current state of each patient, provider, appointment, and other entity	Raw events
Conversation memory	Episodic observations and a consolidated user model with source lineage	Conversation transcripts and prior memory
Structured context	Connector-derived context such as current conditions, medications, and allergies	Current entity and connector records
Operational and analytical views	Scheduling, quality, and workflow-specific summaries	The inputs defined by each view

A new event can update entity state after asynchronous projection and can become input to other derived products on their own processing schedules. Each product documents its own derivation and freshness rather than inheriting a universal deterministic chain.

4. Confidence Resolves Conflicts

When two sources provide conflicting information about the same fact, the applicable projection determines how source-class confidence and recency select the current value. The source classes below are provenance ranks, not probabilities. They are also distinct from the precedence tiers used by enrichment.

Confidence	Source	Example
1.0	Authoritative	Manual entry, explicit relationships, authoritative API writes
0.95	Human-approved class	Named confidence class retained in the world-model registry; current external-write proposal decisions do not promote source observations into it
0.9	High	Operator-verified data, high-quality adapter output
0.8	EHR-trusted	Trusted clinical data from EHR systems
0.7	Verified	Data assigned the verified source class by a supported producer
0.5	Self-report	Patient-submitted form data, patient-confirmed information
0.3	Agent raw	Raw voice agent inference, unverified extraction from conversation
0.0	Rejected	Observations explicitly assigned the rejected source class

FHIR-sourced attribute projections compare numeric source-class confidence, then ingestion time. Enrichment instead compares its confidence tier, effective time, ingestion time, and event identifier, in that order. Different source classes can share an enrichment tier, so a larger numeric confidence value does not always win. A recent caller report can remain in history while an older, higher-ranked source supplies the projected value. Source rank alone does not establish that the selected value is current or correct.

Confidence is a source-class ranking, not model-reported certainty. Supported agent-originated clinical writes default to the agent_raw class unless a trusted server path supplies a different allowed value. Later observations from a higher-ranked source can supersede the projected value without erasing retained provenance.

Phone projections normalize valid numbers before caller matching. International country codes are preserved, North American numbers are standardized when the country can be inferred safely, and non-phone text is excluded. Ambiguous national formats are retained without inventing a country code. This normalization improves matching across differently formatted source values but does not replace identity verification.

Entity-state fields retain the winning event's source and confidence. Other derived products do not inherit a universal confidence rule: structured connector projections, generated memory, and analytical views each define their own derivation and evidence. Consumers should use the provenance and quality signals exposed by the specific product rather than assuming confidence propagates unchanged through every downstream view.

Three Data Channels

It is useful to think about agent data access through three channels. The exact payload and tools depend on the service, session, runtime, and workspace configuration.

Ambient

Selected data that is pushed into the agent's context without a tool call when the session and service configuration make it available. Examples can include patient identity, upcoming appointments, or recent encounter context. Missing or unavailable source data is not invented.

This channel reduces repetitive lookups for the bounded context selected at session or turn construction. It does not guarantee that every current clinical or operational fact is loaded; the agent still uses queried tools for authoritative details outside the ambient payload.

Queried

Data that the agent retrieves on demand through tool calls during a conversation. The agent decides it needs specific information and requests it. Examples: searching for available appointment slots, looking up insurance details, checking medication lists.

Queried data covers information that is too large, too dynamic, or too specific to include in ambient context. Tools should remain the authoritative path for details that require a current lookup.

Extracted

Supported extraction and write tools can capture structured observations from a conversation. Agent-originated clinical writes normally use the agent_raw source class unless a trusted server path assigns another allowed value.

During a live voice call, the system can extract configured structured patient fields from recent conversation context, including contact, demographic, language, address, and insurance information. Captured fields are written as source-attributed events and can become available before the call ends.

Extraction is an explicit configured runtime capability. Do not assume that every statement in a conversation becomes a world-model event.

Extracted data enters the world model with source provenance and confidence. Unattended outbound delivery applies source eligibility, confidence thresholds, schema checks, and destination rules. Where private-preview connector review is enabled, an otherwise eligible event can be staged for approval at any confidence; the decision authorizes that specific proposal without promoting the observation's confidence. See Connectors and EHR Integration.

Open Schema

The event model supports additional types of observations while retaining a common structure for identity, source, and time. New types still require agreed business definitions, validation, and consumer support.

Entity-type and event-type fields are text rather than database enums, so trusted producers can introduce a new type without an enum migration. That does not make arbitrary input self-structuring: the producer must still provide a valid event, and consumers need projection or query support for the new shape.

This flexibility is bounded by the caller's write scope, registered enrichment keys, route validation, and the projection support available for a new type.

Entity Ontology

Entity types use ontological categories rather than domain-specific roles. A person entity can be a patient, a practitioner, or both - the projection function detects roles from the underlying event data rather than requiring a type declaration up front.

Person projection is role-aware. It examines the FHIR resource types on an entity's events to detect which roles the person fills and produces output that includes the relevant sections for each role. A person entity with patient events gets demographics and clinical sections. One with practitioner events gets a profile section. A merged entity with both gets all sections plus a roles list. This means a single person entity can represent the same individual across clinical and operational contexts.

FHIR-Sourced Entity Attributes

When data arrives through EHR connectors that support FHIR, the projection pipeline surfaces a rich set of fields as directly queryable entity attributes. This means agent tools can filter, search, and reason over these fields without parsing raw FHIR resources.

Entity Type	Projected Fields
Patient	Full address (line, city, state, postal code, country), preferred language, marital status, race, ethnicity, emergency contact (name, phone, relationship), facility assignment, primary insurance (payer name, practice payer ID, member ID, policyholder name, policyholder relationship, policyholder DOB)
Appointment	Participants (provider, patient, location references and display names), appointment type, modality, duration, timezone, cancellation reason
Slot	Provider, facility, specialty, visit type IDs and names
Practitioner	Member ID, scheduling eligibility
Location	Full address, timezone, facility identifier, geographic coordinates

State and territory values are normalized to standard two-letter abbreviations (e.g., "Virginia" becomes "VA"), so agent queries and licensed-state filters work consistently regardless of how the source system formats addresses.

These FHIR-sourced attribute projections prefer higher numeric source-class confidence, then later ingestion time. Do not generalize that exact ordering to all entity data: enrichment, relationships, and other projections have their own resolution rules.

Other built-in entity types - place, organization, outbound task, call, and encounter - have dedicated projection logic. Unknown types can fall back to generic projection; richer custom projections require a supported configuration or implementation path.

Entity Enrichment

Entity enrichment adds workspace-defined attributes to an entity, such as a preferred communication channel or a program-specific status. Each attribute follows registered validation rules and retains source evidence. Use existing resource fields where they already represent the intended information; define enrichment keys for the additional attributes the workflow needs.

Each enrichment value is a per-key event carrying provenance fields such as source, source system, confidence, and effective time. A patient's preferred language from a human operator, a configured data import, and a call transcript can coexist as separate events. The projection groups source-confidence values into precedence tiers, then selects within a tier by effective time, ingestion time, and event identifier. The tiers are not one-to-one with the named source classes.

Registry-Governed Keys

Each workspace registers its enrichment keys before use. The registry specifies the entity type, allowed values, value type, minimum write confidence, and whether the value is personally identifiable information (PII). Supported types include string, number, boolean, date, enum, and JSON.

API writes against unregistered keys are rejected. Agent-extracted values with unregistered keys are dropped before entering the event stream. Register the required keys and verify the retained values when testing a capture workflow; a conversation mentioning an attribute does not prove it was stored.

The key identifier and value type are immutable after registration. To change them, admins create a new key and migrate. Unregistering a key stops future writes but does not itself rewrite existing entity.enriched events; separate retention or source-lifecycle actions can still affect historical availability.

Resolve Competing Enrichment Values

Manual admin edits, supported connector backfills, structured intake, and agent extraction can all contribute enrichment values. The projection applies the precedence rules described above to choose a value while preserving the contributing observations. Inspect that provenance when a projected value differs from a recent conversation or correction.

Entity Search

The current entity list supports case-insensitive text search across identifiers, display name, entity type, medical-record number, and phone, with additional filters for entity type, source, source system, FHIR resource type, and projection availability. The entity-intelligence search surface provides display-name search with selected filters.

Meaning-based entity retrieval is not currently available. The legacy search_semantic compatibility tool returns no results; use the supported text and field filters instead.

Write Semantics

World-model writes submit events, and entity state is projected asynchronously. A successful API response does not imply that the new value is already visible in the entity projection. Use the response semantics of the specific endpoint and allow for projection delay. Supported patterns include:

• Single-event submission followed by asynchronous entity projection
• Deterministic entity identifiers when the caller supplies a canonical identifier or explicit entity ID; creation without either is not idempotent
• FHIR upserts that link a new event to the prior event for the same source resource through supersedes
• Per-key enrichment history with current-winner selection by the enrichment precedence tier and its timestamp and identifier tiebreakers

Fresh Enrichment During a Conversation

Where enabled for the workspace, supported interactive enrichment writes can also become available through a temporary read overlay before the asynchronous projection catches up. Conversation reads use the same precedence-tier, timestamp, and identifier ordering as the enrichment projection. A newer observation in a lower tier does not displace a higher-tier value; within one tier, recency can decide even when numeric source-confidence values differ.

This path is best-effort and requires the applicable write and read capabilities to be enabled. A failed overlay write or read falls back to projection freshness. Connector ingestion, replay, and batch updates still follow their asynchronous projection path. The overlay does not make all world-model writes immediately visible.

Write Scope Isolation

Supported agent write tools receive a server-constructed write scope that limits the workspace and entity they can target, whether creation is allowed, and the resource types or confidence available to the operation. The exact scope depends on the session and runtime.

Trusted system services use separate service authorization rather than an agent session's write scope. Their access is not evidence that a model-originated tool call can bypass its own scope.

Write scope constrains supported model-originated persistence paths, while the applicable projection rules separately select the read value from eligible retained observations. Customers should validate the specific tools, projections, and runtimes they enable rather than infer one universal check across every code path.

Write scope isolation is one of the platform's structural safety controls. For how this fits into the broader safety architecture, see Runtime Safety.

Direct Agent Access via Platform Functions

Beyond the three data channels, agents can query world model data directly using platform functions. These are SQL, AI, Python, and table-valued functions that run on the platform's compute layer and return results mid-conversation. Unlike the ambient channel (pre-loaded context) or the queried channel (built-in tool calls), platform functions can join live entity data with analytical aggregations in a single call.

Registered platform functions can cover common patterns: entity confidence assessment (which source classes and update times support this patient's projection?), caller history lookup (what happened in prior calls with this number?), and patient summary briefings. Availability depends on workspace registration and the selected runtime. For the long tail of questions no pre-built function anticipated, a workspace registers parameterized data queries (wsq_<name>) that run against its own custom tables. Platform functions are read-only; recording new observations as world model events is done through dedicated write tools. Those tools enforce the write scope for their runtime, and accepted events become visible through the asynchronous projection semantics described above.

For the full platform functions reference, see Platform Functions.

Developer Guide - For API endpoints, SDK examples, and integration details, see the Data & World Model section of the developer guide.