Concept: Realities

Status: fixture-rehearsed. All reality endpoints (reality.fork, reality.commit, reality.diff, reality.promote, reality.discard) are implemented as fixture flows in crates/gestalt-cloud; recent commits (31cd1e3) added durable worldline records.

What a reality is

A reality in Gestalt is a named history that atoms live in. Every atom names exactly one reality. Refusing to do so refuses admission.

The kinds of reality:

record           the company's actual past and present
projected:<id>   a bounded possible worldline (a "what-if")
shared_projected:<id>   a projection visible to a counterparty (future)

The first implementation supports record and projected:<id>. shared_projected is reserved for the mesh and not yet operational.

Why two realities

Companies routinely need to ask:

What would happen if we did X?

Examples:

“What if we add a French warehouse and start selling to French customers?”
“What if we restructure these contracts under a new template?”
“What if we promote this provisional advisor opinion to a binding one?”
“What if this disputed payment counts toward closing March?”

Conventional software answers these by either:

pretending the question is the same as the answer (modify the database, hope you can roll back), or
modeling the future entirely outside the system (a spreadsheet, an email thread, a slide deck), losing causal continuity.

Gestalt makes the future first-class. A projection is not a draft, not a sandbox, not a test mode. It is a governed worldline:

atoms admitted into a projection are real atoms,
they pass Gravity,
they emit effects,
they open closure surfaces,
they create projected obligations,
they may be cited by other projected atoms,
they produce receipts.

What they don’t do is leak into record.

Forking a projection

const fork = await client.realityFork({
  tenant: "tenant_node:rheinwerk_calibration",
  purpose: "march close what-if: count disputed payment",
});

// fork.body.projection is the new reality ref, e.g. "reality:m6_projection_repair"
// fork.body.contextTransition records the assumption set

A fork records:

the branch point (which record atom you forked from),
the assumptions (what you are pretending is true),
a purpose string (so the projection is legible later).

Committing into a projection

Use reality.commit with the projected reality ref:

const result = await client.realityCommit({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: fork.body.projection,
  evidence: ["evidence_bundle:disputed_payment_observation"],
  leak_to_record: false,
});

Important: leak_to_record: false is the default. Setting it to true is intentionally unsupported in the membrane — the only way an atom enters record from a projection is promotion, which is its own gated act.

Diff between record and projected

const diff = await client.realityDiff({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: fork.body.projection,
});

// diff.body shows: atoms only in projection, atoms only in record,
//   diverging closure surfaces, diverging tensions,
//   record_leak: false (verifies isolation)

The diff is the basic instrument for explaining a projection to an operator, an advisor, or yourself.

Promotion

Promotion is the act of moving (re-crossing) projected atoms into record under current record conditions. Promotion is not a copy. It is a fresh Gravity admission.

const promotion = await client.realityPromote({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: fork.body.projection,
  evidence: ["evidence_bundle:projection_promotion_approval"],
});

if (promotion.outcome === "admitted") {
  // each promoted atom is a fresh admission citing the projection's atoms as cause
}

Why fresh admission and not copy:

The world may have changed since the projection was created. A capability may have been superseded. A standing may have lapsed. An authority epoch may have transitioned. New evidence may now be required.
Promotion must re-evaluate Gravity against current record conditions, not against the conditions at fork time.
The promotion atom itself is a governed act citing approval evidence — it carries its own effects and its own commitment.

This is the discipline that lets a company rehearse futures without becoming silently bound by them.

Discard

const discard = await client.realityDiscard({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: fork.body.projection,
});

Discard ends a projection while preserving the explanation: who discarded it, when, why. The projection’s atoms become immutable artifacts of paths not taken — useful for explaining decisions to auditors and counterparties.

Required reality on every atom

Gravity refuses any atom that:

has no reality,
is a record atom descending from projected parents,
is a projected atom descending from a different projection,
promotes without a promotion atom,
discards by deleting the projection body,
gives a serious Zeitgestalt answer without query context.

These rules are constitutional, not configuration. They prevent the single most dangerous failure mode: silent leakage between simulation and truth.

Effects in a projection are projected effects

When an atom in a projection emits effects, those effects exist in the projection only:

A projected invoice opens a projected receivable closure surface.
A projected role grant allows projected invoices.
A projected legal strategy creates projected obligations.

You can ask Zeitgestalt questions in a projection just like in record. The answer is scoped to that projection.

Worked example: France market entry

A German GmbH wants to know what changes if it adds a French warehouse and starts selling to French customers.

Step 1 — fork:

const fork = await client.realityFork({
  tenant: "tenant_node:rheinwerk_calibration",
  purpose: "evaluate FR warehouse + FR customer market",
});

Step 2 — assert effective context transition (in projection):

This would use a future authority.context.transition operation (see 022 item 19). For now, a fixture-rehearsed flow uses authority.resolveContext:

const resolution = await client.resolveAuthorityContext({
  subjectCompany: "company_geist:rheinwerk_calibration",
  effectiveContext: "effective_context:fixture_de_gmbh",
  to: ["FR"],
  tags: ["warehouse_country:FR", "fr_b2c_customer"],
  evidenceRefs: [],
});

// resolution.body.matchedDemands lists:
//   - sovereign_demand:de_registered_office_continuity
//   - sovereign_demand:fr_tax_establishment_and_vat
//   - (more depending on signal tags)

Step 3 — admit projected atoms representing the proposed change. Issue projected invoices to French customers, observe that:

new closure surfaces open (FR VAT posture, FR establishment registration),
new effects emerge (RequireExternalAuthority, RequireAdvisorOpinion),
some atoms refuse (required_evidence_missing for FR establishment evidence).

Step 4 — diff:

const diff = await client.realityDiff({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: fork.body.projection,
});

// the diff shows the new authority topology: which spheres activate,
// which capabilities are now required, which obligations would open,
// which proof gaps exist

Step 5 — promote or discard. If the company decides to proceed, it gathers the missing evidence (FR establishment registration, Steuerberater/avocat opinions), then attempts promotion. If Gravity re-admits, the projected atoms become fresh record atoms. If anything is missing, promotion refuses with a structured explanation.

If the company decides not to proceed, it discards the projection. The discard atom records the reason. The projection’s atoms remain inspectable as evidence of the rehearsal.

What a projection is not

Not a sandbox. A sandbox suggests “this doesn’t count.” A projection is governed; its atoms count within the projection.
Not a draft folder. Drafts are Koerper objects. Projections are Geist objects.
Not a backup or fork-of-database. A projection is a worldline, not a full data copy. It shares the branch-point ancestry with record.
Not a test mode. Test fixtures live in fixture mode. Projections are first-class even in production.

Worldline coherence: what Gravity guarantees

Gravity refuses atoms that violate worldline coherence. Specifically:

- record atoms cannot cite projected atoms as cause
- projected atoms cannot cite atoms from a different projection as cause
- projected atoms cite their projection's branch-point record atoms freely
- promotion produces fresh record atoms; the projection's atoms remain in the projection
- discard does not delete; it records the discard atom and freezes the projection

These rules are why a projection is safe to run on production data: it cannot contaminate record.