Governance from the SDK

Governance is enforced server-side, on every path, regardless of which client you hold. What the SDK gives you is a typed way to read the outcome — and an honest statement of which parts of the policy surface it can reach today.

Three outcomes, not two

A governed call resolves one of three ways. Only one of them throws.

Outcome	How it arrives	What to do
allow	the normal result	proceed
park	body `{ status: "pending_approval", approval_id }` (HTTP 202)	a human must decide; poll or wait
deny	a thrown `NaiveError`	read `err.code` — it is not retryable as-is

A park is success-with-deferral. It does not throw, and reading its result as if the work had happened is the single most common governance bug.

import { asDecision } from "@usenaive-sdk/server";

const outcome = asDecision(await client.cards.create({ name: "Ads", spendingLimitCents: 50000 }));

if (outcome.decision === "park") {
  console.log(outcome.approvalId, outcome.action, outcome.primitive, outcome.message);
  await client.approvals.wait(outcome.approvalId);
} else {
  outcome.value;   // executed
}

asDecision folds on the body discriminator (status: "pending_approval"), not the HTTP status — Http.request discards the status code, so 202-vs-200 is not observable from this client at all. The body discriminator is the only signal that survives the transport, and the API sends it on every gated route.For a boolean check without the fold, isPendingApproval(res) is exported too. See Errors and Approvals.

`brain.forget` is the sharp case

const res = await naive.brain.forget({ scope: "entity", scope_ref: "Acme Corp" });
if (res.decision === "park") {
  // 🔴 NOTHING WAS ERASED. A human must approve it first.
} else {
  // erased
}

A human caller executes the erase immediately; an agent caller parks it and the erase does not happen. BrainHandle.forget returns a Decision<T> precisely so those two cannot be confused. The legacy BrainClient.forget returns Promise<unknown> and a resolved promise there reads as “it happened” — it does not.

The denial vocabulary

NaiveError.code stays typed as string — narrowing it would break every existing e.code === "…" comparison in customer code. The closed union ships alongside it:

import { NaiveError, isNaiveErrorCode, denialOf } from "@usenaive-sdk/server";
import type { NaiveErrorCode } from "@usenaive-sdk/server";

try {
  await support.runs.start({ /* … */ });
} catch (err) {
  if (err instanceof NaiveError && isNaiveErrorCode(err.code)) {
    const code: NaiveErrorCode = err.code;   // narrowed
    const detail = denialOf(err);            // structured denial, when the API sent one
  }
}

The 36 members of NAIVE_ERROR_CODES, by family:

Governance — capability_denied, approval_required, approval_expired, budget_exceeded, unpriceable, statute_denied, grant_expired, grant_spent, unnamed_approver, approver_set_empty, pending_limit_exceeded, enforcement_unavailable, snapshot_stale, unknown_action, unknown_resource, residency_violation, outside_active_window, rate_limited, concurrency_limited
Deploy — manifest_stale, company_block_conflict, brain_retention_unsupported, residency_unsupported_on_runtime, plan_required
Brain — brain_not_permitted, brain_not_bound, brain_invalid_input
Transport — unauthorized, not_found, conflict, server_error, malformed_response, network, timeout, contract_version_mismatch, not_implemented

NAIVE_ERROR_CODES is exported as a runtime array, so you can switch exhaustively without transcribing the list.

What the SDK cannot reach yet

There is no policy, grants, limits, spend or attestation client on this SDK. Those REST operations exist and answer — GET /v1/policy/snapshot, POST /v1/policy/explain, GET /v1/policy/statute, GET /v1/grants, GET /v1/limits, GET /v1/spend, GET /v1/attestations, GET /v1/connections/policy — but no namespace on NaiveClient maps to them.Both audit methods are wired, to GET /v1/policy/decisions and GET /v1/policy/decisions/{id} — the published address of the ledger reader. (An earlier version of this client named /v1/audit/decisions, which has never been mounted.) Both routes answer 501 not_configured on this build, because policy_decisions has no table yet, and the refusal says so on the wire rather than being guessed at client-side.naive.forTenant(id).logs is a different table — primitive call events, not governance decisions — so do not substitute one for the other.There is no CLI group for them either — naive policy, naive grants, naive limits and naive spend are not registered commands. Until a client lands, reach the mounted governance routes over REST, or through the untyped escape hatch on the same credential and host:

const snapshot = await naive.legacy.invoke("GET", "/v1/policy/snapshot");
const why = await naive.legacy.invoke("POST", "/v1/policy/explain", {
  action: "payments.transfer",
  subject: alice.id,
});

POST /v1/policy/explain reports the engine’s verdict vocabulary — it says park, never approve — plus the layer and the config path that decided. It is the fastest way to answer “why was this denied” without reading a ledger that has no reader.

The manifest-digest fence is not implemented

defineConfig returns your config by identity and computes no digest, so there is nothing for the client to send and nothing to compare against the applied manifest. The onDigestMismatch option is absent rather than accepted-and-ignored. digestsOf(err) is exported and will decode a manifest_stale error if the API ever sends one; today nothing does. See also: Teams & the durable runtime · Errors · Account Kits · Governance gateway.

​Three outcomes, not two

​brain.forget is the sharp case

​The denial vocabulary

​What the SDK cannot reach yet

​The manifest-digest fence is not implemented

Three outcomes, not two

`brain.forget` is the sharp case

The denial vocabulary

What the SDK cannot reach yet

The manifest-digest fence is not implemented