@supersolutions/super-router-storage-postgres 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,563 @@
+import { revalidate } from "./access.js";
+import pg from "pg";
+import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { Service, RouterError, EventSchema, } from "@supersolutions/super-router-contracts";
+import { charge, } from "@supersolutions/super-router-core";
+export const LOCAL_DATABASE_URL = "postgresql://superrouter:local-development-only@127.0.0.1:25432/superrouter";
+const scope = (p) => [p.workspace, p.environment];
+export class PostgresStore {
+    pool;
+    constructor(url) {
+        this.pool = new pg.Pool({ connectionString: url, max: 10 });
+    }
+    async close() {
+        await this.pool.end();
+    }
+    async migrate() {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            await c.query("SELECT pg_advisory_xact_lock(hashtextextended('superrouter:migrate',0))");
+            await c.query("CREATE TABLE IF NOT EXISTS sr_migrations(version integer PRIMARY KEY)");
+            const r = await c.query("SELECT 1 FROM sr_migrations WHERE version=1");
+            if (!r.rowCount) {
+                await c.query(await readFile(new URL("../migrations/001_initial.sql", import.meta.url), "utf8"));
+                await c.query("INSERT INTO sr_migrations VALUES(1)");
+            }
+            for (const [version, file] of [
+                [2, "002_integrity.sql"],
+                [3, "003_membership_subscriptions.sql"],
+                [4, "004_integration_bindings.sql"],
+                [5, "005_checkouts.sql"],
+            ]) {
+                const done = await c.query("SELECT 1 FROM sr_migrations WHERE version=$1", [version]);
+                if (!done.rowCount) {
+                    await c.query(await readFile(new URL("../migrations/" + file, import.meta.url), "utf8"));
+                    await c.query("INSERT INTO sr_migrations VALUES($1)", [version]);
+                }
+            }
+            await c.query("COMMIT");
+        }
+        catch (e) {
+            await c.query("ROLLBACK");
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async tx(p, fn) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            await c.query("SELECT pg_advisory_xact_lock(hashtextextended($1,0))", [
+                JSON.stringify(scope(p)),
+            ]);
+            const out = await fn(c);
+            await c.query("COMMIT");
+            return out;
+        }
+        catch (e) {
+            await c.query("ROLLBACK");
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async row(c, p, id) {
+        const r = await c.query("SELECT * FROM sr_requests WHERE workspace=$1 AND environment=$2 AND id=$3 AND customer=$4", [...scope(p), id, p.customer]);
+        if (!r.rows[0])
+            throw new RouterError("resource_not_found", 404);
+        if (p.service_ids && !p.service_ids.includes(r.rows[0].service.id))
+            throw new RouterError("scope_denied", 403);
+        return {
+            ...r.rows[0],
+            service: Service.parse(r.rows[0].service),
+        };
+    }
+    async replay(p, key, digest) {
+        const r = await this.pool.query("SELECT * FROM sr_requests WHERE workspace=$1 AND environment=$2 AND idem=$3", [...scope(p), key]);
+        if (!r.rows[0])
+            return null;
+        if (r.rows[0].digest !== digest || r.rows[0].customer !== p.customer)
+            throw new RouterError("idempotency_conflict", 409);
+        return r.rows[0];
+    }
+    async get(p, id) {
+        return this.row(this.pool, p, id);
+    }
+    async publish(p, raw, mode = "self-host", expectedVersion) {
+        if (!p.scopes.includes("service:write"))
+            throw new RouterError("scope_denied", 403);
+        const s = Service.parse(raw);
+        if (p.service_ids && !p.service_ids.includes(s.id))
+            throw new RouterError("scope_denied", 403);
+        if (mode === "cloud" && s.offerings.some((o) => o.source === "byok"))
+            throw new RouterError("byok_not_allowed", 403);
+        await this.tx(p, async (c) => {
+            await revalidate(c, p, "service:write");
+            const latest = await c.query("SELECT config,version FROM sr_services WHERE workspace=$1 AND environment=$2 AND id=$3 ORDER BY version DESC LIMIT 1", [...scope(p), s.id]);
+            const previous = latest.rows[0]
+                ? Service.parse(latest.rows[0].config)
+                : undefined;
+            if (expectedVersion !== undefined &&
+                previous?.version !== expectedVersion)
+                throw new RouterError("service_version_conflict", 409);
+            if (mode === "cloud" && p.auth_key_id) {
+                // Database-authenticated developers cannot provision or rewrite platform supply economics.
+                if (!previous ||
+                    JSON.stringify(previous.platform_price) !==
+                        JSON.stringify(s.platform_price) ||
+                    JSON.stringify(previous.offerings) !== JSON.stringify(s.offerings))
+                    throw new RouterError("platform_pricing_protected", 403);
+            }
+            const r = await c.query("SELECT config FROM sr_services WHERE workspace=$1 AND environment=$2 AND id=$3 AND version=$4", [...scope(p), s.id, s.version]);
+            if (r.rowCount) {
+                if (JSON.stringify(Service.parse(r.rows[0].config)) !== JSON.stringify(s))
+                    throw new RouterError("version_exists", 409);
+                return;
+            }
+            if (previous && s.version <= previous.version)
+                throw new RouterError("service_version_conflict", 409);
+            await c.query("UPDATE sr_services SET active=false WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), s.id]);
+            await c.query("INSERT INTO sr_services(workspace,environment,id,version,config) VALUES($1,$2,$3,$4,$5)", [...scope(p), s.id, s.version, s]);
+            await c.query("INSERT INTO sr_audit(id,workspace,environment,actor,action,resource,details) VALUES($1,$2,$3,$4,$5,$6,$7)", [
+                randomUUID(),
+                ...scope(p),
+                p.member_id ?? "trusted-host",
+                "service.published",
+                s.id,
+                { version: s.version },
+            ]);
+        });
+        return s;
+    }
+    async getService(p, id, version) {
+        if (p.service_ids && !p.service_ids.includes(id))
+            throw new RouterError("scope_denied", 403);
+        const r = await this.pool.query(`SELECT config FROM sr_services WHERE workspace=$1 AND environment=$2 AND id=$3 AND ${version === undefined ? "active=true" : "version=$4"}`, [...scope(p), id, ...(version === undefined ? [] : [version])]);
+        if (!r.rows[0])
+            throw new RouterError("resource_not_found", 404);
+        return Service.parse(r.rows[0].config);
+    }
+    async list(p) {
+        const r = await this.pool.query("SELECT config FROM sr_services WHERE workspace=$1 AND environment=$2 AND active=true ORDER BY id LIMIT 100", scope(p));
+        return r.rows
+            .map((x) => Service.parse(x.config))
+            .filter((s) => !p.service_ids || p.service_ids.includes(s.id));
+    }
+    async grant(p, kind, asset, amount, source, expires) {
+        if (!p.scopes.includes("billing:write"))
+            throw new RouterError("scope_denied", 403);
+        if (!/^[1-9][0-9]{0,29}$/.test(amount))
+            throw new RouterError("invalid_amount");
+        return this.tx(p, async (c) => {
+            await revalidate(c, p, "billing:write");
+            return this.grantTx(c, p, kind, asset, amount, source, expires);
+        });
+    }
+    /** Internal trusted composition: caller owns the tenant transaction and authorization. */
+    async grantTx(c, p, kind, asset, amount, source, expires, serviceIds, sourceKind = "purchased") {
+        const owner = kind === "platform_sale" ? p.workspace : p.customer;
+        const prior = await c.query("SELECT b.*,a.asset,a.owner,a.kind FROM sr_buckets b JOIN sr_accounts a ON (a.workspace,a.environment,a.id)=(b.workspace,b.environment,b.account) WHERE b.workspace=$1 AND b.environment=$2 AND b.source=$3", [...scope(p), source]);
+        if (prior.rows[0]) {
+            const b = prior.rows[0];
+            if (b.granted !== amount ||
+                b.asset !== asset ||
+                b.owner !== owner ||
+                b.kind !== kind ||
+                (b.expires_at?.toISOString() ?? null) !==
+                    (expires?.toISOString() ?? null))
+                throw new RouterError("idempotency_conflict", 409);
+            if (JSON.stringify(b.service_ids ?? null) !==
+                JSON.stringify(serviceIds ?? null) ||
+                b.source_kind !== sourceKind)
+                throw new RouterError("idempotency_conflict", 409);
+            return b.account;
+        }
+        await c.query("INSERT INTO sr_accounts(workspace,environment,id,owner,kind,asset) VALUES($1,$2,$3,$4,$5,$6) ON CONFLICT(workspace,environment,owner,kind,asset) DO NOTHING", [...scope(p), randomUUID(), owner, kind, asset]);
+        const r = await c.query("SELECT id FROM sr_accounts WHERE workspace=$1 AND environment=$2 AND owner=$3 AND kind=$4 AND asset=$5", [...scope(p), owner, kind, asset]);
+        const account = r.rows[0].id;
+        await c.query("UPDATE sr_accounts SET balance=balance+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), account, amount]);
+        await c.query("INSERT INTO sr_buckets(workspace,environment,id,account,source,expires_at,remaining,granted,service_ids,source_kind) VALUES($1,$2,$3,$4,$5,$6,$7,$7,$8,$9)", [
+            ...scope(p),
+            randomUUID(),
+            account,
+            source,
+            expires ?? null,
+            amount,
+            serviceIds ?? null,
+            sourceKind,
+        ]);
+        await c.query("INSERT INTO sr_journal(workspace,environment,business_key,asset,debit,credit,amount,reason) VALUES($1,$2,$3,$4,$5,$6,$7,$8)", [
+            ...scope(p),
+            "grant:" + source,
+            asset,
+            "issuer:" + asset,
+            account,
+            amount,
+            "grant",
+        ]);
+        return account;
+    }
+    async accounts(p, s) {
+        const legs = [];
+        for (const [kind, price] of [
+            ["customer_sale", s.price],
+            ["platform_sale", s.platform_price],
+        ]) {
+            if (!price)
+                continue;
+            const owner = kind === "platform_sale" ? p.workspace : p.customer;
+            const r = await this.pool.query("SELECT id FROM sr_accounts WHERE workspace=$1 AND environment=$2 AND owner=$3 AND kind=$4 AND asset=$5", [...scope(p), owner, kind, price.asset]);
+            if (!r.rows[0])
+                throw new RouterError("insufficient_balance", 402);
+            legs.push({ kind, account: r.rows[0].id, price, reserved: "0" });
+        }
+        return legs;
+    }
+    async reserve(p, key, digest, service, legs, deadline, decision) {
+        return this.tx(p, async (c) => {
+            await revalidate(c, p, "invoke");
+            if (p.service_ids && !p.service_ids.includes(service.id))
+                throw new RouterError("scope_denied", 403);
+            if (service.requires_subscription) {
+                const entitlement = await c.query("SELECT 1 FROM sr_entitlements WHERE workspace=$1 AND environment=$2 AND customer=$3 AND $4=ANY(service_ids) AND period_start<=now() AND period_end>now()", [...scope(p), p.customer, service.id]);
+                if (!entitlement.rowCount)
+                    throw new RouterError("subscription_required", 403);
+            }
+            const old = await c.query("SELECT * FROM sr_requests WHERE workspace=$1 AND environment=$2 AND idem=$3", [...scope(p), key]);
+            if (old.rows[0]) {
+                if (old.rows[0].digest !== digest ||
+                    old.rows[0].customer !== p.customer)
+                    throw new RouterError("idempotency_conflict", 409);
+                return { request: old.rows[0], fresh: false };
+            }
+            // Admission and service publication share the tenant transaction lock.
+            // Replays keep their admitted snapshot; fresh work must reserve the active price.
+            const active = await c.query("SELECT 1 FROM sr_services WHERE workspace=$1 AND environment=$2 AND id=$3 AND version=$4 AND active=true", [...scope(p), service.id, service.version]);
+            if (!active.rowCount)
+                throw new RouterError("inactive_service_version", 409);
+            const id = randomUUID();
+            await c.query("INSERT INTO sr_requests(workspace,environment,id,customer,idem,digest,service,legs,deadline,route_decision) VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)", [
+                ...scope(p),
+                id,
+                p.customer,
+                key,
+                digest,
+                service,
+                JSON.stringify(legs),
+                deadline,
+                decision ?? null,
+            ]);
+            for (const leg of [...legs].sort((a, b) => a.account.localeCompare(b.account))) {
+                let remaining = BigInt(leg.reserved);
+                const buckets = await c.query("SELECT * FROM sr_buckets WHERE workspace=$1 AND environment=$2 AND account=$3 AND (expires_at IS NULL OR expires_at>now()) AND (service_ids IS NULL OR $4=ANY(service_ids)) ORDER BY expires_at ASC NULLS LAST, CASE source_kind WHEN 'subscription' THEN 0 WHEN 'promotion' THEN 1 ELSE 2 END,id FOR UPDATE", [...scope(p), leg.account, service.id]);
+                for (const b of buckets.rows) {
+                    const available = BigInt(b.remaining) - BigInt(b.held);
+                    const take = available < remaining ? available : remaining;
+                    if (take <= 0n)
+                        continue;
+                    await c.query("UPDATE sr_buckets SET held=held+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), b.id, take.toString()]);
+                    await c.query("INSERT INTO sr_allocations(workspace,environment,request,bucket,account,amount) VALUES($1,$2,$3,$4,$5,$6)", [...scope(p), id, b.id, leg.account, take.toString()]);
+                    remaining -= take;
+                    if (!remaining)
+                        break;
+                }
+                if (remaining > 0n)
+                    throw new RouterError("insufficient_balance", 402);
+                await c.query("UPDATE sr_accounts SET held=held+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), leg.account, leg.reserved]);
+            }
+            return { request: await this.row(c, p, id), fresh: true };
+        });
+    }
+    async begin(p, id, o, bound) {
+        return this.tx(p, async (c) => {
+            await revalidate(c, p, "invoke");
+            const r = await this.row(c, p, id);
+            if (r.cancel_requested || Date.now() > new Date(r.deadline).getTime())
+                throw new RouterError("cancelled", 409);
+            if (r.billing !== "reserved")
+                throw new RouterError("state_conflict", 409);
+            const disabled = await c.query("SELECT 1 FROM sr_disabled_connections WHERE workspace=$1 AND environment=$2 AND offering=$3", [...scope(p), o.id]);
+            if (disabled.rowCount)
+                throw new RouterError("connection_disabled", 409);
+            const snapshot = r.service.offerings.find((x) => x.id === o.id);
+            if (!snapshot || JSON.stringify(snapshot) !== JSON.stringify(o))
+                throw new RouterError("state_conflict", 409);
+            const sum = await c.query("SELECT provider_spent+provider_held+$4::numeric AS total FROM sr_requests WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id, bound]);
+            if (BigInt(sum.rows[0].total) > BigInt(r.service.max_provider_cost))
+                throw new RouterError("budget_exceeded", 402);
+            const attempt = randomUUID();
+            await c.query("INSERT INTO sr_attempts(workspace,environment,id,request,offering,cost_bound) VALUES($1,$2,$3,$4,$5,$6)", [...scope(p), attempt, id, o.id, bound]);
+            await c.query("UPDATE sr_requests SET execution='running',provider_held=provider_held+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id, bound]);
+            return attempt;
+        });
+    }
+    async output(p, id) {
+        await this.tx(p, async (c) => {
+            await this.row(c, p, id);
+            await c.query("UPDATE sr_requests SET output_started=true WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id]);
+        });
+    }
+    async attemptResult(p, id, attempt, status, usage, cost, upstream) {
+        await this.tx(p, async (c) => {
+            const r = await this.row(c, p, id);
+            if (!["reserved", "pending"].includes(r.billing))
+                throw new RouterError("state_conflict", 409);
+            const a = await c.query("SELECT * FROM sr_attempts WHERE workspace=$1 AND environment=$2 AND id=$3 AND request=$4 FOR UPDATE", [...scope(p), attempt, id]);
+            const row = a.rows[0];
+            if (!row)
+                throw new RouterError("resource_not_found", 404);
+            if (row.status !== "dispatched")
+                return;
+            await c.query("UPDATE sr_attempts SET status=$4,usage=$5,cost=$6,upstream_id=$7 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), attempt, status, usage, cost, upstream ?? null]);
+            if (cost !== null)
+                await c.query("UPDATE sr_requests SET provider_spent=provider_spent+$4,provider_held=provider_held-$5 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id, cost, row.cost_bound]);
+        });
+    }
+    async event(c, p, id, type) {
+        const payload = EventSchema.parse({
+            id: randomUUID(),
+            type,
+            schema_version: 1,
+            workspace_id: p.workspace,
+            environment_id: p.environment,
+            request_id: id,
+            occurred_at: new Date().toISOString(),
+        });
+        await c.query("INSERT INTO sr_outbox(id,workspace,environment,request,payload) VALUES($1,$2,$3,$4,$5)", [payload.id, ...scope(p), id, payload]);
+    }
+    async finish(p, id, execution, usage, pending) {
+        await this.tx(p, (c) => this.finishTx(c, p, id, execution, usage, pending));
+    }
+    async finishTx(c, p, id, execution, usage, pending) {
+        const r = await this.row(c, p, id);
+        if (["settled", "released"].includes(r.billing))
+            return;
+        if (pending && !r.output_started) {
+            const attempts = await c.query("SELECT 1 FROM sr_attempts WHERE workspace=$1 AND environment=$2 AND request=$3", [...scope(p), id]);
+            if (!attempts.rowCount) {
+                pending = false;
+                execution = "cancelled";
+            }
+        }
+        if (usage) {
+            const over = await c.query("SELECT 1 FROM sr_attempts WHERE workspace=$1 AND environment=$2 AND request=$3 AND cost>cost_bound", [...scope(p), id]);
+            if (over.rowCount)
+                pending = true;
+        }
+        if (pending ||
+            (usage && r.legs.some((l) => charge(usage, l.price) > BigInt(l.reserved)))) {
+            if (r.billing !== "pending")
+                await this.event(c, p, id, "reconciliation.required");
+            await c.query("UPDATE sr_requests SET execution=$4,billing='pending' WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id, execution]);
+            await c.query("INSERT INTO sr_reconciliation(workspace,environment,request,reason) VALUES($1,$2,$3,$4) ON CONFLICT DO NOTHING", [...scope(p), id, pending ? "unknown_outcome" : "reservation_exceeded"]);
+            return;
+        }
+        for (const leg of r.legs) {
+            let due = usage ? charge(usage, leg.price) : 0n;
+            const amount = due;
+            const allocations = await c.query("SELECT a.*,b.expires_at FROM sr_allocations a JOIN sr_buckets b ON (a.workspace,a.environment,a.bucket)=(b.workspace,b.environment,b.id) WHERE a.workspace=$1 AND a.environment=$2 AND a.request=$3 AND a.account=$4 ORDER BY b.expires_at ASC NULLS LAST, CASE b.source_kind WHEN 'subscription' THEN 0 WHEN 'promotion' THEN 1 ELSE 2 END,b.id", [...scope(p), id, leg.account]);
+            for (const a of allocations.rows) {
+                const take = due < BigInt(a.amount) ? due : BigInt(a.amount);
+                due -= take;
+                await c.query("UPDATE sr_allocations SET charged=$5 WHERE workspace=$1 AND environment=$2 AND request=$3 AND bucket=$4", [...scope(p), id, a.bucket, take.toString()]);
+                await c.query("UPDATE sr_buckets SET remaining=remaining-$4,held=held-$5 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), a.bucket, take.toString(), a.amount]);
+            }
+            await c.query("UPDATE sr_accounts SET balance=balance-$4,held=held-$5 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), leg.account, amount.toString(), leg.reserved]);
+            await c.query("INSERT INTO sr_settlements VALUES($1,$2,$3,$4,$5,$6)", [
+                ...scope(p),
+                id,
+                leg.kind,
+                leg.account,
+                amount.toString(),
+            ]);
+            await c.query("INSERT INTO sr_journal(workspace,environment,business_key,asset,debit,credit,amount,reason) VALUES($1,$2,$3,$4,$5,$6,$7,$8)", [
+                ...scope(p),
+                "settle:" + id + ":" + leg.kind,
+                leg.price.asset,
+                leg.account,
+                "consumed:" + leg.price.asset,
+                amount.toString(),
+                "settlement",
+            ]);
+        }
+        await c.query("UPDATE sr_requests SET execution=$4,billing=$5 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id, execution, usage ? "settled" : "released"]);
+        await this.expire(c, p);
+        await this.event(c, p, id, usage ? "billing.settled" : "billing.released");
+    }
+    async expire(c, p) {
+        const rows = await c.query("SELECT * FROM sr_buckets WHERE workspace=$1 AND environment=$2 AND expires_at<=now() AND remaining>held FOR UPDATE", scope(p));
+        for (const b of rows.rows) {
+            const n = BigInt(b.remaining) - BigInt(b.held);
+            await c.query("UPDATE sr_buckets SET remaining=held WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), b.id]);
+            await c.query("UPDATE sr_accounts SET balance=balance-$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), b.account, n.toString()]);
+            const asset = await c.query("SELECT asset FROM sr_accounts WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), b.account]);
+            await c.query("INSERT INTO sr_journal(workspace,environment,business_key,asset,debit,credit,amount,reason) VALUES($1,$2,$3,$4,$5,$6,$7,$8)", [
+                ...scope(p),
+                "expire:" + randomUUID(),
+                asset.rows[0].asset,
+                b.account,
+                "expired:" + asset.rows[0].asset,
+                n.toString(),
+                "expiry",
+            ]);
+        }
+    }
+    async balance(p) {
+        return this.tx(p, async (c) => {
+            await this.expire(c, p);
+            const r = await c.query("SELECT id,kind,asset,balance::text,held::text,(balance-held)::text AS available FROM sr_accounts WHERE workspace=$1 AND environment=$2 AND (owner=$3 OR (owner=$1 AND kind='platform_sale')) ORDER BY kind", [...scope(p), p.customer]);
+            return r.rows;
+        });
+    }
+    async cancel(p, id) {
+        await this.tx(p, async (c) => {
+            await this.row(c, p, id);
+            await c.query("UPDATE sr_requests SET cancel_requested=true WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), id]);
+        });
+    }
+    async disable(p, offering) {
+        if (!p.scopes.includes("service:write"))
+            throw new RouterError("scope_denied", 403);
+        await this.pool.query("INSERT INTO sr_disabled_connections VALUES($1,$2,$3) ON CONFLICT DO NOTHING", [...scope(p), offering]);
+    }
+    async trace(p, id) {
+        if (!p.scopes.includes("operations:read"))
+            throw new RouterError("scope_denied", 403);
+        const request = await this.get(p, id);
+        const attempts = await this.pool.query("SELECT id,offering,status,cost,usage FROM sr_attempts WHERE workspace=$1 AND environment=$2 AND request=$3 ORDER BY created_at", [...scope(p), id]);
+        const settlements = await this.pool.query("SELECT kind,amount FROM sr_settlements WHERE workspace=$1 AND environment=$2 AND request=$3", [...scope(p), id]);
+        return { request, attempts: attempts.rows, settlements: settlements.rows };
+    }
+    /**
+     * Recent requests across all customers of the workspace/environment, newest first,
+     * with each attempt's offering, status and provider cost and the settled amount per ledger.
+     * Read-only operator view; amounts are atom strings.
+     */
+    async recent(p, limit = 50, customer) {
+        if (!p.scopes.includes("operations:read"))
+            throw new RouterError("scope_denied", 403);
+        const n = Math.min(Math.max(Math.trunc(limit) || 50, 1), 200);
+        const r = await this.pool.query(`SELECT r.id, r.customer, r.service->>'id' AS service, (r.service->>'version')::int AS service_version,
+        r.execution, r.billing, r.provider_spent::text AS provider_cost, r.created_at,
+        COALESCE((SELECT json_agg(json_build_object('offering',a.offering,'status',a.status,'cost',a.cost::text,'usage',a.usage) ORDER BY a.created_at)
+          FROM sr_attempts a WHERE a.workspace=r.workspace AND a.environment=r.environment AND a.request=r.id),'[]') AS attempts,
+        COALESCE((SELECT json_object_agg(s.kind,s.amount::text)
+          FROM sr_settlements s WHERE s.workspace=r.workspace AND s.environment=r.environment AND s.request=r.id),'{}') AS settled
+       FROM sr_requests r WHERE r.workspace=$1 AND r.environment=$2 AND ($4::text IS NULL OR r.customer=$4)
+       ORDER BY r.created_at DESC, r.id DESC LIMIT $3`, [...scope(p), n, customer ?? null]);
+        return r.rows;
+    }
+    /** Never redispatch an expired uncertain attempt. Operator resolution requires evidence. */
+    async recover() {
+        const rows = await this.pool.query("SELECT * FROM sr_requests WHERE deadline<now() AND billing='reserved'");
+        for (const r of rows.rows) {
+            const p = {
+                workspace: r.workspace,
+                environment: r.environment,
+                customer: r.customer,
+                scopes: [],
+            };
+            await this.tx(p, async (c) => {
+                const current = await this.row(c, p, r.id);
+                if (current.billing !== "reserved")
+                    return;
+                const a = await c.query("SELECT * FROM sr_attempts WHERE workspace=$1 AND environment=$2 AND request=$3 ORDER BY created_at", [...scope(p), r.id]);
+                const last = a.rows.at(-1);
+                const knownSuccess = ["succeeded", "partial"].includes(last?.status) && last?.usage;
+                await this.finishTx(c, p, r.id, knownSuccess ? last.status : a.rowCount ? "unknown" : "cancelled", knownSuccess ? last.usage : null, Boolean(a.rowCount) && !knownSuccess);
+            });
+        }
+        return rows.rowCount ?? 0;
+    }
+    async resolveWaiver(p, id, evidence) {
+        if (!p.scopes.includes("billing:write") || evidence.length < 10)
+            throw new RouterError("scope_denied", 403);
+        await this.tx(p, async (c) => {
+            const r = await this.row(c, p, id);
+            if (r.billing !== "pending")
+                throw new RouterError("state_conflict", 409);
+            await this.finishTx(c, p, id, "failed", null, false);
+            await c.query("UPDATE sr_reconciliation SET state='open',reason='provider_cost_pending_after_customer_waiver',resolution=$4,resolved_at=NULL WHERE workspace=$1 AND environment=$2 AND request=$3", [...scope(p), id, evidence]);
+        });
+    }
+    async refund(p, id, kind, amount, key, reason) {
+        if (!p.scopes.includes("billing:write"))
+            throw new RouterError("scope_denied", 403);
+        if (!/^[1-9][0-9]{0,29}$/.test(amount) || reason.length < 5 || !key)
+            throw new RouterError("invalid_refund");
+        return this.tx(p, async (c) => {
+            const r = await this.row(c, p, id);
+            const leg = r.legs.find((l) => l.kind === kind);
+            if (!leg)
+                throw new RouterError("resource_not_found", 404);
+            const old = await c.query("SELECT * FROM sr_refunds WHERE workspace=$1 AND environment=$2 AND business_key=$3", [...scope(p), key]);
+            if (old.rows[0]) {
+                const o = old.rows[0];
+                if (o.request !== id ||
+                    o.kind !== kind ||
+                    o.amount !== amount ||
+                    o.reason !== reason)
+                    throw new RouterError("idempotency_conflict", 409);
+                return;
+            }
+            const result = await c.query("SELECT * FROM sr_settlements WHERE workspace=$1 AND environment=$2 AND request=$3 AND kind=$4", [...scope(p), id, kind]);
+            if (!result.rows[0])
+                throw new RouterError("state_conflict", 409);
+            const refunded = await c.query("SELECT COALESCE(sum(amount),0)::text AS total FROM sr_refunds WHERE workspace=$1 AND environment=$2 AND request=$3 AND kind=$4", [...scope(p), id, kind]);
+            if (BigInt(amount) + BigInt(refunded.rows[0].total) >
+                BigInt(result.rows[0].amount))
+                throw new RouterError("refund_exceeded", 409);
+            let remaining = BigInt(amount);
+            const allocations = await c.query("SELECT * FROM sr_allocations WHERE workspace=$1 AND environment=$2 AND request=$3 AND account=$4 ORDER BY bucket", [...scope(p), id, leg.account]);
+            for (const a of allocations.rows) {
+                const available = BigInt(a.charged) - BigInt(a.refunded);
+                const n = available < remaining ? available : remaining;
+                if (n <= 0n)
+                    continue;
+                await c.query("UPDATE sr_allocations SET refunded=refunded+$5 WHERE workspace=$1 AND environment=$2 AND request=$3 AND bucket=$4", [...scope(p), id, a.bucket, n.toString()]);
+                await c.query("UPDATE sr_buckets SET remaining=remaining+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), a.bucket, n.toString()]);
+                remaining -= n;
+            }
+            if (remaining !== 0n)
+                throw new RouterError("allocation_invariant", 500);
+            await c.query("UPDATE sr_accounts SET balance=balance+$4 WHERE workspace=$1 AND environment=$2 AND id=$3", [...scope(p), leg.account, amount]);
+            await c.query("INSERT INTO sr_refunds(workspace,environment,request,kind,business_key,amount,reason) VALUES($1,$2,$3,$4,$5,$6,$7)", [...scope(p), id, kind, key, amount, reason]);
+            await c.query("INSERT INTO sr_journal(workspace,environment,business_key,asset,debit,credit,amount,reason) VALUES($1,$2,$3,$4,$5,$6,$7,$8)", [
+                ...scope(p),
+                "refund:" + key,
+                leg.price.asset,
+                "consumed:" + leg.price.asset,
+                leg.account,
+                amount,
+                reason,
+            ]);
+            await this.expire(c, p);
+        });
+    }
+    async claimEvents(limit = 20, tenant) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+            throw new RouterError("invalid_limit");
+        return this.tx({
+            workspace: "system",
+            environment: "outbox",
+            customer: "worker",
+            scopes: [],
+        }, async (c) => {
+            const rows = await c.query(`SELECT id FROM sr_outbox WHERE (state='pending' OR (state='delivering' AND lease_until<now())) ${tenant ? "AND workspace=$2 AND environment=$3" : ""} ORDER BY created_at,id LIMIT $1 FOR UPDATE SKIP LOCKED`, [limit, ...(tenant ? [tenant.workspace, tenant.environment] : [])]);
+            if (!rows.rowCount)
+                return [];
+            const claimed = await c.query("UPDATE sr_outbox SET state='delivering',generation=generation+1,lease_until=now()+interval '30 seconds' WHERE id=ANY($1) RETURNING id,generation,payload", [rows.rows.map((x) => x.id)]);
+            return claimed.rows;
+        });
+    }
+    async ackEvent(id, generation) {
+        const r = await this.pool.query("UPDATE sr_outbox SET state='delivered',lease_until=NULL WHERE id=$1 AND generation=$2 AND state='delivering' AND lease_until>now()", [id, generation]);
+        return r.rowCount === 1;
+    }
+}
+export { ControlPlane } from "./control.js";

package/migrations/001_initial.sql

@@ -0,0 +1,68 @@
+CREATE TABLE IF NOT EXISTS sr_services (
+ workspace text NOT NULL, environment text NOT NULL, id text NOT NULL, version integer NOT NULL CHECK(version>0),
+ config jsonb NOT NULL, active boolean NOT NULL DEFAULT true, PRIMARY KEY(workspace,environment,id,version)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS sr_service_active ON sr_services(workspace,environment,id) WHERE active;
+CREATE TABLE IF NOT EXISTS sr_accounts (
+ workspace text NOT NULL, environment text NOT NULL, id text NOT NULL, owner text NOT NULL, kind text NOT NULL,
+ asset text NOT NULL, balance numeric(38,0) NOT NULL DEFAULT 0 CHECK(balance>=0), held numeric(38,0) NOT NULL DEFAULT 0 CHECK(held>=0 AND held<=balance),
+ PRIMARY KEY(workspace,environment,id), UNIQUE(workspace,environment,owner,kind,asset)
+);
+CREATE TABLE IF NOT EXISTS sr_buckets (
+ workspace text NOT NULL, environment text NOT NULL, id text NOT NULL, account text NOT NULL, source text NOT NULL,
+ expires_at timestamptz, remaining numeric(38,0) NOT NULL CHECK(remaining>=0), held numeric(38,0) NOT NULL DEFAULT 0 CHECK(held>=0 AND held<=remaining),
+ PRIMARY KEY(workspace,environment,id), UNIQUE(workspace,environment,source),
+ FOREIGN KEY(workspace,environment,account) REFERENCES sr_accounts(workspace,environment,id)
+);
+CREATE TABLE IF NOT EXISTS sr_requests (
+ workspace text NOT NULL, environment text NOT NULL, id text NOT NULL, customer text NOT NULL, idem text NOT NULL, digest text NOT NULL,
+ service jsonb NOT NULL, legs jsonb NOT NULL, execution text NOT NULL DEFAULT 'accepted', billing text NOT NULL DEFAULT 'reserved',
+ cancel_requested boolean NOT NULL DEFAULT false, output_started boolean NOT NULL DEFAULT false,
+ provider_spent numeric(38,0) NOT NULL DEFAULT 0 CHECK(provider_spent>=0), provider_held numeric(38,0) NOT NULL DEFAULT 0 CHECK(provider_held>=0),
+ deadline timestamptz NOT NULL, created_at timestamptz NOT NULL DEFAULT now(),
+ PRIMARY KEY(workspace,environment,id), UNIQUE(workspace,environment,idem)
+);
+CREATE TABLE IF NOT EXISTS sr_allocations (
+ workspace text NOT NULL, environment text NOT NULL, request text NOT NULL, bucket text NOT NULL, account text NOT NULL,
+ amount numeric(38,0) NOT NULL CHECK(amount>=0), PRIMARY KEY(workspace,environment,request,bucket),
+ FOREIGN KEY(workspace,environment,request) REFERENCES sr_requests(workspace,environment,id),
+ FOREIGN KEY(workspace,environment,bucket) REFERENCES sr_buckets(workspace,environment,id),
+ FOREIGN KEY(workspace,environment,account) REFERENCES sr_accounts(workspace,environment,id)
+);
+CREATE TABLE IF NOT EXISTS sr_attempts (
+ workspace text NOT NULL, environment text NOT NULL, id text NOT NULL, request text NOT NULL, offering text NOT NULL,
+ status text NOT NULL DEFAULT 'dispatched', cost_bound numeric(38,0) NOT NULL, cost numeric(38,0), usage jsonb, upstream_id text,
+ created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY(workspace,environment,id),
+ FOREIGN KEY(workspace,environment,request) REFERENCES sr_requests(workspace,environment,id)
+);
+CREATE TABLE IF NOT EXISTS sr_disabled_connections (
+ workspace text NOT NULL, environment text NOT NULL, offering text NOT NULL, PRIMARY KEY(workspace,environment,offering)
+);
+CREATE TABLE IF NOT EXISTS sr_settlements (
+ workspace text NOT NULL, environment text NOT NULL, request text NOT NULL, kind text NOT NULL, account text NOT NULL, amount numeric(38,0) NOT NULL CHECK(amount>=0),
+ PRIMARY KEY(workspace,environment,request,kind), FOREIGN KEY(workspace,environment,request) REFERENCES sr_requests(workspace,environment,id),
+ FOREIGN KEY(workspace,environment,account) REFERENCES sr_accounts(workspace,environment,id)
+);
+-- A transfer encodes BOTH sides in one immutable row; equal amounts by construction.
+-- Counterpart names are not spendable accounts and may hold issuer/consumed balances.
+CREATE TABLE IF NOT EXISTS sr_journal (
+ workspace text NOT NULL, environment text NOT NULL, business_key text NOT NULL, asset text NOT NULL,
+ debit text NOT NULL, credit text NOT NULL, amount numeric(38,0) NOT NULL CHECK(amount>=0), reason text NOT NULL,
+ created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY(workspace,environment,business_key), CHECK(debit<>credit)
+);
+CREATE OR REPLACE FUNCTION sr_immutable() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'append-only record'; END $$;
+DROP TRIGGER IF EXISTS sr_journal_immutable ON sr_journal;
+CREATE TRIGGER sr_journal_immutable BEFORE UPDATE OR DELETE ON sr_journal FOR EACH ROW EXECUTE FUNCTION sr_immutable();
+CREATE TABLE IF NOT EXISTS sr_outbox (
+ id text PRIMARY KEY, workspace text NOT NULL, environment text NOT NULL, request text NOT NULL, payload jsonb NOT NULL,
+ state text NOT NULL DEFAULT 'pending', generation integer NOT NULL DEFAULT 0, lease_until timestamptz,
+ created_at timestamptz NOT NULL DEFAULT now(), UNIQUE(workspace,environment,request,payload),
+ FOREIGN KEY(workspace,environment,request) REFERENCES sr_requests(workspace,environment,id)
+);
+CREATE TABLE IF NOT EXISTS sr_reconciliation (
+ workspace text NOT NULL, environment text NOT NULL, request text NOT NULL, reason text NOT NULL,
+ state text NOT NULL DEFAULT 'open', resolution text, resolved_at timestamptz,
+ PRIMARY KEY(workspace,environment,request), FOREIGN KEY(workspace,environment,request) REFERENCES sr_requests(workspace,environment,id)
+);
+CREATE INDEX IF NOT EXISTS sr_requests_pending ON sr_requests(deadline) WHERE billing IN ('reserved','pending');
+CREATE INDEX IF NOT EXISTS sr_outbox_pending ON sr_outbox(state,lease_until,created_at);

package/migrations/002_integrity.sql

@@ -0,0 +1,22 @@
+ALTER TABLE sr_requests ADD COLUMN IF NOT EXISTS route_decision jsonb;
+ALTER TABLE sr_buckets ADD COLUMN IF NOT EXISTS granted numeric(38,0);
+UPDATE sr_buckets b SET granted=j.amount FROM sr_journal j WHERE (b.workspace,b.environment,'grant:'||b.source)=(j.workspace,j.environment,j.business_key) AND b.granted IS NULL;
+CREATE OR REPLACE FUNCTION sr_service_immutable() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+ IF OLD.config IS DISTINCT FROM NEW.config OR OLD.version<>NEW.version OR OLD.id<>NEW.id OR OLD.workspace<>NEW.workspace OR OLD.environment<>NEW.environment THEN
+  RAISE EXCEPTION 'published service is immutable';
+ END IF;
+ RETURN NEW;
+END $$;
+CREATE TRIGGER sr_service_immutable BEFORE UPDATE ON sr_services FOR EACH ROW EXECUTE FUNCTION sr_service_immutable();
+CREATE TRIGGER sr_settlement_immutable BEFORE UPDATE OR DELETE ON sr_settlements FOR EACH ROW EXECUTE FUNCTION sr_immutable();
+CREATE TABLE sr_refunds (
+ workspace text NOT NULL, environment text NOT NULL, request text NOT NULL, kind text NOT NULL, business_key text NOT NULL,
+ amount numeric(38,0) NOT NULL CHECK(amount>0), reason text NOT NULL, created_at timestamptz NOT NULL DEFAULT now(),
+ PRIMARY KEY(workspace,environment,business_key),
+ FOREIGN KEY(workspace,environment,request,kind) REFERENCES sr_settlements(workspace,environment,request,kind)
+);
+CREATE TRIGGER sr_refund_immutable BEFORE UPDATE OR DELETE ON sr_refunds FOR EACH ROW EXECUTE FUNCTION sr_immutable();
+ALTER TABLE sr_allocations ADD COLUMN IF NOT EXISTS charged numeric(38,0) NOT NULL DEFAULT 0;
+ALTER TABLE sr_allocations ADD COLUMN IF NOT EXISTS refunded numeric(38,0) NOT NULL DEFAULT 0;
+ALTER TABLE sr_allocations ADD CONSTRAINT sr_allocation_charges CHECK(charged>=0 AND refunded>=0 AND refunded<=charged AND charged<=amount);