Skip to content
Gestalt

API: Evidence (witnesses and connectors)

Capability state: evidence.witness.fixture and evidence.connector.ingest are fixture-rehearsed; evidence.connector.status is staging-durable. No real connector ingestion of external systems exists today (see 022 gap report item 11).

The evidence operations admit redacted, content-hashed witness records into the Geist. They are how external systems (banks, shops, DATEV, Stripe, etc.) contribute to company truth without ever exposing raw payloads through the membrane.

evidence.witness.fixture

Section titled “evidence.witness.fixture”

Emit normalized connector witness fixture records.

POST /v1/evidence/witness-fixture
state: fixture-rehearsed
sdk_role: emit normalized connector witness fixture records
request_record: CloudEvidenceWitnessFixtureRequest
responses: connector_witnesses | evidence | receipt

Request

Section titled “Request”

A request to emit a curated batch of fixture witness records (used during scenario rehearsal).

Response

Section titled “Response”
{
  "operation": "evidence.witness.fixture",
  "outcome": "admitted",
  "body": {
    "connectorWitnesses": [...],
    "evidence": [...]
  },
  "receipt": {...}
}

evidence.connector.ingest

Section titled “evidence.connector.ingest”

Submit controlled fixture connector evidence as redacted witness material.

POST /v1/evidence/connectors/ingest
state: fixture-rehearsed
sdk_role: submit controlled fixture connector evidence as redacted witness material
request_record: CloudConnectorEvidenceIngestRequest
responses: connector_witness | observed_input | transform_receipt | evidence_bundle | refusal | receipt

Request

Section titled “Request”
interface ConnectorEvidenceIngestRequest {
  tenant?: GestaltRef;
  subject?: GestaltRef;
  kind:
    | "invoice"
    | "payment"
    | "bookkeeping"
    | "advisor"
    | "registry"
    | "human_presence"
    | "identity_fallback"
    | "closure_clearance";
  idempotency_key?: string;
  source_system?: string;
  source_label?: string;
  source_hash?: string;
  transform_hash?: string;
  raw_kind?: string;
  claims?: string[];
  amount_cents?: number;
  currency?: string;
  invoice?: GestaltRef;
  human_presence_receipt?: GestaltRef;
  face_match_receipt?: GestaltRef;
  advisor_decision?: "reserve" | "clear";
  stale?: boolean;
  outside_tenant?: boolean;
  fixture?: boolean;     // MUST be true today
}

fixture: true is required today. The membrane refuses with connector_fixture_only for any non-fixture ingest.

Response

Section titled “Response”
{
  "operation": "evidence.connector.ingest",
  "outcome": "admitted",
  "body": {
    "connectorWitness": "connector_witness:fixture_sdk",
    "observedInput": "observed_input:fixture_sdk",
    "transformReceipt": "transform_receipt:fixture_sdk",
    "evidenceBundle": "evidence_bundle:fixture_sdk",
    "rawConnectorPayloadExposed": false,
    "evidenceCreatesAuthority": false,
    "productionAdmission": false
  },
  "receipt": {...}
}

The pipeline a connector witness flows through:

observed_input    the redacted witnessed material
transform_hash    a deterministic shaping into evidence shape
evidence_bundle   the signed, content-addressed bundle ready for atom citation

evidenceCreatesAuthority: false is asserted explicitly: evidence backs claims, it does not create authority. Authority comes from Pendulums and packages.

SDK example

Section titled “SDK example”
const ingested = await client.connectorEvidenceIngest({
  tenant: "tenant_node:rheinwerk_calibration",
  subject: "company_geist:rheinwerk_calibration",
  kind: "invoice",
  idempotency_key: "ingest-001",
  source_system: "fixture_connector",
  source_label: "fixture",
  source_hash: "sha256:fixture_invoice",
  transform_hash: "sha256:fixture_transform",
  raw_kind: "fixture_json",
  claims: ["invoice_payload"],
  amount_cents: 11900,
  currency: "EUR",
  fixture: true,
});

Refusal codes

Section titled “Refusal codes”
connector_fixture_only        request.fixture must be true today
evidence_stale                stale: true was provided
connector_tenant_scope_mismatch  outside_tenant: true was provided
connector_idempotency_collision
connector_evidence_kind_unknown
human_presence_creates_standing_refused
identity_fallback_creates_standing_refused

The membrane explicitly refuses any attempt to use connector evidence to create standing — evidence backs claims about facts, not about authority.

evidence.connector.status

Section titled “evidence.connector.status”

Inspect redacted connector evidence summaries without raw payload access.

GET /v1/evidence/connectors/status
state: staging-durable
sdk_role: inspect redacted connector evidence summaries without raw payload access
responses: connector_witnesses | observed_inputs | transform_receipts | evidence_bundles | receipt

Response

Section titled “Response”
{
  "operation": "evidence.connector.status",
  "outcome": "verified",
  "body": {
    "rawConnectorPayloadExposed": false,
    "rawDbExposed": false,
    "productionAdmission": false,
    "connectorWitnesses": [...],
    "observedInputs": [...],
    "transformReceipts": [...],
    "evidenceBundles": [...]
  },
  "receipt": {...}
}

Counts and refs only. Raw payload bytes are never returned.

SDK example

Section titled “SDK example”
const status = await client.connectorEvidenceStatus();

What evidence does and does not do

Section titled “What evidence does and does not do”

Does:

  • backs claims in atoms,
  • carries content hashes and source provenance,
  • supports idempotent ingestion,
  • preserves audit trail without exposing raw payload through the membrane.

Does not:

  • create authority,
  • create standing,
  • modify atoms after admission,
  • expose raw payloads.

This separation is part of why the connector pipeline is safe to extend without giving connectors policy-making power.

Section titled “Where to read next”