World Model Internals

Projection engines, write methods, auto-enrichment, and write scope isolation inside the event-sourced world model.

This page covers the internal mechanics of the world model: how events are written, how entity state is computed, how embeddings are generated, and how write permissions are enforced.

Write Methods

The world model exposes seven write methods. Each runs as a single database transaction that writes the event and recomputes the affected entity's state:

Method	What It Does
insert_event	Write a single event and recompute the entity it belongs to
ensure_entity	Create an entity shell if it doesn't exist (idempotent - does nothing if already present)
insert_fhir_event	Convenience wrapper that maps a FHIR resource to a world model event
upsert_fhir_event	Source-scoped idempotent write - creates, updates, or skips based on whether the source has already written this event
link_event_to_entity	Retroactively link a single event to an entity (for events that arrived before entity resolution completed)
link_events_to_entity	Batch version - links multiple events in one transaction
recompute_entity_state	Re-run the projection function for an entity without writing new events

All seven methods follow the same transactional pattern: the event write and the entity state recomputation happen atomically. There is no window where an event exists but the entity hasn't been updated.

Projection Engines

Entity state is never stored directly. It is computed from events by a projection function specific to the entity type:

Patient projection aggregates demographics, conditions, medications, allergies, appointments, and encounters. When multiple events provide the same field, the one with the highest confidence wins. Ties are broken by ingestion timestamp (most recent wins).

Outbound task projection computes status, priority, attempt count, retry timing, and call outcome from outbound-related events. This is what drives the connector runner's outbound dispatch loop.

Generic projection handles entity types without a specialized projection. It takes the highest-confidence event as the authoritative state.

Projections run inside the same transaction as the event write. This means entity state is always consistent with the event stream. If a transaction fails, neither the event nor the state update is persisted.

Auto-Enrichment

After an event is written and committed, the system generates vector embeddings in the background. This happens asynchronously - zero impact on write latency - and enables semantic search over world model data.

Embedding generation uses the configured provider (OpenAI, Gemini, or Vertex AI). If embedding credentials are unavailable, writes succeed without embeddings. Search functionality degrades, but data integrity is preserved. No event is ever blocked or dropped because of an embedding failure.

Write Scope Isolation

Voice agent tool writes are constrained by a write scope - a permission boundary that limits what entities and event types the agent can modify during a call. The write scope is configured per workspace and defines:

• Which entity types the agent can write to

• Which event types it can create

• What confidence level its writes carry

System services (connector runner, platform API) are trusted and bypass this restriction. They handle verified, confidence-gated data and operate outside the write scope.

This prevents a voice agent from accidentally overwriting authoritative EHR data with lower-confidence voice-extracted data. A patient's verified insurance information from a direct EHR integration cannot be replaced by something the caller mentioned on a phone call - the write scope blocks it at the data layer.

The write scope is enforced at the world writer layer, not at the API level. This means it cannot be bypassed by direct database access or alternative code paths. Every write from a voice agent context passes through the same permission check.

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