Skip to content
Gestalt

API: Reality

Capability state: fixture-rehearsed → staging-durable. Per reference/capability-state.md: reality.fork and reality.diff are staging-durable; reality.commit, reality.promote, reality.discard are fixture-rehearsed.

The reality operations let you fork projected worldlines, admit atoms into them, diff them against record, promote successful projections, or discard them while preserving the explanation. See concepts: realities.

reality.fork

Section titled “reality.fork”

Fork a governed projected reality from record.

POST /v1/reality/fork
state: staging-durable
sdk_role: fork governed projected reality
request_record: CloudRealityForkRequest
responses: projection | context_transition | receipt

Request

Section titled “Request”
interface RealityForkRequest {
  tenant?: GestaltRef;
  purpose?: string;
}

Response

Section titled “Response”
{
  "operation": "reality.fork",
  "outcome": "projected",
  "body": {
    "projection": "reality:m6_projection_repair",
    "contextTransition": "context_transition:..."
  },
  "receipt": {...}
}

SDK example

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

reality.commit

Section titled “reality.commit”

Admit an atom under a projected reality without record leakage.

POST /v1/reality/commit
state: fixture-rehearsed
sdk_role: admit atom under projected reality without record leakage
request_record: CloudRealityCommitRequest
responses: atom | refusal | receipt

Request

Section titled “Request”
interface RealityCommitRequest {
  tenant?: GestaltRef;
  reality?: GestaltRef;       // the projected reality ref
  evidence?: GestaltRef[];
  leak_to_record?: boolean;   // default false; true is intentionally unsupported
}

The leak_to_record: true option is preserved in the contract for explicit refusal — Gestalt deliberately refuses any caller asking for projection-to-record leakage. The only legitimate path is reality.promote.

reality.diff

Section titled “reality.diff”

Compare record and projected realities.

POST /v1/reality/diff
state: staging-durable
sdk_role: compare record and projected realities
const diff = await client.realityDiff({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:m6_projection_repair",
  evidence: [],
});

The response carries record_leak: false to confirm isolation.

reality.promote

Section titled “reality.promote”

Request projection promotion with authority evidence.

POST /v1/reality/promote
state: fixture-rehearsed
sdk_role: request projection promotion with authority evidence
const promotion = await client.realityPromote({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:m6_projection_repair",
  evidence: ["evidence_bundle:projection_promotion_approval"],
});

Refused with reality_promotion_authority_missing if the required projection-promotion approval evidence is not cited.

Promotion is a fresh Gravity admission, not a copy. Atoms are re-evaluated against current record conditions and admitted as new record atoms citing the projection’s atoms as cause.

reality.discard

Section titled “reality.discard”

Discard an active projection while preserving the explanation.

POST /v1/reality/discard
state: fixture-rehearsed
sdk_role: discard active projection while preserving explanation
const discard = await client.realityDiscard({
  tenant: "tenant_node:rheinwerk_calibration",
  reality: "reality:m6_projection_repair",
});

What worldline coherence guarantees

Section titled “What worldline coherence guarantees”

Gravity refuses any atom that:

  • has no reality named,
  • is a record atom citing projected parents as cause,
  • is a projected atom citing atoms from a different projection,
  • promotes without an explicit promotion atom,
  • discards by deleting the projection body.

These rules are constitutional, not configuration. They prevent silent leakage between simulation and truth.

Refusal codes

Section titled “Refusal codes”
reality_unspecified
reality_record_cites_projected
reality_projected_cites_other_projection
reality_promotion_authority_missing
reality_promotion_atom_missing
reality_discard_attempts_delete
required_evidence_missing

See reference/refusal-codes.md.

Section titled “Where to read next”