Skip to content
Gestalt

API: Lens and intervention

Capability state: every operation in this file is staging-durable (Koerper-ingress fixture). Lens scope, redacted disclosure, intervention request, and intervention issue are recorded in durable M7 state but refuse production admission and reject raw connector payloads or biometric material at the membrane. See 022 gap report for the broader Koerper-ingress surface.

The lens-and-intervention cluster covers the scoped disclosure and professional-intervention surface — the operations that let an advisor (or another scoped reader) see explicitly named fields, and let them request or issue a professional intervention without ever holding admin authority.

Two coupled lanes:

  • Lens lane — lens.scope defines a named set of allowed_fields over a subject for a stated purpose; lens.disclose returns redacted disclosures over an existing scope and refuses raw connector payloads or biometric material.
  • Intervention lane — intervention.request records a professional intervention request against an open advisor matter; intervention.issue records the intervention disposition as scoped evidence (citing other evidence refs only — raw payloads are refused).

A lens scope or intervention never creates standing or admin authority on its own. intervention.issue asserts advisor_becomes_admin: false explicitly.

See also:

lens.scope

Section titled “lens.scope”

Define a scoped lens over allowed fields for Koerper/advisor access.

POST /v1/lens/scope
state: staging-durable
sdk_role: define a scoped lens over allowed fields for Koerper/advisor access
request_record: CloudLensScopeRequest
responses: lens_scope | refusal | receipt

Request

Section titled “Request”
interface LensScopeRequest {
  tenant: GestaltRef;
  lens: GestaltRef;
  subject: GestaltRef;
  matter?: GestaltRef;
  allowed_fields: string[];     // must be non-empty
  purpose: string;
  unscoped: boolean;            // refused if true
  fixture: boolean;             // must be true
}

Response

Section titled “Response”
{
  "operation": "lens.scope",
  "outcome": "admitted",
  "body": {
    "lens_scope": "lens_scope:...",
    "status": "active",
    "raw_db_exposed": false,
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

The handler refuses with lens_unscoped_disclosure_refused when unscoped is true or allowed_fields is empty: a lens scope must always name explicit fields and a stated purpose.

SDK example

Section titled “SDK example”
const scope = await client.lensScope({
  tenant: "tenant_node:rheinwerk_calibration",
  lens: "lens:m21_advisor_fixture",
  subject: "company_geist:rheinwerk_calibration",
  matter: "advisor_matter:m21_fixture",
  allowed_fields: [
    "invoice.summary",
    "payment.status",
    "proof.receipts",
  ],
  purpose: "advisor_review",
  unscoped: false,
  fixture: true,
});

lens.disclose

Section titled “lens.disclose”

Disclose redacted lens fields without raw DB connector or biometric material.

POST /v1/lens/disclose
state: staging-durable
sdk_role: disclose redacted lens fields without raw DB connector or biometric material
request_record: CloudLensDiscloseRequest
responses: lens_disclosure | refusal | receipt

Request

Section titled “Request”
interface LensDiscloseRequest {
  tenant: GestaltRef;
  lens_scope: GestaltRef;
  fields: string[];
  include_raw_connector_payload: boolean;  // refused if true
  include_biometric_material: boolean;     // refused if true
  fixture: boolean;                         // must be true
}

Response

Section titled “Response”
{
  "operation": "lens.disclose",
  "outcome": "admitted",
  "body": {
    "lens_disclosure": "lens_disclosure:...",
    "status": "disclosed",
    "redaction": {
      "raw_connector_payload_exposed": false,
      "biometric_material_exposed": false,
      "raw_db_exposed": false
    },
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

The handler refuses with lens_disclosure_raw_material_refused if either include_raw_connector_payload or include_biometric_material is true.

SDK example

Section titled “SDK example”
const disclosure = await client.lensDisclose({
  tenant: "tenant_node:rheinwerk_calibration",
  lens_scope: "lens_scope:m21_fixture",
  fields: ["invoice.summary", "proof.receipts"],
  include_raw_connector_payload: false,
  include_biometric_material: false,
  fixture: true,
});

intervention.request

Section titled “intervention.request”

Request scoped professional intervention without admin authority.

POST /v1/interventions/request
state: staging-durable
sdk_role: request scoped professional intervention without admin authority
request_record: CloudInterventionRequestRequest
responses: intervention_request | refusal | receipt

Request

Section titled “Request”
interface InterventionRequestRequest {
  tenant: GestaltRef;
  matter: GestaltRef;
  requested_by: GestaltRef;
  reason: string;
  evidence: GestaltRef[];
  fixture: boolean;              // must be true
}

Response

Section titled “Response”
{
  "operation": "intervention.request",
  "outcome": "admitted",
  "body": {
    "intervention_request": "intervention_request:...",
    "status": "requested",
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

SDK example

Section titled “SDK example”
const request = await client.interventionRequest({
  tenant: "tenant_node:rheinwerk_calibration",
  matter: "advisor_matter:m21_fixture",
  requested_by: "human_person:anna",
  reason: "fixture intervention requested before period close",
  evidence: ["evidence_bundle:fixture_invoice"],
  fixture: true,
});

intervention.issue

Section titled “intervention.issue”

Issue scoped professional intervention evidence without raw payload disclosure.

POST /v1/interventions/issue
state: staging-durable
sdk_role: issue scoped professional intervention evidence without raw payload disclosure
request_record: CloudInterventionIssueRequest
responses: intervention_issue | refusal | receipt

Request

Section titled “Request”
interface InterventionIssueRequest {
  tenant: GestaltRef;
  intervention_request: GestaltRef;
  issued_by: GestaltRef;
  disposition: string;
  evidence: GestaltRef[];
  raw_payload?: unknown;         // refused if present
  fixture: boolean;              // must be true
}

Response

Section titled “Response”
{
  "operation": "intervention.issue",
  "outcome": "admitted",
  "body": {
    "intervention_issue": "intervention_issue:...",
    "status": "issued",
    "raw_connector_payload_exposed": false,
    "advisor_becomes_admin": false,
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

advisor_becomes_admin: false and raw_connector_payload_exposed: false are explicit boundary assertions. The handler refuses with intervention_raw_payload_refused if raw_payload is supplied.

SDK example

Section titled “SDK example”
const issue = await client.interventionIssue({
  tenant: "tenant_node:rheinwerk_calibration",
  intervention_request: "intervention_request:m21_fixture",
  issued_by: "human_person:steuerberater_fixture",
  disposition: "reserve_until_payment_clears",
  evidence: ["evidence_bundle:fixture_advisor"],
  fixture: true,
});

Refusal codes

Section titled “Refusal codes”

Selected refusal codes returned by this cluster (see refusal.codes for the full list):

koerper_fixture_only
lens_unscoped_disclosure_refused
lens_disclosure_raw_material_refused
intervention_raw_payload_refused
Section titled “Where to read next”