Skip to content
Gestalt

API: Shop (hosted operator delegate)

Capability state: fixture-rehearsed. shop.prepare and shop.commit walk through the hosted operator delegate fixture in crates/gestalt-cloud. The hosted operator (tenant_node:gestalt_hosted_operator) is a fixture standing.

The shop operations exist for shop-origin serious actions — when the acting party is a remote customer (a buyer in a webshop, a marketplace user) and the company Geist needs an act admitted on their behalf through a Gestalt-hosted operator delegate.

When to use shop endpoints vs intent endpoints

Section titled “When to use shop endpoints vs intent endpoints”

Use intent.* when:

  • The actor is a known human or agent of the tenant (Geschaeftsfuehrer, Prokurist, internal workcell).
  • The actor’s vessel signs the intent.

Use shop.* when:

  • The actor is an external party (a webshop customer, a marketplace buyer).
  • The actor has no Gestalt vessel of their own.
  • The tenant has delegated narrow scoped authority to a hosted operator to sign on its behalf for shop-origin acts.

shop.prepare

Section titled “shop.prepare”

Prepare a shop-origin serious action through the shared authority resolver.

POST /v1/shop/prepare
runtime_owner: cloud_geist
sdk_role: prepare shop-origin serious action through shared authority resolver
request_record: CloudIntentPrecheckRequest
responses: prepare_token | refusal | pending_action | receipt

Request

Section titled “Request”
// Same shape as IntentPrecheckRequest
interface IntentPrecheckRequest {
  tenant: GestaltRef;
  capability: GestaltRef;
  action: string;
  evidence: GestaltRef[];
  fixture?: boolean;
}

Response

Section titled “Response”

Admitted (prepare token issued):

{
  "operation": "shop.prepare",
  "outcome": "admitted",
  "body": { "prepareToken": "fixture-prepare-token" },
  "receipt": {
    "ref": "receipt:fixture_shop_prepare",
    "outcome": "admitted",
    "reasons": ["shop prepare fixture admitted"],
    "fixture": true
  }
}

The prepareToken is a single-use token that the Koerper passes to shop.commit to complete the act through the hosted operator.

SDK example

Section titled “SDK example”
const prepared = await client.prepareShop({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: ["evidence_bundle:invoice_payload"],
});


// prepared.body.prepareToken

shop.commit

Section titled “shop.commit”

Commit a shop-origin serious action through the runtime signer with the issued prepare token.

POST /v1/shop/commit
runtime_owner: cloud_geist
sdk_role: commit shop-origin serious action through runtime signer with issued prepare token
request_record: CloudIntentCommitRequest
responses: atom | signer_provenance | durable_commit | refusal | receipt

Request

Section titled “Request”

The commit request must include the prepare token from shop.prepare.

Response

Section titled “Response”
{
  "operation": "shop.commit",
  "outcome": "admitted",
  "body": {
    "signer": { "kind": "hosted_operator_delegate" },
    "durableCommit": { "status": "fixture" }
  },
  "receipt": {
    "ref": "receipt:fixture_shop_commit",
    "outcome": "admitted",
    "reasons": ["shop commit fixture admitted"],
    "fixture": true
  }
}

signer.kind confirms the act was signed through the hosted operator delegate, not through a direct tenant signer.

durableCommit.status is "fixture" today; it will be "durable" when production admission lands.

SDK example

Section titled “SDK example”
const committed = await client.commitShop({
  tenant: "tenant_node:rheinwerk_calibration",
  capability: "capability:issue_invoice_fixture_v1",
  action: "issue",
  evidence: ["evidence_bundle:invoice_payload"],
  // ... include the prepare token in the request
});

The hosted operator

Section titled “The hosted operator”

The hosted operator is a Gestalt-managed delegate that holds a narrow scoped grant from the tenant. Its standing is governed by authority.hostedOperator.grant and authority.hostedOperator.revoke — see authority.md.

The hosted operator’s scopes today are fixture-defined and limited to issuing invoices and observing payments under the fixture invoice capability. Real shop-origin governance will require a richer grant model.

Refusal codes

Section titled “Refusal codes”
shop_prepare_token_expired
shop_prepare_token_used
hosted_operator_grant_missing
hosted_operator_grant_revoked
hosted_operator_scope_mismatch
required_evidence_missing
Section titled “Where to read next”