# 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.
