Skip to content
Gestalt

API: Capabilities

Capability state: fixture-rehearsed → staging-durable. capability.publish and capability.policy.evaluate are routed membrane operations with M7-backed durable evidence. They publish and evaluate fixture capability manifests today; real Verlag trust roots, reviewer signature chains, import resolution, and production capability publication remain gaps (see 022 gap report item 8).

These operations are how a Koerper or a publisher Vessel exposes a capability manifest into the membrane and asks the cloud Geist to evaluate it as a runtime constraint. They are the first concrete membrane endpoints for the capability publication discipline described in Meditation 009 and concepts: atoms and capabilities.

capability.publish

Section titled “capability.publish”

Publish a fixture capability manifest into membrane-visible durable evidence.

POST /v1/capabilities/publish
runtime_owner: cloud_geist
sdk_role: publish a fixture capability manifest into membrane-visible durable evidence
request_record: CloudCapabilityPublishRequest
responses: capability_manifest | durable_state | refusal | receipt

Request

Section titled “Request”
interface CapabilityPublishRequest {
  tenant?: GestaltRef;
  // capability manifest fields (publisher, schema, predicate,
  // effect grammar, required evidence, imports, attestations, ...)
  // For exact shape today, see CloudCapabilityPublishRequest in
  // crates/gestalt-cloud/src/lib.rs
}

Response

Section titled “Response”
{
  "operation": "capability.publish",
  "outcome": "admitted",
  "body": {
    "capability": "capability:published_fixture_capability_v1",
    "capabilityManifest": "capability_manifest:fixture_sdk_published",
    "durableState": { "evidenceRef": "...", "publicationStatus": "fixture_durable" }
  },
  "receipt": {
    "ref": "receipt:fixture_capability_publish",
    "outcome": "admitted",
    "reasons": ["capability publication fixture returned"],
    "fixture": true
  }
}

The published capability becomes citable by future atoms in the same tenant. Today the publication is fixture — it does not create real Verlag-grade trust, professional reviewer signatures, or production admission.

SDK example

Section titled “SDK example”
const published = await client.capabilityPublish({
  tenant: "tenant_node:rheinwerk_calibration",
  // ... capability manifest fields
});

What “fixture-durable” means here

Section titled “What “fixture-durable” means here”
  • The capability manifest is persisted into M7 evidence storage (recent commit 9d3570e).
  • It survives cloud restarts.
  • It is policy-evaluable inside the fixture runtime.
  • It is not signed by a real publisher PKI.
  • It does not carry attached professional attestations.
  • It does not participate in real authority package activation.

For the production gap, see ../concepts/authority-packages.md and 022 item 8.

capability.policy.evaluate

Section titled “capability.policy.evaluate”

Evaluate capability manifest policy clauses as runtime constraints and receive a durable policy receipt.

POST /v1/capabilities/policy/evaluate
runtime_owner: cloud_geist
sdk_role: evaluate capability manifest policy clauses as runtime constraints and receive a durable policy receipt
request_record: CloudCapabilityPolicyEvaluateRequest
responses: capability_manifest | policy_evaluation | refusal | receipt

Request

Section titled “Request”
interface CapabilityPolicyEvaluateRequest {
  tenant?: GestaltRef;
  capability?: GestaltRef;
  capabilityManifest?: GestaltRef;
  // evaluation context (subject, evidence refs, candidate atom shape, ...)
}

Response

Section titled “Response”
{
  "operation": "capability.policy.evaluate",
  "outcome": "verified",
  "body": {
    "capabilityManifest": "capability_manifest:fixture_sdk",
    "policyEvaluation": "policy_evaluation:fixture_sdk",
    "decision": { "holds": true | false, "requiresIntervention": [...] }
  },
  "receipt": {
    "ref": "receipt:fixture_capability_policy_evaluation",
    "outcome": "verified",
    "reasons": ["capability policy fixture evaluation returned"],
    "fixture": true
  }
}

SDK example

Section titled “SDK example”
const evaluation = await client.capabilityPolicyEvaluate({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:published_fixture_capability_v1",
  // ... evaluation context
});

Policy evaluation outcomes

Section titled “Policy evaluation outcomes”

The capability’s predicate may return more than true / false. See ../concepts/atoms-and-capabilities.md:

holds
refuses
requires_discretion
admits_under_reservation
requires_evidence
requires_intervention
position_only
evidence_only

The policy evaluation result reports which the manifest’s policy clauses produced for the supplied context.

Refusal codes

Section titled “Refusal codes”
capability_manifest_malformed
capability_manifest_imports_unresolved
capability_manifest_imports_cyclic
capability_publisher_unsigned        (production-only)
capability_attestation_missing       (production-only)
capability_self_publication_refused  (publisher cannot self-attest)
capability_policy_evaluation_failed

What you can build today against these endpoints

Section titled “What you can build today against these endpoints”
  • Publish toy capability manifests for development and demonstration.
  • Evaluate a capability’s policy against a hypothetical context to drive Koerper UI (“would this admit?”).
  • Inspect the durable state of published manifests.

What you cannot build yet

Section titled “What you cannot build yet”
  • Production-grade Verlag publication.
  • Cross-tenant capability sharing through a real registry.
  • Reviewer signature workflows.
  • Liability terms binding the publisher.
  • Capability supersession with real version chains.
Section titled “Where to read next”