@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/contracts/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/contracts/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAOL,gBAAgB,EACjB,MAAM,OAAO,CAAC;AAGf,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AACxD,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,QAAiC,CAAC;AACtE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,4GAA4G;AAC5G,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;iBAK1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;wFACwF;AACxF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;iBAS3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,4FAA4F;AAC5F,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAW5D,mGAAmG;AACnG,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAY1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/contracts/webhooks.js

@@ -0,0 +1,71 @@
+/**
+ * The webhook wire contract (go-prod spec §4.5, Appendix B): what a receiver is POSTed and how it
+ * proves the POST came from this oracle. Signing and delivery are S2/S7's — this file is only the
+ * shape a receiver codes against.
+ *
+ * Signature: `Oracle-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 over "<t>.<raw body>">`,
+ * keyed by the endpoint's `whsec_…` secret. The timestamp is inside the MAC so a captured POST
+ * cannot be replayed later with a fresh `t`; receivers should refuse a `t` older than 5 minutes.
+ * During a secret rotation the header carries one `v1=` per live secret. `Oracle-Event-Id` equals
+ * the envelope's `id` — delivery is at-least-once, so receivers de-duplicate on it.
+ */
+import { z } from "zod";
+import { BaseUnitAmount, ClaimId, ClaimRecord, EventId, SettlementId, SourceId, WebhookEventType, } from "./api.js";
+import { SourcePausedReason } from "./errors.js";
+export { WebhookEventType };
+export const ORACLE_SIGNATURE_HEADER = "Oracle-Signature";
+export const ORACLE_EVENT_ID_HEADER = "Oracle-Event-Id";
+/** One `t=` and one or more `v1=` (several while a rotated secret overlaps). */
+export const ORACLE_SIGNATURE_FORMAT = /^t=(\d+)(,v1=[0-9a-f]{64})+$/;
+export const WEBHOOK_API_VERSION = "v1";
+/** §4.5: 8 attempts over 24 h — 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h after the first. */
+export const WEBHOOK_MAX_ATTEMPTS = 8;
+/** A receiver that has not answered 2xx within this is a failed attempt, retried. */
+export const WEBHOOK_TIMEOUT_MS = 10_000;
+/** `source.*` data: the source's state after the change; `issues` are the engine's on `rubric-unusable`. */
+export const SourceEventData = z.object({
+    sourceId: SourceId,
+    status: z.enum(["active", "paused"]),
+    pausedReason: SourcePausedReason.nullable(),
+    issues: z.array(z.object({ code: z.string(), message: z.string(), path: z.string() })).optional(),
+});
+/** `payment.settled` data — the facilitator accepted the claim's receipt and settled its reservation
+ *  (contracts v1.3: once per claim, `settlementId` replaces the hold id `chargeId`). */
+export const PaymentEventData = z.object({
+    claimId: ClaimId,
+    settlementId: SettlementId,
+    /** How it was paid (v1.4): PAY in upay, card in US cents, or USDC on Base (`exact`) in USDC
+     *  base units (1 unit = 1 micro-USD = 1 upay). */
+    scheme: z.enum(["ixo-pay", "stripe-manual-capture", "exact"]),
+    amount: BaseUnitAmount,
+    asset: z.enum(["upay", "usd", "usdc"]),
+    status: z.literal("settled"),
+});
+/** `balance.low`: the deed's credits fell under the source's `refillFloorCents` (§12.4). */
+export const BalanceLowData = z.object({
+    sourceId: SourceId,
+    balanceCents: z.int(),
+    floorCents: z.int().min(0),
+});
+const envelope = (type, data) => z.object({
+    id: EventId,
+    type: z.literal(type),
+    createdAt: z.iso.datetime(),
+    apiVersion: z.literal(WEBHOOK_API_VERSION),
+    data,
+});
+/** `{ id, type, createdAt, apiVersion, data }`; `claim.*` carry the §4.4 record, never answers. */
+export const WebhookEnvelope = z.discriminatedUnion("type", [
+    envelope("claim.accepted", ClaimRecord),
+    envelope("claim.decided", ClaimRecord),
+    envelope("claim.review_required", ClaimRecord),
+    envelope("claim.folded", ClaimRecord),
+    envelope("claim.unusable", ClaimRecord),
+    envelope("claim.failed", ClaimRecord),
+    envelope("claim.review_expired", ClaimRecord),
+    envelope("source.paused", SourceEventData),
+    envelope("source.resumed", SourceEventData),
+    envelope("payment.settled", PaymentEventData),
+    envelope("balance.low", BalanceLowData),
+]);
+//# sourceMappingURL=webhooks.js.map

package/dist/contracts/webhooks.js.map

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

package/dist/contracts/work-order.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `WorkOrderBuilder` seam — what a developer must send for a protocol (`GET
+ * /v1/api/protocols/:did`, Go Prod §4.2, §13.1 "know before you send"). Implemented by S8
+ * (`src/lib/work-order/**`); called by S3's protocols route, which adds the `price` from
+ * `PaymentGate.quote`.
+ *
+ * Built from the protocol's claim form (`#vct`) and the engine's manifest (`engine.getManifest`) —
+ * the manifest is still the only reading of the rubric (CLAUDE.md "the oracle never parses a
+ * rubric"): facts are NAMES only, review tasks come from `manifest.review.taskDetails`.
+ */
+import type { OracleEnv } from "../env.js";
+import type { ProtocolWorkOrder } from "./api.js";
+export type WorkOrder = Omit<ProtocolWorkOrder, "price">;
+export type WorkOrderResult = {
+    ok: true;
+    workOrder: WorkOrder;
+}
+/** The engine's manifest says the rubric cannot bind — the route answers it as `unusable` with the issues. */
+ | {
+    ok: false;
+    reason: "rubric-unusable";
+    issues: unknown;
+};
+/**
+ * Throws only on transient trouble (engine or chain unreachable) — the route answers 503. Callers
+ * may cache the result per protocol for as long as the manifest cache (5 min).
+ */
+export type WorkOrderBuilder = (env: OracleEnv, protocolDid: string) => Promise<WorkOrderResult>;
+//# sourceMappingURL=work-order.d.ts.map

package/dist/contracts/work-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order.d.ts","sourceRoot":"","sources":["../../src/contracts/work-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAE/C,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;AAEzD,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE;AACpC,8GAA8G;GAC5G;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC"}

package/dist/contracts/work-order.js

@@ -0,0 +1,12 @@
+/**
+ * The `WorkOrderBuilder` seam — what a developer must send for a protocol (`GET
+ * /v1/api/protocols/:did`, Go Prod §4.2, §13.1 "know before you send"). Implemented by S8
+ * (`src/lib/work-order/**`); called by S3's protocols route, which adds the `price` from
+ * `PaymentGate.quote`.
+ *
+ * Built from the protocol's claim form (`#vct`) and the engine's manifest (`engine.getManifest`) —
+ * the manifest is still the only reading of the rubric (CLAUDE.md "the oracle never parses a
+ * rubric"): facts are NAMES only, review tasks come from `manifest.review.taskDetails`.
+ */
+export {};
+//# sourceMappingURL=work-order.js.map

package/dist/contracts/work-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order.js","sourceRoot":"","sources":["../../src/contracts/work-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/cron/ai-cost.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The AI Gateway's USD, after the fact (spec 2026-10-02 §6.2). A gateway call's cost is not in its
+ * response — it is on the gateway's log entry, readable a few seconds later. The facts lane writes
+ * the call to `ai_calls` (builder.ts); this job, every fifth minute, reads each pending row's log
+ * and records `cost` as micro-USD. For operators and admin apps only — no verdict reads it.
+ *
+ * Bounded: 50 rows a run, oldest first, none younger than 60 s (the log may not be written yet).
+ * A log not found for an hour is `unavailable` (logging off, retention), as is a log with no cost
+ * (a model the gateway has no price for). The log API itself failing (anything but "not found")
+ * stops the run — one report, no hammering, nothing closed, the next run asks again — and only a
+ * row it has refused for a day is closed, so nothing blocks the queue for good.
+ * Never an alert: missing analytics is not a person's emergency. No `AI` binding ⇒ a no-op.
+ */
+import type { Config } from "../config.js";
+import type { Database } from "../db/client.js";
+import type { OracleEnv } from "../env.js";
+import type { Logger } from "../lib/logger.js";
+import type { Metrics } from "../lib/metrics.js";
+export declare function backfillAiCosts(deps: {
+    db: Database;
+    env: OracleEnv;
+    config: Config;
+    logger: Logger;
+    metrics?: Metrics;
+}, now?: number): Promise<{
+    ok: number;
+    unavailable: number;
+}>;
+//# sourceMappingURL=ai-cost.d.ts.map

package/dist/cron/ai-cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-cost.d.ts","sourceRoot":"","sources":["../../src/cron/ai-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAW9C,wBAAsB,eAAe,CACnC,IAAI,EAAE;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EACzF,GAAG,SAAa,GACf,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAqD9C"}

package/dist/cron/ai-cost.js

@@ -0,0 +1,80 @@
+/**
+ * The AI Gateway's USD, after the fact (spec 2026-10-02 §6.2). A gateway call's cost is not in its
+ * response — it is on the gateway's log entry, readable a few seconds later. The facts lane writes
+ * the call to `ai_calls` (builder.ts); this job, every fifth minute, reads each pending row's log
+ * and records `cost` as micro-USD. For operators and admin apps only — no verdict reads it.
+ *
+ * Bounded: 50 rows a run, oldest first, none younger than 60 s (the log may not be written yet).
+ * A log not found for an hour is `unavailable` (logging off, retention), as is a log with no cost
+ * (a model the gateway has no price for). The log API itself failing (anything but "not found")
+ * stops the run — one report, no hammering, nothing closed, the next run asks again — and only a
+ * row it has refused for a day is closed, so nothing blocks the queue for good.
+ * Never an alert: missing analytics is not a person's emergency. No `AI` binding ⇒ a no-op.
+ */
+import { and, asc, eq, lt } from "drizzle-orm";
+import { aiCalls } from "../db/schema.js";
+import { reportError } from "../lib/sentry.js";
+const BATCH = 50;
+const SETTLE_MS = 60_000;
+/** A log still not found after this is gone (logging off, retention). */
+const GIVE_UP_MS = 60 * 60_000;
+/** The log API refusing a row this long is not a blip — close it so the queue moves. */
+const API_GIVE_UP_MS = 24 * 60 * 60_000;
+const RETAIN_MS = 90 * 24 * 60 * 60_000;
+export async function backfillAiCosts(deps, now = Date.now()) {
+    const done = { ok: 0, unavailable: 0 };
+    const ai = deps.env.AI;
+    const gatewayId = deps.config.AI_GATEWAY_ID;
+    if (!ai || !gatewayId)
+        return done;
+    const { db, logger } = deps;
+    await db.delete(aiCalls).where(lt(aiCalls.createdAt, new Date(now - RETAIN_MS)));
+    const due = await db
+        .select()
+        .from(aiCalls)
+        .where(and(eq(aiCalls.costStatus, "pending"), lt(aiCalls.createdAt, new Date(now - SETTLE_MS))))
+        .orderBy(asc(aiCalls.createdAt))
+        .limit(BATCH);
+    const gateway = ai.gateway(gatewayId);
+    for (const row of due) {
+        let cost;
+        try {
+            cost = (await gateway.getLog(row.callId)).cost;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const age = now - row.createdAt.getTime();
+            if (/not ?found/i.test(detail)) {
+                if (age < GIVE_UP_MS)
+                    continue; // not written yet — the next run asks again
+            }
+            else if (age < API_GIVE_UP_MS) {
+                // The log API itself is failing (an outage, a permission): stop here rather than hammer it
+                // for the rest of the batch. Nothing is closed — a blip must not cost the analytics.
+                logger.warn("ai.cost.read-failed", { callId: row.callId, detail });
+                reportError(err, { lane: "cron", step: "ai-cost" });
+                break;
+            }
+            cost = null; // gone, or refused for a day: close it so it never blocks the queue
+        }
+        if (typeof cost === "number" && Number.isFinite(cost)) {
+            const micro = Math.round(cost * 1_000_000);
+            await db
+                .update(aiCalls)
+                .set({ costMicroUsd: micro, costStatus: "ok", costAt: new Date(now) })
+                .where(eq(aiCalls.callId, row.callId));
+            deps.metrics?.count("ai.cost_micro_usd", micro, { op: row.model, outcome: "cloudflare" });
+            done.ok++;
+        }
+        else {
+            await db
+                .update(aiCalls)
+                .set({ costStatus: "unavailable", costAt: new Date(now) })
+                .where(eq(aiCalls.callId, row.callId));
+            logger.info("ai.cost.unavailable", { callId: row.callId, model: row.model });
+            done.unavailable++;
+        }
+    }
+    return done;
+}
+//# sourceMappingURL=ai-cost.js.map

package/dist/cron/ai-cost.js.map

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

package/dist/cron/api-lane.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The Decision API lane's share of each cron tier (Go Prod §7.3; the tiers are cron/scan.ts
+ * `CRON_TIERS`), a no-op unless `API_LANE` is on.
+ *
+ * minute:
+ *   - resume: sources paused `engine-credits` come back once the engine's `/me` says ok (one read,
+ *     only while one is paused) — the sources' half of `cron/billing.ts`; and per-review
+ *     collections paused for payment (cron/payer-billing.ts);
+ *   - webhook retry: every delivery whose `nextAttemptAt` has come (lib/api-lane/webhooks.ts); an
+ *     event enqueued without an inline attempt (`source.*`, `payment.settled`, `balance.low`) gets
+ *     its first one here;
+ *   - review batches: the review emails held for a member's 15-minute window go out as one once
+ *     it has run out (lib/api-lane/reviewers.ts, §10.1) — at most `FLUSH_MEMBERS` members a tick;
+ *   - the lane's backlog gauges (cron/backlog.ts), after the retry so they show what it left.
+ * five (with a facilitator configured — `X402_FACILITATOR_URL`, not `API_PAYMENTS`, whose off must
+ * never strand a claim already paid), the payment crons (lib/payments/reconcile.ts):
+ *   - the reconcile (start reserved claims whose start was lost, re-settle decided claims until
+ *     their transfer is paid), then the unsettled-charge gauge, which shows what it left;
+ *   - the balance watch (`balance.low`).
+ * hour:
+ *   - housekeeping: the operational records' trim and the uploads an organisation's own action
+ *     marked (lib/api-lane/retention.ts) — never a claim's content or personal data, which only the
+ *     organisation erases. A missed hour is caught up by the next — the sweep reads by time;
+ *   - the legacy payment-header seal and the review-billing delegation reminders;
+ *   - reviewers: the 3- and 14-day reminders for claims nobody answered (§10.4), the
+ *     `claim.review_expired` announcement for a paid review closed unanswered at its `answerBy`
+ *     (lib/api-lane/notify.ts), and the review rooms' membership (kick whoever's grant ended;
+ *     `ROOMS_PER_PASS` rooms an hour, least recently synced first) — all read by time;
+ *   - linked collections: each link's linker must still be a member who may link and the
+ *     collection's owner on chain (a company link: the engine still names that company), else the
+ *     link goes (every link an hour up to `RECHECK_CAP`, least recently checked first; a failed
+ *     read keeps the link but leaves it unverified — lib/api-lane/linked.ts).
+ * Each job is contained: one failing never stops the others.
+ */
+import type { CronCtx } from "./collection.js";
+import type { CronTier } from "./scan.js";
+/** `tier`: the trigger that fired (cron/scan.ts) — only its jobs run. */
+export declare function runApiLaneTick(ctx: CronCtx, tier: CronTier, now?: Date): Promise<void>;
+//# sourceMappingURL=api-lane.d.ts.map

package/dist/cron/api-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-lane.d.ts","sourceRoot":"","sources":["../../src/cron/api-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAkBH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC,yEAAyE;AACzE,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,OAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAsJf"}

package/dist/cron/api-lane.js

@@ -0,0 +1,203 @@
+/**
+ * The Decision API lane's share of each cron tier (Go Prod §7.3; the tiers are cron/scan.ts
+ * `CRON_TIERS`), a no-op unless `API_LANE` is on.
+ *
+ * minute:
+ *   - resume: sources paused `engine-credits` come back once the engine's `/me` says ok (one read,
+ *     only while one is paused) — the sources' half of `cron/billing.ts`; and per-review
+ *     collections paused for payment (cron/payer-billing.ts);
+ *   - webhook retry: every delivery whose `nextAttemptAt` has come (lib/api-lane/webhooks.ts); an
+ *     event enqueued without an inline attempt (`source.*`, `payment.settled`, `balance.low`) gets
+ *     its first one here;
+ *   - review batches: the review emails held for a member's 15-minute window go out as one once
+ *     it has run out (lib/api-lane/reviewers.ts, §10.1) — at most `FLUSH_MEMBERS` members a tick;
+ *   - the lane's backlog gauges (cron/backlog.ts), after the retry so they show what it left.
+ * five (with a facilitator configured — `X402_FACILITATOR_URL`, not `API_PAYMENTS`, whose off must
+ * never strand a claim already paid), the payment crons (lib/payments/reconcile.ts):
+ *   - the reconcile (start reserved claims whose start was lost, re-settle decided claims until
+ *     their transfer is paid), then the unsettled-charge gauge, which shows what it left;
+ *   - the balance watch (`balance.low`).
+ * hour:
+ *   - housekeeping: the operational records' trim and the uploads an organisation's own action
+ *     marked (lib/api-lane/retention.ts) — never a claim's content or personal data, which only the
+ *     organisation erases. A missed hour is caught up by the next — the sweep reads by time;
+ *   - the legacy payment-header seal and the review-billing delegation reminders;
+ *   - reviewers: the 3- and 14-day reminders for claims nobody answered (§10.4), the
+ *     `claim.review_expired` announcement for a paid review closed unanswered at its `answerBy`
+ *     (lib/api-lane/notify.ts), and the review rooms' membership (kick whoever's grant ended;
+ *     `ROOMS_PER_PASS` rooms an hour, least recently synced first) — all read by time;
+ *   - linked collections: each link's linker must still be a member who may link and the
+ *     collection's owner on chain (a company link: the engine still names that company), else the
+ *     link goes (every link an hour up to `RECHECK_CAP`, least recently checked first; a failed
+ *     read keeps the link but leaves it unverified — lib/api-lane/linked.ts).
+ * Each job is contained: one failing never stops the others.
+ */
+import { and, eq } from "drizzle-orm";
+import { loadConfig } from "../config.js";
+import { apiSources } from "../db/schema.js";
+import { recheckCollectionLinks } from "../lib/api-lane/linked.js";
+import { announceExpiredReviews } from "../lib/api-lane/notify.js";
+import { resumeCreditPausedSources } from "../lib/api-lane/pause.js";
+import { sweepHousekeeping } from "../lib/api-lane/retention.js";
+import { flushReviewBatches, remindReviewers, syncReviewRooms } from "../lib/api-lane/reviewers.js";
+import { deliverDueWebhooks } from "../lib/api-lane/webhooks.js";
+import { createEngineClient } from "../lib/engine/client.js";
+import { timeCronJob } from "../lib/metrics.js";
+import { sealLegacyHeaders } from "../lib/payments/header-seal.js";
+import { reconcilePayments, watchBalances } from "../lib/payments/reconcile.js";
+import { remindCapDelegations, remindExpiringDelegations } from "../lib/payments/review-billing.js";
+import { reportAlert, reportError } from "../lib/sentry.js";
+import { apiBacklog, chargeBacklog } from "./backlog.js";
+import { resumePayerBilling } from "./payer-billing.js";
+/** `tier`: the trigger that fired (cron/scan.ts) — only its jobs run. */
+export async function runApiLaneTick(ctx, tier, now = new Date()) {
+    const config = loadConfig(ctx.env);
+    if (!config.API_LANE)
+        return;
+    const { db, logger } = ctx;
+    const alerts = { config, cache: ctx.env.CACHE_KV, logger };
+    const job = async (name, run) => {
+        try {
+            await timeCronJob(ctx.metrics, `api-lane.${name}`, run);
+        }
+        catch (err) {
+            logger.error(`cron.api-lane.${name}.failed`, {
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            // A job that fails here fails every minute until someone looks — the retries, the reconcile
+            // and the housekeeping sweep have no other owner.
+            reportError(err, { lane: "api-lane", step: name });
+            await reportAlert(alerts, `api-lane.job-failed.${name}`, { job: name });
+        }
+    };
+    const reviewers = {
+        db,
+        config,
+        logger,
+        metrics: ctx.metrics,
+        trace: ctx.deps.trace,
+        cache: ctx.env.CACHE_KV,
+        email: ctx.env.EMAIL,
+    };
+    if (tier === "minute") {
+        await minute();
+    }
+    else if (tier === "five") {
+        await five();
+    }
+    else {
+        await hour();
+    }
+    async function minute() {
+        await job("resume", async () => {
+            const paused = await db
+                .select({ sourceId: apiSources.sourceId })
+                .from(apiSources)
+                .where(and(eq(apiSources.status, "paused"), eq(apiSources.pausedReason, "engine-credits")))
+                .limit(1);
+            if (paused.length === 0)
+                return;
+            const engine = createEngineClient({
+                config,
+                trace: ctx.deps.trace,
+                logger,
+                cache: ctx.env.CACHE_KV,
+            });
+            // Unreachable is not "funded": stay paused until the engine says so (warn, as billing.ts does).
+            const me = await engine.me().catch((err) => {
+                logger.warn("cron.api-lane.engine-credits.unreadable", { detail: String(err) });
+                return null;
+            });
+            if (me?.billingStatus === "ok")
+                await resumeCreditPausedSources(db, logger);
+        });
+        // Per-review collections paused for payment (cron/payer-billing.ts): only while one is.
+        await job("payer-billing-resume", async () => {
+            const resumed = await resumePayerBilling({
+                db,
+                config,
+                logger,
+                metrics: ctx.metrics,
+                trace: ctx.deps.trace,
+                cache: ctx.env.CACHE_KV,
+                env: ctx.env,
+            });
+            if (resumed.length > 0)
+                logger.info("cron.payer-billing.resumed-all", { resumed });
+        });
+        await job("webhooks", async () => {
+            const attempted = await deliverDueWebhooks({
+                db,
+                config,
+                logger,
+                metrics: ctx.metrics,
+                cache: ctx.env.CACHE_KV,
+            });
+            if (attempted > 0)
+                logger.info("cron.webhooks.attempted", { attempted });
+        });
+        await apiBacklog(ctx, now);
+        await job("review-batches", async () => {
+            const sent = await flushReviewBatches(reviewers, now);
+            if (sent > 0)
+                logger.info("cron.review-batches.sent", { sent });
+        });
+    }
+    async function five() {
+        if (!config.X402_FACILITATOR_URL)
+            return;
+        const pay = { config, logger, trace: ctx.deps.trace, cache: ctx.env.CACHE_KV, db };
+        await job("payments-reconcile", () => reconcilePayments({ ...pay, env: ctx.env }, now));
+        // After the reconcile, so it shows what arm (b) left; not every minute (cron/backlog.ts says why).
+        await chargeBacklog(ctx, now);
+        await job("balance-watch", () => watchBalances({ ...pay, metrics: ctx.metrics, email: ctx.env.EMAIL }, now));
+    }
+    async function hour() {
+        // Still named "retention": the `api-lane.retention` timing and the `api-lane.job-failed.retention`
+        // alert (decision-engine ops/runbooks) key on it. The job is the housekeeping sweep.
+        await job("retention", async () => {
+            const swept = await sweepHousekeeping(db, ctx.env.API_UPLOADS, now);
+            logger.info("cron.housekeeping.swept", swept);
+        });
+        // Charge rows written before payment headers were sealed (payments/header-seal.ts): a page an
+        // hour until none is left in the clear.
+        await job("header-seal", async () => {
+            const sealed = await sealLegacyHeaders(db, config);
+            if (sealed > 0)
+                logger.info("cron.header-seal.sealed", { sealed });
+        });
+        await job("review-billing-reminders", async () => {
+            await remindExpiringDelegations(reviewers, now);
+            await remindCapDelegations(reviewers, now);
+        });
+        await job("review-reminders", async () => {
+            const sent = await remindReviewers(reviewers, now);
+            if (sent > 0)
+                logger.info("cron.review-reminders.sent", { sent });
+        });
+        await job("review-expiry", async () => {
+            const expired = await announceExpiredReviews(db, now);
+            if (expired > 0)
+                logger.info("cron.review-expiry.announced", { expired });
+        });
+        await job("review-rooms", () => syncReviewRooms(reviewers, now));
+        await job("collection-links", async () => {
+            // A company link (register's) is held to the engine's company answer, not a member's.
+            const engine = createEngineClient({
+                config,
+                trace: ctx.deps.trace,
+                logger,
+                cache: ctx.env.CACHE_KV,
+            });
+            const dropped = await recheckCollectionLinks({
+                db,
+                config,
+                logger,
+                trace: ctx.deps.trace,
+                companyOf: (id) => engine.getCollectionCompany(id),
+            }, now);
+            logger.info("cron.collection-links.rechecked", { dropped });
+        });
+    }
+}
+//# sourceMappingURL=api-lane.js.map

package/dist/cron/api-lane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-lane.js","sourceRoot":"","sources":["../../src/cron/api-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AACjG,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrD,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAY,EACZ,IAAc,EACd,GAAG,GAAG,IAAI,IAAI,EAAE;IAEhB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ;QAAE,OAAO;IAC7B,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC3D,MAAM,GAAG,GAAG,KAAK,EAAE,IAAY,EAAE,GAA2B,EAAE,EAAE;QAC9D,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,iBAAiB,IAAI,SAAS,EAAE;gBAC3C,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACzD,CAAC,CAAC;YACH,4FAA4F;YAC5F,kDAAkD;YAClD,WAAW,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,WAAW,CAAC,MAAM,EAAE,uBAAuB,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CAAC;IACF,MAAM,SAAS,GAAG;QAChB,EAAE;QACF,MAAM;QACN,MAAM;QACN,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;QACrB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;QACvB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK;KACrB,CAAC;IAEF,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,MAAM,MAAM,EAAE,CAAC;IACjB,CAAC;SAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,EAAE,CAAC;IACf,CAAC;IAED,KAAK,UAAU,MAAM;QACnB,MAAM,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAC7B,MAAM,MAAM,GAAG,MAAM,EAAE;iBACpB,MAAM,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;iBACzC,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC;iBAC1F,KAAK,CAAC,CAAC,CAAC,CAAC;YACZ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAChC,MAAM,MAAM,GAAG,kBAAkB,CAAC;gBAChC,MAAM;gBACN,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;gBACrB,MAAM;gBACN,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,gGAAgG;YAChG,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACzC,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChF,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;YACH,IAAI,EAAE,EAAE,aAAa,KAAK,IAAI;gBAAE,MAAM,yBAAyB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;QAEH,wFAAwF;QACxF,MAAM,GAAG,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE;YAC3C,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC;gBACvC,EAAE;gBACF,MAAM;gBACN,MAAM;gBACN,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;gBACrB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;gBACvB,GAAG,EAAE,GAAG,CAAC,GAAG;aACb,CAAC,CAAC;YACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACrF,CAAC,CAAC,CAAC;QAEH,MAAM,GAAG,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;YAC/B,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC;gBACzC,EAAE;gBACF,MAAM;gBACN,MAAM;gBACN,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,IAAI,SAAS,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;QAEH,MAAM,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAE3B,MAAM,GAAG,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;YACrC,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACtD,IAAI,IAAI,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,UAAU,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,oBAAoB;YAAE,OAAO;QACzC,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;QACnF,MAAM,GAAG,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,EAAE,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACxF,mGAAmG;QACnG,MAAM,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC9B,MAAM,GAAG,CAAC,eAAe,EAAE,GAAG,EAAE,CAC9B,aAAa,CAAC,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,CAC3E,CAAC;IACJ,CAAC;IAED,KAAK,UAAU,IAAI;QACjB,mGAAmG;QACnG,qFAAqF;QACrF,MAAM,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YAChC,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;YACpE,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,8FAA8F;QAC9F,wCAAwC;QACxC,MAAM,GAAG,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;YAClC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YACnD,IAAI,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE;YAC/C,MAAM,yBAAyB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YAChD,MAAM,oBAAoB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,CAAC,kBAAkB,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACnD,IAAI,IAAI,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,CAAC,eAAe,EAAE,KAAK,IAAI,EAAE;YACpC,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACtD,IAAI,OAAO,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;QAEjE,MAAM,GAAG,CAAC,kBAAkB,EAAE,KAAK,IAAI,EAAE;YACvC,sFAAsF;YACtF,MAAM,MAAM,GAAG,kBAAkB,CAAC;gBAChC,MAAM;gBACN,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;gBACrB,MAAM;gBACN,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAC1C;gBACE,EAAE;gBACF,MAAM;gBACN,MAAM;gBACN,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;gBACrB,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,CAAC;aACnD,EACD,GAAG,CACJ,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/cron/backlog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The backlog gauges, once per minute tick (observability spec §2.2): what is waiting, and how
+ * long the oldest of it has waited — the numbers an operator alerts on before a customer notices.
+ * Every query is served by an existing index or reads a table with one row per customer, so a
+ * tick costs a handful of index reads however large the ledgers grow:
+ *   - `collections.paused` — `watched_collections (status, lastScannedAt)`;
+ *   - `review.pending` — `decisions (status, createdAt)` (a fold moves the row off `pending_review`);
+ *   - `backlog.webhook.*` — `matrix_deliveries (kind, status, nextAttemptAt)`, the retry cron's own;
+ *   - `sources.paused` — `api_sources`, one row per source;
+ *   - `backlog.charge.unsettled.oldest_age_s` (with a facilitator configured) — a decided claim
+ *     with a receipt whose charge is still `reserved`: the facilitator has not accepted the receipt
+ *     (the reconcile's arm (b)). `api_charges (status, updatedAt)` narrows to the `reserved` rows
+ *     and each joins `decisions` by its primary key — but the reserved set is every live
+ *     reservation (claims in flight, reviews held for up to 30 days, failed claims waiting out
+ *     their 24 h), which grows with traffic, so this one is read after the five-minute reconcile
+ *     rather than every minute. Age from the decision row's `updatedAt` (the receipt landed with it).
+ * Not here: the oldest queued / processing ingest, for want of an index (`claim_ingests` has no
+ * `status` index, and migrations are not this lane's to add) — it would scan the whole ledger every
+ * minute.
+ *
+ * Best-effort: a gauge that cannot be read is a warn, never a failed tick.
+ */
+import type { Database } from "../db/client.js";
+import type { CronCtx } from "./collection.js";
+/** Paused rows per reason (`unknown` for none), plus a `total` that is always present. */
+export type ByReason = Record<string, number> & {
+    total: number;
+};
+export interface ChainBacklog {
+    reviewPending: number;
+    collectionsPaused: ByReason;
+}
+export interface ApiBacklog {
+    webhookDue: number;
+    webhookOldestAgeS: number;
+    sourcesPaused: ByReason;
+}
+/**
+ * The chain lane's share: paused collections by reason, decisions waiting for a reviewer. Read
+ * here, emitted by `chainBacklog` — the operator status route (routes/v1/admin.ts) serves the same
+ * numbers live.
+ */
+export declare function readChainBacklog(db: Database): Promise<ChainBacklog>;
+/** The Decision API lane's share: webhooks due for an attempt, and paused sources by reason. */
+export declare function readApiBacklog(db: Database, now: Date): Promise<ApiBacklog>;
+export declare function chainBacklog(ctx: CronCtx): Promise<void>;
+export declare function apiBacklog(ctx: CronCtx, now: Date): Promise<void>;
+/** Decided claims whose receipt the facilitator has not accepted: how long the oldest has waited. */
+export declare function chargeBacklog(ctx: CronCtx, now: Date): Promise<void>;
+//# sourceMappingURL=backlog.d.ts.map

package/dist/cron/backlog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlog.d.ts","sourceRoot":"","sources":["../../src/cron/backlog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAS7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,QAAQ,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAU1E;AAED,gGAAgG;AAChG,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAwBjF;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE;AAWD,qGAAqG;AACrG,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAS1E"}