z0 Glossary

Canonical definitions for all z0 terms. This is the single source of truth.

When writing documentation, code, or discussing z0, use these terms precisely. If a term is missing, add it here first before using it elsewhere.

---

Primitives

The three irreducible concepts. See PRIMITIVES.md for formal specifications.

Entity

Something with identity that participates in economic activity. Entities have types (account, asset, tool, etc.), lifecycle states, and relationships to other entities. Everything that has an ID and matters economically is an Entity.

Fact

An immutable record of something that happened. Facts are append-only, timestamped, and typed. They form the ledger—the source of truth. Examples: invocation, outcome, charge, cost, access_granted.

Config

A versioned setting that governs behavior or determines values. Configs have versions; changes create new versions rather than mutations. Every Fact that depends on a Config records which version was applied.

---

Entity Types

Account

An Entity that transacts money. Accounts have subtypes: platform (z0 itself), tenant (agency), customer (buyer), publisher (partner). Accounts are the anchors of economic relationships.

Asset

An Entity created or operated through a tool that generates outcomes. Assets have owners, lifecycles, and costs. Examples: phone number, article, video, landing page, agent.

Tool

An Entity that executes invocations. Tools are global (tenant_id = null) and grouped by Vendor. Examples: Twilio Voice, OpenAI GPT-4, any API that z0 orchestrates.

Vendor

An Entity that groups Tools for accounts payable purposes. Vendors are global. Examples: Twilio Inc, OpenAI, Google.

Campaign

An Entity that scopes Configs and provides economic context for Facts. Campaigns group settings and define the context in which assets operate. Assets are not permanently assigned to campaigns—campaign context flows through at runtime.

User

A human actor. Users are global (tenant_id = null); their access to specific accounts is tracked via access_* Facts. Users can have subtypes: platform (z0 staff), standard (regular user).

Contact

An attribution target—the person or business receiving touches across multiple invocations. Contacts belong to tenants and may have multiple identifiers (phone, email). Contacts enable multi-touch attribution.

Deal

A conversion target synced from external CRM systems. z0 does not create Deals; z0 syncs them and tracks outcomes. Deals belong to Contacts. Deal status: open, won, lost. Deal stage (from CRM) is metadata.

---

Fact Types

Invocation

A Fact recording that a Tool was called. The atomic unit of tool interaction. Has inputs, outputs, timing, and generates Cost facts.

Outcome

A Fact recording a resolved business state. Outcomes have subtypes (call_qualified, deal_won, etc.) and can come from internal evaluation or external systems (CRM, Calendly).

Charge

A Fact recording accounts receivable—money owed to us (z0 or tenant) from a customer. Every charge traces to an outcome via source_id.

Payout

A Fact recording accounts payable—money owed to a partner/publisher. Every payout traces to an outcome via source_id.

Cost

A Fact recording accounts payable—money owed to a vendor for tool usage. Every cost traces to an invocation via source_id.

Deposit

A Fact recording prepaid funds received from a customer.

Lifecycle

A Fact recording an Entity state change. Used to track status transitions over time.

Access Facts

Facts recording permission changes for users:

• access_granted: User given access to an entity
• access_modified: User permissions changed
• access_revoked: User access removed

All access Facts require user_id and entity_id.

Decision

A Fact recording an autonomous agent choice. Includes the action taken, alternatives considered, reasoning, and which autonomy Config permitted the decision. Required for AI auditability.

Reconciliation

A Fact recording when cached state diverged from the ledger. Includes the cache type, cached value, calculated value, and resolution action. Used for observability and debugging.

---

Config Types

Pricing Config

Logic config that determines what to charge or pay per outcome. Evaluated at outcome time.

Qualification Config

Logic config that determines what counts as a valid outcome. Evaluated at outcome time.

Routing Config

Logic config that determines where to send traffic. Evaluated at invocation time.

Budget Config

Policy config that sets spending eligibility thresholds. Determines whether an entity can participate in routing decisions.

Billing Config

Policy config that defines payment relationships and terms between accounts.

Autonomy Config

Policy config that defines what actions an agent is permitted to take automatically.

Hours Config

Policy config that defines operating schedule—when an entity is available.

---

Cached State Types

Derived state for runtime performance. Not primitives. Reconcilable against Facts.

BudgetState

Tracks remaining budget for an entity. Derived from charge Facts. Used for eligibility filtering.

CapState

Tracks rate limit consumption. Derived from invocation Facts. Supports multiple cap types (daily, hourly, concurrent).

PrepaidBalance

Tracks prepaid account balance. Derived from deposit and charge Facts.

AccessState

Tracks current user permissions for an entity. Derived from access_* Facts.

ContactCanonical

Maps merged contact IDs to their canonical (surviving) contact. Derived from contact_merged Facts.

Update timing: ContactCanonical is updated synchronously when the contact_merged Fact is written. The merge operation is atomic—the Fact write and cache update occur in the same Durable Object transaction.

Query pattern: Always resolve contact_id through ContactCanonical before attribution queries to ensure merged contacts are handled correctly.

SettlementState

Tracks incurred vs settled economics for an Account. Essential for understanding the gap between “what we owe” and “what we’ve paid.”

Fields:

• pending_charges/payouts/costs: Amounts incurred but not yet settled
• settled_charges/payouts/costs: Amounts that have completed settlement
• settlement_lag_ms: Current delay between incurred and settled
• oldest_pending_at: Timestamp of oldest unsettled item

Derivation: From charge, payout, cost Facts plus their settlement_* counterpart Facts.

Use case: Monitoring settlement health, detecting settlement delays, AR/AP aging reports.

---

Core Concepts

Control Plane

The layer that governs how tools are used, what assets exist, and how economics flow. z0 is a control plane—it sits between tools and outcomes, providing visibility and governance. z0 has no native capabilities; it orchestrates external tools.

Ledger

The append-only log of Facts stored in each Durable Object. The source of truth. Immutable. Everything else (cached state, calculations, views) derives from the ledger.

Storage: Each Entity has its own ledger stored as a facts table in its Durable Object’s SQLite database. Cross-entity queries use D1 replication.

Properties:

• Append-only: Facts are inserted, never updated or deleted
• Ordered: Facts have monotonically increasing IDs within a ledger
• Immutable: Once written, a Fact cannot change
• Authoritative: On conflict between cached state and ledger, ledger wins

Economic Truth

The verifiable, auditable answer to “was this worth it?” Requires connecting costs to outcomes through complete traceability chains.

Attribution

The calculation of which assets, touches, or actions get credit for an outcome. Attribution is performed by the Interpretation Engine using the ledger plus an attribution model (Config). Attribution is calculation, not storage.

Attribution Levels

Three levels of attribution granularity:

• Invocation level: Which asset/campaign drove this call? (Always available)
• Contact level: Which touches reached this person? (Requires contact_id)
• Deal level: Which touches led to this sale? (Requires contact → deal chain)

Interpretation Engine

The calculation layer that produces attribution, ROI, revenue splits, and other derived metrics. Stateless. Takes ledger data + Config (attribution model) as input. Fully re-runnable with different models.

RTB (Real-Time Bidding) Model

The execution model for routing decisions. Budget is eligibility—no budget means not in the auction. Cached state is checked before routing. Eligibility is filtered, then selection/auction occurs.

Reconciliation

The process of validating cached state against Facts. Ensures cached state doesn’t drift from ledger truth.

Process:

1. Replay all relevant Facts for an Entity
2. Recalculate what cached state should be
3. Compare with current cached state
4. If different: log a reconciliation Fact, apply correction

Resolution: Facts always win. If BudgetState shows $500 remaining but Facts calculate $450, BudgetState is corrected to $450.

Frequency: Configurable per tenant via Config. Typically runs on schedule (hourly/daily) and on-demand when anomalies detected.

Observability: Every drift generates a reconciliation Fact with cached_value, calculated_value, and resolution action.

Invocation Chaining

Linking related invocations via parent_invocation_id. Used for multi-step workflows like call transfers, AI agent chains, and retry sequences. Enables cost aggregation and workflow tracing across multiple tool calls.

Trace ID

An optional identifier on Facts that links business events to execution traces. Enables correlation between “what happened” (Facts) and “how it happened” (spans/traces). Propagated through all downstream calls in a request.

Soft Delete

The pattern for disabling Configs without destroying data. Configs are never deleted—they are disabled by setting enabled: false. This preserves historical references and audit trails.

Why not hard delete: Facts reference Config versions by ID. Deleting a Config would break those references. Setting enabled: false removes the Config from active use while preserving the historical record.

Pattern:

PATCH /v1/configs/webhooks/{id}
{ "enabled": false }

Query behavior: By default, list endpoints exclude disabled Configs. Use ?include_disabled=true to see them.

Idempotency Key

A client-provided identifier that ensures an operation executes exactly once. If the same key is submitted again, the original result is returned without re-executing.

Storage: Idempotency keys are stored in SQLite within the Durable Object, with TTL-based expiration.

Format: Typically {client_id}:{operation}:{unique_id} or a UUID.

Scope: Keys are scoped to the Entity they operate on. The same key on different Entities is treated as distinct.

Escalation

An autonomous agent action that requires human approval. When an agent encounters a decision that exceeds its autonomy Config thresholds, it escalates rather than acting.

Types:

• Hard threshold exceeded: Action blocked, human must approve
• Soft threshold exceeded: Action logged as requiring review, may proceed with caution flag

Audit: Escalations generate decision Facts with escalation_triggered subtype.

---

Infrastructure Terms

Durable Object

A Cloudflare primitive providing single-threaded, stateful compute with strong consistency. Used in z0 for per-entity ledgers and cached state.

Worker

A Cloudflare serverless function running at the edge. Stateless compute that handles requests and orchestrates other infrastructure.

D1

Cloudflare’s distributed SQLite database. Used for reporting and cross-entity queries.

R2

Cloudflare’s object storage. Used for context store (recordings, transcripts), archives.

Queue

Cloudflare’s message queue. Used for async processing, decoupling producers from consumers.

Workflow

Cloudflare’s durable execution primitive. Used for long-running, multi-step processes (outcome resolution, migrations).

Circuit Breaker

A failure protection pattern that stops calling a failing service to prevent cascade failures. Named after electrical circuit breakers.

States:

• Closed: Normal operation, requests pass through
• Open: Failures exceeded threshold, requests fail fast without calling service
• Half-Open: Testing if service recovered, limited requests allowed

z0 Usage: Protects external tool calls (Twilio, AI providers). When a vendor fails repeatedly, circuit opens to prevent wasting budget on doomed calls.

Dead Letter Queue (DLQ)

A queue for messages that couldn’t be processed after all retry attempts. Enables human review and manual recovery without blocking the main processing pipeline.

Contents: Original message, error details, retry history, timestamps.

Resolution: Items in DLQ can be inspected, fixed, and replayed, or discarded if truly unrecoverable.

Workers for Platforms

Cloudflare’s multi-tenant worker isolation. Provides per-tenant metering, isolation, and deployment.

Analytics Engine

Cloudflare’s high-cardinality metrics system. Used for real-time usage metrics and dashboards.

---

Resource Types

Not primitives. Named settings with identity.

Template

Reusable content (email templates, SMS templates, scripts).

Integration

External system connection (HubSpot, Salesforce, Calendly). Holds configuration and secret references, not actual credentials.

---

Economic Terms

AR (Accounts Receivable)

Money owed to us. Tracked via charge Facts.

AP (Accounts Payable)

Money owed to others. Tracked via cost Facts (to vendors) and payout Facts (to partners).

ROI (Return on Investment)

Economic measure: (revenue - cost) / cost. Calculated by Interpretation Engine, not stored.

TTV (Time to Value)

Duration from action (invocation) to realized outcome. A key metric for economic evaluation.

Settlement

The process of converting incurred economics (what was owed) into settled economics (what was paid). Settlement bridges the gap between “we owe you $100” and “$100 transferred to your account.”

z0 Model: z0 tracks economics at both stages:

• Incurred: charge/payout/cost Facts record what’s owed
• Settled: settlement_* Facts record when actual money moved

Why both: Revenue recognition timing differs from cash flow timing. A charge may be incurred today but not settled until the invoice is paid next month.

Hot Path / Cold Path

Architectural separation between time-critical and time-tolerant operations.

Hot Path: Operations that must complete in milliseconds. Examples: RTB eligibility checks, routing decisions, cached state reads. Hot path uses Durable Object memory and SQLite.

Cold Path: Operations that can take seconds to minutes. Examples: reconciliation, settlement processing, report generation. Cold path uses Queues, Workflows, and D1.

Design Principle: Never put cold-path operations on the hot path. Route decisions should never wait for settlement calculations.

Currency Handling

Storage: Facts always store amounts in their original currency. A charge from a EUR customer stores EUR. A cost from a USD vendor stores USD. Currency is never converted at write time.

Why: Currency conversion rates change. Converting at write time bakes in a rate that may be disputed, restated, or simply wrong for the reporting period. Storing original currency preserves economic truth.

Conversion: Currency conversion is performed at reporting time using exchange rates appropriate to the report’s purpose:

• Financial reports: Use official rates for the reporting period
• Real-time dashboards: Use current spot rates
• Reconciliation: Use rates specified in billing Configs

Rate Storage: Exchange rates used in calculations are stored as metadata on aggregations/reports, not as Facts. This allows recalculation with different rates without modifying the ledger.

Multi-Currency Queries:

// Facts store original amounts
Fact { type: "charge", amount: 100, currency: "EUR", ... }
Fact { type: "cost", amount: 85, currency: "USD", ... }

// Reporting layer converts at query time
SELECT
  SUM(amount * exchange_rate(currency, 'USD', report_date)) as total_usd
FROM facts
WHERE ...

Invariants:

• Facts never store converted amounts
• Facts never store exchange rates (rates are not events)
• Currency field is required on all monetary Facts (charge, cost, payout, deposit)
• Empty/null currency is invalid

Default Currency: Accounts have a default_currency in their Config. New monetary Facts default to this currency when source doesn’t specify. Tenant billing Config specifies the billing currency for invoices.

---

Relationship Terms

Owner

The account that owns an asset. Determines tenant_id for the asset. Ownership is economic—who pays, who benefits.

Operated By

The tool that operates an asset. A phone number is operated by Twilio Voice. Operational relationship, not ownership.

Parent

Hierarchical relationship between entities. Customers and publishers have tenant as parent. Campaigns have account as parent.

---

Status Values

Entity Status

• active: Operating normally
• paused: Temporarily inactive
• retired: Permanently inactive

Deal Status

• open: In progress
• won: Closed successfully
• lost: Closed unsuccessfully

---

Abbreviations

Abbrev	Expansion	Definition
AP	Accounts Payable	Money owed to others
AR	Accounts Receivable	Money owed to us
CRM	Customer Relationship Management	External system (HubSpot, Salesforce)
DLQ	Dead Letter Queue	Queue for messages that failed all retries
DO	Durable Object	Cloudflare’s stateful compute primitive
MCP	Model Context Protocol	Standard for AI model tool integration
ROI	Return on Investment	(revenue - cost) / cost
RTB	Real-Time Bidding	Routing model where budget = eligibility
TTL	Time to Live	Expiration duration for cached data
TTV	Time to Value	Duration from action to outcome

---

Adding New Terms

1. Check if the concept maps to an existing term
2. If truly new, add it to the appropriate section above
3. Include: term name, concise definition, examples if helpful
4. Ensure consistency with PRIMITIVES.md and PRINCIPLES.md
5. Update any documents that use the term inconsistently