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

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