# PARC Request Model (v0.1.2)

This document defines Kernite's request model using a Cedar-style PARC shape:

- `principal`
- `action` (represented as `operation`)
- `resource`
- `context`

Kernite keeps this model JSON-native so it remains deterministic and easy to embed in APIs and workers.

## Why PARC

Kernite's purpose is deterministic policy decisions with machine-operable feedback.

PARC is a strong fit because:

- It keeps authorization intent explicit instead of hiding behavior in ad hoc payload fields.
- It supports both RBAC and ABAC patterns without changing the contract shape.
- It maps well to relationship operations like `associate`, where actor and resource context matter.

## Request Shape

`POST /v1/execute` accepts:

- `workspace_id` (required)
- `object_type` (required)
- `operation` (required)
- `principal` (required object)
- `payload` (required object)
- `resource` (optional object)
- `context` (optional object)
- `policy_context` (optional object)

Example:

```json
{
  "workspace_id": "workspace-demo",
  "principal": {
    "type": "token",
    "id": "api:ops-bot",
    "attributes": {
      "role": "admin",
      "hasVerifiedEmail": true
    }
  },
  "object_type": "association_edge",
  "operation": "associate",
  "resource": {
    "type": "association_edge",
    "id": "assoc-edge-001"
  },
  "context": {
    "source": "internal"
  },
  "payload": {
    "source_id": "record-001",
    "target_id": "record-002"
  }
}
```

## Policy Conditions (`when`-style)

Kernite supports policy-level `conditions` that mirror Cedar-style `when` intent.
Each condition is an object:

- `left`: dot-path into normalized request context
- `op`: `eq` or `neq`
- `right`: comparison value

All conditions are combined with AND semantics.

Supported roots for `left` path:

- `operation`
- `object_type`
- `principal.*`
- `resource.*`
- `context.*`
- `payload.*`

Example policy fragment:

```json
{
  "policy_key": "association_admin_only",
  "effect": "deny",
  "conditions": [
    { "left": "operation", "op": "eq", "right": "associate" },
    { "left": "principal.attributes.role", "op": "neq", "right": "admin" }
  ],
  "deny_reason_code": "associate_forbidden_non_admin",
  "deny_reason_message": "Only admin can associate records.",
  "rules": []
}
```

## Validation and Execute Boundary

`/v1/execute` is the external PEP boundary and always runs:

1. request validation and normalization
2. policy evaluation

Invalid requests are returned as HTTP 400 with structured validation errors.

## Compatibility Notes

- `operation=associate` is supported in v0.1.2.
- Existing v1 response contract fields remain stable.
- `conditions` are additive and optional; policies without conditions keep previous behavior.
