Skip to content
Gestalt

API: Advisor

Capability state: every operation in this file is staging-durable (Koerper-ingress fixture). Advisor matters, opinions, and evidence requests are recorded in durable M7 state but refuse production admission and reject raw connector payloads at the membrane. See 022 gap report for the broader Koerper-ingress surface.

The advisor cluster covers the scoped advisor membrane — the operations a Steuerberater, Anwalt, or other professional advisor uses to open a matter, issue an opinion, or request additional evidence without ever holding admin authority over the company graph.

Three coupled lanes:

  • Matter lane — advisor.openMatter opens a scoped advisor matter naming a company, an advisor, a matter kind, an explicit scope, and the citing evidence; it does not grant admin access.
  • Opinion lane — advisor.issueOpinion records an advisor decision on an open matter as scoped evidence (citing other evidence refs only — raw connector payloads are refused).
  • Evidence-request lane — advisor.requestEvidence records a scoped request for additional evidence on an open matter without exposing the full tenant graph.

A worked end-to-end example for the German invoice/payment advisor flow lives in vertical-de-invoice-payment-advisor.md; this page covers the generic advisor membrane API that the vertical builds on.

An advisor matter or opinion never creates standing or admin authority on its own — advisor.issueOpinion asserts advisor_becomes_admin: false explicitly. See standing-and-mandates.md for the authority-creation surface and lens-and-intervention.md for the scoped disclosure and intervention companion surface.

advisor.openMatter

Section titled “advisor.openMatter”

Open a scoped advisor matter without granting admin access.

POST /v1/advisor/matters/open
state: staging-durable
sdk_role: open a scoped advisor matter without granting admin access
request_record: CloudAdvisorMatterRequest
responses: advisor_matter | refusal | receipt

Request

Section titled “Request”
interface AdvisorMatterRequest {
  tenant: GestaltRef;
  company: GestaltRef;
  advisor: GestaltRef;
  matter_kind: string;
  scope: string[];
  evidence: GestaltRef[];
  fixture: boolean;          // must be true
}

Response

Section titled “Response”
{
  "operation": "advisor.openMatter",
  "outcome": "admitted",
  "body": {
    "matter": "advisor_matter:...",
    "status": "open",
    "raw_company_graph_exposed": false,
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

The response asserts raw_company_graph_exposed: false explicitly: opening a matter scopes the advisor to the named matter kind, scope, and evidence, not to the full company graph.

SDK example

Section titled “SDK example”
const matter = await client.advisorOpenMatter({
  tenant: "tenant_node:rheinwerk_calibration",
  company: "company_geist:rheinwerk_calibration",
  advisor: "human_person:steuerberater_fixture",
  matter_kind: "invoice_payment_review",
  scope: ["invoice", "payment", "bookkeeping"],
  evidence: ["evidence_bundle:fixture_invoice"],
  fixture: true,
});

advisor.issueOpinion

Section titled “advisor.issueOpinion”

Issue scoped advisor opinion evidence without raw connector payloads.

POST /v1/advisor/opinions/issue
state: staging-durable
sdk_role: issue scoped advisor opinion evidence without raw connector payloads
request_record: CloudAdvisorOpinionRequest
responses: advisor_opinion | refusal | receipt

Request

Section titled “Request”
interface AdvisorOpinionRequest {
  tenant: GestaltRef;
  matter: GestaltRef;
  advisor: GestaltRef;
  decision: string;
  evidence: GestaltRef[];
  raw_payload?: unknown;     // refused if present
  fixture: boolean;          // must be true
}

Response

Section titled “Response”
{
  "operation": "advisor.issueOpinion",
  "outcome": "admitted",
  "body": {
    "opinion": "advisor_opinion:...",
    "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 advisor_raw_payload_refused if raw_payload is supplied and with koerper_fixture_only if fixture is not true.

SDK example

Section titled “SDK example”
const opinion = await client.advisorIssueOpinion({
  tenant: "tenant_node:rheinwerk_calibration",
  matter: "advisor_matter:m21_fixture",
  advisor: "human_person:steuerberater_fixture",
  decision: "clear",
  evidence: ["evidence_bundle:fixture_advisor"],
  fixture: true,
});

advisor.requestEvidence

Section titled “advisor.requestEvidence”

Request scoped advisor evidence without exposing full tenant graph.

POST /v1/advisor/evidence/request
state: staging-durable
sdk_role: request scoped advisor evidence without exposing full tenant graph
request_record: CloudAdvisorEvidenceRequest
responses: advisor_evidence_request | refusal | receipt

Request

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

Response

Section titled “Response”
{
  "operation": "advisor.requestEvidence",
  "outcome": "admitted",
  "body": {
    "evidence_request": "advisor_evidence_request:...",
    "status": "requested",
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

SDK example

Section titled “SDK example”
const evidenceRequest = await client.advisorRequestEvidence({
  tenant: "tenant_node:rheinwerk_calibration",
  matter: "advisor_matter:m21_fixture",
  requested_evidence: ["payment_observation"],
  reason: "fixture advisor needs payment evidence",
  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
advisor_raw_payload_refused
Section titled “Where to read next”