docs/api_surface_v0.md

# API Surface v0

Clean product one-liner: the harness should look like one API that steers a graph-backed control loop.

Layman version: the user talks to one operator, not six subsystems.

## Primary endpoint

`POST /turn`

This is the product boundary.

## Orientation rule

Every turn response should also carry one machine-readable system context packet.

Why in plain English: a fresh agent should not have to inspect folders to learn where it is, what governs it, or which payloads it may emit.

## Cause And Effect Over The API

| API input | Runtime cause | API output | Why it matters |
| --- | --- | --- | --- |
| `user_input` | intent classification | `lane` | tells the system which authority surface to use |
| `receipt_state` | proof-aware routing | `receipt_requirements` | promotion and mutation stay governed |
| `task_state` | bounded objective shaping | `decision_brief` | user sees one actionable outcome |
| `tool_state` | candidate route pressure | `control_vector` | the system shows how it wants to steer |
| `alpha_state` | urgency/confidence pressure | `tensor_surface` | operator sees compact posture, not raw internals |
| `execution_gate` | authority decision | `ui_projection` | UX mode follows real control state |
| `system_context` | lineage + policy hydration | `system_context` | a fresh agent can orient in one pull |

## Request packet

| Field | Meaning |
| --- | --- |
| `user_input` | the user ask |
| `thread_state` | current local conversation state |
| `receipt_state` | what has already been proven |
| `task_state` | bounded objective and next move |
| `tool_state` | candidate tools and routes |
| `alpha_state` | urgency, confidence, promotion pressure |

## Response packet

| Field | Meaning | Why it matters |
| --- | --- | --- |
| `lane` | active operating lane | tells the system where it is working |
| `control_vector` | plan/execute/review/promote posture | steering signal |
| `tensor_surface` | strongest source, dominant stage, weakest metric, frontier read | compact control panel |
| `execution_gate` | whether bounded execution is allowed | safety interlock |
| `receipt_requirements` | proof required before promotion | governance boundary |
| `ui_projection` | visible user mode and layout | turns machinery into UX |
| `decision_brief` | short human-facing outcome | product surface |
| `system_context` | system lineage, VSM governance, and payload templates | agent bootstrap surface |

## Input To Output Flow

```mermaid
flowchart LR
  A["POST /turn"] --> B["Classify ask + load graph/receipts"]
  B --> C["Hydrate lineage + policy + payload context"]
  C --> D["Compute lane + control vector + tensor surface"]
  D --> E["Check execution gate"]
  E -->|closed| F["Return chat or inspect packet"]
  E -->|open| G["Run bounded execution"]
  G --> H["Emit receipt + graph state"]
  H --> I["Return confirm packet with proof + context"]
```

## Why that matters for emergence

The API is not just transport.
It is the place where local causes become visible system behavior.

If the same API keeps:
- reading prior receipts
- computing control posture
- updating graph state
- and returning the new posture

then the API becomes the stable projection of an evolving control system.

## Minimal behavior contract

| Ask type | Expected lane | Expected UI mode |
| --- | --- | --- |
| understanding / summary | `memory` | `chat` |
| compare / plan | `planning` | `chat` |
| bounded mutation | `execution` | `confirm` |
| debug / why / inspect | `audit` or `planning` | `inspect` |

## Deterministic boundary

Clean product one-liner: `POST /turn` should expose one kernel, but not every turn should be model-shaped.

| Query class | Kernel behavior | Why |
| --- | --- | --- |
| exact lookup | deterministic answer from runtime or graph state | exact state should stay cheap and replayable |
| unsupported lookup | deterministic abstention | unsupported asks should fail closed |
| semantic interpretation | model over packet state | abstraction belongs where ambiguity exists |
| execution request | deterministic manifest gate, then bounded action | authority should open only through policy |

Layman version: the turn API is one front door, but behind it there are two responsibilities: the kernel proves and retrieves exact state, and the model interprets lawful packet state when the ask is genuinely semantic.

## Why this API wins

| API shape | Read |
| --- | --- |
| raw tool surface | loses |
| many separate endpoints with different mental models | loses |
| one turn endpoint with structured control output | wins |