sparta_worlds 0.6.0

package/server/dist/twin/router.js

@@ -0,0 +1,279 @@
+import { canonicalHash } from "../core/canonical.js";
+import { apiError, authenticationError, idempotencyError, StripeError, toZendeskShape, UNSUPPORTED_PARAMETER_CODE, ZendeskError, } from "../core/errors.js";
+import { sleep } from "../core/nondeterministic.js";
+import { authExpiryThreshold, evaluateRequestRules } from "../scenario/engine.js";
+import { parseFormBody } from "./params.js";
+import { chargeRoutes } from "./resources/charges.js";
+import { customerRoutes } from "./resources/customers.js";
+import { eventRoutes } from "./resources/events.js";
+import { invoiceRoutes } from "./resources/invoices.js";
+import { paymentIntentRoutes } from "./resources/payment_intents.js";
+import { productRoutes } from "./resources/products.js";
+import { refundRoutes } from "./resources/refunds.js";
+import { surfaceOf } from "./resources/shared.js";
+import { processRenewals, RenewalFailed, subscriptionRoutes } from "./resources/subscriptions.js";
+import { ticketRoutes } from "./resources/tickets.js";
+import { refusedParameterError } from "./unsupported.js";
+export const ALL_TWIN_ROUTES = [
+    ...customerRoutes,
+    ...productRoutes,
+    ...invoiceRoutes,
+    ...paymentIntentRoutes,
+    ...chargeRoutes,
+    ...refundRoutes,
+    ...subscriptionRoutes,
+    ...eventRoutes,
+    ...ticketRoutes,
+];
+const COMPILED = ALL_TWIN_ROUTES.map((r) => ({
+    ...r,
+    segments: r.pattern.split("/").filter(Boolean),
+}));
+function matchRoute(method, path) {
+    if (path.length > 1 && path.endsWith("/"))
+        return undefined;
+    const segs = path.split("/").filter(Boolean);
+    for (const route of COMPILED) {
+        if (route.method !== method)
+            continue;
+        if (route.segments.length !== segs.length)
+            continue;
+        const pathParams = {};
+        let ok = true;
+        for (let i = 0; i < segs.length; i++) {
+            const pat = route.segments[i];
+            if (pat.startsWith(":"))
+                pathParams[pat.slice(1)] = decodeURIComponent(segs[i]);
+            else if (pat !== segs[i]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok)
+            return { route, pathParams };
+    }
+    return undefined;
+}
+function extractApiKey(req) {
+    const header = req.headers.authorization;
+    if (header) {
+        if (header.startsWith("Bearer "))
+            return header.slice(7).trim();
+        if (header.startsWith("Basic ")) {
+            try {
+                const decoded = Buffer.from(header.slice(6).trim(), "base64").toString("utf8");
+                return decoded.split(":")[0] || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+function sendError(reply, err, surface = "stripe") {
+    const rendered = surface === "zendesk" && err instanceof StripeError ? toZendeskShape(err) : err;
+    let response = reply.status(rendered.status);
+    if (rendered instanceof StripeError)
+        for (const [name, value] of Object.entries(rendered.headers))
+            response = response.header(name, value);
+    void response.header("content-type", "application/json").send(JSON.stringify(rendered.toJSON()));
+}
+function resetInFlight() {
+    return apiError("worlds: this world was reset or destroyed while the request was in flight, so the request was not executed and no trace of it remains. Retry it against the world as it is now, if it still exists.");
+}
+const refusalsLogged = new Set();
+function warnRefusedWorldOnce(req, worldId, reason) {
+    if (refusalsLogged.has(worldId))
+        return;
+    refusalsLogged.add(worldId);
+    req.log.warn({ world_id: worldId }, `twin API key refused: ${reason}`);
+}
+export function shouldStoreIdempotency(input) {
+    return input.method === "POST" && input.key !== null && input.phase !== "validation";
+}
+export function registerTwinApi(app, manager, dispatcher) {
+    const serve = async (req, reply, ctx) => {
+        const { apiKey, method, path, surface } = ctx;
+        const auth = manager.authenticate(apiKey);
+        if (!auth || auth.status === "unreadable") {
+            if (auth)
+                warnRefusedWorldOnce(req, auth.worldId, auth.reason);
+            return sendError(reply, authenticationError(`Invalid API Key provided: ${redactKey(apiKey)}`), surface);
+        }
+        if (auth.status === "expired") {
+            return sendError(reply, new StripeError(401, {
+                type: "invalid_request_error",
+                code: "api_key_expired",
+                message: `Expired API Key provided: ${redactKey(apiKey)}`,
+            }), surface);
+        }
+        const world = auth.world;
+        const generation = world.generation;
+        const uses = world.bumpApiKeyUse(apiKey);
+        const expiry = authExpiryThreshold(world);
+        if (expiry !== undefined && uses > expiry) {
+            world.logRequest({ method, path, status: 401, injected: true });
+            return sendError(reply, new StripeError(401, {
+                type: "invalid_request_error",
+                code: "api_key_expired",
+                message: `Expired API Key provided: ${redactKey(apiKey)}`,
+            }), surface);
+        }
+        const outcome = evaluateRequestRules(world, method, path);
+        if (outcome.latencyMs > 0) {
+            await sleep(outcome.latencyMs);
+            if (world.generation !== generation)
+                return sendError(reply, resetInFlight(), surface);
+        }
+        if (outcome.inject) {
+            world.logRequest({ method, path, status: outcome.inject.status, injected: true });
+            return sendError(reply, outcome.inject, surface);
+        }
+        const match = matchRoute(method, path);
+        if (!match) {
+            world.logRequest({ method, path, status: 404, matched: false });
+            return sendError(reply, new StripeError(404, {
+                type: "invalid_request_error",
+                message: `Unrecognized request URL (${method}: ${path}). If you are trying to list objects, remove the trailing slash. The twin implements a documented subset of the API — see docs/scope.md.`,
+            }), surface);
+        }
+        const params = { ...req.query };
+        if (typeof req.body === "string" && req.body.length > 0) {
+            Object.assign(params, parseFormBody(req.body));
+        }
+        else if (req.body && typeof req.body === "object") {
+            Object.assign(params, req.body);
+        }
+        for (const key of Object.keys(params)) {
+            if (key.includes("[")) {
+                const re = parseFormBody(`${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`);
+                delete params[key];
+                deepMerge(params, re);
+            }
+        }
+        const refusal = refusedParameterError(method, match.route.pattern, params);
+        if (refusal) {
+            world.logRequest({ method, path, status: 400, unsupported: refusal.body.param });
+            return sendError(reply, refusal, surface);
+        }
+        const idempotencyKey = req.headers["idempotency-key"] || null;
+        let refused = false;
+        await manager.withLock(world.id, async () => {
+            if (world.generation !== generation) {
+                refused = true;
+                return sendError(reply, resetInFlight(), surface);
+            }
+            if (world.clockMode === "auto") {
+                try {
+                    world.db.transaction(() => {
+                        world.advanceClock(world.autoTickSeconds);
+                        processRenewals(world);
+                    });
+                }
+                catch (err) {
+                    req.log.error(err);
+                    const message = err instanceof RenewalFailed
+                        ? err.message
+                        : `worlds: the auto clock tick failed (${err instanceof Error ? err.message : String(err)}); the clock did not move and nothing was written.`;
+                    world.logRequest({ method, path, status: 500 });
+                    return sendError(reply, apiError(message), surface);
+                }
+            }
+            const paramsHash = canonicalHash({ path, params });
+            if (method === "POST" && idempotencyKey !== null) {
+                const prior = world.getIdempotency(idempotencyKey);
+                if (prior) {
+                    if (prior.params_hash !== paramsHash || prior.path !== path) {
+                        world.logRequest({ method, path, status: 400 });
+                        return sendError(reply, idempotencyError(`Keys for idempotent requests can only be used with the same parameters they were first used with. Try using a key other than '${idempotencyKey}' if you meant to execute a different request.`), surface);
+                    }
+                    world.logRequest({ method, path, status: prior.status });
+                    void reply
+                        .status(prior.status)
+                        .header("content-type", "application/json")
+                        .header("idempotent-replayed", "true")
+                        .send(prior.body);
+                    return;
+                }
+            }
+            let status = 200;
+            let bodyJson;
+            let phase = null;
+            let unsupported;
+            try {
+                const result = world.db.transaction(() => match.route.handler({ world, params, pathParams: match.pathParams, idempotencyKey, path }));
+                status = result.status ?? 200;
+                bodyJson = JSON.stringify(result.body);
+            }
+            catch (err) {
+                const known = err instanceof StripeError || err instanceof ZendeskError;
+                if (!known)
+                    req.log.error(err);
+                let rendered = known
+                    ? err
+                    : apiError(err instanceof Error ? err.message : String(err));
+                phase = rendered instanceof StripeError ? rendered.phase : "execution";
+                if (rendered instanceof StripeError && rendered.body.code === UNSUPPORTED_PARAMETER_CODE)
+                    unsupported = rendered.body.param;
+                if (surface === "zendesk" && rendered instanceof StripeError)
+                    rendered = toZendeskShape(rendered);
+                status = rendered.status;
+                bodyJson = JSON.stringify(rendered.toJSON());
+            }
+            if (idempotencyKey !== null && shouldStoreIdempotency({ method, key: idempotencyKey, phase })) {
+                world.putIdempotency(idempotencyKey, method, path, paramsHash, status, bodyJson);
+            }
+            world.logRequest({ method, path, status, unsupported });
+            void reply.status(status).header("content-type", "application/json").send(bodyJson);
+        });
+        if (!refused)
+            dispatcher.drainSoon(world);
+    };
+    const handle = async (req, reply) => {
+        const path = (req.raw.url ?? "/").split("?")[0];
+        const method = req.method.toUpperCase();
+        const surface = surfaceOf(path);
+        const apiKey = extractApiKey(req);
+        if (!apiKey) {
+            return sendError(reply, authenticationError("You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY')."), surface);
+        }
+        const worldId = manager.worldIdOf(apiKey);
+        if (worldId === undefined) {
+            return sendError(reply, authenticationError(`Invalid API Key provided: ${redactKey(apiKey)}`), surface);
+        }
+        await manager.enter(worldId);
+        try {
+            await serve(req, reply, { apiKey, method, path, surface });
+        }
+        finally {
+            manager.leave(worldId);
+        }
+    };
+    for (const method of ["GET", "POST", "DELETE", "PUT", "PATCH"]) {
+        app.route({ method, url: "/v1/*", handler: handle });
+        app.route({ method, url: "/v1", handler: handle });
+        app.route({ method, url: "/api/v2/*", handler: handle });
+        app.route({ method, url: "/api/v2", handler: handle });
+    }
+}
+function redactKey(key) {
+    if (key.length <= 12)
+        return key;
+    return `${key.slice(0, 12)}********`;
+}
+function deepMerge(target, source) {
+    for (const [k, v] of Object.entries(source)) {
+        if (v &&
+            typeof v === "object" &&
+            !Array.isArray(v) &&
+            target[k] &&
+            typeof target[k] === "object" &&
+            !Array.isArray(target[k])) {
+            deepMerge(target[k], v);
+        }
+        else {
+            target[k] = v;
+        }
+    }
+}

package/server/dist/twin/unsupported.js

@@ -0,0 +1,212 @@
+import { unsupportedParameter } from "../core/errors.js";
+import { parseKeyPath } from "./params.js";
+const OFF = ["false"];
+const CAPTURE = {
+    param: "capture_method",
+    allowed: ["automatic", "automatic_async"],
+    why: "a manual capture holds funds without moving them; the twin captures on confirm",
+};
+const CAPTURE_OPTIONS = {
+    param: "payment_method_options[card][capture_method]",
+    why: "the card-level capture_method overrides the top-level one: manual holds the funds instead of capturing them",
+};
+const CONNECT = [
+    { param: "application_fee_amount", why: "a Connect fee splits the charge" },
+    { param: "transfer_data", why: "a Connect transfer moves money to another account" },
+    { param: "on_behalf_of", why: "Connect settlement on another account" },
+];
+const SUBSCRIPTION_CONNECT = [
+    { param: "application_fee_percent", why: "a Connect fee splits every invoice's charge" },
+    { param: "transfer_data", why: "a Connect transfer moves every invoice's charge to another account" },
+    { param: "on_behalf_of", why: "Connect settlement on another account" },
+];
+const BILLING_THRESHOLDS = {
+    param: "billing_thresholds",
+    why: "bills when the amount crosses a threshold, not at the period boundary",
+};
+const DISCOUNTS = [
+    { param: "coupon", why: "a discount changes every invoice total" },
+    { param: "discounts", why: "a discount changes every invoice total" },
+    { param: "promotion_code", why: "a discount changes every invoice total" },
+];
+const TAX = [
+    { param: "default_tax_rates", why: "tax changes invoice totals" },
+    { param: "automatic_tax[enabled]", allowed: OFF, why: "tax changes invoice totals" },
+];
+const COLLECTION = [
+    {
+        param: "collection_method",
+        allowed: ["charge_automatically"],
+        why: "send_invoice leaves the invoice open instead of charging it",
+    },
+    { param: "days_until_due", why: "only meaningful with send_invoice" },
+];
+const PAYMENT_BEHAVIOR = {
+    param: "payment_behavior",
+    allowed: ["allow_incomplete", "error_if_incomplete"],
+    why: "default_incomplete and pending_if_incomplete leave the invoice unpaid; the twin charges at once",
+};
+const ITEM_LINE = [
+    {
+        param: "items[0][price_data]",
+        why: "an inline price the twin cannot read; create the price, then pass items[0][price]",
+    },
+    { param: "items[0][tax_rates]", why: "tax changes the line total" },
+    { param: "items[0][discounts]", why: "a discount changes the line total" },
+];
+const CUSTOMER_MONEY = [
+    { param: "coupon", why: "a discount changes every future invoice" },
+    { param: "promotion_code", why: "a discount changes every future invoice" },
+    { param: "cash_balance", why: "a second balance the twin does not model" },
+];
+export const REFUSED_PARAMS = {
+    "POST /v1/payment_intents": [CAPTURE, CAPTURE_OPTIONS, ...CONNECT],
+    "POST /v1/payment_intents/:id/confirm": [CAPTURE, CAPTURE_OPTIONS],
+    "POST /v1/subscriptions": [
+        { param: "trial_period_days", why: "a trial defers the first charge" },
+        { param: "trial_end", why: "a trial defers the first charge" },
+        {
+            param: "trial_from_plan",
+            allowed: OFF,
+            why: "takes the trial from the price's recurring[trial_period_days]; a trial defers the first charge",
+        },
+        ...DISCOUNTS,
+        ...TAX,
+        { param: "billing_cycle_anchor", why: "moves the first period boundary and prorates the first invoice" },
+        { param: "billing_cycle_anchor_config", why: "moves the first period boundary and prorates the first invoice" },
+        { param: "backdate_start_date", why: "bills past periods at creation" },
+        ...COLLECTION,
+        PAYMENT_BEHAVIOR,
+        { param: "cancel_at", why: "the twin models cancel_at_period_end only" },
+        { param: "add_invoice_items", why: "one-time lines change the first invoice total" },
+        ...ITEM_LINE,
+        ...SUBSCRIPTION_CONNECT,
+        BILLING_THRESHOLDS,
+    ],
+    "POST /v1/subscriptions/:id": [
+        { param: "trial_end", why: "a trial defers the next charge" },
+        ...DISCOUNTS,
+        ...TAX,
+        {
+            param: "billing_cycle_anchor",
+            allowed: ["unchanged"],
+            why: "resetting the anchor prorates and moves every renewal",
+        },
+        { param: "proration_date", why: "changes the proration amounts" },
+        { param: "cancel_at", why: "the twin models cancel_at_period_end only" },
+        { param: "pause_collection", why: "pauses charging while the subscription stays active" },
+        ...COLLECTION,
+        PAYMENT_BEHAVIOR,
+        { param: "add_invoice_items", why: "one-time lines change the next invoice total" },
+        ...ITEM_LINE,
+        {
+            param: "items[0][deleted]",
+            allowed: OFF,
+            why: "deletes the one item — Stripe 400s unless another item replaces it, and the twin models exactly one",
+        },
+        ...SUBSCRIPTION_CONNECT,
+        BILLING_THRESHOLDS,
+    ],
+    "DELETE /v1/subscriptions/:id": [
+        { param: "invoice_now", allowed: OFF, why: "invoices pending prorations at once" },
+        { param: "prorate", allowed: OFF, why: "credits the unused time on cancel" },
+    ],
+    "POST /v1/invoices": [
+        ...COLLECTION,
+        { param: "due_date", why: "only meaningful with send_invoice" },
+        {
+            param: "auto_advance",
+            allowed: OFF,
+            why: "Stripe finalizes and collects on its own about an hour later; the twin finalizes and pays only when told to",
+        },
+        { param: "discounts", why: "a discount changes the invoice total" },
+        ...TAX,
+        {
+            param: "pending_invoice_items_behavior",
+            allowed: ["include"],
+            why: "exclude leaves the pending items off the invoice; the twin always sweeps them",
+        },
+        {
+            param: "subscription",
+            why: "includes only that subscription's pending items; the twin sweeps every pending item of the customer",
+        },
+        ...CONNECT,
+    ],
+    "POST /v1/invoiceitems": [
+        { param: "price_data", why: "an inline price the twin cannot read; pass amount + currency, or price" },
+        { param: "unit_amount", why: "the twin reads amount (a total), or price × quantity" },
+        { param: "unit_amount_decimal", why: "the twin reads amount (a total), or price × quantity" },
+        { param: "discounts", why: "a discount changes the line total" },
+        { param: "tax_rates", why: "tax changes the line total" },
+        { param: "invoice", why: "adds the line to a specific draft invoice; the twin sweeps pending items only" },
+    ],
+    "POST /v1/invoices/:id/pay": [
+        { param: "paid_out_of_band", allowed: OFF, why: "marks the invoice paid with no charge" },
+        { param: "forgive", allowed: OFF, why: "writes off the remaining amount" },
+    ],
+    "POST /v1/refunds": [
+        { param: "refund_application_fee", allowed: OFF, why: "a Connect fee refund" },
+        { param: "reverse_transfer", allowed: OFF, why: "a Connect transfer reversal" },
+    ],
+    "POST /v1/customers": CUSTOMER_MONEY,
+    "POST /v1/customers/:id": CUSTOMER_MONEY,
+    "POST /v1/prices": [
+        { param: "billing_scheme", allowed: ["per_unit"], why: "tiered pricing changes the amount per quantity" },
+        { param: "tiers", why: "tiered pricing changes the amount per quantity" },
+        { param: "tiers_mode", why: "tiered pricing changes the amount per quantity" },
+        { param: "transform_quantity", why: "changes the billed quantity" },
+        {
+            param: "recurring[usage_type]",
+            allowed: ["licensed"],
+            why: "metered billing bills reported usage, not the quantity",
+        },
+        {
+            param: "recurring[aggregate_usage]",
+            why: "metered billing; a Plans-era parameter Stripe's current API no longer accepts on a price, refused rather than echoed",
+        },
+        { param: "recurring[meter]", why: "metered billing" },
+        {
+            param: "recurring[trial_period_days]",
+            why: "a trial every subscription created with trial_from_plan takes; a trial defers the first charge",
+        },
+        { param: "unit_amount_decimal", why: "the twin reads unit_amount" },
+        { param: "custom_unit_amount", why: "the customer chooses the amount" },
+        { param: "currency_options", why: "multi-currency prices" },
+        { param: "product_data", why: "an inline product the twin cannot create; create the product, then pass product" },
+    ],
+};
+function lookup(params, param) {
+    let node = params;
+    for (const segment of parseKeyPath(param)) {
+        if (node === null || typeof node !== "object")
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+}
+export function findRefusedParam(method, pattern, params) {
+    for (const rule of REFUSED_PARAMS[`${method} ${pattern}`] ?? []) {
+        const value = lookup(params, rule.param);
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (rule.allowed &&
+            (typeof value === "string" || typeof value === "boolean") &&
+            rule.allowed.includes(String(value)))
+            continue;
+        return { rule, value };
+    }
+    return undefined;
+}
+export function refusedParameterError(method, pattern, params) {
+    const refused = findRefusedParam(method, pattern, params);
+    if (!refused)
+        return undefined;
+    const { rule, value } = refused;
+    const scalar = typeof value === "string" || typeof value === "boolean" || typeof value === "number";
+    return unsupportedParameter({
+        param: rule.param,
+        subject: rule.allowed && scalar ? `${rule.param}=${String(value)}` : rule.param,
+        route: `${method} ${pattern}`,
+        why: rule.why,
+    });
+}

package/server/dist/webhooks/dispatcher.js

@@ -0,0 +1,148 @@
+import { createHmac } from "node:crypto";
+import { deliveryTimestamp } from "../core/nondeterministic.js";
+import { webhookRules } from "../scenario/engine.js";
+export function signPayload(secret, timestamp, payload) {
+    const signed = createHmac("sha256", secret).update(`${timestamp}.${payload}`).digest("hex");
+    return `t=${timestamp},v1=${signed}`;
+}
+export class WebhookDispatcher {
+    flushing = new Map();
+    fetchImpl;
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async flush(world) {
+        const prev = this.flushing.get(world.id) ?? Promise.resolve();
+        const run = prev.catch(() => undefined).then(() => this.flushInner(world));
+        this.flushing.set(world.id, run);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.flushing.get(world.id) === run)
+                this.flushing.delete(world.id);
+        }
+    }
+    async flushInner(world) {
+        const results = [];
+        if (world.closed)
+            return results;
+        const generation = world.generation;
+        const config = world.webhookConfig();
+        if (!config)
+            return results;
+        const eligible = () => world.db
+            .prepare("SELECT seq, event_id, attempts FROM webhook_deliveries WHERE status = 'pending' AND next_attempt_at <= ? ORDER BY seq ASC")
+            .all(world.clock);
+        const { dropEveryNth, reorder } = webhookRules(world);
+        let batch = eligible();
+        if (reorder === "swap_adjacent") {
+            const swapped = [];
+            for (let i = 0; i < batch.length; i += 2) {
+                if (i + 1 < batch.length)
+                    swapped.push(batch[i + 1], batch[i]);
+                else
+                    swapped.push(batch[i]);
+            }
+            batch = swapped;
+        }
+        for (const row of batch) {
+            if (world.generation !== generation)
+                return results;
+            const event = world.getEvent(row.event_id);
+            if (!event)
+                continue;
+            if (dropEveryNth) {
+                const n = world.incrCounter("scenario:webhook_dispatch");
+                if (n % dropEveryNth === 0) {
+                    world.db
+                        .prepare("UPDATE webhook_deliveries SET status = 'dropped', attempts = ? WHERE seq = ?")
+                        .run(row.attempts + 1, row.seq);
+                    results.push({ event_id: event.id, event_type: event.type, status: "dropped", attempt: row.attempts + 1 });
+                    continue;
+                }
+            }
+            const payload = JSON.stringify(event.data);
+            const timestamp = config.signature_time === "logical" ? world.clock : deliveryTimestamp();
+            const attempt = row.attempts + 1;
+            let statusCode;
+            let errorMsg;
+            try {
+                const res = await this.fetchImpl(config.url, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        "stripe-signature": signPayload(config.secret, timestamp, payload),
+                        "user-agent": "worlds-webhooks/0.1",
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(5000),
+                });
+                statusCode = res.status;
+                await res.arrayBuffer().catch(() => undefined);
+                if (world.generation !== generation)
+                    return results;
+                if (res.status >= 200 && res.status < 300) {
+                    world.db
+                        .prepare("UPDATE webhook_deliveries SET status = 'delivered', attempts = ?, last_status_code = ? WHERE seq = ?")
+                        .run(attempt, res.status, row.seq);
+                    results.push({
+                        event_id: event.id,
+                        event_type: event.type,
+                        status: "delivered",
+                        attempt,
+                        status_code: res.status,
+                    });
+                    continue;
+                }
+                errorMsg = `HTTP ${res.status}`;
+            }
+            catch (err) {
+                errorMsg = err instanceof Error ? err.message : String(err);
+            }
+            if (world.generation !== generation)
+                return results;
+            if (attempt > config.max_retries) {
+                world.db
+                    .prepare("UPDATE webhook_deliveries SET status = 'failed', attempts = ?, last_status_code = ?, last_error = ? WHERE seq = ?")
+                    .run(attempt, statusCode ?? null, errorMsg ?? null, row.seq);
+                results.push({
+                    event_id: event.id,
+                    event_type: event.type,
+                    status: "failed",
+                    attempt,
+                    status_code: statusCode,
+                    error: errorMsg,
+                });
+            }
+            else {
+                const nextAt = world.clock + 60 * 2 ** (attempt - 1);
+                world.db
+                    .prepare("UPDATE webhook_deliveries SET attempts = ?, next_attempt_at = ?, last_status_code = ?, last_error = ? WHERE seq = ?")
+                    .run(attempt, nextAt, statusCode ?? null, errorMsg ?? null, row.seq);
+                results.push({
+                    event_id: event.id,
+                    event_type: event.type,
+                    status: "retry_scheduled",
+                    attempt,
+                    status_code: statusCode,
+                    error: errorMsg,
+                    next_attempt_at: nextAt,
+                });
+            }
+        }
+        return results;
+    }
+    drainSoon(world) {
+        setImmediate(() => {
+            try {
+                const config = world.webhookConfig();
+                if (!config?.auto_deliver)
+                    return;
+                void this.flush(world).catch(() => undefined);
+            }
+            catch {
+            }
+        });
+    }
+}

package/server/scenarios/auth-expiry.yaml

@@ -0,0 +1,7 @@
+# The API key works for 10 more requests, then starts returning
+# 401 api_key_expired. Tests whether agents detect auth failure and stop,
+# rather than hammering on or silently reporting success.
+name: auth-expiry
+description: "After 10 authenticated requests, the API key acts expired (401 api_key_expired)."
+rules:
+  - auth: { expire_after_requests: 10 }

package/server/scenarios/intermittent-500s.yaml

@@ -0,0 +1,9 @@
+# Every 3rd twin request fails with a 500 api_error. Deterministic: the
+# counter lives in world state, so the same request script always sees the
+# same failures.
+name: intermittent-500s
+description: "Every 3rd request returns a 500 api_error."
+rules:
+  - match: { path: "/v1/**" }
+    every_nth: 3
+    respond: { status: 500, stripe_error: api_error }

package/server/scenarios/lock-timeouts.yaml

@@ -0,0 +1,12 @@
+# Stripe's OTHER 429. A lock_timeout means another request holds the object's
+# lock, and Stripe marks it retryable (Stripe-Should-Retry: true) — so a stock
+# official SDK retries it silently, with the same idempotency key, and the
+# agent never sees it. A rate-limit 429 carries no such header and the SDK
+# surfaces it. Every 5th Stripe write hits a lock here: the storm a stock
+# integration survives without the model noticing anything happened.
+name: lock-timeouts
+description: "Every 5th Stripe write returns a 429 lock_timeout with Stripe-Should-Retry: true — the storm a stock SDK retries through silently."
+rules:
+  - match: { method: POST, path: "/v1/**" }
+    every_nth: 5
+    respond: { status: 429, stripe_error: lock_timeout }