> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use cases

# Kernite Use-Case Playbooks

This guide shows how to integrate Kernite in three common scenarios:

* LLM-driven actions
* Building your own service/API
* Multi-tenant SaaS platforms

The common rule is the same in all cases:

* evaluate first with `POST /execute` (or managed `POST /v1/execute`)
* only write when decision is `approved`
* persist governance evidence with the write

## Shared Decision Pattern

1. Resolve scope from the write intent:

* `object_type`
* `operation` (`create|update|delete|archive|activate`)

2. Call execute with `workspace_id`, `principal`, payload, and policy context (`policy_context`).
3. If denied:

* do not write
* use `reason_codes` for remediation/retry flow

4. If approved:

* perform the write in the same request path (synchronous gate)

5. Persist evidence on the write record/log:

* hosted mode: store `governance_execution_id`
* local/reference mode: store `ctx_id` and `trace_hash`

Important:

* Do not trust a cached `approved=true` flag in your own DB as the authorization source.
* Re-evaluate at write time.

## 1) LLM Actions (Function Calling / Tool Calling)

### WHY Kernite

* LLM output is probabilistic; write-path safety must be deterministic.
* Agents need machine-readable deny reasons to auto-repair payloads.
* You need verifiable decision evidence for post-incident replay.

### Recommended implementation

Use `execute` as the synchronous gate before every external side effect.

1. Map tool/action to governance scope.

* `POST /customers` -> `object_type=customer`, `operation=create`
* `PATCH /customers/:id` -> `object_type=customer`, `operation=update`

2. Optionally map from OpenAPI `operationId`.

* `Customers_Create` -> `customer/create`
* `Customers_Update` -> `customer/update`

3. Agent orchestrator calls execute.
4. If denied, agent receives machine-readable reason codes and can retry with corrected payload.
5. If approved, backend performs write immediately.

### Async worker note

For queued jobs, evaluate in the worker right before mutation, not only at enqueue time.

## 2) Internal System / Own Service API

### WHY Kernite

* Route-level auth alone does not protect business write invariants.
* Teams need one consistent guard across UI, API, workers, and actions.
* Auditability requires explicit decision linkage, not implicit app logs.

### Recommended implementation

1. Add a write guard in every mutation endpoint/service path.
2. Build a deterministic mapper from route/handler to scope.
3. Call execute synchronously in the write path.
4. Short-circuit on denied.
5. On approved, write and persist governance evidence with the mutation log.

### Suggested mapper inputs

* route + method (`POST /customers`)
* explicit action metadata in code
* OpenAPI `operationId`

Prefer explicit mapping in code/config over ad-hoc string parsing.

## 3) Multi-Tenant SaaS

### WHY Kernite

* Tenant isolation needs policy decisions scoped by workspace, not global checks.
* Zero-trust posture requires server-derived principals and fail-closed behavior.
* Cross-tenant audit and reconciliation need stable evidence contracts.

### Recommended implementation

Apply tenant-scoped execute checks as mandatory middleware in all write paths.

1. Derive stable principal server-side (never trust client-supplied principal).
2. Evaluate policy in the target tenant/workspace where data is mutated.
3. Enforce fail-closed for unknown principal on governed write paths.
4. Scope idempotency by tenant and action.

* `(workspace_id, object_type, operation, idempotency_key)`

5. Persist evidence and run reconciliation checks for writes without governance linkage.

### Background automation

Use stable service/workflow principals.
Do not use ephemeral run IDs as policy identity keys.

## Hosted vs Local Reference

### Hosted mode (managed)

* Policy/execution state is persisted by the managed service.
* Use managed execute endpoint and logs endpoint for audits.
* Query audit trails from managed logs API.

### Local/reference mode (`kernite serve`)

* Reference server supports:
  * `POST /execute`
  * `POST /v1/execute`
  * `GET /health`
* The local server is stateless by default and does not provide a persisted logs API.
* Persist decision evidence (`ctx_id`, `trace_hash`, request metadata) in your application logs/store.

## Audit Trail Checklist

For each successful write, keep:

* tenant/workspace identifier
* principal identifier
* normalized scope (`object_type`, `operation`, target id)
* decision metadata (`ctx_id`, `trace_hash`, reason codes)
* linkage key (`governance_execution_id` in hosted mode)
* request id / idempotency key

This enables replay, reconciliation, and incident review without relying on mutable application-only logs.