@kedge/testing 0.0.0-stage → 0.10.0

package/src/invariants.ts

@@ -0,0 +1,308 @@
+// The invariant suite (K11): one line in a merchant's tests,
+// `describeKedgeInvariants(() => env.DB)`, never edited. After every test it
+// re-derives what the triggers keep and compares it with what's stored, so a
+// plugin or local migration that bypasses a guarantee fails the build, not a
+// store. Each check is a query returning the offending rows.
+import { allocCostSql, releaseCostSql } from "@kedge/db";
+
+interface Check {
+  name: string;
+  /** Why this matters, shown with the offending rows. */
+  rule: string;
+  sql: string;
+}
+
+export const INVARIANTS: readonly Check[] = [
+  {
+    name: "level_reserved_matches_reservations",
+    rule: "inventory_level.reserved equals its active reservations (D-027)",
+    sql: `SELECT l.inventory_item_id, l.location_id, l.reserved, COALESCE(s.q, 0) AS active
+          FROM inventory_level l LEFT JOIN (SELECT inventory_item_id, location_id, SUM(quantity) AS q
+            FROM inventory_reservation WHERE released_at IS NULL GROUP BY 1, 2) s
+          ON s.inventory_item_id = l.inventory_item_id AND s.location_id = l.location_id
+          WHERE l.reserved != COALESCE(s.q, 0)`,
+  },
+  {
+    name: "facts_backed",
+    rule: "every contribution identity of a committed order is backed exactly as declared (K2)",
+    sql: `SELECT f.id, f.plugin, f.cardinality, f.backed_count FROM contribution_fact f
+          JOIN contribution_check c ON c.order_id = f.order_id WHERE f.backed_count != f.cardinality`,
+  },
+  {
+    name: "totals_match_rows",
+    rule: "an order's stored totals equal its lines, fees, adjustments and tax lines; only exclusive tax adds to the total (P0.3 §3.2)",
+    sql: `SELECT o.id FROM "order" o WHERE
+            o.fee_total != (SELECT COALESCE(sum(amount), 0) FROM order_fee WHERE order_id = o.id)
+         OR o.discount_total != -(SELECT COALESCE(sum(amount), 0) FROM order_adjustment WHERE order_id = o.id)
+         OR o.subtotal != (SELECT COALESCE(sum(unit_price * quantity), 0) FROM order_line WHERE order_id = o.id)
+         OR o.tax_total != (SELECT COALESCE(sum(amount), 0) FROM order_tax_line WHERE order_id = o.id)
+         OR o.total != o.subtotal - o.discount_total + o.shipping_total + o.fee_total
+                       + (SELECT COALESCE(sum(amount), 0) FROM order_tax_line WHERE order_id = o.id AND inclusive = 0)`,
+  },
+  {
+    name: "class_totals",
+    rule: "revenue_total and deposit_total split the total by charge class (K4)",
+    sql: `SELECT o.id FROM "order" o WHERE o.revenue_total IS NULL OR o.deposit_total IS NULL
+         OR o.total != o.revenue_total + o.deposit_total
+         OR o.deposit_total != (SELECT COALESCE(sum(unit_price * quantity), 0) FROM order_line WHERE order_id = o.id AND charge_class = 'deposit')
+                             + (SELECT COALESCE(sum(amount), 0) FROM order_fee WHERE order_id = o.id AND charge_class = 'deposit')
+                             + (SELECT COALESCE(sum(amount), 0) FROM order_tax_line WHERE order_id = o.id AND inclusive = 0 AND charge_class = 'deposit')`,
+  },
+  {
+    name: "discounts_on_discountable_revenue",
+    rule: "discounts are allocated to revenue lines whose kind is discountable only (K4)",
+    sql: `SELECT x.adjustment_id, x.order_line_id FROM order_line_adjustment x JOIN order_line l ON l.id = x.order_line_id
+          WHERE l.discountable = 0 OR l.charge_class != 'revenue'`,
+  },
+  {
+    name: "per_parent_quantities",
+    rule: "a per_parent line's quantity is its parent's times its multiplier (P0.3 §1.3)",
+    sql: `SELECT c.id FROM order_line c JOIN order_line p ON p.id = c.parent_line_id
+          WHERE c.quantity_mode = 'per_parent' AND c.quantity != p.quantity * c.quantity_per_parent
+          UNION ALL
+          SELECT c.id FROM order_line c LEFT JOIN order_line p ON p.id = c.parent_line_id
+          WHERE c.parent_line_id IS NOT NULL AND (p.id IS NULL OR p.order_id != c.order_id OR p.parent_line_id IS NOT NULL)`,
+  },
+  {
+    name: "tax_lines_owed",
+    rule: "every taxable line and fee with a positive rate in its order's context has exactly its tax line, with the formula's amount (P0.3 §3.3)",
+    sql: `SELECT z.id FROM (
+            SELECT l.id, l.taxable, l.charge_class AS cls, o.tax_inclusive AS incl,
+                   CASE l.charge_class WHEN 'revenue' THEN o.tax_rate_revenue_ppm ELSE o.tax_rate_deposit_ppm END AS rate,
+                   l.unit_price * l.quantity + (SELECT COALESCE(sum(amount), 0) FROM order_line_adjustment WHERE order_line_id = l.id) AS base,
+                   t.id AS tid, t.rate_ppm AS trate, t.inclusive AS tincl, t.charge_class AS tcls, t.amount AS tamount
+              FROM order_line l JOIN "order" o ON o.id = l.order_id LEFT JOIN order_tax_line t ON t.order_line_id = l.id
+            UNION ALL
+            SELECT f.id, f.taxable, f.charge_class, o.tax_inclusive,
+                   CASE f.charge_class WHEN 'revenue' THEN o.tax_rate_revenue_ppm ELSE o.tax_rate_deposit_ppm END,
+                   f.amount, t.id, t.rate_ppm, t.inclusive, t.charge_class, t.amount
+              FROM order_fee f JOIN "order" o ON o.id = f.order_id LEFT JOIN order_tax_line t ON t.order_fee_id = f.id) z
+          WHERE CASE WHEN z.taxable = 1 AND z.rate > 0 THEN
+              z.tid IS NULL OR z.trate != z.rate OR z.tincl != z.incl OR z.tcls != z.cls
+              OR z.tamount != (z.base / (1000000 + z.incl * z.rate)) * z.rate
+                              + ((z.base % (1000000 + z.incl * z.rate)) * z.rate * 2 + (1000000 + z.incl * z.rate))
+                                / (2 * (1000000 + z.incl * z.rate))
+            ELSE z.tid IS NOT NULL END`,
+  },
+  {
+    name: "orders_sealed",
+    rule: "every order has its seal and the obligation that forced it (P0.3 §1.7)",
+    sql: `SELECT o.id FROM "order" o WHERE NOT EXISTS (SELECT 1 FROM contribution_check c WHERE c.order_id = o.id)
+            OR NOT EXISTS (SELECT 1 FROM order_seal_due d WHERE d.order_id = o.id)`,
+  },
+  {
+    name: "write_once_covers_columns",
+    rule: "the order's write-once guard names every column but status, so a column a later migration adds is frozen until its slice says otherwise (P0.3 §1.7)",
+    sql: `SELECT c.name FROM pragma_table_info('order') c
+          WHERE c.name != 'status'
+            AND instr(COALESCE((SELECT sql FROM sqlite_master WHERE type = 'trigger' AND name = 'order_write_once'), ''),
+                      'NEW.' || c.name || ' IS NOT OLD.' || c.name) = 0`,
+  },
+  {
+    name: "acceptances_in_order_locale",
+    rule: "an acceptance's revision is in its order's locale, one per policy (P0.3 §5.2)",
+    sql: `SELECT a.id FROM policy_acceptance a JOIN policy_revision r ON r.id = a.revision_id JOIN "order" o ON o.id = a.order_id
+          WHERE r.locale != o.locale
+          UNION ALL
+          SELECT min(a.id) FROM policy_acceptance a JOIN policy_revision r ON r.id = a.revision_id
+          GROUP BY a.order_id, r.policy HAVING count(*) > 1`,
+  },
+  {
+    name: "adjustments_allocated",
+    rule: "each adjustment is fully allocated to lines of its own order, and no line goes below zero (D-029)",
+    sql: `SELECT a.id FROM order_adjustment a
+          WHERE a.amount != (SELECT COALESCE(sum(amount), 0) FROM order_line_adjustment WHERE adjustment_id = a.id)
+          UNION ALL
+          SELECT l.id FROM order_line l
+          WHERE l.unit_price * l.quantity + (SELECT COALESCE(sum(amount), 0) FROM order_line_adjustment WHERE order_line_id = l.id) < 0
+          UNION ALL
+          SELECT x.adjustment_id FROM order_line_adjustment x
+          JOIN order_adjustment a ON a.id = x.adjustment_id JOIN order_line l ON l.id = x.order_line_id
+          WHERE a.order_id != l.order_id`,
+  },
+  {
+    name: "status_matches_history",
+    rule: "an order's status is the last state its transition rows reached (K1)",
+    sql: `SELECT o.id, o.status, t.to_state FROM "order" o
+          JOIN transition t ON t.id = (SELECT max(id) FROM transition WHERE aggregate = 'order' AND aggregate_id = o.id)
+          WHERE t.to_state != o.status`,
+  },
+  {
+    name: "placed_orders_have_history",
+    rule: "an order that left pending_payment has a transition row for it (K1)",
+    sql: `SELECT o.id FROM "order" o WHERE o.status != 'pending_payment'
+          AND NOT EXISTS (SELECT 1 FROM transition t WHERE t.aggregate = 'order' AND t.aggregate_id = o.id)`,
+  },
+  {
+    name: "releases_reach_participants",
+    rule: "every release transition owes one obligation to each participant that had a handler for it (K1)",
+    sql: `SELECT t.uid, p.plugin FROM transition t JOIN plugin_participation p ON p.order_id = t.aggregate_id
+          WHERE t.aggregate = 'order' AND t.to_state IN ('expired', 'canceled')
+            AND (',' || p.releases || ',') LIKE ('%,' || t.to_state || ',%')
+            AND NOT EXISTS (SELECT 1 FROM release_obligation r WHERE r.plugin = p.plugin AND r.transition_uid = t.uid)`,
+  },
+  {
+    name: "participants_installed",
+    rule: "only installed plugins take part in orders (§4.1)",
+    sql: `SELECT p.plugin, p.order_id FROM plugin_participation p
+          WHERE NOT EXISTS (SELECT 1 FROM plugin_state s WHERE s.plugin = p.plugin)`,
+  },
+  {
+    name: "fact_guards_installed",
+    rule: "every table holding plugin facts still has core's generated guards (K2): a rebuilt table loses its triggers",
+    sql: `SELECT DISTINCT f.plugin, f.fact_table FROM contribution_fact f WHERE f.fact_table IS NOT NULL
+            AND (SELECT count(*) FROM sqlite_master m WHERE m.type = 'trigger'
+                   AND m.name IN ('kedge_' || f.plugin || '_' || f.fact_table || '_fact_guard',
+                                  'kedge_' || f.plugin || '_' || f.fact_table || '_fact_backed',
+                                  'kedge_' || f.plugin || '_' || f.fact_table || '_fact_immutable',
+                                  'kedge_' || f.plugin || '_' || f.fact_table || '_fact_no_delete')) != 4`,
+  },
+  // P0.4 (dated-capacity.md §2.2): each derived state against its one rebuild
+  // query, and the recorded facts one-directionally.
+  {
+    name: "bucket_held_matches_holds",
+    rule: "capacity_bucket.held is the sum of active holds covering it, and every active hold's buckets exist (§2.2)",
+    sql: `SELECT b.pool_id, b.bucket, b.held FROM capacity_bucket b
+          WHERE b.held != (SELECT coalesce(sum(h.qty), 0) FROM capacity_hold h WHERE h.pool_id = b.pool_id
+                             AND h.released_at IS NULL AND h.first_bucket <= b.bucket AND h.last_bucket >= b.bucket)
+          UNION ALL
+          SELECT h.pool_id, h.id, NULL FROM capacity_hold h WHERE h.released_at IS NULL
+             AND (SELECT count(*) FROM capacity_bucket b WHERE b.pool_id = h.pool_id AND b.bucket BETWEEN h.first_bucket AND h.last_bucket)
+                 != h.last_bucket - h.first_bucket + 1`,
+  },
+  {
+    name: "capacity_base_canonical",
+    rule: "capacity_base is one row at bucket 0 and one per distinct active change at or after the watermark, each the initial base plus the changes up to it (§2.2)",
+    sql: `WITH expected(pool_id, from_bucket) AS (
+            SELECT id, 0 FROM capacity_pool
+            UNION
+            SELECT c.pool_id, c.from_bucket FROM capacity_base_change c JOIN capacity_pool p ON p.id = c.pool_id
+             WHERE c.state = 'active' AND c.from_bucket >= p.compacted_before),
+          want AS (
+            SELECT e.pool_id, e.from_bucket, p.initial_base + coalesce((SELECT sum(c.delta) FROM capacity_base_change c
+                     WHERE c.pool_id = e.pool_id AND c.state = 'active'
+                       AND c.from_bucket <= max(e.from_bucket, p.compacted_before - 1)), 0) AS base
+              FROM expected e JOIN capacity_pool p ON p.id = e.pool_id)
+          -- Each direction in its own subquery: compound operators run left to right, so a bare
+          -- A EXCEPT B UNION ALL B EXCEPT A would drop A's missing rows again (codex code r14).
+          SELECT * FROM (SELECT pool_id, from_bucket, base FROM want EXCEPT SELECT pool_id, from_bucket, base FROM capacity_base)
+          UNION ALL
+          SELECT * FROM (SELECT pool_id, from_bucket, base FROM capacity_base EXCEPT SELECT pool_id, from_bucket, base FROM want)`,
+  },
+  {
+    name: "pending_expiry_rebuild",
+    rule: "pending_expiry is exactly the (resource, expires_at, order) of pending orders' active reservations and holds (§2.2)",
+    sql: `WITH want(k, r, e, o) AS (
+            SELECT 'item', x.inventory_item_id, o.expires_at, o.id FROM inventory_reservation x JOIN "order" o ON o.id = x.order_id
+             WHERE o.status = 'pending_payment' AND x.released_at IS NULL
+            UNION
+            SELECT 'pool', h.pool_id, o.expires_at, o.id FROM capacity_hold h JOIN "order" o ON o.id = h.order_id
+             WHERE o.status = 'pending_payment' AND h.released_at IS NULL)
+          SELECT * FROM (SELECT * FROM want EXCEPT SELECT resource_kind, resource_id, expires_at, order_id FROM pending_expiry)
+          UNION ALL
+          SELECT * FROM (SELECT resource_kind, resource_id, expires_at, order_id FROM pending_expiry EXCEPT SELECT * FROM want)`,
+  },
+  {
+    name: "retirement_queue_rebuild",
+    rule: "hold_retirement_due is exactly the active holds that are orderless or of completed orders (§2.2)",
+    sql: `WITH want(hold_id, pool_id, retire_after) AS (
+            SELECT h.id, h.pool_id, h.retire_after FROM capacity_hold h LEFT JOIN "order" o ON o.id = h.order_id
+             WHERE h.released_at IS NULL AND (h.order_id IS NULL OR o.status = 'completed'))
+          SELECT * FROM (SELECT * FROM want EXCEPT SELECT hold_id, pool_id, retire_after FROM hold_retirement_due)
+          UNION ALL
+          SELECT * FROM (SELECT hold_id, pool_id, retire_after FROM hold_retirement_due EXCEPT SELECT * FROM want)`,
+  },
+  {
+    name: "reopenable_pools_rebuild",
+    rule: "reopenable_hold_pool is exactly the pools of released holds on expired, reopenable orders (§2.2)",
+    sql: `WITH want(pool_id, order_id) AS (
+            SELECT DISTINCT h.pool_id, o.id FROM capacity_hold h JOIN "order" o ON o.id = h.order_id
+             WHERE o.status = 'expired' AND o.reopenable = 1 AND h.released_at IS NOT NULL)
+          SELECT * FROM (SELECT * FROM want EXCEPT SELECT pool_id, order_id FROM reopenable_hold_pool)
+          UNION ALL
+          SELECT * FROM (SELECT pool_id, order_id FROM reopenable_hold_pool EXCEPT SELECT * FROM want)`,
+  },
+  {
+    name: "order_costs_rebuild",
+    rule: "an order's release_cost and current_alloc_cost equal their rebuild queries (p0.4 §2.2)",
+    sql: `SELECT o.id, o.release_cost, o.current_alloc_cost FROM "order" o
+          WHERE o.release_cost != ${releaseCostSql("o.id")} OR o.current_alloc_cost != ${allocCostSql("o.id")}`,
+  },
+  {
+    name: "allocations_within_counts",
+    rule: "an order's active allocations never exceed what it committed: reservation_count and hold_count (§2.2)",
+    sql: `SELECT o.id FROM "order" o
+          WHERE (SELECT count(*) FROM inventory_reservation x WHERE x.order_id = o.id AND x.released_at IS NULL) > o.reservation_count
+             OR (SELECT count(*) FROM capacity_hold h WHERE h.order_id = o.id AND h.released_at IS NULL) > o.hold_count`,
+  },
+  {
+    name: "order_history_marked",
+    rule: "no live reservation, hold or component names an item whose order_history is 0 (§2)",
+    sql: `SELECT x.inventory_item_id FROM inventory_reservation x JOIN inventory_item i ON i.id = x.inventory_item_id
+           WHERE x.released_at IS NULL AND i.order_history = 0
+          UNION ALL
+          SELECT c.inventory_item_id FROM order_line_component c JOIN inventory_item i ON i.id = c.inventory_item_id
+           WHERE i.order_history = 0
+          UNION ALL
+          SELECT p.inventory_item_id FROM capacity_hold h JOIN capacity_pool p ON p.id = h.pool_id
+            JOIN inventory_item i ON i.id = p.inventory_item_id WHERE h.order_id IS NOT NULL AND i.order_history = 0`,
+  },
+  {
+    name: "allocations_match_tracking",
+    rule: "live reservations are on counted items and live order holds on dated items' pools (§2.1)",
+    sql: `SELECT x.id FROM inventory_reservation x JOIN inventory_item i ON i.id = x.inventory_item_id
+           WHERE x.released_at IS NULL AND i.tracking != 'count'
+          UNION ALL
+          SELECT h.id FROM capacity_hold h JOIN capacity_pool p ON p.id = h.pool_id JOIN inventory_item i ON i.id = p.inventory_item_id
+           WHERE h.released_at IS NULL AND p.kind = 'item' AND i.tracking != 'dated'`,
+  },
+  {
+    name: "money_cites_own_contributor",
+    rule: "fees and adjustments cite an identity of their own order and plugin, which participates (K2)",
+    sql: `SELECT m.id FROM (SELECT id, order_id, plugin FROM order_fee UNION ALL SELECT id, order_id, plugin FROM order_adjustment) m
+          WHERE NOT EXISTS (SELECT 1 FROM plugin_participation p WHERE p.order_id = m.order_id AND p.plugin = m.plugin)`,
+  },
+];
+
+export interface Violation {
+  invariant: string;
+  rule: string;
+  rows: unknown[];
+}
+
+/** Runs every invariant query in one batch; returns the ones with offending rows. */
+export async function checkInvariants(db: D1Database): Promise<Violation[]> {
+  const results = await db.batch(INVARIANTS.map((c) => db.prepare(c.sql)));
+  const violations = INVARIANTS.flatMap((c, i) => {
+    const rows = results[i]?.results ?? [];
+    return rows.length > 0 ? [{ invariant: c.name, rule: c.rule, rows }] : [];
+  });
+  // Counters agreeing isn't proof: each backed identity's fact row must exist
+  // in its table (a rebuilt table can lose rows while backed_count stays 1).
+  const tables = (
+    await db
+      .prepare("SELECT DISTINCT fact_table FROM contribution_fact WHERE fact_table IS NOT NULL")
+      .all<{ fact_table: string }>()
+  ).results.map((r) => r.fact_table);
+  for (const table of tables) {
+    if (!/^plg_[a-z0-9_]+$/.test(table)) {
+      violations.push({ invariant: "facts_exist", rule: "fact tables are plugin tables", rows: [{ table }] });
+      continue;
+    }
+    const missing = await db
+      .prepare(
+        `SELECT f.id FROM contribution_fact f WHERE f.fact_table = ? AND f.backed_count > 0
+           AND NOT EXISTS (SELECT 1 FROM "${table}" t WHERE t.contribution_fact_id = f.id)`,
+      )
+      .bind(table)
+      .all()
+      .catch((e: unknown) => ({ results: [{ error: String((e as Error)?.message ?? e) }] }));
+    if (missing.results.length > 0)
+      violations.push({
+        invariant: "facts_exist",
+        rule: "every backed contribution identity still has its fact row (K2)",
+        rows: missing.results,
+      });
+  }
+  return violations;
+}

package/src/ports.ts

@@ -0,0 +1,207 @@
+// Test doubles for P0.6a's journal tests (docs/proposals/p0.6a-relay-timers-effects.md
+// §4.2, §10): a provider that deduplicates by key over a horizon, captures
+// every call, and can lose a response, fail, stall, refuse as not executed or
+// switch accounts. `executions` counts what the provider really did, so a test
+// can tell one email from two whatever the journal recorded.
+
+import {
+  definePort,
+  type EffectOperation,
+  KedgeProviderError,
+  type Observation,
+  type OperationCall,
+  type PortDefinition,
+} from "@kedge/core";
+
+const HOUR = 3_600_000;
+
+export interface CapturedCall {
+  readonly operation: string;
+  readonly providerKey: string;
+  readonly input: Readonly<Record<string, unknown>>;
+  readonly expiresAt: number | null;
+  readonly at: number;
+}
+
+/** One fault, applied to the next matching call and then spent. */
+export type Fault =
+  /** The provider executes, then the response is lost (a network error). */
+  | "lose_response"
+  /** The request never arrives (a network error before sending). */
+  | "fail_before_send"
+  /** The provider refuses without executing, and says so. */
+  | "not_executed"
+  /** The provider refuses for good. */
+  | "final"
+  /** The call waits until `release()`, then behaves normally. */
+  | "stall";
+
+/** A simulated provider. Its clock is its own: a key is remembered for the horizon by it. */
+export class ProviderDouble {
+  readonly calls: CapturedCall[] = [];
+  /** What the provider executed, by provider key: the count a test checks. */
+  readonly executions = new Map<string, number>();
+  /** The provider's dedupe store. */
+  readonly remembered = new Map<string, { result: Record<string, unknown>; at: number }>();
+  /** What an observation reports for a key, overriding what the provider knows. */
+  readonly observed = new Map<string, Observation | { kind: "awaiting" }>();
+  readonly clock = { now: 1_000_000 };
+  /** The account the port reports; change it to switch accounts. */
+  account = "acct_test_1";
+  /** Whether the provider can be observed at all. */
+  observable = true;
+  /** An observation that never answers and ignores its signal, as a stuck SDK call would. */
+  observeHangs = false;
+  /** A provider that can confirm absence: observing a key it never executed answers `not_executed`, not `unknown`. */
+  confirmsAbsence = false;
+  port!: PortDefinition;
+  private readonly faults: { f: Fault; operation: string | undefined }[] = [];
+  private releaseStall: (() => void) | null = null;
+
+  constructor(
+    readonly name: string,
+    readonly horizonMs: number,
+  ) {}
+
+  fault(f: Fault, operation?: string): void {
+    this.faults.push({ f, operation });
+  }
+  release(): void {
+    this.releaseStall?.();
+  }
+  /** How many times the provider really executed anything. */
+  get executed(): number {
+    return [...this.executions.values()].reduce((a, b) => a + b, 0);
+  }
+
+  private take(op: string): Fault | null {
+    const i = this.faults.findIndex((x) => x.operation === undefined || x.operation === op);
+    return i < 0 ? null : (this.faults.splice(i, 1)[0]?.f ?? null);
+  }
+
+  async run(
+    op: string,
+    call: OperationCall,
+    input: Readonly<Record<string, unknown>>,
+    make: () => Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    this.calls.push({
+      operation: op,
+      providerKey: call.providerKey,
+      input,
+      expiresAt: call.expiresAt,
+      at: this.clock.now,
+    });
+    let f = this.take(op);
+    if (f === "stall") {
+      await new Promise<void>((resolve) => {
+        this.releaseStall = resolve;
+      });
+      f = this.take(op);
+    }
+    if (f === "fail_before_send") throw new Error("network: connection reset before the request was sent");
+    if (f === "not_executed") throw new KedgeProviderError("rejected", { notExecuted: true });
+    if (f === "final") throw new KedgeProviderError("declined", { final: true });
+    // A fenced request past its own expiry is refused by the provider (§4.2).
+    if (call.expiresAt !== null && this.clock.now > call.expiresAt)
+      throw new KedgeProviderError("expired", { notExecuted: true });
+    const known = this.remembered.get(call.providerKey);
+    let result: Record<string, unknown>;
+    if (known && this.clock.now - known.at < this.horizonMs) result = known.result;
+    else {
+      result = make();
+      this.remembered.set(call.providerKey, { result, at: this.clock.now });
+      this.executions.set(call.providerKey, (this.executions.get(call.providerKey) ?? 0) + 1);
+    }
+    if (f === "lose_response") throw new Error("network: response lost");
+    return result;
+  }
+
+  async observe(providerKey: string): Promise<Observation> {
+    if (this.observeHangs) await new Promise(() => {});
+    const forced = this.observed.get(providerKey);
+    if (forced) return forced.kind === "awaiting" ? { kind: "unknown" } : forced;
+    if (!this.observable) return { kind: "unknown" };
+    const seen = this.remembered.get(providerKey);
+    if (seen) return { kind: "succeeded", result: seen.result };
+    return this.confirmsAbsence ? { kind: "not_executed" } : { kind: "unknown" };
+  }
+}
+
+let seq = 0;
+const next = (p: string) => `${p}_${++seq}`;
+/** Every code the doubles throw: a final refusal, a verified non-execution, a fenced request past its expiry. */
+const FAILURES = ["declined", "rejected", "expired"];
+
+function finish(d: ProviderDouble, deliveryClass: "effect" | "notification", operations: PortDefinition["operations"]) {
+  d.port = definePort({
+    name: d.name,
+    deliveryClass,
+    // In-memory doubles: synthetic, so only a test or preview Worker may run them (p0.6b §4.2).
+    synthetic: true,
+    credentialMode: async () => "test",
+    dedupe: { enforced: true, scope: "account", horizonMs: d.horizonMs },
+    binding: async () => ({ provider: d.name, account: d.account, installation: null, scope: "default" }),
+    operations,
+  });
+  return d;
+}
+
+/** An email provider: a 24-hour key horizon, `window` resends, observable by key (Resend-like). */
+export function testEmailPort(
+  opts: { name?: string; horizonMs?: number; deliveryClass?: "effect" | "notification" } = {},
+): ProviderDouble {
+  const d = new ProviderDouble(opts.name ?? "test-email", opts.horizonMs ?? 24 * HOUR);
+  const send: EffectOperation = {
+    kind: "effect",
+    version: 1,
+    category: "message",
+    resend: { policy: "window", delayMs: 30_000 },
+    presentation: ["placed_at", "order_number"],
+    erasure: "optional",
+    classified: [{ field: "to", subject: "customer", scope: "email" }],
+    result: { message_id: "id" },
+    failures: FAILURES,
+    call: (input, call) => d.run("send", call, input, () => ({ message_id: next("msg") })),
+    observe: ({ providerKey }) => d.observe(providerKey),
+  };
+  return finish(d, opts.deliveryClass ?? "effect", { send });
+}
+
+/**
+ * A payment provider: a non-charging `initiate` under `window`, a `refund`
+ * under `never`, and an observation that can say awaiting, captured, not
+ * executed or nothing (Stripe-like: keys may be pruned after 24 hours).
+ */
+export function testPaymentPort(opts: { name?: string; horizonMs?: number } = {}): ProviderDouble {
+  const d = new ProviderDouble(opts.name ?? "test-payment", opts.horizonMs ?? 24 * HOUR);
+  const initiate: EffectOperation = {
+    kind: "effect",
+    version: 1,
+    category: "other",
+    resend: { policy: "window", delayMs: 30_000 },
+    erasure: "operational",
+    result: { intent_id: "id", status: "status" },
+    failures: FAILURES,
+    call: (input, call) => d.run("initiate", call, input, () => ({ intent_id: next("pi"), status: "requires_action" })),
+    observe: ({ providerKey }) => d.observe(providerKey),
+  };
+  const refund: EffectOperation = {
+    kind: "effect",
+    version: 1,
+    money: true,
+    category: "refund",
+    resend: { policy: "never" },
+    erasure: "required",
+    result: { refund_id: "id", amount: "amount" },
+    failures: FAILURES,
+    call: (input, call) =>
+      d.run("refund", call, input, () => ({ refund_id: next("re"), amount: Number(input.amount ?? 0) })),
+    observe: ({ providerKey }) => d.observe(providerKey),
+  };
+  return finish(d, "effect", {
+    initiate,
+    refund,
+    status: { kind: "observation", call: async (input) => d.observe(String(input.key)) },
+  });
+}

package/src/requests.ts

@@ -0,0 +1,68 @@
+// Counts D1 requests, the resource D1 runs out of (D-032). A batch is one
+// request; so is each run/all/first/raw of a prepared statement. Scenarios
+// assert exact counts, so a plugin that adds a request to the checkout path
+// fails a test instead of a flash sale (K2).
+
+export interface RequestCounter {
+  /** Use this binding instead of the real one. */
+  readonly db: D1Database;
+  count(): number;
+  reset(): void;
+  /** Requests made while `fn` ran. */
+  during<T>(fn: () => Promise<T>): Promise<{ value: T; requests: number }>;
+}
+
+export function countRequests(real: D1Database): RequestCounter {
+  let n = 0;
+  // D1 needs its own statement objects inside a batch, so every wrapper maps back to one.
+  const realOf = new WeakMap<object, D1PreparedStatement>();
+  const wrapStatement = (s: D1PreparedStatement): D1PreparedStatement => {
+    const wrapped = new Proxy(s, {
+      get(target, prop, receiver) {
+        if (prop === "bind") return (...args: unknown[]) => wrapStatement(target.bind(...args));
+        if (prop === "run" || prop === "all" || prop === "first" || prop === "raw") {
+          const fn = Reflect.get(target, prop, receiver) as (...a: unknown[]) => unknown;
+          return (...args: unknown[]) => {
+            n++;
+            return fn.apply(target, args);
+          };
+        }
+        const v = Reflect.get(target, prop, receiver);
+        return typeof v === "function" ? v.bind(target) : v;
+      },
+    });
+    realOf.set(wrapped, s);
+    return wrapped;
+  };
+  const db = new Proxy(real, {
+    get(target, prop, receiver) {
+      if (prop === "prepare") return (query: string) => wrapStatement(target.prepare(query));
+      if (prop === "batch") {
+        return (stmts: D1PreparedStatement[]) => {
+          n++;
+          return target.batch(stmts.map((s) => realOf.get(s) ?? s));
+        };
+      }
+      if (prop === "exec") {
+        return (q: string) => {
+          n++;
+          return target.exec(q);
+        };
+      }
+      const v = Reflect.get(target, prop, receiver);
+      return typeof v === "function" ? v.bind(target) : v;
+    },
+  });
+  return {
+    db,
+    count: () => n,
+    reset: () => {
+      n = 0;
+    },
+    async during(fn) {
+      const before = n;
+      const value = await fn();
+      return { value, requests: n - before };
+    },
+  };
+}