@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/metrics.js

@@ -0,0 +1,204 @@
+/**
+ * Metrics — named counters, timings and gauges, with two sinks:
+ *
+ *   - the log line (`msg = "metric"`, `metric`/`value`|`ms` plus every tag as its own field), which
+ *     rides the request logger and so inherits its correlation fields — queryable in Workers Logs
+ *     (Observability -> Logs). At `debug` while the dataset is bound (Analytics Engine carries the
+ *     number; this halves Workers Logs volume), at `info` when it isn't, so an operator who never
+ *     binds `METRICS` keeps the whole signal in their logs;
+ *   - Workers Analytics Engine, when the operator binds `METRICS` (optional — docs/guide.md
+ *     "Operating"). That write does not go through the logger, so a `LOG_LEVEL` of `warn` never
+ *     silences a metric.
+ *
+ * The data point has ONE fixed schema, so any dashboard can chart every oracle the same way:
+ *
+ *   index1/blob1 name · blob2 op · blob3 route · blob4 status · blob5 outcome · blob6 network ·
+ *   blob7 id (a low-volume id: a DID or a source id — never a claim id) · double1 value · double2 ms
+ *
+ * so call sites tag with those five canonical keys (`op`/`route`/`status`/`outcome`/`id`); any
+ * other tag reaches the log line only.
+ *
+ * `withMetrics` makes an invocation's `Metrics` ambient (AsyncLocalStorage) for code that has no
+ * `c.var` to read it from — the shared fetch client and the cache reads — without threading it
+ * through every deps object. `node:async_hooks` exists in plain node too, so this module stays
+ * safe for the node lane.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Per `Metrics` instance, i.e. per invocation: a loop writing one point per row is a bug to
+ *  aggregate, not a budget to spend. The last `RESERVED` points are kept for the invocation's own
+ *  summary metrics, so a chatty invocation still reports that it ran and how it ended. */
+export const MAX_POINTS = 250;
+const RESERVED = 10;
+// Plus the two a claim's run writes at most once each — its SLO point and its terminal failure.
+const ESSENTIAL = new Set([
+    "http.request",
+    "cron.tick",
+    "errors",
+    "api.decision.latency",
+    "ingest.terminal",
+]);
+const MAX_BLOB = 256;
+const blob = (v) => v === undefined || v === null || v === "" ? "-" : String(v).slice(0, MAX_BLOB);
+/**
+ * `logger` already carries the base fields (service, env, and on a request path the
+ * requestId/traceId), so a metric's log line inherits its correlation for free. No `sink.dataset`
+ * ⇒ log line only.
+ */
+export function createMetrics(logger, sink) {
+    let points = 0;
+    let capped = false;
+    let failed = false;
+    const line = (fields) => sink?.dataset ? logger.debug("metric", fields) : logger.info("metric", fields);
+    const write = (name, value, ms, tags = {}) => {
+        if (!sink?.dataset)
+            return;
+        if (points >= (ESSENTIAL.has(name) ? MAX_POINTS : MAX_POINTS - RESERVED)) {
+            if (!capped)
+                logger.warn("metrics.capped", { max: MAX_POINTS, metric: name });
+            capped = true;
+            return;
+        }
+        points++;
+        try {
+            sink.dataset.writeDataPoint({
+                indexes: [blob(name)],
+                blobs: [
+                    blob(name),
+                    blob(tags.op),
+                    blob(tags.route),
+                    blob(tags.status),
+                    blob(tags.outcome),
+                    blob(sink.network),
+                    blob(tags.id),
+                ],
+                doubles: [value, ms],
+            });
+        }
+        catch (err) {
+            // A metric must never fail the work it measures — and one broken binding must not turn every
+            // point into a warn line.
+            if (!failed)
+                logger.warn("metrics.write-failed", { metric: name, detail: String(err) });
+            failed = true;
+        }
+    };
+    return {
+        count(name, value = 1, tags) {
+            line({ metric: name, value, ...tags });
+            write(name, value, 0, tags);
+        },
+        timing(name, ms, tags) {
+            line({ metric: name, ms, ...tags });
+            write(name, 1, ms, tags);
+        },
+        gauge(name, value, tags) {
+            line({ metric: name, value, ...tags });
+            write(name, value, 0, tags);
+        },
+    };
+}
+const current = new AsyncLocalStorage();
+/** Run `fn` with `scope` as the invocation's ambient metrics (a request, a cron tick, a workflow). */
+export function withMetrics(scope, fn) {
+    return current.run(scope, fn);
+}
+/**
+ * A workflow step whose callbacks run inside `scope`, each timed as `workflow.step` (op the
+ * workflow, route the step name, status the attempt the step context reports). Timed INSIDE the
+ * callback: a completed step replayed from its checkpoint never calls it, so it records nothing. The Workflows engine calls a `step.do`
+ * callback back from its own context, not run()'s, so the AsyncLocalStorage scope set around
+ * run() is gone by then — the same reason Sentry's wrapped step captures its scope at `do()` time.
+ * Wraps the step it is given (Sentry's, in production) rather than replacing it; every other
+ * member passes through untouched.
+ */
+export function scopedStep(step, scope, workflow) {
+    const inScope = (name, arg) => typeof arg === "function"
+        ? (...args) => withMetrics(scope, async () => {
+            const started = Date.now();
+            let outcome = "error";
+            try {
+                const out = await arg(...args);
+                outcome = "ok";
+                return out;
+            }
+            finally {
+                scope.metrics.timing("workflow.step", Date.now() - started, {
+                    op: workflow,
+                    route: name,
+                    status: args[0]?.attempt,
+                    outcome,
+                });
+            }
+        })
+        : arg;
+    const scopedDo = (name, ...rest) => step.do.call(step, name, ...rest.map((arg) => inScope(name, arg)));
+    return new Proxy(step, {
+        get(target, prop) {
+            if (prop === "do")
+                return scopedDo;
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+const PEER_CODE = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * A code another service answered with, fit to be a label: a peer's error body is not ours to
+ * trust, so anything outside a short code alphabet is `unknown` rather than free text in a blob.
+ */
+export function peerCode(code) {
+    return typeof code === "string" && PEER_CODE.test(code) ? code : "unknown";
+}
+/** The ambient `Metrics`; undefined outside any `withMetrics`, where nothing is recorded. */
+export function currentMetrics() {
+    return current.getStore()?.metrics;
+}
+/** The ambient request's `traceparent`/`requestId` — only the keys it has (none off a request). */
+export function currentCorrelation() {
+    const scope = current.getStore();
+    return {
+        ...(scope?.traceparent ? { traceparent: scope.traceparent } : {}),
+        ...(scope?.requestId ? { requestId: scope.requestId } : {}),
+    };
+}
+/**
+ * `cron.tick` for one scheduled job: how long it ran and whether it threw (rethrown untouched — the
+ * caller's own containment still decides what a failure does).
+ */
+export async function timeCronJob(metrics, job, run) {
+    const started = Date.now();
+    let outcome = "error";
+    try {
+        const out = await run();
+        outcome = "ok";
+        return out;
+    }
+    finally {
+        metrics.timing("cron.tick", Date.now() - started, { op: job, outcome });
+    }
+}
+/** Count an in-isolate (L1) cache lookup. */
+export function countCache(name, hit) {
+    currentMetrics()?.count("cache", 1, { op: name, outcome: hit ? "hit" : "miss" });
+}
+/**
+ * A KV cache read, counted hit/miss/error. A cache is never the source of truth, so a failed read
+ * is a miss to the caller exactly as the old `.catch(() => null)` made it — only now a logged,
+ * counted one instead of a silent one.
+ * A synchronous throw from `read` is caught the same way (logged `cache.error`, returns null).
+ */
+export async function readCache(name, read) {
+    const scope = current.getStore();
+    let value;
+    try {
+        value = await read();
+    }
+    catch (err) {
+        scope?.logger.warn("cache.error", { cache: name, op: "get", detail: String(err) });
+        scope?.metrics.count("cache", 1, { op: name, outcome: "error" });
+        return null;
+    }
+    scope?.metrics.count("cache", 1, { op: name, outcome: value === null ? "miss" : "hit" });
+    return value;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/lib/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/lib/metrics.ts"],"names":[],"mappings":"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"}

package/dist/lib/oauth/approvals.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Per-submit approvals for AI apps over OAuth (spec 2026-10-06 "Approvals"; S3 review §2, §6, §8).
+ * The rows are `mcp_approvals` (schema.ts says what each column holds); this file is every read
+ * and write of them, and the per-grant daily cap.
+ *
+ * The one invariant that moves money: an approval is spent by ONE conditional statement —
+ * `approved` (or `awaiting_3ds`) → `used` — BEFORE anything is paid, so two retries racing on one
+ * approval pay once. How a payment ends decides what becomes of it (S3 review F3):
+ *   - PROVEN to have reserved nothing, and the user can fix it without re-signing (no credits, a
+ *     cap, a declined card, a 503 before `/verify`): put back (`restoreApproval`), and the retry
+ *     pays with the same approval;
+ *   - the card wants 3-D Secure: parked `awaiting_3ds`, bound to that offer and PaymentIntent
+ *     (`awaitCardConfirmation`), and only the resume of exactly those may spend it;
+ *   - anything else — paid, a refused delegation, or ambiguous (a 5xx or a timeout once a payment
+ *     was sent: `/verify` may have reserved and the record failed) — retires the delegation
+ *     (`retireDelegation`), and the same request asks the user again.
+ * A price that moved since the approval is `APPROVAL_STALE`, never a payment at the new price.
+ */
+import { type SQL } from "drizzle-orm";
+import type { Config } from "../../config.js";
+import type { Attachment } from "../../contracts/index.js";
+import type { Database } from "../../db/client.js";
+import { type McpApproval } from "../../db/schema.js";
+/** How long the user has to approve, and then how long the app has to use the approval. */
+export declare const APPROVAL_TTL_MS: number;
+/** What one OAuth grant may spend a day, in cents, whatever its approvals say (S3 review §8). */
+export declare const GRANT_CAP_CENTS_PER_DAY = 2000;
+/** …in upay (1 cent = 10 000 upay): what the atomic counter (`mcp_standing_spends`) compares. */
+export declare const GRANT_CAP_UPAY: number;
+/**
+ * The grant's spend over the last 24 h as the atomic counter has it: every `mcp_standing_spends`
+ * row — the auto-approve path's per-request locks and the one-claim approvals' spends alike (S3
+ * follow-up 4), so racing both paths can never pass the day's cap together.
+ */
+export declare const spentToday: (grantId: string, now: Date) => SQL<unknown>;
+/** ≥ 128 random bits, base64url: an approval id is a capability-shaped link, never guessable. */
+export declare function newApprovalId(): string;
+/**
+ * What an approval is bound to (S3 review "Smaller points"): the protocol, the source, the
+ * canonical body, its attachments and the idempotency key. A different body is a different digest,
+ * so an approval never moves to another claim.
+ */
+export declare function approvalDigest(r: {
+    protocolDid: string;
+    sourceId: string;
+    answers: Record<string, unknown>;
+    attachments: readonly Attachment[];
+    submitter?: string;
+    metadata?: Record<string, unknown>;
+    webhookUrl?: string;
+    idempotencyKey: string;
+}): Promise<string>;
+/** AuthHub's approve page for `id`: it reads the approval from THIS oracle, never from the link. */
+export declare const approveUrl: (config: Pick<Config, "AUTH_HUB_URL" | "ORACLE_HOSTNAME">, id: string) => string;
+/** `$1.20`: what the approve page shows. */
+export declare const priceDisplay: (cents: number) => string;
+/** This app's live (pending or approved) approval of this exact request, if any. */
+export declare function liveApproval(db: Database, grantId: string, requestDigest: string, now?: Date): Promise<{
+    billingMode: "none" | "x402";
+    clientId: string;
+    clientName: string;
+    createdAt: Date;
+    delegation: string | null;
+    did: string;
+    expiresAt: Date;
+    grantId: string;
+    id: string;
+    maxAmountUpay: string;
+    offerId: string | null;
+    paymentIntentId: string | null;
+    price: string;
+    protocolDid: string;
+    requestDigest: string;
+    sourceId: string;
+    status: "approved" | "awaiting_3ds" | "declined" | "expired" | "pending" | "used";
+} | undefined>;
+/**
+ * File a pending approval, or find the one a racing call filed first (the partial unique index
+ * allows one live row per app and request).
+ */
+export declare function fileApproval(db: Database, row: Omit<McpApproval, "id" | "status" | "delegation" | "offerId" | "paymentIntentId" | "expiresAt" | "createdAt">, now?: Date): Promise<McpApproval>;
+/** Retire a live approval (ran out, or the price moved): its delegation goes with it. */
+export declare function expireApproval(db: Database, id: string): Promise<void>;
+/**
+ * Spend an approval: the ONE batch that lets a payment happen — "spent" for exactly one caller per
+ * approval, since the flip needs that caller's own counter row. The delegation stays on the row until the payment ends (`retireDelegation`), so a
+ * payment that never settled can be put back (`restoreApproval`).
+ */
+export declare function spendApproval(db: Database, row: Pick<McpApproval, "id" | "grantId" | "maxAmountUpay">, from?: "approved" | "awaiting_3ds", now?: Date): Promise<"spent" | "lost" | "capped">;
+/** Definitely nothing reserved: the approval is the user's again, delegation and expiry unchanged. */
+export declare function restoreApproval(db: Database, id: string, now?: Date): Promise<boolean>;
+/**
+ * The card wants 3-D Secure: the spent row waits for the person, bound to the offer and the
+ * PaymentIntent the bank challenged. Its delegation stays (the resume's card authorize needs it).
+ */
+export declare function awaitCardConfirmation(db: Database, id: string, bound: {
+    offerId: string;
+    paymentIntentId: string;
+}, now?: Date): Promise<boolean>;
+/**
+ * A payment from the grant's auto-approve met 3-D Secure: the fresh approval of this request is
+ * parked `awaiting_3ds` with the standing delegation, so the resume pays exactly that card offer.
+ */
+export declare function parkStandingPayment(db: Database, id: string, delegation: string, bound: {
+    offerId: string;
+    paymentIntentId: string;
+}): Promise<boolean>;
+/** The payment ended (paid, or ambiguous): the spent row keeps no payment authority. */
+export declare function retireDelegation(db: Database, id: string): Promise<void>;
+/** The back-channel's view: an approval that exists AND is pending AND has not run out. */
+export declare function pendingApproval(db: Database, id: string, now?: Date): Promise<{
+    billingMode: "none" | "x402";
+    clientId: string;
+    clientName: string;
+    createdAt: Date;
+    delegation: string | null;
+    did: string;
+    expiresAt: Date;
+    grantId: string;
+    id: string;
+    maxAmountUpay: string;
+    offerId: string | null;
+    paymentIntentId: string | null;
+    price: string;
+    protocolDid: string;
+    requestDigest: string;
+    sourceId: string;
+    status: "approved" | "awaiting_3ds" | "declined" | "expired" | "pending" | "used";
+} | undefined>;
+/** AuthHub's answer: approved (with its delegation, null for billing `none`), or declined. */
+export declare function answerApproval(db: Database, id: string, answer: {
+    status: "approved";
+    delegation: string | null;
+} | {
+    status: "declined";
+}, now?: Date): Promise<boolean>;
+/** Why a delegation can't pay for an approval: a stable `reason` code and words for a person. */
+export interface DelegationRefusal {
+    reason: "invalid_delegation" | "issuer_mismatch" | "oracle_mismatch" | "facilitator_mismatch" | "amount_mismatch" | "expired" | "expires_too_soon" | "limits_invalid";
+    message: string;
+    /** The delegation's audience — what a `facilitator_mismatch` is logged with. */
+    audience?: string;
+}
+/**
+ * Why `delegation` cannot pay for `row`, or null when it can: a well-formed payment delegation
+ * whose root issuer is the approval's user, bound to this oracle, to OUR facilitator, for exactly
+ * the approved price, and not expired. Its signature is the facilitator's to verify at payment.
+ */
+export declare function delegationRefusal(delegation: string, row: Pick<McpApproval, "did" | "maxAmountUpay">, expect: {
+    oracleDid: string;
+    facilitatorDid: string;
+    /** A standing authority's `until` (standing.ts): the delegation must last at least that long. */
+    validUntil?: number;
+}, now?: number): Promise<DelegationRefusal | null>;
+/**
+ * Has this grant's spend over the last 24 h plus `cents` passed the cap? Every charge that may
+ * still move money counts (`released` / `failed` moved nothing), as the per-key cap counts.
+ */
+export declare function overGrantCap(db: Database, grantId: string, cents: number, now?: number): Promise<boolean>;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/lib/oauth/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../../src/lib/oauth/approvals.ts"],"names":[],"mappings":"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"}

package/dist/lib/oauth/approvals.js

@@ -0,0 +1,273 @@
+/**
+ * Per-submit approvals for AI apps over OAuth (spec 2026-10-06 "Approvals"; S3 review §2, §6, §8).
+ * The rows are `mcp_approvals` (schema.ts says what each column holds); this file is every read
+ * and write of them, and the per-grant daily cap.
+ *
+ * The one invariant that moves money: an approval is spent by ONE conditional statement —
+ * `approved` (or `awaiting_3ds`) → `used` — BEFORE anything is paid, so two retries racing on one
+ * approval pay once. How a payment ends decides what becomes of it (S3 review F3):
+ *   - PROVEN to have reserved nothing, and the user can fix it without re-signing (no credits, a
+ *     cap, a declined card, a 503 before `/verify`): put back (`restoreApproval`), and the retry
+ *     pays with the same approval;
+ *   - the card wants 3-D Secure: parked `awaiting_3ds`, bound to that offer and PaymentIntent
+ *     (`awaitCardConfirmation`), and only the resume of exactly those may spend it;
+ *   - anything else — paid, a refused delegation, or ambiguous (a 5xx or a timeout once a payment
+ *     was sent: `/verify` may have reserved and the record failed) — retires the delegation
+ *     (`retireDelegation`), and the same request asks the user again.
+ * A price that moved since the approval is `APPROVAL_STALE`, never a payment at the new price.
+ */
+import { parsePaymentDelegation } from "@ixo/x402-ixo-pay";
+import { and, eq, gt, inArray, lte, notInArray, sql } from "drizzle-orm";
+import { apiCharges, mcpApprovals, mcpStandingSpends } from "../../db/schema.js";
+import { DAY_MS } from "../api-lane/retention.js";
+import { canonicalJson, sha256Hex } from "../hash.js";
+/** How long the user has to approve, and then how long the app has to use the approval. */
+export const APPROVAL_TTL_MS = 15 * 60_000;
+/** What one OAuth grant may spend a day, in cents, whatever its approvals say (S3 review §8). */
+export const GRANT_CAP_CENTS_PER_DAY = 2000;
+/** …in upay (1 cent = 10 000 upay): what the atomic counter (`mcp_standing_spends`) compares. */
+export const GRANT_CAP_UPAY = GRANT_CAP_CENTS_PER_DAY * 10_000;
+/**
+ * The grant's spend over the last 24 h as the atomic counter has it: every `mcp_standing_spends`
+ * row — the auto-approve path's per-request locks and the one-claim approvals' spends alike (S3
+ * follow-up 4), so racing both paths can never pass the day's cap together.
+ */
+export const spentToday = (grantId, now) => sql `(select coalesce(sum(${mcpStandingSpends.upay}), 0) from ${mcpStandingSpends} where ${mcpStandingSpends.grantId} = ${grantId} and ${mcpStandingSpends.createdAt} > ${now.getTime() - DAY_MS})`;
+/** The counter row a one-claim approval's spend writes (the auto-approve path keys by request). */
+const approvalSpendKey = (id) => `approval:${id}`;
+/** ≥ 128 random bits, base64url: an approval id is a capability-shaped link, never guessable. */
+export function newApprovalId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * What an approval is bound to (S3 review "Smaller points"): the protocol, the source, the
+ * canonical body, its attachments and the idempotency key. A different body is a different digest,
+ * so an approval never moves to another claim.
+ */
+export function approvalDigest(r) {
+    return sha256Hex(canonicalJson({
+        protocolDid: r.protocolDid,
+        sourceId: r.sourceId,
+        answers: r.answers,
+        attachments: r.attachments,
+        submitter: r.submitter ?? null,
+        metadata: r.metadata ?? null,
+        webhookUrl: r.webhookUrl ?? null,
+        idempotencyKey: r.idempotencyKey,
+    }));
+}
+/** AuthHub's approve page for `id`: it reads the approval from THIS oracle, never from the link. */
+export const approveUrl = (config, id) => `${config.AUTH_HUB_URL}/connect/approve?oracle=${encodeURIComponent(config.ORACLE_HOSTNAME)}&id=${id}`;
+/** `$1.20`: what the approve page shows. */
+export const priceDisplay = (cents) => `$${(cents / 100).toFixed(2)}`;
+/** This app's live (pending or approved) approval of this exact request, if any. */
+export async function liveApproval(db, grantId, requestDigest, now = new Date()) {
+    const scope = and(eq(mcpApprovals.grantId, grantId), eq(mcpApprovals.requestDigest, requestDigest));
+    await expireStale(db, scope, now);
+    return db.query.mcpApprovals.findFirst({
+        where: and(scope, inArray(mcpApprovals.status, LIVE)),
+    });
+}
+/** The statuses that still hold (or may yet hold) payment authority. */
+const LIVE = ["pending", "approved", "awaiting_3ds"];
+/**
+ * Rows of `scope` past their window turn `expired`, the delegation nulled in the SAME statement
+ * (S3 review L3): every read and spend runs it first, so no live-looking row outlives its window
+ * by so much as a request. The hourly sweep then deletes them.
+ */
+async function expireStale(db, scope, now) {
+    await db
+        .update(mcpApprovals)
+        .set({ status: "expired", delegation: null })
+        .where(and(scope, inArray(mcpApprovals.status, LIVE), lte(mcpApprovals.expiresAt, now)));
+}
+/**
+ * File a pending approval, or find the one a racing call filed first (the partial unique index
+ * allows one live row per app and request).
+ */
+export async function fileApproval(db, row, now = new Date()) {
+    await db
+        .insert(mcpApprovals)
+        .values({
+        ...row,
+        id: newApprovalId(),
+        expiresAt: new Date(now.getTime() + APPROVAL_TTL_MS),
+        createdAt: now,
+    })
+        .onConflictDoNothing();
+    const filed = await liveApproval(db, row.grantId, row.requestDigest);
+    if (!filed)
+        throw new Error("mcp_approvals: filed but not found");
+    return filed;
+}
+/** Retire a live approval (ran out, or the price moved): its delegation goes with it. */
+export async function expireApproval(db, id) {
+    await db
+        .update(mcpApprovals)
+        .set({ status: "expired", delegation: null })
+        .where(and(eq(mcpApprovals.id, id), inArray(mcpApprovals.status, LIVE)));
+}
+/**
+ * Spend an approval: the ONE batch that lets a payment happen — "spent" for exactly one caller per
+ * approval, since the flip needs that caller's own counter row. The delegation stays on the row until the payment ends (`retireDelegation`), so a
+ * payment that never settled can be put back (`restoreApproval`).
+ */
+export async function spendApproval(db, row, from = "approved", now = new Date()) {
+    const { id, grantId } = row;
+    const upay = Number(row.maxAmountUpay);
+    const spendKey = approvalSpendKey(id);
+    const live = and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, from), gt(mcpApprovals.expiresAt, now));
+    // The resume of a confirmed 3-D Secure payment was counted when it was first spent (N5) —
+    // here, or on the auto-approve path that parked it: it adds nothing to the day's count.
+    const fits = from === "awaiting_3ds"
+        ? sql `1`
+        : sql `${spentToday(grantId, now)} + ${upay} <= ${GRANT_CAP_UPAY}`;
+    const spendId = crypto.randomUUID();
+    // The flip needs THIS attempt's counter row (by the PK and its spendId), so the cap holds by
+    // construction (S3 review of #90). The 3-D Secure resume is the one exception: its row was
+    // written when it was first spent and stays (N5) — it counts nothing new and needs only the row.
+    const counted = from === "awaiting_3ds"
+        ? sql `exists (select 1 from ${mcpStandingSpends} where ${mcpStandingSpends.grantId} = ${grantId} and ${mcpStandingSpends.requestDigest} = ${spendKey})`
+        : sql `exists (select 1 from ${mcpStandingSpends} where ${mcpStandingSpends.grantId} = ${grantId} and ${mcpStandingSpends.requestDigest} = ${spendKey} and ${mcpStandingSpends.spendId} = ${spendId})`;
+    const [, spent] = await db.batch([
+        // The day's counter, written only if this approval is still to spend AND it fits the cap.
+        db
+            .insert(mcpStandingSpends)
+            .select(sql `select ${grantId}, ${spendKey}, ${spendId}, ${from === "awaiting_3ds" ? 0 : upay}, ${now.getTime()} where exists (select 1 from ${mcpApprovals} where ${live}) and ${fits}`)
+            .onConflictDoNothing(),
+        db
+            .update(mcpApprovals)
+            .set({ status: "used" })
+            .where(and(live, counted))
+            .returning({ id: mcpApprovals.id }),
+    ]);
+    if (spent.length === 1)
+        return "spent";
+    const still = await db.query.mcpApprovals.findFirst({ columns: { id: true }, where: live });
+    if (still)
+        return "capped";
+    // Lost to the clock or to another call: expire it if it is the clock, delegation and all.
+    await expireStale(db, eq(mcpApprovals.id, id), now);
+    return "lost";
+}
+/** Definitely nothing reserved: the approval is the user's again, delegation and expiry unchanged. */
+export async function restoreApproval(db, id, now = new Date()) {
+    const [restored] = await db.batch([
+        db
+            .update(mcpApprovals)
+            .set({ status: "approved", offerId: null, paymentIntentId: null })
+            .where(and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "used"), gt(mcpApprovals.expiresAt, now)))
+            .returning({ id: mcpApprovals.id }),
+        // Nothing was paid: its share of the day's cap goes back with it.
+        db.delete(mcpStandingSpends).where(and(
+        // By the PK's grant prefix, never a scan.
+        sql `${mcpStandingSpends.grantId} = (select ${mcpApprovals.grantId} from ${mcpApprovals} where ${mcpApprovals.id} = ${id})`, eq(mcpStandingSpends.requestDigest, approvalSpendKey(id)), sql `exists (select 1 from ${mcpApprovals} where ${mcpApprovals.id} = ${id} and ${mcpApprovals.status} = 'approved')`)),
+    ]);
+    // Nothing matched (the row expired, or moved on): the caller retires the delegation instead.
+    return restored.length === 1;
+}
+/**
+ * The card wants 3-D Secure: the spent row waits for the person, bound to the offer and the
+ * PaymentIntent the bank challenged. Its delegation stays (the resume's card authorize needs it).
+ */
+export async function awaitCardConfirmation(db, id, bound, now = new Date()) {
+    const parked = await db
+        .update(mcpApprovals)
+        .set({ status: "awaiting_3ds", ...bound })
+        .where(and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "used"), gt(mcpApprovals.expiresAt, now)))
+        .returning({ id: mcpApprovals.id });
+    return parked.length === 1;
+}
+/**
+ * A payment from the grant's auto-approve met 3-D Secure: the fresh approval of this request is
+ * parked `awaiting_3ds` with the standing delegation, so the resume pays exactly that card offer.
+ */
+export async function parkStandingPayment(db, id, delegation, bound) {
+    const parked = await db
+        .update(mcpApprovals)
+        .set({ status: "awaiting_3ds", delegation, ...bound })
+        .where(and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "pending")))
+        .returning({ id: mcpApprovals.id });
+    return parked.length === 1;
+}
+/** The payment ended (paid, or ambiguous): the spent row keeps no payment authority. */
+export async function retireDelegation(db, id) {
+    await db
+        .update(mcpApprovals)
+        .set({ delegation: null })
+        .where(and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "used")));
+}
+/** The back-channel's view: an approval that exists AND is pending AND has not run out. */
+export async function pendingApproval(db, id, now = new Date()) {
+    await expireStale(db, eq(mcpApprovals.id, id), now);
+    return db.query.mcpApprovals.findFirst({
+        where: and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "pending")),
+    });
+}
+/** AuthHub's answer: approved (with its delegation, null for billing `none`), or declined. */
+export async function answerApproval(db, id, answer, now = new Date()) {
+    const set = answer.status === "approved"
+        ? {
+            status: "approved",
+            delegation: answer.delegation,
+            expiresAt: new Date(now.getTime() + APPROVAL_TTL_MS),
+        }
+        : { status: "declined", delegation: null };
+    const done = await db
+        .update(mcpApprovals)
+        .set(set)
+        .where(and(eq(mcpApprovals.id, id), eq(mcpApprovals.status, "pending"), gt(mcpApprovals.expiresAt, now)))
+        .returning({ id: mcpApprovals.id });
+    return done.length === 1;
+}
+/**
+ * Why `delegation` cannot pay for `row`, or null when it can: a well-formed payment delegation
+ * whose root issuer is the approval's user, bound to this oracle, to OUR facilitator, for exactly
+ * the approved price, and not expired. Its signature is the facilitator's to verify at payment.
+ */
+export async function delegationRefusal(delegation, row, expect, now = Math.floor(Date.now() / 1000)) {
+    const parsed = await parsePaymentDelegation(delegation);
+    if (!parsed.ok)
+        return { reason: "invalid_delegation", message: parsed.reason };
+    const d = parsed.delegation;
+    if (d.issuer !== row.did) {
+        return { reason: "issuer_mismatch", message: "it is not signed by the approval's user" };
+    }
+    if (!d.oracles?.includes(expect.oracleDid)) {
+        return { reason: "oracle_mismatch", message: "it is not bound to this oracle" };
+    }
+    if (d.audience !== expect.facilitatorDid) {
+        return {
+            reason: "facilitator_mismatch",
+            message: "it is for a different payment facilitator than this oracle's",
+            audience: d.audience,
+        };
+    }
+    // EXACTLY the price: `maxAmount` is a total across rails, so more than one claim's price would be
+    // standing authority this approval never showed the user. (`≥` belongs to a standing grant only.)
+    if (BigInt(d.maxAmount) !== BigInt(row.maxAmountUpay)) {
+        return { reason: "amount_mismatch", message: "its amount is not exactly the approved price" };
+    }
+    if (d.expiration <= now)
+        return { reason: "expired", message: "it has expired" };
+    if (expect.validUntil !== undefined && d.expiration < expect.validUntil) {
+        return { reason: "expires_too_soon", message: "it expires before the auto-approve ends" };
+    }
+    return null;
+}
+/**
+ * Has this grant's spend over the last 24 h plus `cents` passed the cap? Every charge that may
+ * still move money counts (`released` / `failed` moved nothing), as the per-key cap counts.
+ */
+export async function overGrantCap(db, grantId, cents, now = Date.now()) {
+    const [row] = await db
+        .select({ spent: sql `coalesce(sum(${apiCharges.amountCents}), 0)` })
+        .from(apiCharges)
+        .where(and(eq(apiCharges.via, `oauth:${grantId}`), gt(apiCharges.createdAt, new Date(now - DAY_MS)), notInArray(apiCharges.status, ["released", "failed"])));
+    return (row?.spent ?? 0) + cents > GRANT_CAP_CENTS_PER_DAY;
+}
+//# sourceMappingURL=approvals.js.map