Add PulseRouter outcome-settled AI slice

Author: FlowmemoryAI

.github/workflows/ci.yml

@@ -28,6 +28,8 @@ jobs:
           python -m flowmemory_compiler.cli private-compute-demo --pretty
           python -m flowmemory_compiler.cli evidence-schema --pretty
           python -m flowmemory_compiler.cli release-transcript --pretty
+          python -m flowmemory_compiler.cli pulserouter-demo --pretty
+          python -m flowmemory_compiler.cli pulserouter-adversary --pretty
           python -m flowmemory_compiler.cli claim-gate --pretty
           python -m flowmemory_compiler.cli launch-packet --pretty
           python -m flowmemory_compiler.cli production-readiness --pretty

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0
+
+Outcome-settled AI and PulseRouter launch slice.
+
+- Added PulseRouter local router for provider selection by expected successful outcome, not raw token price.
+- Added ComputePulse, ToolCallPulse, ActionPulse, FlowPulseLink, OutcomePulse, ProviderQuote, OutcomePolicy, and RouteScore local data model.
+- Added `pulserouter-demo` and `pulserouter-adversary` CLI commands.
+- Added 22-case adversarial suite for route manipulation, privacy drift, FlowPulse link drift, settlement drift, and cost-accounting drift.
+- Added Outcome-Settled AI and PulseRouter architecture docs plus `PulseRouter.v0` spec.
+- Added PulseRouter checks to release transcript, launch packet, CI demos, and local tests.
+
 ## 0.2.1
 
 Launch packet and adapter conformance hardening.

README.md

@@ -5,7 +5,7 @@ Generic agents make claims. FlowMemory agents can leave warranted receipts.
 FlowMemory Warranted Agents is a local public proof for a new agent primitive:
 
 ```text
-AgentManifest -> WorkRequest -> PolicyCard -> AgentProposal -> AgentRegistry -> AgentRuntime -> EvidenceSchema -> FlowBond -> FlowPulse -> PulsePass -> ScopedProof
+AgentManifest -> WorkRequest -> PolicyCard -> AgentProposal -> AgentRegistry -> AgentRuntime -> EvidenceSchema -> FlowBond -> FlowPulse -> PulsePass -> PulseRouter -> OutcomePulse -> ScopedProof
 ```
 
 The user defines the promise. The agent bonds the promise. The action emits receipt-backed memory. The user privately carries proof of what happened.
@@ -40,6 +40,8 @@ PulsePass gives the user portable private proof.
 
 PolicyCards let the user's rules travel between agents.
 
+PulseRouter routes providers by successful outcomes, not raw token price.
+
 ## Product Stack
 
 ### AgentManifest
@@ -138,6 +140,21 @@ It does not expose the raw receipt history.
 
 FlowCompiler is the conformance engine underneath the stack. It turns proposed actions into required evidence envelopes and rejects futures that cannot become legal machine histories.
 
+### PulseRouter
+
+PulseRouter is the launch MVP for outcome-settled AI.
+
+It compares model/provider routes against a PolicyCard-like user policy, emits
+`ComputePulse`, `ToolCallPulse`, `ActionPulse`, reader-derived `FlowPulse` link,
+and `OutcomePulse`, then proves the selected route is the cheapest successful
+route rather than the cheapest raw inference route.
+
+The public claim is:
+
+```text
+The cheapest model is not the cheapest successful route.
+```
+
 ## Demos
 
 Run the warranted-agent stack:
@@ -155,6 +172,8 @@ python -m flowmemory_compiler.cli agent-registry-demo --pretty
 python -m flowmemory_compiler.cli agent-runtime-demo --pretty
 python -m flowmemory_compiler.cli evidence-schema --pretty
 python -m flowmemory_compiler.cli release-transcript --pretty
+python -m flowmemory_compiler.cli pulserouter-demo --pretty
+python -m flowmemory_compiler.cli pulserouter-adversary --pretty
 python -m flowmemory_compiler.cli claim-gate --pretty
 python -m flowmemory_compiler.cli launch-packet --pretty
 python -m flowmemory_compiler.cli production-readiness --pretty
@@ -198,6 +217,9 @@ BondLedger:
 PrivateCompute:
   scoped predicates over PulsePass without exposing raw receipts
 
+PulseRouter:
+  routes three providers by expected successful outcome, emits pulses, links to FlowPulse, and catches 22 adversarial manipulations
+
 ReleaseTranscript:
   one canonical offline object that summarizes the full framework
 
@@ -281,6 +303,9 @@ Start here for review:
 - `docs/THREAT_MODEL.md`
 - `docs/CLAIM_BOUNDARIES.md`
 - `docs/MARKETING_POSITIONING.md`
+- `docs/OUTCOME_SETTLED_AI.md`
+- `docs/PULSEROUTER_ARCHITECTURE.md`
+- `docs/BUILD_TEST_VERIFY_LOOP.md`
 - `docs/AGENT_RUNTIME.md`
 - `docs/RUNTIME_STATE_MACHINE.md`
 - `docs/AGENT_REGISTRY.md`
@@ -297,6 +322,7 @@ Start here for review:
 - `specs/RuntimeStateMachine.v0.md`
 - `specs/EvidenceSchemas.v0.md`
 - `specs/RuntimeTelemetry.v0.md`
+- `specs/PulseRouter.v0.md`
 - `examples/warranted_agents/README.md`
 
 ## Non-Claims
@@ -316,6 +342,9 @@ This v0 does not claim:
 - full privacy;
 - zero-knowledge privacy;
 - production bond adjudication;
+- production provider marketplace;
+- production wallet settlement;
+- production x402 service;
 - production verifier readiness.
 
 The local `capture-command` helper records command exit code and output hashes. It still does not prove code correctness, semantic truth, or production provenance.
@@ -337,3 +366,11 @@ The user owns the rule. The agent bonds the promise. The FlowPulse carries the m
 ```text
 Actions can look valid to ordinary rails while the machine history behind them is impossible.
 ```
+
+```text
+UsePod finds cheap compute. FlowMemory finds useful compute.
+```
+
+```text
+Outcome-settled AI: agents paid by successful work, not tokens.
+```

docs/BUILD_TEST_VERIFY_LOOP.md

@@ -0,0 +1,69 @@
+# Build Test Verify Loop
+
+Use this loop for every FlowMemory warranted-agent and PulseRouter slice.
+
+## Loop
+
+```text
+1. Build one narrow primitive.
+2. Add the public schema or doc boundary.
+3. Add positive tests.
+4. Add adversarial tests.
+5. Run the local commands.
+6. Run the claim gate.
+7. Update release transcript and launch packet.
+8. Push only after CI-shaped verification passes locally.
+```
+
+## Required Commands
+
+```powershell
+python -m unittest
+python -m flowmemory_compiler.cli pulserouter-demo --pretty
+python -m flowmemory_compiler.cli pulserouter-adversary --pretty
+python -m flowmemory_compiler.cli release-transcript --pretty
+python -m flowmemory_compiler.cli launch-packet --pretty
+python -m flowmemory_compiler.cli production-readiness --pretty
+python -m flowmemory_compiler.cli claim-gate --pretty
+git diff --check
+```
+
+## Exit Criteria
+
+A slice is launch-ready when:
+
+- unit tests pass;
+- demo command exits zero;
+- adversarial suite exits zero;
+- release transcript includes the new primitive;
+- launch packet readiness is `PASSED`;
+- production readiness stays honest about external blockers;
+- claim gate reports zero unguarded overclaims;
+- no whitespace errors are present.
+
+## PulseRouter-Specific Loop
+
+For the outcome layer:
+
+```text
+ProviderQuote -> RouteScore -> ComputePulse -> ToolCallPulse -> ActionPulse -> FlowPulseLink -> OutcomePulse -> adversarial validation
+```
+
+Every new provider adapter must prove:
+
+- policy eligibility;
+- route score;
+- request/response hash;
+- privacy tier;
+- prompt retention claim;
+- canary status;
+- output schema status;
+- bond coverage;
+- x402/payment reference when applicable;
+- outcome settlement link.
+
+## Non-Claims
+
+This loop does not claim production custody, wallet enforcement, production
+settlement, production provider routing, full privacy, zero-knowledge privacy,
+TEE attestation, model correctness, semantic truth, or profit guarantee.

docs/DEVELOPER_HANDOFF.md

@@ -4,7 +4,7 @@ This document is for a developer reviewing FlowMemory Warranted Agents as an arc
 
 ## One Sentence
 
-FlowMemory Warranted Agents turns an agent promise into a deterministic machine history: manifest, request, policy, proposal, registry match, runtime phases, evidence schema checks, bond settlement, FlowPulse memory, private receipt proof, and conformance checks.
+FlowMemory Warranted Agents turns an agent promise into a deterministic machine history: manifest, request, policy, proposal, registry match, runtime phases, evidence schema checks, bond settlement, FlowPulse memory, PulseRouter outcome routing, private receipt proof, and conformance checks.
 
 ## Plain English
 
@@ -22,6 +22,7 @@ Here is the evidence I must produce.
 Here is the bond behind the promise.
 Here is the memory receipt after the action.
 Here is a private proof the user can carry later.
+Here is why the selected provider was useful, not just cheap.
 ```
 
 That is the framework.
@@ -104,6 +105,7 @@ Code:
 - `flowmemory_compiler/flowbond.py`
 - `flowmemory_compiler/pulsepass.py`
 - `flowmemory_compiler/private_compute.py`
+- `flowmemory_compiler/outcome_router.py`
 - `flowmemory_compiler/claim_gate.py`
 - `flowmemory_compiler/production_readiness.py`
 
@@ -117,6 +119,8 @@ Docs:
 - `docs/EVIDENCE_SCHEMA.md`
 - `docs/CLAIM_GATE.md`
 - `docs/RELEASE_TRANSCRIPT.md`
+- `docs/OUTCOME_SETTLED_AI.md`
+- `docs/PULSEROUTER_ARCHITECTURE.md`
 - `docs/PRODUCTION_READINESS_ARCHITECTURE.md`
 - `docs/PRODUCTION_GATE_CHECKLIST.md`
 - `docs/OPERATOR_RUNBOOK.md`
@@ -126,6 +130,7 @@ Docs:
 Spec:
 
 - `specs/WarrantedAgentFramework.v0.md`
+- `specs/PulseRouter.v0.md`
 
 ## Verification Commands
 
@@ -135,6 +140,8 @@ python -m flowmemory_compiler.cli agent-registry-demo --pretty
 python -m flowmemory_compiler.cli agent-runtime-demo --pretty
 python -m flowmemory_compiler.cli evidence-schema --pretty
 python -m flowmemory_compiler.cli release-transcript --pretty
+python -m flowmemory_compiler.cli pulserouter-demo --pretty
+python -m flowmemory_compiler.cli pulserouter-adversary --pretty
 python -m flowmemory_compiler.cli claim-gate --pretty
 python -m flowmemory_compiler.cli production-readiness --pretty
 ```
@@ -155,6 +162,12 @@ The point is narrower:
 Make the agent promise machine-checkable before, during, and after execution.
 ```
 
+PulseRouter adds the outcome layer:
+
+```text
+Route intelligence by receipt-backed successful outcomes, not raw token price.
+```
+
 Production status:
 
 ```text

docs/LAUNCH_CHECKLIST.md

@@ -6,6 +6,8 @@ This checklist keeps the warranted-agent package launchable without overstating
 
 - `python -m unittest discover -s tests -p "test_*.py"` passes.
 - `python -m flowmemory_compiler.cli release-transcript --pretty` prints the current stack.
+- `python -m flowmemory_compiler.cli pulserouter-demo --pretty` selects the private bonded provider and reports no validation faults.
+- `python -m flowmemory_compiler.cli pulserouter-adversary --pretty` catches every bundled adversarial route/outcome manipulation.
 - `python -m flowmemory_compiler.cli claim-gate --pretty` passes with `unguardedOverclaims: 0`.
 - GitHub Actions CI passes on `main`.
 - README opening still explains the category in one screen.
@@ -17,6 +19,8 @@ Use this order:
 
 ```powershell
 python -m flowmemory_compiler.cli release-transcript --pretty
+python -m flowmemory_compiler.cli pulserouter-demo --pretty
+python -m flowmemory_compiler.cli pulserouter-adversary --pretty
 python -m flowmemory_compiler.cli agent-runtime-demo --pretty
 python -m flowmemory_compiler.cli agent-registry-demo --pretty
 python -m flowmemory_compiler.cli evidence-schema --pretty
@@ -27,10 +31,12 @@ The story is:
 
 ```text
 1. Here is the full stack.
-2. Here is the runtime history.
-3. Here is warranty-based discovery.
-4. Here are the evidence contracts.
-5. Here are impossible histories rejected.
+2. Here is outcome routing by successful work, not token price.
+3. Here are adversarial route manipulations rejected.
+4. Here is the runtime history.
+5. Here is warranty-based discovery.
+6. Here are the evidence contracts.
+7. Here are impossible histories rejected.
 ```
 
 ## Public Positioning
@@ -53,6 +59,12 @@ Then show the framework:
 manifest -> quote -> bond -> action -> settlement -> memory -> private proof
 ```
 
+Then show the outcome layer:
+
+```text
+compute -> tool -> action -> FlowPulse -> outcome -> portable user memory
+```
+
 ## Reviewer-Safe Claims
 
 Safe:
@@ -64,6 +76,8 @@ Safe:
 - AgentRuntime records the state machine from quote to private proof;
 - EvidenceSchema checks required local fields for evidence envelopes;
 - PulsePass exposes scoped proofs without raw receipt history;
+- PulseRouter routes providers by expected successful outcome, not raw token price;
+- PulseRouter catches bundled route/outcome manipulation cases;
 - FlowCompiler rejects impossible machine histories in the bundled cases.
 
 Not safe to claim:
@@ -77,6 +91,8 @@ Not safe to claim:
 - semantic truth;
 - zero-knowledge privacy in v0;
 - guaranteed fraud prevention.
+- live provider marketplace;
+- production x402 service;
 
 ## Final Confidence Gate
 

docs/LAUNCH_PACKET.md

@@ -17,6 +17,8 @@ It summarizes:
 - adapter conformance status;
 - runtime success/failure coverage;
 - bundled impossible-history rejection status;
+- PulseRouter outcome-routing validation;
+- PulseRouter adversarial validation;
 - reviewer commands.
 
 Expected shape:
@@ -31,6 +33,8 @@ Checks:
   adapter_conformance_passed                             PASS
   runtime_has_success_and_failure_paths                  PASS
   flowcompiler_rejects_all_bundled_impossible_histories  PASS
+  pulserouter_demo_has_no_validation_faults              PASS
+  pulserouter_adversary_suite_passed                     PASS
 ```
 
 ## Why This Matters