z0 Principles

Non-negotiable truths that govern all z0 design decisions.

These principles are axiomatic. They are not suggestions, best practices, or guidelines. Every pattern, product, and line of code must be traceable back to these principles. If something violates a principle, it is wrong—regardless of how clever, efficient, or expedient it may seem.

---

The Philosophy

You cannot change the past. You can only change how you look at it, and use that to make better decisions in the future.

You are not defined by circumstances, but by how you choose to interpret them.

This philosophy underpins everything. Facts record what happened. Config determines how we interpret it. Together they enable simulation, analysis, and optimization.

---

Platform Principles

10 principles organized by primitive. These are enforced by the SDK.

Fact (3 Principles)

#	Principle	Description
1	Facts are immutable	Once written, a fact cannot be changed. Corrections create new facts.
2	Time-travel to the past is possible	Any moment in history can be reconstructed by replaying facts.
3	Only new facts can be written	Facts append forward only. No backdating, no insertion into the past.

Entity (3 Principles)

#	Principle	Description
1	An entity is defined by its facts and its config	Entity has no independent state. Type, structure, meaning - all derived from facts interpreted through config.
2	An entity has one home	One Durable Object per entity. Single source of truth. No split brain.
3	An entity has one owner	One tenant owns each entity. Tenant isolation is absolute.

Config (4 Principles)

#	Principle	Description
1	Configs are typed and versioned by type	Configs have types (schema, rules, goals, etc.). Each type versions independently.
2	Config changes are facts	Every config change is recorded as a fact. Full audit trail of what changed, when, and why.
3	Configs flow down and cannot be overridden	Platform → Tenant → Entity. Lower levels inherit from above and cannot override what is set above.
4	Config snapshots capture composite state	A snapshot records all config type versions at a point in time, enabling reconstruction.

---

Principle Hierarchy

These are platform-level principles. They are immutable and enforced by the SDK.

Platform Principles (this document)
    |
    v
Tenant Config (can add constraints, cannot remove)
    |
    v
Product Config (can add constraints, cannot remove)

Lower levels may add constraints but cannot remove or weaken platform principles.

---

Applying Principles

When designing or reviewing anything in z0, ask:

Fact Principles

1. Does this modify historical facts? → Violates Fact #1
2. Can any point in history be reconstructed? → Required by Fact #2
3. Does this insert facts into the past? → Violates Fact #3

Entity Principles

4. Does entity have state independent of facts + config? → Violates Entity #1
5. Is there exactly one DO per entity? → Required by Entity #2
6. Does this respect tenant isolation? → Required by Entity #3

Config Principles

7. Are config types versioned independently? → Required by Config #1
8. Are config changes recorded as facts? → Required by Config #2
9. Does this allow lower levels to override higher? → Violates Config #3
10. Can we reconstruct full config state at any time? → Required by Config #4

If any answer is wrong, redesign until all answers are right.

---

Simulation: The Power of Facts + Config

The same facts can be replayed through different config versions:

Facts (locked) + Config v1 → Outcome A (what happened)
Facts (locked) + Config v2 → Outcome B (what would have happened)
Facts (locked) + Config v3 → Outcome C (what if?)

This enables answering questions like:

• “If we had used this pricing model, what would revenue have been?”
• “If we rewarded conversion instead of volume, who would be top performers?”
• “If we changed the attribution window, how would spend shift?”

The past doesn’t change. The lens does.

---

Derived Principles

The following are important operational truths that derive from the 10 platform principles. They are not additional principles—they are consequences.

Derived State Is Disposable

Derives from: Fact #2 (time-travel possible), Entity #1 (defined by facts + config)

Anything not in the ledger (Entity, Fact, Config) can be rebuilt from the ledger. Cached state is optimization, not truth.

Errors Are Facts

Derives from: Fact #1 (immutable), Fact #3 (only new)

If it happened, it’s a fact. Failures, retries, timeouts are facts. Error handling is not exceptional—it’s expected.

Idempotency Is Required

Derives from: Fact #1 (immutable)

Facts are immutable. Network failures cause retries. Without idempotency, retries create duplicate facts, corrupting the ledger.

Three Primitives Only

Derives from: All principles

Entity, Fact, Config. Everything else is a typed instance, derived calculation, or cached state. If something doesn’t map to a primitive, it’s either:

1. A typed instance of a primitive
2. A derived calculation
3. Cached state
4. A product concern (not infrastructure)

---

What Moved to Tenant/Product Level

The following concepts from the previous principles document are valid but are tenant or product level concerns, not platform principles:

Concept	Level	Why
Economics Must Close the Loop	Tenant	Not all tenants need economic tracking
Budget Is Eligibility	Product	RTB-specific semantics
Settlement Is Temporal	Product	Business logic, not platform constraint
Assets Are Owned	Product	Ownership model is product choice
Attribution Is Calculation	Product	Attribution models vary by product
Treat AI as Just Another Tool	Guidance	Good advice, not a constraint

These can be configured as tenant or product level rules using the Config primitive.