docs: truth-sync behavior wording

Author: selfradiance

README.md

@@ -10,7 +10,7 @@ As AI agents reduce the marginal cost of sending bids, API calls, negotiations,
 
 Traditional defenses don't solve this. Rate limits cap volume but don't make bad actions costly. Auth tokens verify identity but don't require skin in the game. Policy engines enforce rules but can't make an agent economically accountable for its behavior.
 
-AgentGate takes a different approach: **before an agent can execute a high-impact action, it must post a bond as collateral.** If the action succeeds, the bond is released. If the agent behaves maliciously, the bond is slashed. This makes bad behavior economically irrational — the agent loses more than it gains.
+AgentGate takes a different approach: **before an agent can execute a high-impact action, it must post a bond as collateral.** If the action resolves cleanly, the reserved exposure is settled and released. If the agent behaves maliciously, the reserved exposure is slashed. This makes bad behavior economically irrational — the agent loses more than it gains.
 
 AgentGate sits as a deterministic choke point between autonomous agents and external actions (market orders, API calls, financial operations), enforcing economic accountability through signed identities and reusable bond-based exposure tracking.
 
@@ -57,7 +57,7 @@ curl -s http://127.0.0.1:3000/v1/bonds/lock \
   -H "x-agentgate-timestamp: $TIMESTAMP" \
   -H "x-agentgate-signature: $SIGNATURE" \
   -H "x-nonce: $(uuidgen)" \
-  -d '{ "identityId": "id_abc123", "amount_cents": 5000, "ttl_seconds": 300, "reason": "marketplace bid" }'
+  -d '{ "identityId": "id_abc123", "amountCents": 5000, "currency": "USD", "ttlSeconds": 300, "reason": "marketplace bid" }'
 ```
 
 Returns a `bondId`.
@@ -84,14 +84,14 @@ curl -s http://127.0.0.1:3000/v1/actions/<actionId>/resolve \
   -d '{ "outcome": "success", "resolverId": "id_resolver123" }'
 ```
 
-Outcome must be one of: `success`, `failed`, or `malicious`. On success/failed, exposure is released. On malicious, the bond is slashed.
+Outcome must be one of: `success`, `failed`, or `malicious`. On `success` or `failed`, that action's reserved exposure is settled and released. On `malicious`, that action's reserved exposure is slashed from the bond.
 
 ### Common Errors
 
 | Error | Cause | Fix |
 |---|---|---|
-| `INVALID_SIGNATURE` | Signature doesn't match body + timestamp | Verify you're signing `sha256(nonce + method + path + timestamp + JSON.stringify(body))` with the correct private key |
-| `TIMESTAMP_EXPIRED` | Timestamp is older than 60 seconds | Use a fresh timestamp for each request |
+| `INVALID_SIGNATURE` | Missing signature headers, stale timestamp, or signature doesn't match the signed payload | Verify you're signing `sha256(nonce + method + path + timestamp + JSON.stringify(body))` with the correct private key and a fresh timestamp |
+| `MISSING_NONCE` | `x-nonce` header is missing | Send a fresh nonce on every POST request |
 | `DUPLICATE_NONCE` | Same nonce reused by the same identity | Generate a fresh UUID for every request |
 | `TIER_BOND_CAP_EXCEEDED` | Bond amount exceeds identity's trust tier cap | Build reputation with successful resolutions to unlock higher tiers |
 | `INSUFFICIENT_BOND_CAPACITY` | Bond doesn't have enough remaining capacity | Lock a larger bond or resolve outstanding actions to free capacity |
@@ -125,16 +125,18 @@ Bonds are not single-use. Each bond represents reusable execution capacity.
 - **Constraint:** `outstanding_exposure_cents + effective_exposure <= amount_cents`
 - If exceeded → `INSUFFICIENT_BOND_CAPACITY`
 - **TTL cap:** maximum 86400 seconds (24 hours) — requests exceeding the cap are rejected
-- Bond status lifecycle: `active` → `occupied` (when action attached) → `released` / `burned` / `slashed`
+- Bond status lifecycle during normal settlement: `active` → `occupied` (when action attached) → `released` / `burned` / `slashed`
+- Idle bonds that are touched after their TTL has elapsed are marked `expired`; expired bonds with open actions are handled by the sweeper
 
 ### Exposure Lifecycle
 
 Bonds support multiple concurrent actions. Each action reserves its own slice of the bond's capacity, and resolving one action only releases that action's exposure — other open actions on the same bond are unaffected.
 
 - **Execute:** exposure reserved, `outstanding_exposure_cents` incremented, bond marked `occupied`
-- **Resolve (success/failed):** that action's exposure released; `refund_cents` accumulated on the bond; bond returns to `active` only when all open actions are resolved
-- **Resolve (malicious):** `amount_cents` reduced (clamped at zero), `slashed_cents` and `burned_cents` increased; bond `burned` only when no open actions remain
-- **Settlement accounting:** `refund_cents`, `burned_cents`, `slashed_cents`, and `closed_at` (ISO timestamp) are persisted on the bond record at resolution time
+- **Resolve (success):** that action's exposure released; `refund_cents` accumulated on the bond; when the last open action settles and no prior burn/slash exists, the bond closes as `released`
+- **Resolve (failed):** that action's exposure released; 95% of that action's effective exposure goes to `refund_cents`, 5% to `burned_cents`; when the last open action settles and no slash exists, the bond closes as `burned`
+- **Resolve (malicious):** that action's exposure released; `amount_cents` reduced (clamped at zero) and `slashed_cents` increased; when the last open action settles, the bond closes as `slashed`
+- **Settlement accounting:** `refund_cents`, `burned_cents`, and `slashed_cents` accumulate as each action settles; `closed_at` is written when the last open action on the bond resolves
 
 ### Auto-Slash Sweeper
 
@@ -153,7 +155,7 @@ The dashboard shows per-identity scores with color coding (green for positive, r
 | Tier | Label | Requirement | Bond Cap |
 |---|---|---|---|
 | 1 | New | Default | 100¢ |
-| 2 | Established | 5 qualifying successes from 5 distinct resolvers, 0 malicious | 500¢ |
+| 2 | Established | 5 qualifying successes from 2 distinct resolvers, 0 malicious | 500¢ |
 | 3 | Trusted | 20 qualifying successes from 20 distinct resolvers, 0 malicious | No tier cap (normal capacity rules) |
 
 - Any malicious resolution forces immediate demotion to Tier 1
@@ -229,7 +231,7 @@ AgentGate includes a prediction market demo that illustrates multi-agent economi
 
 1. An operator creates a market with a yes/no question and a resolution deadline (must be a valid future ISO 8601 timestamp)
 2. Agents take positions by executing a `market.position` action against a locked bond, declaring a `side` of `yes` or `no`
-3. When the market resolves, all open positions are settled automatically — winners' bonds are released, losers' bonds are burned
+3. When the market resolves, winning positions are settled as `success` and losing positions as `failed`; each position settles only its own reserved exposure, so shared bonds stay `occupied` until every attached action is resolved
 
 **REST endpoints:**
 
@@ -238,13 +240,19 @@ AgentGate includes a prediction market demo that illustrates multi-agent economi
 curl -s http://127.0.0.1:3000/markets \
   -H 'content-type: application/json' \
   -H 'x-agentgate-key: YOUR_KEY' \
-  -d '{ "question": "Will BTC hit 100k by Friday?", "resolutionDeadline": "2025-01-10T00:00:00Z" }'
+  -H "x-agentgate-timestamp: $TIMESTAMP" \
+  -H "x-agentgate-signature: $SIGNATURE" \
+  -H "x-nonce: $(uuidgen)" \
+  -d '{ "creatorId": "id_abc123", "question": "Will BTC hit 100k by Friday?", "resolutionDeadline": "2026-04-20T00:00:00Z" }'
 
 # Resolve a market
 curl -s http://127.0.0.1:3000/markets/<marketId>/resolve \
   -H 'content-type: application/json' \
   -H 'x-agentgate-key: YOUR_KEY' \
-  -d '{ "outcome": "yes" }'
+  -H "x-agentgate-timestamp: $TIMESTAMP" \
+  -H "x-agentgate-signature: $SIGNATURE" \
+  -H "x-nonce: $(uuidgen)" \
+  -d '{ "outcome": "yes", "resolverId": "id_abc123" }'
 ```
 
 **MCP tools:** `create_market` and `resolve_market` expose the same flow to Claude Desktop.

docs/roadmap/day1-integration-surface.md

@@ -124,12 +124,13 @@ Notes:
 All state-changing calls require signed headers: :contentReference[oaicite:15]{index=15}
 - `x-agentgate-timestamp`
 - `x-agentgate-signature`
+- `x-nonce`
 
 Signed message:
-- `sha256(timestamp + JSON.stringify(body))`
+- `sha256(nonce + method + path + timestamp + JSON.stringify(body))`
 
 This is too low-level for “agent tool” usage.
-**The adapter layer (Day 2) must generate signatures and timestamps automatically.**
+**The adapter layer (Day 2) must generate signatures, timestamps, and nonces automatically.**
 
 ---
 
@@ -158,11 +159,11 @@ These error codes should be treated as “first-class” by agent tooling:
 
 ### AUTH / SIGNING
 - `INVALID_SIGNATURE`
-- `TIMESTAMP_TOO_OLD` (replay prevention)
+- `MISSING_NONCE`
 
 ### BOND / CAPACITY
 - `INSUFFICIENT_BOND_CAPACITY` :contentReference[oaicite:17]{index=17}
-- `BOND_EXPIRED` / `BOND_INACTIVE`
+- `BOND_EXPIRED` / `BOND_NOT_ACTIVE`
 
 ### OUTBOUND SAFETY (for market.http)
 - `DESTINATION_BLOCKED` :contentReference[oaicite:18]{index=18}

docs/threat-model.md

@@ -37,10 +37,9 @@ Rate limits cap volume. Auth gates cap access. AgentGate caps economic exposure.
 **How AgentGate resists this:**
 
 - All state-changing requests include a millisecond timestamp in the `x-agentgate-timestamp` header.
+- All state-changing requests also require an `x-nonce` header, and nonces are stored per identity and rejected on reuse.
 - Requests older than 60 seconds are rejected.
-- The signature covers the timestamp + request body, so modifying either invalidates the signature.
-
-**Known gap:** There is no nonce store. Within the 60-second window, a replayed request with an identical timestamp and body would pass verification. A nonce-based deduplication layer is a future improvement.
+- The signature covers `nonce + method + path + timestamp + JSON.stringify(body)`, so tampering with any signed field invalidates the request.
 
 ### 3. Forged or Tampered Requests
 
@@ -49,7 +48,9 @@ Rate limits cap volume. Auth gates cap access. AgentGate caps economic exposure.
 **How AgentGate resists this:**
 
 - All state-changing endpoints require an Ed25519 signature.
-- The signed message is: `sha256(timestamp + JSON.stringify(body))`.
+- Identity registration itself requires proof-of-possession: the caller must sign the registration request with the private key matching the public key being registered.
+- Public keys are unique at the database level, so the same key cannot register multiple identities.
+- The signed message is: `sha256(nonce + method + path + timestamp + JSON.stringify(body))`.
 - The signature is verified against the registered public key for that identity.
 - Ed25519 is a strong, well-studied cryptographic scheme — forging a signature without the private key is computationally infeasible.
 
@@ -72,7 +73,7 @@ Rate limits cap volume. Auth gates cap access. AgentGate caps economic exposure.
 **How AgentGate resists this:**
 
 - Actions must be explicitly resolved (success, failed, or malicious).
-- If resolved as malicious: the bond's `amount_cents` is reduced (clamped at zero), `slashed_cents` is increased, and the bond is burned.
+- If resolved as malicious: the action's reserved exposure is slashed, the bond's `amount_cents` is reduced (clamped at zero), and `slashed_cents` is increased. Once the last open action settles, the bond closes as `slashed`.
 - The reputation system penalizes malicious actions heavily: -20 points per malicious resolution vs. +10 for success.
 - An agent's reputation score follows its identity permanently — there is no way to "reset" a damaged score except by building a long track record of good behavior.
 
@@ -84,26 +85,22 @@ Being honest about limitations is as important as describing defenses. AgentGate
 
 ### Bond Expiry Enforcement
 
-Bonds have a `ttl_seconds` field, but expiry is only checked when an action tries to use the bond. There is no background process that automatically expires or releases bonds when their TTL elapses. An expired bond sits in "active" status until something touches it.
+Bonds with open actions are swept every 60 seconds: if the bond TTL has elapsed while an action is still open, AgentGate auto-resolves that action as `malicious`. But idle bonds are not expired by a separate background pass; an unused expired bond is marked `expired` when something tries to use it.
 
-**Impact:** Low risk in current single-user local deployment. Higher risk in multi-agent or multi-tenant scenarios.
+**Impact:** Honest but slightly asymmetric lifecycle behavior. The economic guarantee is enforced for open actions, but unused expired bonds remain lazily marked until touched.
 
 ### Auto-Slash on Timeout
 
-If an action is executed but never resolved (the agent crashes, disconnects, or simply ignores the resolution step), the action stays open indefinitely. There is no sweeper process that detects timed-out actions and automatically slashes the bond.
+AgentGate does auto-slash unresolved actions, but only on bond TTL expiry. There is no separate per-action timeout shorter than the bond's TTL.
 
-**Impact:** This is the biggest gap in the economic model. An agent can tie up bond capacity forever by executing actions and never resolving them. This is the highest-priority planned fix.
+**Impact:** Timeout behavior is tied to bond design. A long-lived bond allows a long-lived unresolved action; a short-lived bond forces faster settlement.
 
 ### Multi-Instance / Distributed Deployment
 
 AgentGate uses SQLite with in-memory assumptions. Running multiple Node.js processes against the same database will produce race conditions and incorrect exposure tracking. This is a single-instance system.
 
 **Impact:** Fine for local development and single-server deployment. Not suitable for distributed or high-availability setups without architectural changes.
 
-### Identity Revocation
-
-There is currently no mechanism to revoke or ban an identity. A malicious identity with a slashed reputation can still create new bonds and attempt actions (as long as it has the collateral). The progressive minimum bond and reputation score make this increasingly expensive, but there is no hard ban.
-
 ### Real Economic Collateral
 
 Bonds are denominated in cents but are not backed by real money, cryptocurrency, or any external payment system. The collateral is purely internal accounting. AgentGate enforces the *economic logic* of bonding, but does not yet connect to real-world value transfer.
@@ -125,13 +122,13 @@ AgentGate does not handle TLS termination, DDoS protection, or network-layer sec
 | Attack | Defense | Status |
 |---|---|---|
 | Synthetic pressure / spam | Bond requirement + progressive minimums + rate limit | ✅ Implemented |
-| Replay attacks | Timestamp validation (60-second window) + signed requests | ✅ Implemented (no nonce store) |
-| Forged requests | Ed25519 signature verification | ✅ Implemented |
+| Replay attacks | Timestamp validation + nonce store + nonce-bound signed requests | ✅ Implemented |
+| Forged requests | Ed25519 signature verification + proof-of-possession on identity registration | ✅ Implemented |
 | Outbound SSRF | HTTP allowlist + protocol/timeout/size limits | ✅ Implemented |
 | Malicious actions | Bond slashing + reputation penalty | ✅ Implemented |
 | Unresolved action timeout | Background sweeper + auto-slash | ✅ Implemented — via `sweepExpiredActions()` in service.ts — runs every 60 seconds, slashes bonds whose TTL has expired with unresolved actions |
-| Bond auto-expiry | TTL enforcement via background process | ✅ Implemented — via `sweepExpiredActions()` in service.ts — runs every 60 seconds, slashes bonds whose TTL has expired with unresolved actions |
-| Identity revocation | Ban list or revocation mechanism | 📋 Future |
+| Bond auto-expiry | TTL enforcement on use, plus sweeper for expired bonds with open actions | ⚠️ Partial — open actions are swept; idle expired bonds are marked on next use |
+| Identity revocation | Manual ban/unban endpoints + auto-ban after 3 malicious resolutions | ✅ Implemented |
 | Sybil / identity farming | Proof-of-stake or external identity binding | 📋 Future |
 | Real economic collateral | Payment system integration | 📋 Future |
 | Multi-instance deployment | Distributed database or coordination layer | 📋 Future |
@@ -141,13 +138,13 @@ AgentGate does not handle TLS termination, DDoS protection, or network-layer sec
 
 ## Known Limitations
 
-### Identity Model Does Not Enforce Public Key Uniqueness or Proof-of-Possession
+### Identity Creation Is Unique-Per-Key but Still Cheap Across Fresh Keys
 
-The current identity registration endpoint (`POST /v1/identities`) accepts any valid Ed25519 public key and creates a new identity for it — without checking whether that key is already registered and without requiring the caller to prove they hold the corresponding private key.
+The current identity registration endpoint (`POST /v1/identities`) does enforce proof-of-possession and public-key uniqueness: the caller must sign the registration request with the matching private key, and the same public key cannot be registered twice.
 
 This means:
 
-- **A single actor can create multiple identities** using the same public key, or different keys they control, spreading activity across them.
+- **A single actor can still create multiple identities** by generating fresh keypairs they control.
 - **Reputation tracking is diluted.** A bad actor with a -40 reputation score can create a fresh identity and start over at 0.
 - **Per-identity rate limits (10 actions/60s) can be circumvented** by rotating across identities.
 - **The 3-malicious-actions auto-ban threshold resets** with each new identity, so an attacker is never permanently banned — only temporarily inconvenienced.
@@ -156,9 +153,8 @@ This means:
 
 **Future hardening options:**
 
-1. **Unique index on `public_key`** — prevent the same key from registering multiple identities.
-2. **Signed registration challenges (proof-of-possession)** — require the caller to sign a server-issued challenge during `POST /v1/identities`, proving they hold the private key. This prevents identity squatting on keys the caller doesn't control.
-3. **Key-fingerprint-scoped enforcement** — move bans, rate limits, and reputation scoring from `identity_id` to the public key fingerprint. This way, creating a new identity with the same key inherits the existing reputation and restrictions, closing the reset loophole entirely.
+1. **External identity binding** — tie keys to proof-of-stake, KYC, or other scarce credentials.
+2. **Cross-key reputation linkages** — add stronger operator-side heuristics or attestations for related identities when the deployment warrants it.
 
 ### GET Endpoints Do Not Require Authentication