Spaces:
Runtime error
Runtime error
File size: 4,593 Bytes
3436bdd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | # 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 |
|