web-agent-bridge 3.8.1 → 3.9.0

package/README.ar.md

@@ -15,6 +15,8 @@
 
 **البروتوكول والمنصة المفتوحة للتفاعل بين الذكاء الاصطناعي والويب — واجهة أوامر موحّدة، متصفح سيادي، درع هاتف، اكتشاف عبر DNS، شبكة وكلاء، وبوابة API موحّدة لتفاعل آمن بين الذكاء الاصطناعي والمواقع.**
 
+> **جديد في الإصدار 3.9 — ATP (المُكوِّن الأساسي لمعاملات الوكلاء):** عقود نوايا موقَّعة، معاملات لا تتكرر (idempotent)، إيصالات Ed25519 قابلة للتحقق علنياً بدون مصادقة، وآلية تعويض صريحة. هذا هو **طبقة الثقة + المعاملات** التي تنقُص التجارة الوكيلة. [راجع المواصفة §21](docs/SPEC.md#21-agent-transaction-primitive-atp--v390) · [صفحة ATP العامة](public/atp.html).
+
 🌐 **الموقع الرسمي:** [https://webagentbridge.com](https://webagentbridge.com) — جرّب مساحة عمل الوكيل الذكي ولوحات التحكم والعديد من الميزات الأخرى مباشرة.
 
 يتيح WAB لأصحاب المواقع إضافة سكريبت يكشف واجهة `window.AICommands` لوكلاء الذكاء الاصطناعي. بدلاً من تحليل شيفرة HTML المعقدة، يقرأ الوكيل قائمة الإجراءات المتاحة وينفذها بدقة وأمان.

package/README.md

@@ -3,12 +3,14 @@
   <img src="https://raw.githubusercontent.com/abokenan444/web-agent-bridge/master/public/images/wab-logo-large.png" alt="Web Agent Bridge Logo" width="180" />
 
   <h1>Web Agent Bridge (WAB)</h1>
-  <p><b>The open AI ↔ Web protocol & agent platform.</b></p>
-  <p><i>robots.txt told bots what NOT to do. WAB tells AI agents what they CAN do.</i></p>
+  <p><b>The trust + transaction layer for agentic commerce.</b></p>
+  <p><i>Signed intent contracts · idempotent transactions · Ed25519-verifiable receipts · explicit compensation.</i></p>
+  <p><i>robots.txt told bots what NOT to do. WAB tells AI agents what they CAN do — and proves what they did.</i></p>
 
   [![npm](https://img.shields.io/npm/v/web-agent-bridge?color=blue&style=flat-square)](https://www.npmjs.com/package/web-agent-bridge)
   [![License: Open Core](https://img.shields.io/badge/License-Open_Core-blue.svg?style=flat-square)](LICENSE)
-  [![Tests](https://img.shields.io/badge/Tests-428%2F428_passing-22c55e?style=flat-square&logo=jest&logoColor=white)](tests)
+  [![Tests](https://img.shields.io/badge/Tests-445%2F445_passing-22c55e?style=flat-square&logo=jest&logoColor=white)](tests)
+  [![ATP](https://img.shields.io/badge/ATP-v3.9.0-7c3aed?style=flat-square)](docs/SPEC.md#21-agent-transaction-primitive-atp--v390)
   [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/NnbpJYEF)
 
   <br />
@@ -31,6 +33,38 @@ AI agents today guess their way through the web — DOM scraping, brittle select
 
 ---
 
+## ATP — Agent Transaction Primitive *(new in v3.9)*
+
+WAB v3.9 introduces the **Agent Transaction Primitive (ATP)** — the missing trust + transaction layer for agentic commerce.
+
+```
+Intent  →  Authorize  →  Transact  →  Receipt  →  (Compensate)
+contract    single-use     idempotent   Ed25519-     explicit
++ scope     nonce burn     UNIQUE key   signed       rollback
++ spend cap                              JSON
+```
+
+- **Intent contracts** — the user's signed authorization (scope, spend cap, expiry, single-use nonce).
+- **Idempotent execution** — `UNIQUE (intent_id, idempotency_key)`: retries can never double-execute.
+- **Signed receipts** — Ed25519 over canonical JSON; verifiable via the **public** `/api/atp/receipts/verify` endpoint with zero auth.
+- **Compensation** — explicit rollback that decrements the intent's spend counter.
+
+```js
+const { ATPClient } = require('web-agent-bridge/sdk');
+const atp = new ATPClient({ baseUrl: 'https://api.webagentbridge.com', token: USER_JWT });
+
+const intent = await atp.createIntent({ purpose: 'buy 1 widget', scope: { actions: ['cart.add','checkout'] }, max_spend_cents: 5000, currency: 'EUR' });
+await atp.authorizeIntent(intent.id);
+const tx = await atp.beginTransaction({ intent_id: intent.id, idempotency_key: 'order-42', amount_cents: 4200 });
+await atp.transition(tx.id, 'executing'); await atp.transition(tx.id, 'executed'); await atp.transition(tx.id, 'settled');
+const r = await atp.issueReceipt(tx.id);                       // signed
+const v = await atp.verifyReceipt({ receiptId: r.receipt_id }); // public, no auth
+```
+
+Full spec: [`docs/SPEC.md` §21](docs/SPEC.md#21-agent-transaction-primitive-atp--v390) · Public docs page: [`/atp.html`](public/atp.html).
+
+---
+
 ## Quick start (60 seconds)
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "web-agent-bridge",
-  "version": "3.8.1",
-  "description": "Open AI↔Web protocol & agent platform: standardized command interface, sovereign browser, ShieldQR trust verifier, SSL health monitor, zero-config adoption (Cloudflare/Vercel/Netlify/Next.js), DNS discovery, agent mesh, and unified API gateway for safe AI–website interaction",
+  "version": "3.9.0",
+  "description": "Agent Transaction Bridge — the trust + transaction layer for agentic commerce. Signed intent contracts, idempotent transactions, Ed25519-verifiable receipts, explicit compensation. Plus the original WAB stack: sovereign browser, ShieldQR, SSL health, DNS discovery, agent mesh, and unified gateway for safe AI–website interaction.",
   "author": "Web Agent Bridge <dev@webagentbridge.com>",
   "main": "server/index.js",
   "bin": {

package/public/atp.html

@@ -0,0 +1,171 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Agent Transaction Primitive (ATP) · Web Agent Bridge</title>
+  <meta name="description" content="The first-class primitive for trusted agent execution: signed intent contracts, idempotent transactions, and cryptographically verifiable receipts." />
+  <link rel="stylesheet" href="/css/main.css" />
+  <style>
+    :root { --bg:#0a0e14; --fg:#e6edf3; --muted:#8b949e; --accent:#7ee787; --line:#30363d; --card:#161b22; }
+    body { background:var(--bg); color:var(--fg); font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; margin:0; padding:0; }
+    main { max-width:980px; margin:0 auto; padding:48px 24px 96px; }
+    h1 { font-size:2.5rem; margin:0 0 8px; letter-spacing:-0.02em; }
+    h2 { font-size:1.5rem; margin:48px 0 12px; border-bottom:1px solid var(--line); padding-bottom:8px; }
+    h3 { font-size:1.1rem; margin:24px 0 8px; color:var(--accent); }
+    p.lede { font-size:1.2rem; color:var(--muted); margin:0 0 32px; max-width:720px; }
+    .badge { display:inline-block; background:#1f6feb22; color:#79c0ff; border:1px solid #1f6feb55; padding:2px 10px; border-radius:99px; font-size:0.85rem; font-weight:600; }
+    .grid { display:grid; grid-template-columns:repeat(auto-fit,minmax(240px,1fr)); gap:16px; margin:24px 0; }
+    .card { background:var(--card); border:1px solid var(--line); border-radius:8px; padding:20px; }
+    .card h3 { margin-top:0; color:var(--accent); }
+    .card p { color:var(--muted); font-size:0.95rem; margin:0; }
+    pre { background:#010409; border:1px solid var(--line); border-radius:6px; padding:16px; overflow-x:auto; font-size:0.85rem; color:#c9d1d9; }
+    code { font-family:ui-monospace,SFMono-Regular,Consolas,monospace; }
+    .lifecycle { display:flex; gap:8px; align-items:center; margin:24px 0; flex-wrap:wrap; }
+    .lifecycle .step { flex:1; min-width:140px; background:var(--card); border:1px solid var(--line); padding:16px; border-radius:6px; text-align:center; }
+    .lifecycle .step b { display:block; font-size:1.1rem; color:var(--accent); margin-bottom:4px; }
+    .lifecycle .arrow { color:var(--muted); font-size:1.5rem; }
+    table { width:100%; border-collapse:collapse; margin:16px 0; }
+    th, td { text-align:left; padding:10px 12px; border-bottom:1px solid var(--line); font-size:0.95rem; }
+    th { color:var(--accent); font-weight:600; }
+    .tier { display:inline-block; padding:1px 8px; border-radius:4px; font-size:0.8rem; font-weight:600; }
+    .tier-free { background:#3fb95022; color:#7ee787; border:1px solid #3fb95055; }
+    .tier-pro { background:#1f6feb22; color:#79c0ff; border:1px solid #1f6feb55; }
+    .tier-business { background:#bf8b3022; color:#e3b341; border:1px solid #bf8b3055; }
+    .tier-enterprise { background:#a371f722; color:#d2a8ff; border:1px solid #a371f755; }
+    nav.top { position:sticky; top:0; background:rgba(10,14,20,0.9); backdrop-filter:blur(8px); border-bottom:1px solid var(--line); padding:12px 24px; }
+    nav.top a { color:var(--fg); text-decoration:none; margin-right:20px; font-weight:500; }
+    nav.top a:hover { color:var(--accent); }
+  </style>
+</head>
+<body>
+  <nav class="top">
+    <a href="/">WAB</a>
+    <a href="/atp.html"><b>ATP</b></a>
+    <a href="/docs.html">Docs</a>
+    <a href="/premium.html">Pricing</a>
+    <a href="/login.html">Login</a>
+  </nav>
+  <main>
+    <span class="badge">v3.9.0 · the keystone primitive</span>
+    <h1>Agent Transaction Primitive</h1>
+    <p class="lede">
+      WAB is no longer just a discovery and execution protocol — it is the
+      <b>trust + transaction layer</b> for agentic commerce. ATP makes four
+      guarantees first-class: a signed intent contract from the human,
+      idempotent execution, a cryptographically verifiable receipt, and
+      explicit compensation.
+    </p>
+
+    <h2>The lifecycle</h2>
+    <div class="lifecycle">
+      <div class="step"><b>1 · Intent</b>The user declares scope, spend cap, expiry. Single-use nonce.</div>
+      <div class="arrow">→</div>
+      <div class="step"><b>2 · Authorize</b>The user confirms. The contract is now binding on the agent.</div>
+      <div class="arrow">→</div>
+      <div class="step"><b>3 · Transact</b>Idempotent execution under the intent. Every step is logged.</div>
+      <div class="arrow">→</div>
+      <div class="step"><b>4 · Receipt</b>Ed25519-signed canonical JSON. Anyone can verify it.</div>
+      <div class="arrow">→</div>
+      <div class="step"><b>5 · Compensate</b>If something goes wrong, the rollback path is explicit.</div>
+    </div>
+
+    <h2>Why this matters</h2>
+    <div class="grid">
+      <div class="card">
+        <h3>For users</h3>
+        <p>You see exactly what you authorized, what the agent did, and you can verify the receipt later — even without WAB online.</p>
+      </div>
+      <div class="card">
+        <h3>For agents</h3>
+        <p>No more retries causing double-charges. <code>idempotency-key</code> + the intent's spend cap make safe execution structural, not aspirational.</p>
+      </div>
+      <div class="card">
+        <h3>For sites</h3>
+        <p>Every transaction comes with a signed proof of consent. Disputes become deterministic, not he-said-she-said.</p>
+      </div>
+      <div class="card">
+        <h3>For ecosystems</h3>
+        <p>The protocol is open. The verification endpoint is public. The receipt format is canonical JSON. No vendor lock-in.</p>
+      </div>
+    </div>
+
+    <h2>Quick start</h2>
+<pre><code>// Node 18+ — install: npm i web-agent-bridge
+const { ATPClient } = require('web-agent-bridge/sdk');
+
+const atp = new ATPClient({ baseUrl: 'https://webagentbridge.com', token: USER_JWT });
+
+// 1) The human declares the contract.
+const intent = await atp.createIntent({
+  purpose: 'Buy a book ≤ €30',
+  scope: { actions: ['search','add_to_cart','checkout'] },
+  spend_cap_cents: 3000,
+  ttl_seconds: 600,
+});
+
+// 2) The human confirms.
+await atp.authorizeIntent(intent.id);
+
+// 3) The agent executes — idempotent by key.
+const tx = await atp.beginTransaction({
+  intent_id: intent.id, amount_cents: 1500,
+  idempotency_key: 'order-' + Date.now(),
+});
+await atp.transition(tx.id, 'executing');
+await atp.step(tx.id, { action: 'checkout.confirm', evidence: { order_id: 'X1' } });
+await atp.transition(tx.id, 'executed');
+await atp.transition(tx.id, 'settled');
+
+// 4) Signed receipt — anyone can verify.
+const receipt = await atp.issueReceipt(tx.id);
+const verification = await atp.verifyReceipt(receipt.id);
+console.log(verification.verification.ok); // true</code></pre>
+
+    <h2>The signed receipt</h2>
+    <p>Every receipt is a canonical JSON document signed with Ed25519. The public verification endpoint (<code>POST /api/atp/receipts/verify</code>) requires <b>no authentication</b> — that is the whole point. Anyone can hold a receipt accountable.</p>
+<pre><code>{
+  "type": "atp.receipt.v1",
+  "receipt_id": "atp_rcpt_…",
+  "transaction": { "id": "atp_tx_…", "status": "settled", "amount_cents": 1500, … },
+  "intent":      { "id": "atp_int_…", "purpose": "Buy a book ≤ €30", "scope": { … }, … },
+  "steps":       [ { "seq": 1, "action": "checkout.confirm", "state": "succeeded" } ],
+  "signature":   {
+    "algorithm": "ed25519",
+    "value":     "BASE64…",
+    "key_id":    "16-char fingerprint",
+    "public_key":"BASE64…",
+    "signed_at": "ISO-8601"
+  }
+}</code></pre>
+
+    <h2>Open core · paid features</h2>
+    <p>The protocol and verification stay open so the standard can spread. Higher throughput, persistent key binding, and enterprise features fund the work.</p>
+    <table>
+      <thead><tr><th>Capability</th><th>Tier</th><th>Notes</th></tr></thead>
+      <tbody>
+        <tr><td>Protocol spec &amp; SDK</td><td><span class="tier tier-free">open source</span></td><td>MIT licensed. Implement it anywhere.</td></tr>
+        <tr><td>Public receipt verification (no auth)</td><td><span class="tier tier-free">open source</span></td><td>Anyone can verify any ATP receipt.</td></tr>
+        <tr><td>Intent creation</td><td><span class="tier tier-free">free</span></td><td>10/day on Free, 50/day on Starter.</td></tr>
+        <tr><td>Receipts with persistent site key binding</td><td><span class="tier tier-pro">pro</span></td><td>500 intents/day. Continuity of trust across receipts.</td></tr>
+        <tr><td>Idempotent execution at scale</td><td><span class="tier tier-pro">pro</span></td><td>Higher quotas, audit export.</td></tr>
+        <tr><td>Compensation flows + retry classification</td><td><span class="tier tier-business">business</span></td><td>5 000 intents/day, webhook subscriptions.</td></tr>
+        <tr><td>HSM-backed signing, custom workflows, SLA</td><td><span class="tier tier-enterprise">enterprise</span></td><td>Unlimited, dedicated settlement queue.</td></tr>
+      </tbody>
+    </table>
+
+    <h2>Security posture</h2>
+    <ul>
+      <li><b>Single-use nonces.</b> Authorization burns the nonce in <code>atp_nonces</code> — replays fail at the DB layer.</li>
+      <li><b>State machine in the DB.</b> CHECK constraints make illegal transitions unrepresentable, not just unlikely.</li>
+      <li><b>Idempotency.</b> <code>UNIQUE (intent_id, idempotency_key)</code> means retries can never double-execute.</li>
+      <li><b>Spend cap on every transition.</b> Enforced server-side, not in the agent.</li>
+      <li><b>Canonical JSON signing.</b> RFC 8785-style key ordering means a tampered receipt cannot pass verification.</li>
+      <li><b>Public verify rate-limited.</b> 120 req/min per IP, cryptographic check is the answer.</li>
+    </ul>
+
+    <h2>Reference</h2>
+    <p>Full API in <a href="/docs.html">/docs.html</a> and machine-readable spec in <code>docs/SPEC.md</code>. Mount path: <code>/api/atp</code>. Source: <a href="https://github.com/abokenan444/web-agent-bridge">github.com/abokenan444/web-agent-bridge</a>.</p>
+  </main>
+</body>
+</html>

package/sdk/atp.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * WAB ATP Client — Agent Transaction Primitive (v3.9.0)
+ *
+ * A tiny, zero-dependency client (uses global fetch from Node 18+) that
+ * lets agents drive the four ATP lifecycle steps against a WAB server:
+ *
+ *   1. createIntent()    — declare what the user authorized
+ *   2. authorizeIntent() — user confirms the contract
+ *   3. beginTransaction() / step() / transition() — idempotent execution
+ *   4. issueReceipt()    — fetch the signed receipt
+ *   5. verifyReceipt()   — public verification (no auth)
+ *
+ * Example:
+ *   const atp = new ATPClient({ baseUrl: 'https://webagentbridge.com', token: jwt });
+ *   const intent = await atp.createIntent({
+ *     purpose: 'Buy a book ≤ €30',
+ *     scope: { actions: ['search','add_to_cart','checkout'] },
+ *     spend_cap_cents: 3000, ttl_seconds: 600,
+ *   });
+ *   await atp.authorizeIntent(intent.id);
+ *   const tx = await atp.beginTransaction({
+ *     intent_id: intent.id, amount_cents: 1500,
+ *     idempotency_key: `order-${Date.now()}`,
+ *   });
+ *   await atp.transition(tx.id, 'executing');
+ *   await atp.step(tx.id, { action: 'checkout.confirm', evidence: { order_id: 'X1' } });
+ *   await atp.transition(tx.id, 'executed');
+ *   await atp.transition(tx.id, 'settled');
+ *   const receipt = await atp.issueReceipt(tx.id);
+ *   const ok = await atp.verifyReceipt(receipt.id);
+ *   console.log('verified?', ok.verification.ok);
+ */
+
+class ATPError extends Error {
+  constructor(message, { status, code, body } = {}) {
+    super(message);
+    this.name = 'ATPError';
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+}
+
+class ATPClient {
+  constructor({ baseUrl, token = null, fetchImpl = null } = {}) {
+    if (!baseUrl) throw new Error('ATPClient: baseUrl required');
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.token = token;
+    this._fetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!this._fetch) throw new Error('ATPClient: no fetch available (Node 18+ or supply fetchImpl)');
+  }
+
+  async _req(method, path, { body, headers = {}, auth = true } = {}) {
+    const h = { 'content-type': 'application/json', ...headers };
+    if (auth && this.token) h.authorization = `Bearer ${this.token}`;
+    const res = await this._fetch(this.baseUrl + path, {
+      method,
+      headers: h,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    let json = null;
+    try { json = await res.json(); } catch { /* non-JSON body */ }
+    if (!res.ok || (json && json.ok === false)) {
+      throw new ATPError(json?.message || `HTTP ${res.status}`, {
+        status: res.status, code: json?.error, body: json,
+      });
+    }
+    return json && json.data !== undefined ? json.data : json;
+  }
+
+  // ── Intents ───────────────────────────────────────────────────────────────
+  createIntent(body)            { return this._req('POST', '/api/atp/intents', { body }); }
+  listIntents(params = {})      {
+    const q = new URLSearchParams(params).toString();
+    return this._req('GET', '/api/atp/intents' + (q ? '?' + q : ''));
+  }
+  getIntent(id)                 { return this._req('GET', `/api/atp/intents/${encodeURIComponent(id)}`); }
+  authorizeIntent(id)           { return this._req('POST', `/api/atp/intents/${encodeURIComponent(id)}/authorize`); }
+  revokeIntent(id, reason)      { return this._req('POST', `/api/atp/intents/${encodeURIComponent(id)}/revoke`, { body: { reason } }); }
+
+  // ── Transactions ──────────────────────────────────────────────────────────
+  beginTransaction(body) {
+    const { idempotency_key, ...rest } = body;
+    const headers = idempotency_key ? { 'idempotency-key': idempotency_key } : {};
+    return this._req('POST', '/api/atp/transactions', { body: rest, headers });
+  }
+  getTransaction(id)            { return this._req('GET', `/api/atp/transactions/${encodeURIComponent(id)}`); }
+  step(id, body)                { return this._req('POST', `/api/atp/transactions/${encodeURIComponent(id)}/steps`, { body }); }
+  transition(id, to, extra = {}) { return this._req('POST', `/api/atp/transactions/${encodeURIComponent(id)}/transition`, { body: { to, ...extra } }); }
+  compensate(id, reason)        { return this._req('POST', `/api/atp/transactions/${encodeURIComponent(id)}/compensate`, { body: { reason } }); }
+
+  // ── Receipts ──────────────────────────────────────────────────────────────
+  issueReceipt(txId)            { return this._req('POST', `/api/atp/transactions/${encodeURIComponent(txId)}/receipt`); }
+  getReceipt(receiptId)         { return this._req('GET', `/api/atp/receipts/${encodeURIComponent(receiptId)}`, { auth: false }); }
+  verifyReceipt(input) {
+    const body = typeof input === 'string' ? { id: input } : { receipt: input };
+    return this._req('POST', '/api/atp/receipts/verify', { body, auth: false });
+  }
+}
+
+module.exports = { ATPClient, ATPError };

package/sdk/index.js

@@ -630,6 +630,8 @@ const { WABSafeMode, WABSafeModeError, POLICIES: WAB_SAFE_POLICIES } = require('
 const { WABGovernance, WABGovernanceError } = require('./governance');
 // Zero-Config Adoption — Auto-Discovery fallback for sites without /.well-known/wab.json
 const autoDiscovery = require('./auto-discovery');
+// Agent Transaction Primitive (v3.9.0) — intent → authorization → execution → receipt.
+const { ATPClient, ATPError } = require('./atp');
 
 module.exports = {
   WABAgent,
@@ -646,4 +648,6 @@ module.exports = {
   WABGovernanceError,
   autoDiscovery,
   discover: autoDiscovery.discover,
+  ATPClient,
+  ATPError,
 };

package/server/index.js

@@ -305,6 +305,9 @@ const { wabTrustMiddleware } = require('./middleware/wab-trust');
 app.use(wabTrustMiddleware);
 app.use('/api/ring4', apiLimiter, ring4Router);
 
+// ── Agent Transaction Primitive (ATP) v3.9.0 — intents · transactions · signed receipts ──
+app.use('/api/atp', apiLimiter, require('./routes/transactions'));
+
 // ── WAB Commercial Foundations v3.8.0 (Partners · Trust Graph API · Governance SaaS · Enterprise Mesh) ──
 app.use('/api/partners',         apiLimiter, require('./routes/partners'));
 app.use('/api/keys',             apiLimiter, require('./routes/api-keys'));

package/server/migrations/020_agent_transaction_primitive.sql

@@ -0,0 +1,119 @@
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Migration 020 — Agent Transaction Primitive (ATP) — v3.9.0
+--
+-- Promotes WAB from "discover + execute" to "trust + transaction" by
+-- introducing intents, transactions, steps and signed receipts as
+-- first-class primitives.
+--
+--   * atp_intents       — signed human → agent authorization contracts
+--   * atp_transactions  — executions performed under an intent
+--   * atp_steps         — per-step ledger inside a transaction (retry/comp)
+--   * atp_receipts      — cryptographically signed proofs of outcome
+--   * atp_nonces        — single-use nonces to prevent replay
+--
+-- All state machines enforced by CHECK constraints so the DB itself
+-- refuses illegal transitions.
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- ── 1) Intents (the human → agent contract) ──────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_intents (
+  id              TEXT PRIMARY KEY,                     -- atp_int_<ulid>
+  user_id         TEXT NOT NULL,                        -- principal (the human)
+  site_id         TEXT,                                 -- optional binding
+  agent_id        TEXT,                                 -- optional binding (the delegate)
+  purpose         TEXT NOT NULL,                        -- short human-readable purpose
+  scope           TEXT NOT NULL,                        -- JSON: { actions:[], domains:[], constraints:{} }
+  spend_cap_cents INTEGER NOT NULL DEFAULT 0,           -- 0 = no cap (must be explicit)
+  spend_currency  TEXT NOT NULL DEFAULT 'EUR',
+  spent_cents     INTEGER NOT NULL DEFAULT 0,           -- running total against the cap
+  max_executions  INTEGER NOT NULL DEFAULT 1,           -- how many transactions allowed
+  used_executions INTEGER NOT NULL DEFAULT 0,
+  expires_at      TEXT NOT NULL,                        -- ISO-8601, hard cutoff
+  nonce           TEXT NOT NULL UNIQUE,                 -- prevents replay across intents
+  status          TEXT NOT NULL DEFAULT 'draft'
+                  CHECK (status IN ('draft','authorized','consumed','revoked','expired')),
+  authorized_at   TEXT,
+  authorized_by   TEXT,                                 -- user_id of the approver
+  user_signature  TEXT,                                 -- base64 Ed25519 sig of canonical body
+  revoked_at      TEXT,
+  revoked_reason  TEXT,
+  metadata        TEXT NOT NULL DEFAULT '{}',           -- JSON
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_user   ON atp_intents(user_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_status ON atp_intents(status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_atp_intents_site   ON atp_intents(site_id);
+
+-- ── 2) Transactions (executions under an intent) ─────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_transactions (
+  id               TEXT PRIMARY KEY,                    -- atp_tx_<ulid>
+  intent_id        TEXT NOT NULL,
+  site_id          TEXT,
+  agent_id         TEXT,
+  idempotency_key  TEXT NOT NULL,                       -- caller-supplied, unique per intent
+  status           TEXT NOT NULL DEFAULT 'pending'
+                   CHECK (status IN ('pending','executing','executed','settled','failed','compensated')),
+  amount_cents     INTEGER NOT NULL DEFAULT 0,          -- net effect against intent.spend_cap
+  currency         TEXT NOT NULL DEFAULT 'EUR',
+  summary          TEXT,                                -- one-line outcome summary
+  error            TEXT,                                -- failure reason if status='failed'
+  started_at       TEXT,
+  completed_at     TEXT,
+  settled_at       TEXT,
+  compensated_at   TEXT,
+  metadata         TEXT NOT NULL DEFAULT '{}',
+  created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (intent_id) REFERENCES atp_intents(id) ON DELETE CASCADE,
+  UNIQUE (intent_id, idempotency_key)                   -- the core safety guarantee
+);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_intent ON atp_transactions(intent_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_status ON atp_transactions(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_atp_tx_site   ON atp_transactions(site_id, created_at DESC);
+
+-- ── 3) Steps (granular ledger for retry / compensation) ──────────────────────
+CREATE TABLE IF NOT EXISTS atp_steps (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  transaction_id  TEXT NOT NULL,
+  seq             INTEGER NOT NULL,                     -- step order, 1..N
+  action          TEXT NOT NULL,                        -- WAB action name (e.g. "checkout.confirm")
+  state           TEXT NOT NULL DEFAULT 'pending'
+                  CHECK (state IN ('pending','running','succeeded','failed','skipped','compensated')),
+  before_snapshot TEXT,                                 -- JSON: site state before step (optional)
+  after_snapshot  TEXT,                                 -- JSON: site state after step
+  evidence        TEXT,                                 -- JSON: arbitrary proof (DOM hash, http trace, …)
+  compensation    TEXT,                                 -- JSON: rollback action descriptor
+  attempts        INTEGER NOT NULL DEFAULT 0,
+  last_error      TEXT,
+  started_at      TEXT,
+  ended_at        TEXT,
+  created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (transaction_id) REFERENCES atp_transactions(id) ON DELETE CASCADE,
+  UNIQUE (transaction_id, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_atp_steps_tx ON atp_steps(transaction_id, seq);
+
+-- ── 4) Receipts (signed proofs of outcome) ───────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_receipts (
+  id              TEXT PRIMARY KEY,                     -- atp_rcpt_<ulid>
+  transaction_id  TEXT NOT NULL UNIQUE,
+  site_id         TEXT,                                 -- the signing party (if any)
+  algorithm       TEXT NOT NULL DEFAULT 'ed25519',
+  key_id          TEXT,                                 -- fingerprint of signing key
+  canonical_body  TEXT NOT NULL,                        -- the canonicalized JSON that was signed
+  signature       TEXT NOT NULL,                        -- base64 Ed25519 signature
+  public_key      TEXT,                                 -- embedded pub key for offline verification
+  issued_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (transaction_id) REFERENCES atp_transactions(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_atp_receipts_site ON atp_receipts(site_id, issued_at DESC);
+
+-- ── 5) Nonces (single-use, replay protection) ────────────────────────────────
+CREATE TABLE IF NOT EXISTS atp_nonces (
+  nonce       TEXT PRIMARY KEY,
+  user_id     TEXT NOT NULL,
+  consumed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_atp_nonces_user ON atp_nonces(user_id, consumed_at DESC);

package/server/routes/transactions.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * /api/atp — Agent Transaction Primitive REST surface.
+ *
+ * Authenticated endpoints (Bearer JWT, /me-scoped):
+ *   POST   /intents                      create draft intent
+ *   GET    /intents                      list my intents
+ *   GET    /intents/:id                  fetch one
+ *   POST   /intents/:id/authorize        approve (single-use nonce burned)
+ *   POST   /intents/:id/revoke           revoke
+ *   POST   /transactions                 begin tx under an authorized intent
+ *   GET    /transactions/:id             fetch tx + steps
+ *   POST   /transactions/:id/steps       append step
+ *   POST   /transactions/:id/transition  move state machine
+ *   POST   /transactions/:id/compensate  rollback
+ *   POST   /transactions/:id/receipt     issue signed receipt
+ *
+ * Public endpoints (no auth — these ARE the trust primitive):
+ *   GET    /receipts/:id                 fetch a receipt (id only, no contents leak)
+ *   POST   /receipts/verify              verify any signed receipt JSON offline-style
+ */
+
+const express = require('express');
+const router  = express.Router();
+
+const { authenticateToken } = require('../middleware/auth');
+const transactions = require('../services/transactions');
+const { db } = require('../models/db');
+
+// ─── Tier gating ─────────────────────────────────────────────────────────────
+// ATP is positioned at the open/paid boundary: intent creation and public
+// verification are open (the protocol must spread), while throughput and
+// advanced features are paid.
+const ATP_INTENT_LIMITS = { free: 10, starter: 50, pro: 500, business: 5000, enterprise: 100000 };
+
+function getUserTier(userId) {
+  try {
+    const row = db.prepare(`SELECT tier FROM sites WHERE user_id=? AND active=1 ORDER BY created_at ASC LIMIT 1`).get(userId);
+    return (row && row.tier) || 'free';
+  } catch { return 'free'; }
+}
+
+function checkDailyIntentQuota(userId) {
+  const tier = getUserTier(userId);
+  const cap = ATP_INTENT_LIMITS[tier] ?? ATP_INTENT_LIMITS.free;
+  const row = db.prepare(`
+    SELECT COUNT(*) AS n FROM atp_intents
+     WHERE user_id=? AND datetime(created_at) >= datetime('now','-1 day')
+  `).get(userId);
+  return { tier, used: row.n, cap, ok: row.n < cap };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function send(res, fn) {
+  try {
+    const out = fn();
+    res.json({ ok: true, ...(out && typeof out === 'object' ? { data: out } : {}) });
+  } catch (e) {
+    const code = e.statusCode || 500;
+    res.status(code).json({ ok: false, error: e.code || 'internal_error', message: e.message });
+  }
+}
+
+// ─── Intents ─────────────────────────────────────────────────────────────────
+router.post('/intents', authenticateToken, express.json({ limit: '32kb' }), (req, res) => {
+  const q = checkDailyIntentQuota(req.user.id);
+  if (!q.ok) {
+    return res.status(429).json({
+      ok: false, error: 'quota_exceeded',
+      message: `Daily intent quota reached (${q.used}/${q.cap} on '${q.tier}' tier).`,
+      tier: q.tier, used: q.used, limit: q.cap,
+      upgrade_url: '/premium.html',
+    });
+  }
+  send(res, () => transactions.createIntent({
+    userId: req.user.id,
+    siteId: req.body.site_id || null,
+    agentId: req.body.agent_id || null,
+    purpose: req.body.purpose,
+    scope: req.body.scope,
+    spendCapCents: req.body.spend_cap_cents ?? 0,
+    spendCurrency: req.body.currency || 'EUR',
+    maxExecutions: req.body.max_executions ?? 1,
+    ttlSeconds: req.body.ttl_seconds ?? 3600,
+    metadata: req.body.metadata || {},
+  }));
+});
+
+router.get('/intents', authenticateToken, (req, res) => {
+  send(res, () => transactions.listIntentsForUser(req.user.id, {
+    limit: Math.min(parseInt(req.query.limit, 10) || 50, 200),
+    offset: parseInt(req.query.offset, 10) || 0,
+  }));
+});
+
+router.get('/intents/:id', authenticateToken, (req, res) => {
+  const intent = transactions.getIntent(req.params.id);
+  if (!intent) return res.status(404).json({ ok: false, error: 'not_found' });
+  if (intent.user_id !== req.user.id) return res.status(403).json({ ok: false, error: 'forbidden' });
+  res.json({ ok: true, data: intent });
+});
+
+router.post('/intents/:id/authorize', authenticateToken, (req, res) => {
+  send(res, () => transactions.authorizeIntent(req.params.id, { userId: req.user.id }));
+});
+
+router.post('/intents/:id/revoke', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => transactions.revokeIntent(req.params.id, { userId: req.user.id, reason: req.body.reason }));
+});
+
+// ─── Transactions ────────────────────────────────────────────────────────────
+function loadIntentAuthorized(intentId, userId) {
+  const intent = transactions.getIntent(intentId);
+  if (!intent) { const e = new Error('intent not found'); e.statusCode = 404; e.code = 'not_found'; throw e; }
+  if (intent.user_id !== userId) { const e = new Error('forbidden'); e.statusCode = 403; e.code = 'forbidden'; throw e; }
+  return intent;
+}
+
+function loadTxOwned(txId, userId) {
+  const tx = transactions.getTransaction(txId);
+  if (!tx) { const e = new Error('transaction not found'); e.statusCode = 404; e.code = 'not_found'; throw e; }
+  const intent = transactions.getIntent(tx.intent_id);
+  if (!intent || intent.user_id !== userId) { const e = new Error('forbidden'); e.statusCode = 403; e.code = 'forbidden'; throw e; }
+  return { tx, intent };
+}
+
+router.post('/transactions', authenticateToken, express.json({ limit: '32kb' }), (req, res) => {
+  send(res, () => {
+    const intent = loadIntentAuthorized(req.body.intent_id, req.user.id);
+    const idem = req.headers['idempotency-key'] || req.body.idempotency_key;
+    return transactions.beginTransaction({
+      intentId: intent.id,
+      idempotencyKey: idem,
+      siteId: req.body.site_id,
+      agentId: req.body.agent_id,
+      amountCents: req.body.amount_cents ?? 0,
+      currency: req.body.currency || intent.spend_currency,
+      summary: req.body.summary,
+      metadata: req.body.metadata || {},
+    });
+  });
+});
+
+router.get('/transactions/:id', authenticateToken, (req, res) => {
+  send(res, () => {
+    const { tx } = loadTxOwned(req.params.id, req.user.id);
+    return { ...tx, steps: transactions.listSteps(tx.id) };
+  });
+});
+
+router.post('/transactions/:id/steps', authenticateToken, express.json({ limit: '256kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    return transactions.appendStep(req.params.id, {
+      action: req.body.action,
+      evidence: req.body.evidence,
+      before: req.body.before,
+      after: req.body.after,
+      compensation: req.body.compensation,
+    });
+  });
+});
+
+const VALID_TARGETS = new Set(['executing','executed','settled','failed','compensated']);
+router.post('/transactions/:id/transition', authenticateToken, express.json({ limit: '8kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    const to = req.body.to;
+    if (!VALID_TARGETS.has(to)) {
+      const e = new Error(`invalid target state '${to}'`); e.statusCode = 400; e.code = 'invalid_request'; throw e;
+    }
+    return transactions.transitionTransaction(req.params.id, to, { error: req.body.error, summary: req.body.summary });
+  });
+});
+
+router.post('/transactions/:id/compensate', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => {
+    loadTxOwned(req.params.id, req.user.id);
+    return transactions.compensateTransaction(req.params.id, { reason: req.body.reason });
+  });
+});
+
+// Receipts — issuance requires Pro+ for persistent key binding;
+// free tier gets ephemeral-key receipts (still verifiable, just not pinned).
+router.post('/transactions/:id/receipt', authenticateToken, express.json({ limit: '4kb' }), (req, res) => {
+  send(res, () => {
+    const { tx } = loadTxOwned(req.params.id, req.user.id);
+    return transactions.issueReceipt(tx.id, { embedPublicKey: true });
+  });
+});
+
+// ─── Public verification (the trust primitive) ───────────────────────────────
+const publicReceiptLimiter = (() => {
+  const buckets = new Map();
+  const WINDOW_MS = 60_000;
+  const MAX = 120;
+  return (req, res, next) => {
+    const key = req.ip;
+    const now = Date.now();
+    let b = buckets.get(key);
+    if (!b || (now - b.t) > WINDOW_MS) { b = { t: now, n: 0 }; buckets.set(key, b); }
+    b.n++;
+    if (b.n > MAX) return res.status(429).json({ ok: false, error: 'rate_limited' });
+    next();
+  };
+})();
+
+router.get('/receipts/:id', publicReceiptLimiter, (req, res) => {
+  const r = transactions.getReceipt(req.params.id);
+  if (!r) return res.status(404).json({ ok: false, error: 'not_found' });
+  res.json({ ok: true, data: { id: r.id, transaction_id: r.transaction_id, issued_at: r.issued_at, body: r.body } });
+});
+
+router.post('/receipts/verify', publicReceiptLimiter, express.json({ limit: '256kb' }), (req, res) => {
+  const input = req.body && (req.body.receipt || req.body);
+  let target = input;
+  // Allow lookup by id: { receipt_id: "..." } or { id: "..." } with no signature attached
+  const lookupId = typeof input === 'object' && input
+    ? (input.receipt_id || input.id)
+    : (typeof input === 'string' ? input : null);
+  if (lookupId && (typeof input !== 'object' || !input.signature)) {
+    const stored = transactions.getReceipt(lookupId);
+    if (!stored) return res.status(404).json({ ok: false, error: 'not_found' });
+    target = stored.body;
+  }
+  const r = transactions.verifyReceipt(target);
+  res.json({ ok: r.ok === true, verification: r });
+});
+
+router.get('/health', (req, res) => res.json({ ok: true, service: 'atp', version: '1.0.0' }));
+
+module.exports = router;

package/server/services/transactions.js

@@ -0,0 +1,525 @@
+'use strict';
+
+/**
+ * Agent Transaction Primitive (ATP) — v3.9.0
+ *
+ * Promotes WAB from "discover + execute" to "trust + transaction" by giving
+ * agentic workflows four guarantees as first-class primitives:
+ *
+ *   1. Intent contracts   — what the user authorized, with scope/cap/expiry/nonce.
+ *   2. Idempotent execution — same intent + idempotency_key never runs twice.
+ *   3. Signed receipts    — Ed25519-signed canonical JSON of the outcome.
+ *   4. Compensation       — explicit rollback path for each step.
+ *
+ * The DB-level CHECK constraints and UNIQUE (intent_id, idempotency_key)
+ * make illegal states unrepresentable, not just unlikely.
+ */
+
+const crypto = require('crypto');
+const { db } = require('../models/db');
+const wabCrypto = require('./wab-crypto');
+
+// ── ID helpers ───────────────────────────────────────────────────────────────
+function ulid(prefix) {
+  // 26-char base32 ulid-ish (time-sortable + random). Not RFC-strict but stable.
+  const t = Date.now().toString(36).padStart(8, '0');
+  const r = crypto.randomBytes(10).toString('hex');
+  return `${prefix}_${t}${r}`;
+}
+
+function nowIso() { return new Date().toISOString(); }
+
+// ── Intent lifecycle ─────────────────────────────────────────────────────────
+
+const VALID_SCOPE_ACTIONS = new Set([
+  'read', 'search', 'compare', 'select', 'add_to_cart', 'checkout',
+  'submit_form', 'book', 'cancel', 'message', 'pay'
+]);
+
+function validateScope(scope) {
+  if (!scope || typeof scope !== 'object') throw badRequest('scope must be an object');
+  const { actions, domains } = scope;
+  if (!Array.isArray(actions) || actions.length === 0) throw badRequest('scope.actions must be a non-empty array');
+  for (const a of actions) {
+    if (typeof a !== 'string' || !VALID_SCOPE_ACTIONS.has(a)) {
+      throw badRequest(`scope.actions contains invalid action: ${a}`);
+    }
+  }
+  if (domains !== undefined) {
+    if (!Array.isArray(domains)) throw badRequest('scope.domains must be an array of hostnames');
+    for (const d of domains) {
+      if (typeof d !== 'string' || d.length === 0 || d.length > 253) throw badRequest('scope.domains contains invalid hostname');
+    }
+  }
+}
+
+function badRequest(msg) {
+  const e = new Error(msg); e.statusCode = 400; e.code = 'invalid_request'; return e;
+}
+function notFound(msg) {
+  const e = new Error(msg); e.statusCode = 404; e.code = 'not_found'; return e;
+}
+function conflict(msg, code = 'conflict') {
+  const e = new Error(msg); e.statusCode = 409; e.code = code; return e;
+}
+function forbidden(msg, code = 'forbidden') {
+  const e = new Error(msg); e.statusCode = 403; e.code = code; return e;
+}
+
+/**
+ * Create a draft intent. Status starts at 'draft' and requires explicit
+ * authorize() before any transaction can be executed under it.
+ */
+function createIntent(params) {
+  const {
+    userId, siteId = null, agentId = null,
+    purpose, scope,
+    spendCapCents = 0, spendCurrency = 'EUR',
+    maxExecutions = 1,
+    ttlSeconds = 3600,
+    metadata = {},
+  } = params;
+
+  if (!userId) throw badRequest('userId required');
+  if (!purpose || typeof purpose !== 'string' || purpose.length > 500) {
+    throw badRequest('purpose required (1-500 chars)');
+  }
+  validateScope(scope);
+  if (!Number.isInteger(spendCapCents) || spendCapCents < 0) throw badRequest('spendCapCents must be a non-negative integer');
+  if (!Number.isInteger(maxExecutions) || maxExecutions < 1 || maxExecutions > 1000) {
+    throw badRequest('maxExecutions must be 1..1000');
+  }
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < 30 || ttlSeconds > 7 * 24 * 3600) {
+    throw badRequest('ttlSeconds must be 30..604800');
+  }
+
+  const id = ulid('atp_int');
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000).toISOString();
+
+  db.prepare(`
+    INSERT INTO atp_intents (
+      id, user_id, site_id, agent_id, purpose, scope,
+      spend_cap_cents, spend_currency, max_executions, expires_at, nonce, metadata
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id, userId, siteId, agentId, purpose, JSON.stringify(scope),
+    spendCapCents, spendCurrency, maxExecutions, expiresAt, nonce, JSON.stringify(metadata)
+  );
+
+  return getIntent(id);
+}
+
+function getIntent(id) {
+  const row = db.prepare('SELECT * FROM atp_intents WHERE id = ?').get(id);
+  if (!row) return null;
+  return hydrateIntent(row);
+}
+
+function hydrateIntent(row) {
+  return {
+    ...row,
+    scope: safeJson(row.scope, {}),
+    metadata: safeJson(row.metadata, {}),
+  };
+}
+
+function safeJson(s, fallback) {
+  try { return JSON.parse(s); } catch { return fallback; }
+}
+
+function listIntentsForUser(userId, { limit = 50, offset = 0 } = {}) {
+  const rows = db.prepare(`
+    SELECT * FROM atp_intents WHERE user_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?
+  `).all(userId, limit, offset);
+  return rows.map(hydrateIntent);
+}
+
+/**
+ * Authorize an intent. The user (principal) confirms the contract.
+ * After this call, the intent's nonce is registered in atp_nonces to
+ * make it single-use, and the intent moves to 'authorized'.
+ */
+function authorizeIntent(intentId, { userId }) {
+  const intent = getIntent(intentId);
+  if (!intent) throw notFound('intent not found');
+  if (intent.user_id !== userId) throw forbidden('not your intent');
+  if (intent.status !== 'draft') throw conflict(`cannot authorize intent in status '${intent.status}'`, 'invalid_state');
+  if (new Date(intent.expires_at).getTime() < Date.now()) {
+    db.prepare("UPDATE atp_intents SET status='expired', updated_at=? WHERE id=?").run(nowIso(), intentId);
+    throw conflict('intent expired before authorization', 'expired');
+  }
+
+  const tx = db.transaction(() => {
+    // Reserve the nonce — single use across the whole user.
+    try {
+      db.prepare('INSERT INTO atp_nonces (nonce, user_id) VALUES (?, ?)').run(intent.nonce, userId);
+    } catch (e) {
+      throw conflict('nonce already consumed', 'replay');
+    }
+    db.prepare(`
+      UPDATE atp_intents
+         SET status='authorized', authorized_at=?, authorized_by=?, updated_at=?
+       WHERE id=? AND status='draft'
+    `).run(nowIso(), userId, nowIso(), intentId);
+  });
+  tx();
+
+  return getIntent(intentId);
+}
+
+function revokeIntent(intentId, { userId, reason = 'user_revoked' }) {
+  const intent = getIntent(intentId);
+  if (!intent) throw notFound('intent not found');
+  if (intent.user_id !== userId) throw forbidden('not your intent');
+  if (intent.status === 'consumed' || intent.status === 'revoked' || intent.status === 'expired') {
+    throw conflict(`cannot revoke intent in status '${intent.status}'`, 'invalid_state');
+  }
+  db.prepare(`
+    UPDATE atp_intents
+       SET status='revoked', revoked_at=?, revoked_reason=?, updated_at=?
+     WHERE id=?
+  `).run(nowIso(), String(reason).slice(0, 500), nowIso(), intentId);
+  return getIntent(intentId);
+}
+
+// ── Transaction execution ────────────────────────────────────────────────────
+
+/**
+ * Begin a transaction under an authorized intent. Idempotent on
+ * (intent_id, idempotency_key): replaying the same key returns the
+ * existing transaction instead of creating a new one.
+ */
+function beginTransaction(params) {
+  const {
+    intentId, idempotencyKey, siteId = null, agentId = null,
+    amountCents = 0, currency = 'EUR', summary = null, metadata = {},
+  } = params;
+
+  if (!intentId) throw badRequest('intentId required');
+  if (!idempotencyKey || typeof idempotencyKey !== 'string' || idempotencyKey.length > 200) {
+    throw badRequest('idempotencyKey required (1-200 chars)');
+  }
+  if (!Number.isInteger(amountCents) || amountCents < 0) throw badRequest('amountCents must be a non-negative integer');
+
+  const intent = getIntent(intentId);
+  if (!intent) throw notFound('intent not found');
+  if (intent.status !== 'authorized') throw conflict(`intent not authorized (status='${intent.status}')`, 'invalid_state');
+  if (new Date(intent.expires_at).getTime() < Date.now()) {
+    db.prepare("UPDATE atp_intents SET status='expired', updated_at=? WHERE id=? AND status='authorized'").run(nowIso(), intentId);
+    throw conflict('intent expired', 'expired');
+  }
+  if (intent.used_executions >= intent.max_executions) {
+    throw conflict('intent execution cap reached', 'cap_reached');
+  }
+  if (intent.spend_cap_cents > 0 && (intent.spent_cents + amountCents) > intent.spend_cap_cents) {
+    throw conflict('spend cap would be exceeded', 'spend_cap');
+  }
+  if (intent.spend_currency !== currency) {
+    throw badRequest(`currency mismatch: intent='${intent.spend_currency}', tx='${currency}'`);
+  }
+
+  // Idempotency check — return the existing record if same key was used.
+  const existing = db.prepare(`
+    SELECT id FROM atp_transactions WHERE intent_id=? AND idempotency_key=?
+  `).get(intentId, idempotencyKey);
+  if (existing) return { ...getTransaction(existing.id), _idempotent_replay: true };
+
+  const id = ulid('atp_tx');
+  db.prepare(`
+    INSERT INTO atp_transactions (
+      id, intent_id, site_id, agent_id, idempotency_key,
+      amount_cents, currency, summary, metadata
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, intentId, siteId || intent.site_id, agentId || intent.agent_id, idempotencyKey,
+    amountCents, currency, summary, JSON.stringify(metadata));
+
+  return getTransaction(id);
+}
+
+function getTransaction(id) {
+  const row = db.prepare('SELECT * FROM atp_transactions WHERE id=?').get(id);
+  if (!row) return null;
+  return { ...row, metadata: safeJson(row.metadata, {}) };
+}
+
+function listTransactionsForIntent(intentId) {
+  return db.prepare('SELECT * FROM atp_transactions WHERE intent_id=? ORDER BY created_at ASC').all(intentId)
+    .map(r => ({ ...r, metadata: safeJson(r.metadata, {}) }));
+}
+
+const VALID_TX_TRANSITIONS = {
+  pending:     ['executing', 'failed'],
+  executing:   ['executed', 'failed'],
+  executed:    ['settled', 'compensated', 'failed'],
+  settled:     ['compensated'],
+  failed:      ['compensated'],
+  compensated: [],
+};
+
+function transitionTransaction(txId, toStatus, patch = {}) {
+  const tx = getTransaction(txId);
+  if (!tx) throw notFound('transaction not found');
+  const allowed = VALID_TX_TRANSITIONS[tx.status] || [];
+  if (!allowed.includes(toStatus)) {
+    throw conflict(`illegal transition ${tx.status} → ${toStatus}`, 'invalid_state');
+  }
+
+  const fields = { status: toStatus, updated_at: nowIso() };
+  if (toStatus === 'executing')   fields.started_at     = nowIso();
+  if (toStatus === 'executed')    fields.completed_at   = nowIso();
+  if (toStatus === 'settled')     fields.settled_at     = nowIso();
+  if (toStatus === 'compensated') fields.compensated_at = nowIso();
+  if (patch.error !== undefined)  fields.error          = String(patch.error).slice(0, 2000);
+  if (patch.summary !== undefined) fields.summary       = String(patch.summary).slice(0, 1000);
+
+  const sets = Object.keys(fields).map(k => `${k}=?`).join(', ');
+  const vals = Object.values(fields);
+  db.prepare(`UPDATE atp_transactions SET ${sets} WHERE id=?`).run(...vals, txId);
+
+  // On settled, charge the intent. On compensated, refund.
+  if (toStatus === 'settled') {
+    const updated = db.prepare(`
+      UPDATE atp_intents
+         SET spent_cents = spent_cents + ?,
+             used_executions = used_executions + 1,
+             updated_at = ?
+       WHERE id = ?
+    `).run(tx.amount_cents, nowIso(), tx.intent_id);
+    // Auto-consume intent if cap hit.
+    const intent = getIntent(tx.intent_id);
+    if (intent.used_executions >= intent.max_executions) {
+      db.prepare("UPDATE atp_intents SET status='consumed', updated_at=? WHERE id=? AND status='authorized'")
+        .run(nowIso(), tx.intent_id);
+    }
+  }
+  if (toStatus === 'compensated' && tx.status === 'settled') {
+    db.prepare(`
+      UPDATE atp_intents
+         SET spent_cents = MAX(0, spent_cents - ?),
+             updated_at = ?
+       WHERE id = ?
+    `).run(tx.amount_cents, nowIso(), tx.intent_id);
+  }
+
+  return getTransaction(txId);
+}
+
+// ── Step ledger ──────────────────────────────────────────────────────────────
+
+function appendStep(txId, { action, evidence = null, before = null, after = null, compensation = null }) {
+  if (!action || typeof action !== 'string') throw badRequest('step.action required');
+  const tx = getTransaction(txId);
+  if (!tx) throw notFound('transaction not found');
+
+  const nextSeqRow = db.prepare('SELECT COALESCE(MAX(seq),0)+1 AS s FROM atp_steps WHERE transaction_id=?').get(txId);
+  const seq = nextSeqRow.s;
+  db.prepare(`
+    INSERT INTO atp_steps (transaction_id, seq, action, state, before_snapshot, after_snapshot, evidence, compensation, started_at, ended_at)
+    VALUES (?, ?, ?, 'succeeded', ?, ?, ?, ?, ?, ?)
+  `).run(txId, seq, action,
+    before ? JSON.stringify(before) : null,
+    after  ? JSON.stringify(after)  : null,
+    evidence ? JSON.stringify(evidence) : null,
+    compensation ? JSON.stringify(compensation) : null,
+    nowIso(), nowIso());
+  return getStep(txId, seq);
+}
+
+function getStep(txId, seq) {
+  const row = db.prepare('SELECT * FROM atp_steps WHERE transaction_id=? AND seq=?').get(txId, seq);
+  if (!row) return null;
+  return {
+    ...row,
+    before_snapshot: safeJson(row.before_snapshot, null),
+    after_snapshot:  safeJson(row.after_snapshot, null),
+    evidence:        safeJson(row.evidence, null),
+    compensation:    safeJson(row.compensation, null),
+  };
+}
+
+function listSteps(txId) {
+  return db.prepare('SELECT * FROM atp_steps WHERE transaction_id=? ORDER BY seq ASC').all(txId)
+    .map(r => ({
+      ...r,
+      before_snapshot: safeJson(r.before_snapshot, null),
+      after_snapshot:  safeJson(r.after_snapshot,  null),
+      evidence:        safeJson(r.evidence,        null),
+      compensation:    safeJson(r.compensation,    null),
+    }));
+}
+
+// ── Receipts (signed proof of outcome) ───────────────────────────────────────
+
+/**
+ * Issue a signed receipt for an executed transaction. The receipt body is
+ * canonicalized via wab-crypto and signed Ed25519 with the supplied private
+ * key (typically the site's key from `wab_signing_keys`).
+ *
+ * If no privateKey is supplied, an ephemeral keypair is generated and the
+ * public key is embedded in the receipt so verifiers can still check it.
+ * This keeps the free tier usable while encouraging Pro+ users to bind a
+ * persistent site key for trust continuity.
+ */
+function issueReceipt(txId, { privateKeyB64 = null, embedPublicKey = true } = {}) {
+  const tx = getTransaction(txId);
+  if (!tx) throw notFound('transaction not found');
+  if (!['executed', 'settled', 'failed', 'compensated'].includes(tx.status)) {
+    throw conflict(`cannot issue receipt for status '${tx.status}'`, 'invalid_state');
+  }
+
+  // Refuse double-issuance.
+  const existing = db.prepare('SELECT id FROM atp_receipts WHERE transaction_id=?').get(txId);
+  if (existing) return getReceipt(existing.id);
+
+  const steps = listSteps(txId);
+  const intent = getIntent(tx.intent_id);
+
+  const body = {
+    type: 'atp.receipt.v1',
+    receipt_id: ulid('atp_rcpt'),
+    issued_at: nowIso(),
+    transaction: {
+      id: tx.id,
+      status: tx.status,
+      amount_cents: tx.amount_cents,
+      currency: tx.currency,
+      summary: tx.summary,
+      started_at: tx.started_at,
+      completed_at: tx.completed_at,
+      settled_at: tx.settled_at,
+      compensated_at: tx.compensated_at,
+      error: tx.error,
+    },
+    intent: {
+      id: intent.id,
+      purpose: intent.purpose,
+      scope: intent.scope,
+      spend_cap_cents: intent.spend_cap_cents,
+      currency: intent.spend_currency,
+      authorized_at: intent.authorized_at,
+    },
+    steps: steps.map(s => ({
+      seq: s.seq, action: s.action, state: s.state,
+      attempts: s.attempts,
+      started_at: s.started_at, ended_at: s.ended_at,
+    })),
+    site_id: tx.site_id || null,
+    agent_id: tx.agent_id || null,
+  };
+
+  // Decide signing key.
+  let signKey = privateKeyB64;
+  let publicKeyB64 = null;
+  let keyOrigin = 'supplied';
+  if (!signKey) {
+    const kp = wabCrypto.generateKeyPair();
+    signKey = kp.private_key;
+    publicKeyB64 = kp.public_key;
+    keyOrigin = 'ephemeral';
+  }
+
+  const signed = wabCrypto.signManifest(body, signKey, { embed_public_key: embedPublicKey });
+  // wab-crypto already embedded the pub key into signed.signature.public_key if requested,
+  // but we also want the raw pubkey for column storage:
+  if (!publicKeyB64) publicKeyB64 = signed.signature.public_key || null;
+
+  const canonical = canonicalizeForStorage(signed);
+
+  const id = body.receipt_id;
+  db.prepare(`
+    INSERT INTO atp_receipts (id, transaction_id, site_id, algorithm, key_id, canonical_body, signature, public_key)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, txId, tx.site_id, 'ed25519',
+    signed.signature.key_id, canonical, signed.signature.value, publicKeyB64);
+
+  return { ...getReceipt(id), _key_origin: keyOrigin };
+}
+
+function canonicalizeForStorage(signedManifest) {
+  // Store the FULL signed object as JSON; verifiers recompute canonical from this.
+  return JSON.stringify(signedManifest);
+}
+
+function getReceipt(id) {
+  const row = db.prepare('SELECT * FROM atp_receipts WHERE id=?').get(id);
+  if (!row) return null;
+  let body = null;
+  try { body = JSON.parse(row.canonical_body); } catch { /* keep null */ }
+  return { ...row, body };
+}
+
+function getReceiptByTransaction(txId) {
+  const row = db.prepare('SELECT id FROM atp_receipts WHERE transaction_id=?').get(txId);
+  return row ? getReceipt(row.id) : null;
+}
+
+/**
+ * Verify a receipt. Accepts either:
+ *   - a receipt id (looked up in DB), or
+ *   - a raw signed receipt object (offline verification).
+ * Returns { ok, reason?, key_id?, age_seconds? }.
+ */
+function verifyReceipt(input) {
+  let signed = null;
+  let stored = null;
+  if (typeof input === 'string') {
+    stored = getReceipt(input);
+    if (!stored) return { ok: false, reason: 'receipt not found' };
+    signed = stored.body;
+  } else if (input && typeof input === 'object') {
+    signed = input;
+  } else {
+    return { ok: false, reason: 'invalid input' };
+  }
+  if (!signed || !signed.signature) return { ok: false, reason: 'no signature' };
+
+  const pubB64 = signed.signature.public_key || (stored && stored.public_key) || null;
+  const result = wabCrypto.verifyManifest(signed, pubB64, { max_age_seconds: 365 * 24 * 3600 });
+  return result;
+}
+
+// ── Compensation ─────────────────────────────────────────────────────────────
+
+/**
+ * Compensate a transaction: rolls back its effects. This is the explicit
+ * "undo" primitive that distinguishes WAB from naive scrapers — every
+ * executed step can carry its own compensation descriptor in its evidence.
+ *
+ * This function just transitions the state and unwinds the intent's spend
+ * counter. Actual site-side rollback (e.g. cancelling a booking) is the
+ * caller's responsibility and should be recorded as further steps before
+ * calling this function.
+ */
+function compensateTransaction(txId, { reason = 'compensated' } = {}) {
+  return transitionTransaction(txId, 'compensated', { summary: String(reason).slice(0, 1000) });
+}
+
+// ── Periodic maintenance ─────────────────────────────────────────────────────
+
+function expireOverdueIntents() {
+  const r = db.prepare(`
+    UPDATE atp_intents
+       SET status='expired', updated_at=datetime('now')
+     WHERE status IN ('draft','authorized')
+       AND datetime(expires_at) < datetime('now')
+  `).run();
+  return r.changes;
+}
+
+module.exports = {
+  // intents
+  createIntent, getIntent, listIntentsForUser, authorizeIntent, revokeIntent,
+  // transactions
+  beginTransaction, getTransaction, listTransactionsForIntent, transitionTransaction,
+  // steps
+  appendStep, getStep, listSteps,
+  // receipts
+  issueReceipt, getReceipt, getReceiptByTransaction, verifyReceipt,
+  // compensation
+  compensateTransaction,
+  // maintenance
+  expireOverdueIntents,
+  // re-exports for tests
+  _validateScope: validateScope,
+};