# Design Philosophy

This document explains why Kernite currently uses Python and why the implementation stays intentionally small.

## 1) Deterministic Decisions First

Kernite exists to produce deterministic decision outputs (`decision`, `reason_codes`, `trace_hash`) from policy input.  
The core value is contract stability and explainability, not language novelty.

Design implications:

- normalize input explicitly
- return machine-readable reasons
- preserve compatibility on the public response contract

## 2) Minimal Runtime Surface

Kernite keeps runtime dependencies minimal (`dependencies = []` in `pyproject.toml`) to reduce:

- install friction
- supply-chain risk
- operational drift across environments

This is useful for both fast-growing startups and enterprise companies.

## 3) Simple, Auditable Evaluation Model

Current evaluation is explicit JSON/rule processing in a small code surface (`src/kernite/evaluator.py`, `src/kernite/core.py`).

Benefits:

- easy to inspect and review
- low cognitive overhead for contributors
- straightforward reasoning about deny paths

## 3.1) Cedar-style PARC Semantics

Kernite adopts a Cedar-style PARC request model (`principal`, `operation`, `resource`, `context`) while remaining JSON-native.

Rationale:

- Relationship operations (such as `associate`) need explicit actor and target context.
- PARC avoids overloading business payload fields with authorization semantics.
- A JSON-native model preserves deterministic behavior and low runtime complexity.

See `docs/parc-model.md` for the concrete request and condition model.

## 4) Performance Is Measured, Then Optimized

Python is acceptable while SLOs are met.  
If production benchmarks show sustained shortfall (latency, throughput, or cost), optimize in this order:

1. improve data model and algorithmic hotspots
2. add caching or partial evaluation only where deterministic behavior is preserved
3. move only proven hot paths to Go or Rust while keeping the external contract stable

This avoids premature rewrites and preserves integration compatibility.
