Skip to content
Gestalt

Concept: Atoms and capabilities

Status: fixture-rehearsed. Atoms are admitted into in-process world snapshots and into the durable cloud commit journal. The membrane exposes capability.publish and capability.policy.evaluate as staging-durable fixture surfaces today; production-grade capability publication (real Verlag-signed instruments, real reviewer standing) remains closed. Built-in fixture capabilities still live as constants in crates/gestalt-cloud/src/lib.rs.

The atom

Section titled “The atom”

The atom is the smallest durable unit of business reality in Gestalt. Every serious transition — issuing an invoice, granting a mandate, observing a payment, recording an advisor opinion, opening a matter, admitting a tension — is an atom.

An atom carries eight dimensions:

Subject       who acts or speaks
Cause         which prior facts does this depend on
Authority     who or what makes the act admissible
Content       what material claim is being made
Evidence      what supports the claim
Governance    which rules, policies, laws, contracts, or packages evaluated it
Effects       what future operations are created, required, blocked, warned, or escalated
Commitment    what proof seals the transition

The crucial dimension over a typical event-sourced system is Effects. Some atoms do not only record the past. They change the admissibility landscape for future atoms. A new tax-audit-open situation atom may require future invoice atoms to cite explicit evidence. A standing revocation atom may refuse future role-grant atoms by the revoked actor.

Atoms cite capabilities

Section titled “Atoms cite capabilities”

Every atom cites a capability by content address.

The atom does not say “I am an invoice.” It says:

I am an act proposed under this capability, this predicate, this schema, this version, this publisher, this authority context, and this mandate chain.

The capability tells Gravity (and any downstream auditor) what the act means: which schema the content must conform to, which predicates apply, which evidence is required, which effects are emitted, which discretion points exist, which authority sources back the meaning.

Without capability citation, atoms would be expensive JSON. With it, atoms become legible across decades, across replaced Koerpers, and across changes in operational doctrine.

Capabilities are themselves atoms

Section titled “Capabilities are themselves atoms”

A capability is not a Rust enum, a build-time registry entry, a string pair like invoice.issue.v1, or a document hidden in a bundle file.

A capability is an admitted publication in a worldline. It is an atom.

It carries:

publisher              who published it (a Verlag, a company, a chamber)
subject                what kind of act it defines
capability identity    a stable name (and a content commitment that is canonical)
input schema           the shape of admissible content
predicate              the structural conditions that must hold
effect grammar         what effects this kind of act can emit
required evidence      what evidence kinds atoms must cite
allowed discretion     where professional or operational judgment lives
authority sources      which Pendulum publications back this capability
import set             which other capabilities this one depends on
version relation       what prior version this supersedes / refines
validity window        when this capability is operative
reliance terms         what relying parties may depend on
attestations           scoped statements by professional bodies
commitment             the canonical content hash

Other atoms cite capabilities by their canonical content commitment. Human-readable names like gestalt.invoice.issue.de.v1 are useful for operators but are not the canonical identity. The hash is.

This matters because legal-operational definitions change. An old invoice capability may remain valid for atoms already admitted under it. A new one may tighten evidence requirements. A Steuerberater-reviewed version may replace an internal draft. A Verlag may publish a better template. A court may force a stricter interpretation. Old atoms do not become invalid because the capability changed; they cite what governed them when they crossed.

The fixed point

Section titled “The fixed point”

If capabilities are atoms, a recursion appears: which capability admits the first capability atom?

Gestalt resolves this with one fixed point hardcoded into Gravity:

gestalt.capability.publish.v1

Its identity is a stable bootstrap constant. Gravity does not know every domain; it knows how to recognize a well-formed capability publication:

  • the schema is canonical,
  • the predicate language is bounded,
  • imports resolve and are acyclic,
  • fuel and resource budgets exist,
  • referenced authority sources are named,
  • publisher standing is present,
  • attestations are shaped,
  • the capability commitment is reproducible.

After that, every domain capability is ordinary content-addressed publication.

The kernel knows one privileged capability because the constitution must be small. A kernel with many privileged domain capabilities would already be a law product disguised as substrate. A kernel with none would be unable to start.

Capability imports

Section titled “Capability imports”

Capabilities call other capabilities. An invoice capability may import:

  • standing validation,
  • invoice numbering,
  • VAT posture,
  • evidence custody,
  • XRechnung document hash,
  • receivable closure-surface creation.

Imports are content-addressed. At publication time, the capability records direct imports, transitive import closure, resource budget, and conflict policy for import versions. At admission time, Gravity verifies the declared import closure against the capability’s commitment — it does not chase an unbounded dynamic graph.

This keeps admission deterministic and the capability’s dependency world inspectable. When an auditor asks why an invoice was admitted, the answer is not “because code version 712 said so.” It is:

Because this invoice capability imported these standing, tax, numbering, evidence, and document capabilities, each at these content-addressed versions, under this authority epoch.

Predicates: more than true / false

Section titled “Predicates: more than true / false”

Predicates do not only return true or false. Real company life needs richer outcomes:

holds                        the structural condition is satisfied
refuses                      the condition fails
requires_discretion          a professional or operational judgment must be issued
admits_under_reservation     can be admitted but a reservation is recorded
requires_evidence            specific evidence must be cited
requires_intervention        a signed professional act must be issued
position_only                can be recorded as a position (claim) but not bound
evidence_only                only an evidence atom may be admitted

This does not make Gravity fuzzy. It means a capability can declare that a branch cannot be computed and must be carried as a position or as a required intervention.

What an atom looks like (fixture shape)

Section titled “What an atom looks like (fixture shape)”
{
  "ref": "atom:01H...",
  "subject": "company_geist:rheinwerk_calibration",
  "actor": "human_person:anna",
  "vessel": "vessel:fixture_sdk",
  "reality": "reality:record",
  "capability": "capability:issue_invoice_fixture_v1",
  "authority_epoch": "authority_epoch:fixture_2026_04",
  "effective_context": "effective_context:fixture_de_gmbh",
  "standing": "standing_grant:anna_gf_fixture",
  "cause": ["atom:..."],
  "content": { "amount_cents": 11900, "currency": "EUR", ... },
  "evidence": ["evidence_bundle:invoice_payload"],
  "effects": [
    {"mode": "OpenClosureSurface", "kind": "receivable"},
    {"mode": "RequireCounterpartyAck"}
  ],
  "commitment": "sha256:..."
}

In real production this commitment will be a signature over canonical bytes by the runtime signer (see 022 item 17). Today it is a fixture commitment.

What an atom looks like in your code

Section titled “What an atom looks like in your code”

You don’t construct atoms directly. You construct intent envelopes and the Geist mints atoms when Gravity admits them.

const response = await client.precheckIntent({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: ["evidence_bundle:invoice_payload"],
});


if (response.outcome === "admitted") {
  // response.body.atomRef is your handle to the new atom
}

For the matching intent.commit operation see api/intents-and-commits.md.

Capability failure is product

Section titled “Capability failure is product”

A refusal to admit an atom is not a generic error. It is a governed finding. The structured refusal carries:

failed_gate                    which gate refused
capability_ref                 which capability was being cited
source_atoms                   what was being cited as cause
locus                          where in the envelope it failed
reason                         human-readable code
remedy_hint                    what could fix it
required_evidence              what evidence would unblock
required_intervention          what professional act would unblock
possible_projection_path       could this work in a projection
whether_failure_is_recordable  does the company need to remember this

Some failures should themselves be recorded:

  • An employee tried to bind a contract without standing.
  • An agent attempted a risky production-continuity message.
  • A projected close failed; the failure explains why the projection cannot promote.

The refusal surface is therefore not just developer experience. It is part of Gestalt’s memory of paths not taken.

See reference/refusal-codes.md.

Worked example: the German invoice capability (fixture)

Section titled “Worked example: the German invoice capability (fixture)”

The fixture capability capability:issue_invoice_fixture_v1 declares (today the membrane exposes capability.publish and capability.policy.evaluate as staging-durable fixture surfaces; production-grade capability publication remains closed):

  • subject — company_geist:*
  • input schema — { amount_cents, currency, line_items, customer, ... }
  • predicate — actor has invoice-issue standing, customer is named, amounts are positive, currency is EUR
  • effect grammar — emits OpenClosureSurface(receivable), RequireCounterpartyAck, optionally RequireAdvisorOpinion
  • required evidence — evidence_bundle:invoice_payload (the XRechnung-shaped payload bytes)
  • imports — fixture standing capability, fixture VAT posture capability, fixture receivable-surface capability
  • authority sources — fixture German invoice / VAT / GoBD Pendulum source materials

Issuing an invoice atom against this capability passes Gravity if all the above are satisfied. Refusing it produces a structured refusal naming exactly which gate failed.

The real (non-fixture) German invoice capability does not exist yet. The Verlag package pipeline is exposed as staging-durable fixture operations — authority.package.publisher.onboard, authority.package.reviewer.onboard, authority.package.import, authority.package.review, authority.package.activate, and authority.package.revoke — but production package activation remains closed and fixture activations cannot flip production admission.

What you should remember

Section titled “What you should remember”
  1. Atoms are the unit. Everything else (closures, tensions, projections) sits around atoms.
  2. Atoms cite capabilities. Capabilities are themselves atoms.
  3. The kernel knows exactly one privileged capability: gestalt.capability.publish.v1. Everything else is content-addressed publication.
  4. Capability imports are declared and verified at admission. No dynamic mystery.
  5. Predicates have more outcomes than true/false. Discretion, reservation, and required intervention are first-class.
  6. Refusals are findings, not errors.
Section titled “Where to read next”