Guide: projecting context transitions

Status: fixture-rehearsed. All reality endpoints walk end-to-end as fixtures. See api/reality.md and concepts/realities.md.

This guide walks the most useful application of projected reality: asking “what would happen if our company added a foreign warehouse / hired a foreign employee / changed jurisdiction?” without binding the answer.

The setup

Take the worked example from concepts/realities.md: A German GmbH wants to know what changes if it adds a French warehouse and starts selling to French customers.

const tenant = "tenant_node:rheinwerk_calibration";

Step 1 — fork a projection

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

console.log(fork.outcome);    // "projected"
console.log(fork.body.projection);    // "reality:m6_projection_repair"

The fork records:

• the branch point (which record atom you forked from),
• the assumptions (what you are pretending is true),
• the purpose string.

Step 2 — resolve authority context for the projection

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: [],
});

console.log(resolution.body.matchedDemands);
// [
//   "sovereign_demand:de_registered_office_continuity",
//   "sovereign_demand:eu_intra_union_goods_route",
//   "sovereign_demand:fr_tax_establishment_and_vat"
// ]

The matched demands tell you which authority spheres activate when you make this transition. Each demand carries:

• which jurisdiction(s),
• which capability families that demand affects,
• what evidence the company will need,
• what professional intervention may be required.

Step 3 — admit projected atoms

The next step in the conceptual flow is to admit atoms inside the projection — for example, try issuing an invoice to a French customer under the projected FR authority topology, and observe whether the membrane refuses for missing FR establishment evidence. The refusal would live in the projection, not in record.

This isn’t on the SDK yet. None of the SDK’s domain operations (client.economicInvoice, client.effectIntent, client.commitShop, etc.) accept a reality parameter that would target a forked projection — they all admit against record. The projection-targeted admission path requires lower-level APIs not yet on the SDK convenience surface. See 022 gap report.

For now you can:

• Use realityFork and realityDiff to inspect the projection’s branch point and isolation,
• Use zeitgestaltQuery with the projection ref to ask narrative questions scoped to it (Step 5 below),
• Promote or discard the projection (Steps 6a / 6b) — these do exist on the SDK.

The “rehearse a projected invoice and see it refuse” loop will become expressible from the SDK once a projection-targeting domain entry point lands.

Step 4 — diff against record

const diff = await client.realityDiff({
  tenant,
  reality: fork.body.projection,
  evidence: [],
});

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

The diff is the basic instrument for explaining the projection to an operator, an advisor, or yourself. A Koerper renders it as:

• “If we make this change, N new closure surfaces will open.”
• “M atoms that admit in record will refuse here.”
• “K new effects will fire.”
• “J advisor opinions will be required.”

Step 5 — ask Zeitgestalt about the projection

const why = await client.zeitgestaltQuery({
  tenant,
  reality: fork.body.projection,
  question: "what blocks promotion?",
  entitlement: "entitlement:fixture_zeitgestalt",
});

In the projection, this answer scopes to the projection’s atoms and the projected authority topology.

Step 6a — promote (if the company decides to proceed)

Gather the missing evidence (FR establishment registration, Steuerberater/avocat opinions). Then attempt promotion:

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

If admitted: the projected atoms become fresh record atoms citing the projection’s atoms as cause. They are re-evaluated against current record conditions, not against fork-time conditions.

If refused with reality_promotion_authority_missing: you do not have the required projection-promotion approval evidence. Gather it, then retry.

Step 6b — discard (if the company decides not to proceed)

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

The discard atom records who discarded, when, why. The projection’s atoms remain inspectable as evidence of the rehearsal — useful for explaining the decision later.

Common patterns

What-if before commit

Use reality.fork for any irreversible operational change (jurisdiction move, contract restructuring, large refund policy change). Walk the consequence cascade in the projection. Decide. Promote or discard.

Rehearsal before period close

Fork before a period close to see whether outstanding receivables would resolve under different assumptions. Reasoning in a projection is safe; the record close is unaffected.

Multiple projections side by side

Each projection is independent. You can fork from the same record atom into multiple projections to compare scenarios:

const a = await client.realityFork({ tenant, purpose: "FR option" });
const b = await client.realityFork({ tenant, purpose: "AT option" });
// admit projected atoms in each independently

reality.diff works against either.

What you cannot do

• Leak from projection to record. leak_to_record: true is refused.
• Cross projections. A projected atom cannot cite atoms from a different projection.
• Promote without evidence. Refused with reality_promotion_authority_missing.
• Discard by deleting. Refused with reality_discard_attempts_delete. Discard is its own admitted lifecycle act.

Where to read next

• Concepts: realities
• API: reality
• API: zeitgestalt and tensions
• API: authority — authority.resolveContext