Data model

Everything in Fibric reduces to a small set of objects: an envelope records that something happened, a plan records what an operator proposes to do about it, an action is one governed step of that plan, and a receipt records how each step disposed. All of it is owned by exactly one tenant, optionally under a reseller. This page is the field-level reference for those objects, with names taken directly from the kernel types.

#The object graph

The flow of one governed operation, left to right:

source system ──> EventEnvelope ──> operator ──> ExecutionPlan ──> executor ──> Receipt
                       │                              │                │
                  event_log row                 PlannedAction[]   ALLOW / ALERT /
                  (tenant-scoped)               each with          BLOCK / DEDUP
                                                entity_key +       per action
                                                idempotency_key

Every object in the chain carries the tenancy pair, reseller_id and tenant_id, and a correlation_id ties the chain together end to end: given a receipt you can walk back to the plan, the envelope, and the source event that started it. The architecture overview covers the flow; the sections below cover the fields.

#Envelopes

The EventEnvelope is the one canonical event shape. A commerce webhook, a sensor reading, a cron tick, and an operator's own output all become envelopes, which is what makes the platform vertical-agnostic: a thermostat fault and a support message flow through identical machinery. The interface, from packages/kernel/src/envelope.ts:

Envelopes are constructed through makeEnvelope(input), which fills event_id, defaults reseller_id, workspace_id, agent_id, and session_id to null, defaults payload to {}, and generates a correlation_id when none is given. Over HTTP the same shape is created by POST /v1/events; see the Events API and the event envelope concept page.

#Entities and entity keys

Fibric has no entity table. An entity is whatever real-world thing your actions must not trample concurrently, one order, one conversation, one HVAC zone, and it exists in the data model as a key: the entity_key that every planned action carries. Actions sharing an entity_key are serialized by the executor's single-flight gate; actions on different keys run independently.

Key discipline matters more than key format. Derive the key from the thing itself, stable across retries and across operators:

conversation:kustomer:64f2…      one support conversation
order:magento:SO-10884           one commerce order
asset:hvac:bldg-2:zone-14        one physical zone

The Events API also indexes events by the entity keys of the actions they triggered, so GET /v1/events?entity=order:magento:SO-10884 reconstructs everything that ever touched one order. See Single-flight & idempotency for the serialization semantics.

#Plans and actions

An operator's entire output is an ExecutionPlan: optional reasoning plus an ordered list of actions. The operator proposes; the deterministic executor disposes. From packages/kernel/src/trust.ts:

Plans surface over HTTP with pl_ identifiers and a lifecycle (proposed, approval for ALERT actions, execution, veto); see the Actions & plans API.

#Action results and dispositions

Each action the executor processes produces an ActionResult. Its decision field is an ActionDisposition, the three trust decisions plus one the executor adds itself:

#Receipts

A receipt is the durable, tenant-scoped record of one disposition: what was proposed, what the gate decided, what ran, what came back, and who approved or vetoed if a human was involved. Receipts are immutable and append-only; correcting course produces a new receipt (an undo is itself a receipted action), never an edit. They carry the correlation_id of their originating envelope, which is what makes the ledger walkable. Receipts have their own concept page, Receipts & audit, and their own API, including export.

#Tenants, resellers, workspaces

Ownership is a three-level hierarchy defined in db/migrations/0001_tenancy.sql:

The tenant boundary is the hard wall, enforced by Postgres row-level security on every tenant table; the workspace boundary subdivides what is already inside it. The enforcement mechanics, the verbatim policy, the fibric_app role, are documented in Tenancy & isolation, and the environment implications in Environments.

#Identifiers

API-surfaced objects use prefixed identifiers so an id is recognizable out of context:

Internal rows, tenants, resellers, envelopes at rest, use UUIDs. entity_key and idempotency_key are caller-defined strings, not platform identifiers; the platform treats them as opaque.

#Storage shape

The event log is the exemplar every tenant table follows: the envelope's fields become columns, the tenancy pair is physically present on the row, and tenant_id is NOT NULL with a foreign key, so a row without an owner cannot reach disk.

CREATE TABLE IF NOT EXISTS event_log (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  reseller_id     uuid,
  tenant_id       uuid NOT NULL REFERENCES tenants(id),
  workspace_id    uuid,
  source          text NOT NULL,
  event_type      text NOT NULL,
  correlation_id  uuid NOT NULL,
  payload         jsonb NOT NULL DEFAULT '{}',
  created_at      timestamptz NOT NULL DEFAULT now()
);

Continue with the event envelope for envelope semantics in depth, the API overview for the HTTP view of these objects, and Reliability and delivery semantics for how they behave under retries and failures.