[codex] protocol discovery and verifiable execution milestone

README.md

@@ -11,12 +11,15 @@ return.check_eligibility -> return.create -> pickup.schedule
 The prototype includes:
 
 - `actions.json`-style manifest schema and validation.
+- `.well-known/constraint-net/actions.json` manifest discovery.
 - A SoundMart demo manifest.
 - Manifest ingestion at `POST /v1/manifests`.
-- A coherence path planner.
+- Generic capability graph planning from action metadata.
 - Tier 0-2 preflight and confirmation rules.
+- Idempotent, replay-safe execution.
 - Mock OpenAPI-backed execution.
-- Signed intent, consent, and execution receipts.
+- Signed intent, consent, and execution receipts with chain verification.
+- A minimal `constraint-net` CLI.
 - A Fastify browser demo console at `/`.
 
 ## Run
@@ -39,6 +42,15 @@ pnpm test
 pnpm typecheck
 ```
 
+## Protocol Quickstart
+
+```bash
+pnpm cli validate examples/soundmart/actions.json
+pnpm dev
+pnpm cli ingest-url http://127.0.0.1:4173/.well-known/constraint-net/actions.json --server http://127.0.0.1:4173
+pnpm cli plan --goal "Return my headphones from SoundMart and choose the fastest free pickup" --merchant soundmart.example --server http://127.0.0.1:4173
+```
+
 ## Demo Flow
 
 In the browser console:
@@ -57,8 +69,16 @@ The executions return signed receipt IDs for intent, consent, and execution.
 
 - `GET /v1/health`
 - `POST /v1/manifests`
+- `POST /v1/manifests/ingest-url`
 - `POST /v1/actions/search`
 - `POST /v1/executions/preflight`
 - `POST /v1/confirmations/:id/decision`
 - `POST /v1/executions`
 - `GET /v1/receipts/:id`
+- `POST /v1/receipts/verify`
+
+## Docs
+
+- [Protocol overview](docs/protocol.md)
+- [Publisher onboarding](docs/publisher-onboarding.md)
+- [Agent builder guide](docs/agent-builder-guide.md)

docs/agent-builder-guide.md

@@ -0,0 +1,106 @@
+# Agent Builder Guide
+
+This guide shows the minimum flow an agent should use with Constraint Net.
+
+## 1. Ingest a Publisher Manifest
+
+```http
+POST /v1/manifests/ingest-url
+content-type: application/json
+```
+
+```json
+{
+  "url": "https://soundmart.example/.well-known/constraint-net/actions.json"
+}
+```
+
+## 2. Plan an Action Path
+
+```http
+POST /v1/actions/search
+content-type: application/json
+```
+
+```json
+{
+  "goal": "Return my headphones from SoundMart and choose the fastest free pickup",
+  "constraints": {
+    "merchant": "soundmart.example",
+    "risk_tiers_allowed": [0, 1, 2],
+    "requires_reversible": true
+  },
+  "available_inputs": {
+    "order_id": "ord_123",
+    "item_id": "item_headphones",
+    "reason": "changed_mind",
+    "pickup_window": "fastest_free_2026-04-29_09-12"
+  }
+}
+```
+
+## 3. Preflight
+
+```http
+POST /v1/executions/preflight
+content-type: application/json
+```
+
+```json
+{
+  "action_id": "urn:action:soundmart.example:return.create:v1",
+  "manifest_digest": "sha256-...",
+  "inputs": {
+    "order_id": "ord_123",
+    "item_id": "item_headphones",
+    "reason": "changed_mind"
+  }
+}
+```
+
+Tier 2 actions return `confirmation_required`.
+
+## 4. Confirm
+
+```http
+POST /v1/confirmations/:id/decision
+content-type: application/json
+```
+
+```json
+{
+  "decision": "confirm"
+}
+```
+
+## 5. Execute
+
+```http
+POST /v1/executions
+content-type: application/json
+```
+
+```json
+{
+  "preflight_id": "pre_...",
+  "confirmation_id": "conf_...",
+  "idempotency_key": "agent-run-123"
+}
+```
+
+Reusing the same `preflight_id` and `idempotency_key` returns the original execution result and receipt IDs. Reusing the same preflight with a different key is blocked after success.
+
+## 6. Verify Receipts
+
+```http
+POST /v1/receipts/verify
+content-type: application/json
+```
+
+```json
+{
+  "receipts": []
+}
+```
+
+The verifier checks signatures and hash links between receipts.

docs/protocol.md

@@ -0,0 +1,45 @@
+# Constraint Net Protocol
+
+Constraint Net is a discovery, planning, consent, execution, and receipt protocol for agent-safe actions.
+
+The core idea is simple: agents should not scrape pages or blindly call APIs for side-effectful work. They should discover publisher-declared capabilities, plan a coherent path under constraints, ask for consent when risk requires it, execute with replay protection, and return receipts that can be verified later.
+
+## Publisher Manifests
+
+Publishers expose an actions manifest at:
+
+```text
+https://<publisher-domain>/.well-known/constraint-net/actions.json
+```
+
+The manifest declares actions, schemas, planning metadata, risk tier, reversibility, confirmation policy, OpenAPI bindings, key discovery, and signatures.
+
+## Trust Rules
+
+- Manifests must validate against schema version `0.1`.
+- Manifests must be active, unexpired, and signed.
+- The manifest publisher domain must match the discovered domain.
+- Tier 2 side effects must be reversible and require confirmation.
+- Side-effectful OpenAPI actions must require idempotency.
+- Execution must pin the manifest digest observed at preflight.
+
+## Agent Flow
+
+1. Discover a publisher manifest.
+2. Validate and ingest it.
+3. Plan a capability path from the user goal.
+4. Preflight a selected step.
+5. Ask the user to confirm Tier 2 side effects.
+6. Execute with an idempotency key.
+7. Verify intent, consent, and execution receipts.
+
+## Local Endpoints
+
+- `POST /v1/manifests`
+- `POST /v1/manifests/ingest-url`
+- `POST /v1/actions/search`
+- `POST /v1/executions/preflight`
+- `POST /v1/confirmations/:id/decision`
+- `POST /v1/executions`
+- `GET /v1/receipts/:id`
+- `POST /v1/receipts/verify`

docs/publisher-onboarding.md

@@ -0,0 +1,37 @@
+# Publisher Onboarding
+
+Use this checklist to make a publisher capability available to agents through Constraint Net.
+
+1. Define the actions the publisher is willing to expose.
+2. Add input and output schemas for every action.
+3. Add planning metadata:
+   - `intent_tags`
+   - `requires`
+   - `produces`
+   - optional `after`
+4. Add risk, reversibility, confirmation, and idempotency metadata.
+5. Add public keys under `key_discovery.public_keys`.
+6. Sign the manifest over its canonical unsigned payload.
+7. Host it at `/.well-known/constraint-net/actions.json`.
+8. Validate it locally:
+
+```bash
+pnpm cli validate examples/soundmart/actions.json
+```
+
+9. Ingest it into a running Constraint Net gateway:
+
+```bash
+pnpm cli ingest-url https://<domain>/.well-known/constraint-net/actions.json
+```
+
+## Safety Requirements
+
+Tier 2 actions are side-effectful. They must:
+
+- require confirmation
+- declare a reversible path
+- require idempotency for execution
+- return outputs that validate against `output_schema`
+
+Provider prose is never a policy input. The manifest fields are the policy surface.