@opengeni/db 1.1.0 → 1.2.0

package/drizzle/0613_model_scoped_promotional_credits.sql

@@ -0,0 +1,238 @@
+-- deployment-mode: rolling
+-- Deploy every reader and debit writer before configuring scoped offers.
+-- Existing grants keep NULL eligibility and remain unrestricted.
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '10min';
+
+ALTER TABLE credit_ledger_entries ADD COLUMN eligible_model_ids text[];
+ALTER TABLE credit_ledger_entries ADD CONSTRAINT credit_ledger_scope_valid CHECK (
+  eligible_model_ids IS NULL OR (type = 'grant' AND amount_micros > 0
+    AND cardinality(eligible_model_ids) BETWEEN 1 AND 40
+    AND array_position(eligible_model_ids, NULL) IS NULL
+    AND array_position(eligible_model_ids, '') IS NULL)
+);
+CREATE UNIQUE INDEX credit_ledger_entries_id_account_idx ON credit_ledger_entries (id, account_id);
+CREATE INDEX credit_ledger_scoped_grants_idx ON credit_ledger_entries (account_id, created_at, id)
+  WHERE eligible_model_ids IS NOT NULL;
+CREATE FUNCTION opengeni_private.preserve_credit_grant_scope() RETURNS trigger
+LANGUAGE plpgsql SET search_path = pg_catalog AS $body$
+BEGIN
+  IF NEW.eligible_model_ids IS DISTINCT FROM OLD.eligible_model_ids
+    OR (OLD.eligible_model_ids IS NOT NULL AND (
+      NEW.amount_micros IS DISTINCT FROM OLD.amount_micros
+      OR NEW.account_id IS DISTINCT FROM OLD.account_id
+      OR NEW.metadata->>'creditOfferLabel' IS DISTINCT FROM OLD.metadata->>'creditOfferLabel'
+      OR NEW.metadata->>'creditOfferId' IS DISTINCT FROM OLD.metadata->>'creditOfferId'
+      OR NEW.source_type IS DISTINCT FROM OLD.source_type
+    )) THEN
+    RAISE EXCEPTION 'Issued promotional credit terms are immutable' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $body$;
+REVOKE ALL ON FUNCTION opengeni_private.preserve_credit_grant_scope() FROM PUBLIC;
+CREATE TRIGGER preserve_credit_grant_scope BEFORE UPDATE ON credit_ledger_entries
+  FOR EACH ROW EXECUTE FUNCTION opengeni_private.preserve_credit_grant_scope();
+
+CREATE TABLE credit_debit_allocations (
+  account_id uuid NOT NULL,
+  debit_entry_id uuid NOT NULL,
+  grant_entry_id uuid NOT NULL,
+  amount_micros bigint NOT NULL CONSTRAINT credit_debit_allocations_positive CHECK (amount_micros > 0),
+  PRIMARY KEY (debit_entry_id, grant_entry_id),
+  FOREIGN KEY (debit_entry_id, account_id) REFERENCES credit_ledger_entries (id, account_id) ON DELETE CASCADE,
+  FOREIGN KEY (grant_entry_id, account_id) REFERENCES credit_ledger_entries (id, account_id) ON DELETE CASCADE
+);
+CREATE INDEX credit_debit_allocations_grant_idx ON credit_debit_allocations (account_id, grant_entry_id);
+ALTER TABLE credit_debit_allocations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE credit_debit_allocations FORCE ROW LEVEL SECURITY;
+CREATE POLICY credit_debit_allocations_account_isolation ON credit_debit_allocations
+  USING (opengeni_private.account_rls_visible(account_id))
+  WITH CHECK (opengeni_private.account_rls_visible(account_id));
+REVOKE ALL ON credit_debit_allocations FROM PUBLIC;
+DO $grants$ BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT ON credit_debit_allocations TO opengeni_app;
+  END IF;
+END $grants$;
+
+
+-- Runtime policy: one deployment-wide default, with signup/coupon overrides.
+-- Revisions stay available so an in-flight call can settle under its admitted policy.
+CREATE TABLE opengeni_private.credit_promotion_policy_revisions (
+  revision bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  policy jsonb NOT NULL,
+  operator text NOT NULL CHECK (operator = btrim(operator) AND length(operator) BETWEEN 1 AND 200),
+  reason text NOT NULL CHECK (reason = btrim(reason) AND length(reason) BETWEEN 6 AND 1000),
+  database_role text NOT NULL DEFAULT session_user,
+  changed_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+REVOKE ALL ON opengeni_private.credit_promotion_policy_revisions FROM PUBLIC;
+CREATE TRIGGER credit_promotion_policy_revisions_immutable
+  BEFORE UPDATE OR DELETE ON opengeni_private.credit_promotion_policy_revisions
+  FOR EACH ROW EXECUTE FUNCTION reject_verified_signup_trial_switch_revision_mutation();
+CREATE TRIGGER credit_promotion_policy_revisions_no_truncate
+  BEFORE TRUNCATE ON opengeni_private.credit_promotion_policy_revisions
+  FOR EACH STATEMENT EXECUTE FUNCTION reject_verified_signup_trial_switch_revision_mutation();
+
+CREATE FUNCTION set_credit_promotion_policy(p_policy jsonb, p_operator text, p_reason text)
+RETURNS bigint LANGUAGE plpgsql SET search_path = pg_catalog AS $body$
+DECLARE
+  model_list jsonb;
+  offer jsonb;
+  written_revision bigint;
+BEGIN
+  IF p_policy IS NULL OR jsonb_typeof(p_policy) <> 'object'
+    OR NOT p_policy ? 'defaultModelIds'
+    OR p_policy - ARRAY['defaultModelIds', 'signupModelIds', 'offers'] <> '{}'::jsonb
+    OR (p_policy ? 'offers' AND jsonb_typeof(p_policy->'offers') <> 'object') THEN
+    RAISE EXCEPTION 'Policy requires defaultModelIds and optional signupModelIds/offers' USING ERRCODE = '22023';
+  END IF;
+  FOR offer IN SELECT value FROM jsonb_each(coalesce(p_policy->'offers', '{}'::jsonb)) LOOP
+    IF jsonb_typeof(offer) <> 'object'
+      OR offer - ARRAY['label', 'eligibleModelIds'] <> '{}'::jsonb
+      OR jsonb_typeof(offer->'label') IS DISTINCT FROM 'string'
+      OR length(btrim(offer->>'label')) NOT BETWEEN 1 AND 120 THEN
+      RAISE EXCEPTION 'Invalid credit offer' USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+  FOR model_list IN
+    SELECT p_policy->'defaultModelIds'
+    UNION ALL SELECT p_policy->'signupModelIds' WHERE p_policy ? 'signupModelIds'
+    UNION ALL SELECT value->'eligibleModelIds'
+      FROM jsonb_each(coalesce(p_policy->'offers', '{}'::jsonb)) WHERE value ? 'eligibleModelIds'
+  LOOP
+    IF jsonb_typeof(model_list) IS DISTINCT FROM 'array' THEN
+      RAISE EXCEPTION 'Model list must be an array' USING ERRCODE = '22023';
+    END IF;
+    IF jsonb_array_length(model_list) NOT BETWEEN 1 AND 40 OR EXISTS (
+      SELECT 1 FROM jsonb_array_elements(model_list) id
+      WHERE jsonb_typeof(id) <> 'string' OR length(btrim(id #>> '{}')) NOT BETWEEN 1 AND 200
+        OR id #>> '{}' <> btrim(id #>> '{}')
+    ) THEN
+      RAISE EXCEPTION 'Model list requires 1-40 canonical model IDs' USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+  -- Serializes revision order across simultaneous operator updates.
+  PERFORM pg_advisory_xact_lock(hashtextextended('credit-promotion-policy', 0));
+  INSERT INTO opengeni_private.credit_promotion_policy_revisions (policy, operator, reason)
+    VALUES (p_policy, p_operator, p_reason) RETURNING revision INTO written_revision;
+  RETURN written_revision;
+END $body$;
+REVOKE ALL ON FUNCTION set_credit_promotion_policy(jsonb, text, text) FROM PUBLIC;
+DO $policy_acl$
+DECLARE grantee_name text;
+BEGIN
+  FOR grantee_name IN
+    SELECT DISTINCT r.rolname FROM pg_class c
+    CROSS JOIN LATERAL aclexplode(coalesce(c.relacl, acldefault('r', c.relowner))) a
+    JOIN pg_roles r ON r.oid = a.grantee
+    WHERE c.oid = 'opengeni_private.credit_promotion_policy_revisions'::regclass AND a.grantee <> c.relowner
+  LOOP
+    EXECUTE format('REVOKE ALL ON opengeni_private.credit_promotion_policy_revisions FROM %I', grantee_name);
+  END LOOP;
+  FOR grantee_name IN
+    SELECT DISTINCT r.rolname FROM pg_proc p
+    CROSS JOIN LATERAL aclexplode(coalesce(p.proacl, acldefault('f', p.proowner))) a
+    JOIN pg_roles r ON r.oid = a.grantee
+    WHERE p.oid = 'set_credit_promotion_policy(jsonb,text,text)'::regprocedure AND a.grantee <> p.proowner
+  LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION set_credit_promotion_policy(jsonb,text,text) FROM %I', grantee_name);
+  END LOOP;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT ON opengeni_private.credit_promotion_policy_revisions TO opengeni_app;
+  END IF;
+END $policy_acl$;
+
+CREATE OR REPLACE FUNCTION opengeni_private.grant_verified_signup_trial_credit()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path FROM CURRENT
+AS $body$
+DECLARE
+  verified_owner boolean;
+  account_owner boolean;
+  runtime_enabled boolean;
+  inserted_count integer;
+  model_ids jsonb;
+BEGIN
+  IF pg_catalog.current_setting('opengeni.verified_signup_trial_enabled', true)
+      IS DISTINCT FROM 'on' THEN
+    RETURN NEW;
+  END IF;
+
+  -- Shared against the setter's exclusive lock; a missing revision fails closed.
+  PERFORM pg_catalog.pg_advisory_xact_lock_shared(
+    pg_catalog.hashtextextended('verified-signup-trial-switch', 0)
+  );
+  SELECT revision.grants_enabled
+  INTO runtime_enabled
+  FROM opengeni_private.verified_signup_trial_switch_revisions revision
+  ORDER BY revision.revision DESC
+  LIMIT 1;
+  IF runtime_enabled IS DISTINCT FROM TRUE THEN
+    RETURN NEW;
+  END IF;
+
+  -- This is a defense in depth check: the sole receipt writer already checks
+  -- the canonical verified human and the absence of prior memberships.
+  SELECT candidate.email_verified IS TRUE
+  INTO verified_owner
+  FROM auth_users candidate
+  WHERE candidate.id = NEW.auth_user_id;
+  SELECT account.external_source = 'better-auth:user'
+    AND account.external_id = NEW.auth_user_id
+  INTO account_owner
+  FROM managed_accounts account
+  WHERE account.id = NEW.account_id;
+  IF verified_owner IS DISTINCT FROM TRUE
+    OR account_owner IS DISTINCT FROM TRUE
+    OR opengeni_private.current_subject_id() IS DISTINCT FROM 'user:' || NEW.auth_user_id
+    OR opengeni_private.current_account_id() IS DISTINCT FROM NEW.account_id
+    OR NEW.result ->> 'organizationId' IS DISTINCT FROM NEW.account_id::text
+  THEN
+    RAISE EXCEPTION 'verified signup trial requires an exact new owner'
+      USING ERRCODE = '42501';
+  END IF;
+
+  SELECT coalesce(policy->'signupModelIds', policy->'defaultModelIds') INTO model_ids
+    FROM opengeni_private.credit_promotion_policy_revisions ORDER BY revision DESC LIMIT 1;
+  model_ids := coalesce(model_ids, nullif(pg_catalog.current_setting('opengeni.signup_credit_model_ids', true), '')::jsonb);
+  INSERT INTO credit_ledger_entries (
+    account_id, workspace_id, type, amount_micros, source_type, source_id,
+    idempotency_key, metadata, eligible_model_ids
+  ) VALUES (
+    NEW.account_id, NULL, 'grant', 10000000, 'verified_signup_trial',
+    NEW.auth_user_id, 'verified-signup-trial:v1:' || NEW.auth_user_id,
+    pg_catalog.jsonb_build_object('campaign', 'verified_signup_trial_v1',
+      'creditOfferLabel', 'Signup credits'),
+    CASE WHEN model_ids IS NULL THEN NULL
+      ELSE ARRAY(SELECT pg_catalog.jsonb_array_elements_text(model_ids)) END
+  ) ON CONFLICT (idempotency_key) DO NOTHING;
+  GET DIAGNOSTICS inserted_count = ROW_COUNT;
+  IF inserted_count <> 1 THEN
+    RAISE EXCEPTION 'verified signup trial credit idempotency collision'
+      USING ERRCODE = '23505';
+  END IF;
+  RETURN NEW;
+END
+$body$;
+
+-- CREATE OR REPLACE resets SET search_path FROM CURRENT: re-pin both definers.
+DO $posture$
+DECLARE
+  data_schema text := pg_catalog.current_schema();
+BEGIN
+  EXECUTE pg_catalog.format(
+    'ALTER FUNCTION opengeni_private.grant_verified_signup_trial_credit() '
+      || 'SET search_path = pg_catalog, %I, opengeni_private, pg_temp',
+    data_schema
+  );
+  EXECUTE pg_catalog.format(
+    'ALTER FUNCTION %I.set_verified_signup_trial_credits_enabled(boolean, text, text) '
+      || 'SET search_path = pg_catalog, %I, pg_temp',
+    data_schema,
+    data_schema
+  );
+END
+$posture$;

package/drizzle/0614_quiescence_command_containment.sql

@@ -0,0 +1,7 @@
+-- deployment-mode: rolling
+-- Additive reason: existing capture/termination fences remain unchanged.
+ALTER TABLE sandbox_leases
+  DROP CONSTRAINT sandbox_leases_command_containment_reason_check,
+  ADD CONSTRAINT sandbox_leases_command_containment_reason_check
+  CHECK (command_containment_reason IS NULL OR command_containment_reason IN
+    ('idle_containment', 'provider_deadline_containment', 'quiescence_containment'));

package/drizzle/0615_credit_promotion_policy_validation.sql

@@ -0,0 +1,63 @@
+-- deployment-mode: rolling
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '10min';
+
+-- Keep owner SQL updates readable by CreditPromotionPolicy. Replacing the
+-- function preserves its owner-only ACL and the immutable revision history.
+CREATE OR REPLACE FUNCTION set_credit_promotion_policy(p_policy jsonb, p_operator text, p_reason text)
+RETURNS bigint LANGUAGE plpgsql SET search_path = pg_catalog AS $body$
+DECLARE
+  -- ECMAScript String.trim whitespace; PostgreSQL btrim defaults to ASCII space.
+  trim_chars CONSTANT text := U&'\0009\000A\000B\000C\000D\0020\00A0\1680\2000\2001\2002\2003\2004\2005\2006\2007\2008\2009\200A\2028\2029\202F\205F\3000\FEFF';
+  model_list jsonb;
+  model_id text;
+  offer_id text;
+  offer jsonb;
+  offer_label text;
+  written_revision bigint;
+BEGIN
+  IF p_policy IS NULL OR jsonb_typeof(p_policy) <> 'object'
+    OR NOT p_policy ? 'defaultModelIds'
+    OR p_policy - ARRAY['defaultModelIds', 'signupModelIds', 'offers'] <> '{}'::jsonb
+    OR (p_policy ? 'offers' AND jsonb_typeof(p_policy->'offers') <> 'object') THEN
+    RAISE EXCEPTION 'Policy requires defaultModelIds and optional signupModelIds/offers' USING ERRCODE = '22023';
+  END IF;
+  FOR offer_id, offer IN SELECT key, value FROM jsonb_each(coalesce(p_policy->'offers', '{}'::jsonb)) LOOP
+    IF offer_id = '' OR jsonb_typeof(offer) <> 'object'
+      OR offer - ARRAY['label', 'eligibleModelIds'] <> '{}'::jsonb
+      OR jsonb_typeof(offer->'label') IS DISTINCT FROM 'string' THEN
+      RAISE EXCEPTION 'Invalid credit offer' USING ERRCODE = '22023';
+    END IF;
+    offer_label := btrim(offer->>'label', trim_chars);
+    -- JavaScript string limits count UTF-16 units: supplementary characters use two.
+    IF length(regexp_replace(offer_label, U&'[\+010000-\+10FFFF]', 'xx', 'g')) NOT BETWEEN 1 AND 120 THEN
+      RAISE EXCEPTION 'Invalid credit offer label' USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+  FOR model_list IN
+    SELECT p_policy->'defaultModelIds'
+    UNION ALL SELECT p_policy->'signupModelIds' WHERE p_policy ? 'signupModelIds'
+    UNION ALL SELECT value->'eligibleModelIds'
+      FROM jsonb_each(coalesce(p_policy->'offers', '{}'::jsonb)) WHERE value ? 'eligibleModelIds'
+  LOOP
+    IF jsonb_typeof(model_list) IS DISTINCT FROM 'array' THEN
+      RAISE EXCEPTION 'Model list must be an array' USING ERRCODE = '22023';
+    END IF;
+    IF jsonb_array_length(model_list) NOT BETWEEN 1 AND 40 OR EXISTS (
+      SELECT 1 FROM jsonb_array_elements(model_list) id WHERE jsonb_typeof(id) <> 'string'
+    ) THEN
+      RAISE EXCEPTION 'Model list requires 1-40 canonical model IDs' USING ERRCODE = '22023';
+    END IF;
+    FOR model_id IN SELECT jsonb_array_elements_text(model_list) LOOP
+      IF model_id <> btrim(model_id, trim_chars)
+        OR length(regexp_replace(model_id, U&'[\+010000-\+10FFFF]', 'xx', 'g')) NOT BETWEEN 1 AND 200 THEN
+        RAISE EXCEPTION 'Model list requires 1-40 canonical model IDs' USING ERRCODE = '22023';
+      END IF;
+    END LOOP;
+  END LOOP;
+  -- Serializes revision order across simultaneous operator updates.
+  PERFORM pg_advisory_xact_lock(hashtextextended('credit-promotion-policy', 0));
+  INSERT INTO opengeni_private.credit_promotion_policy_revisions (policy, operator, reason)
+    VALUES (p_policy, p_operator, p_reason) RETURNING revision INTO written_revision;
+  RETURN written_revision;
+END $body$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -115,12 +115,12 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "1.1.0",
-    "@opengeni/codex": "1.1.0",
-    "@opengeni/config": "1.1.0",
-    "@opengeni/contracts": "1.1.0",
-    "@opengeni/network": "1.1.0",
-    "@opengeni/observability": "1.1.0",
+    "@opengeni/codemode": "1.2.0",
+    "@opengeni/codex": "1.2.0",
+    "@opengeni/config": "1.2.0",
+    "@opengeni/contracts": "1.2.0",
+    "@opengeni/network": "1.2.0",
+    "@opengeni/observability": "1.2.0",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },

package/src/credit-balances.ts

@@ -0,0 +1,109 @@
+import type { BillingBalance, PromotionalCreditBalance } from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import type { Database } from "./database";
+import { rawRows, withAccountRls } from "./database";
+import * as schema from "./schema";
+
+/** Read totals and grant remainders from one database snapshot. */
+type CreditBalanceSnapshot = BillingBalance & { creditPolicyRevision?: number };
+
+export async function getBillingBalance(
+  db: Database,
+  accountId: string,
+  policyRevision?: number,
+): Promise<CreditBalanceSnapshot> {
+  return await withAccountRls(db, accountId, async (tx) => {
+    const [row] = await rawRows<{
+      balance: string;
+      grants: PromotionalCreditBalance[];
+      revision: number;
+    }>(
+      tx,
+      sql`
+      with current_policy as (
+        select revision, policy from opengeni_private.credit_promotion_policy_revisions
+        where (${policyRevision ?? null}::bigint is null or revision <= ${policyRevision ?? null}::bigint)
+        order by revision desc limit 1
+      )
+      select
+        coalesce((select revision from current_policy), 0)::int as revision,
+        (select coalesce(sum(amount_micros), 0)::text
+          from ${schema.creditLedgerEntries} where account_id = ${accountId}) as balance,
+        coalesce((select jsonb_agg(jsonb_build_object(
+          'grantId', g.id,
+          'label', coalesce(g.metadata->>'creditOfferLabel', 'Promotional credits'),
+          'eligibleModelIds', coalesce(
+            (select coalesce(
+              case when g.source_type = 'verified_signup_trial' then policy->'signupModelIds'
+                else policy->'offers'->(g.metadata->>'creditOfferId')->'eligibleModelIds' end,
+              policy->'defaultModelIds'
+            ) from current_policy), to_jsonb(g.eligible_model_ids)),
+          'remainingMicros', g.amount_micros - coalesce(used.amount, 0)
+        ) order by g.created_at, g.id)
+          from ${schema.creditLedgerEntries} g
+          left join (
+            select grant_entry_id, sum(amount_micros) as amount
+            from ${schema.creditDebitAllocations} where account_id = ${accountId}
+            group by grant_entry_id
+          ) used on used.grant_entry_id = g.id
+          where g.account_id = ${accountId} and g.eligible_model_ids is not null
+            and g.amount_micros > coalesce(used.amount, 0)
+        ), '[]'::jsonb) as grants
+    `,
+    );
+    const balanceMicros = Number(row?.balance ?? 0);
+    const promotionalCredits = row?.grants ?? [];
+    return {
+      accountId,
+      creditPolicyRevision: row?.revision ?? 0,
+      balanceMicros,
+      generalBalanceMicros:
+        balanceMicros - promotionalCredits.reduce((sum, grant) => sum + grant.remainingMicros, 0),
+      promotionalCredits,
+      currency: "usd",
+      updatedAt: new Date().toISOString(),
+    };
+  });
+}
+
+/** Missing model means a non-model resource, which can only use general credits. */
+export function spendableCreditMicros(balance: BillingBalance, modelId?: string): number {
+  return (
+    Math.max(0, balance.generalBalanceMicros ?? balance.balanceMicros) +
+    (balance.promotionalCredits ?? []).reduce(
+      (sum, grant) =>
+        sum + (modelId && grant.eligibleModelIds.includes(modelId) ? grant.remainingMicros : 0),
+      0,
+    )
+  );
+}
+
+export async function getSpendableCreditBalance(
+  db: Database,
+  accountId: string,
+  modelId?: string,
+  policyRevision?: number,
+): Promise<CreditBalanceSnapshot> {
+  const balance = await getBillingBalance(db, accountId, policyRevision);
+  return { ...balance, balanceMicros: spendableCreditMicros(balance, modelId) };
+}
+
+export function planCreditDebit(
+  balance: BillingBalance,
+  requestedMicros: number,
+  modelId?: string,
+) {
+  if (!Number.isSafeInteger(requestedMicros) || requestedMicros <= 0) {
+    throw new Error("credit debit requires a positive, safe integer micro amount");
+  }
+  const debitedMicros = Math.min(requestedMicros, spendableCreditMicros(balance, modelId));
+  let remaining = debitedMicros;
+  const allocations: { grantEntryId: string; amountMicros: number }[] = [];
+  for (const grant of balance.promotionalCredits ?? []) {
+    if (!remaining || !modelId || !grant.eligibleModelIds.includes(modelId)) continue;
+    const amountMicros = Math.min(remaining, grant.remainingMicros);
+    allocations.push({ grantEntryId: grant.grantId, amountMicros });
+    remaining -= amountMicros;
+  }
+  return { debitedMicros, allocations };
+}

package/src/credit-promotion-policy.ts

@@ -0,0 +1,12 @@
+import { CreditPromotionPolicy } from "@opengeni/config";
+import { sql } from "drizzle-orm";
+import { rawRows, type Database } from "./database";
+
+/** Runtime policy supersedes deployment bootstrap configuration. No process cache. */
+export async function readCreditPromotionPolicy(db: Database) {
+  const [row] = await rawRows<{ policy: unknown }>(
+    db,
+    sql`select policy from opengeni_private.credit_promotion_policy_revisions order by revision desc limit 1`,
+  );
+  return row ? CreditPromotionPolicy.parse(row.policy) : null;
+}

package/src/database.ts

@@ -6,6 +6,8 @@ import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 
 import {
+  DatabaseTransactionError,
+  isDatabasePersistenceFailure,
   runIdempotentPersistenceTransaction,
   type IdempotentPersistenceTransactionOptions,
 } from "./persistence-errors";
@@ -521,6 +523,39 @@ async function restoreRlsContextSettings(
   }
 }
 
+/** Attribute only failures outside the application callback to our transaction
+ * driver. BEGIN/COMMIT/ROLLBACK can throw raw postgres.js errors, unlike ORM
+ * queries. This supplies provenance, never transaction retry permission. */
+async function withDatabaseTransactionProvenance<T>(
+  db: Database,
+  fn: (db: Database) => Promise<T>,
+  transactionConfig?: PgTransactionConfig,
+): Promise<T> {
+  let entered = false;
+  let callbackFailure: { error: unknown } | undefined;
+  try {
+    return await db.transaction(async (tx) => {
+      entered = true;
+      try {
+        return await fn(tx as unknown as Database);
+      } catch (error) {
+        callbackFailure = { error };
+        throw error;
+      }
+    }, transactionConfig);
+  } catch (error) {
+    // A provider/tool rejection propagated by a successful rollback is still
+    // the provider/tool's error, even if it has a connection-looking code.
+    if (callbackFailure && callbackFailure.error === error) throw error;
+    if (!isDatabasePersistenceFailure(error)) throw error;
+    throw new DatabaseTransactionError(
+      entered ? "settlement" : "admission",
+      error,
+      callbackFailure?.error,
+    );
+  }
+}
+
 export async function withRlsContext<T>(
   db: Database,
   context: RlsContext,
@@ -535,49 +570,53 @@ export async function withRlsContext<T>(
     restoreParentScope ? "savepoint_admission" : "transaction_admission",
   );
   try {
-    return await db.transaction(async (tx) => {
-      admission("completed");
-      const setup = startDatabaseTiming("rls_setup");
-      const scoped = tx as unknown as Database;
-      let parentScope: RlsContextSettings | null;
-      try {
-        parentScope = restoreParentScope ? await readRlsContextSettings(scoped) : null;
-        await setRlsContext(scoped, context);
-        if (context.workspaceId && sessionTenancyFence === "shared") {
-          await scoped.execute(
-            sql`select pg_advisory_xact_lock_shared(hashtextextended(${`session-tenancy:${context.workspaceId}`}, 0))`,
-          );
+    return await withDatabaseTransactionProvenance(
+      db,
+      async (tx) => {
+        admission("completed");
+        const setup = startDatabaseTiming("rls_setup");
+        const scoped = tx as unknown as Database;
+        let parentScope: RlsContextSettings | null;
+        try {
+          parentScope = restoreParentScope ? await readRlsContextSettings(scoped) : null;
+          await setRlsContext(scoped, context);
+          if (context.workspaceId && sessionTenancyFence === "shared") {
+            await scoped.execute(
+              sql`select pg_advisory_xact_lock_shared(hashtextextended(${`session-tenancy:${context.workspaceId}`}, 0))`,
+            );
+          }
+          // Defense-in-depth: read the LOCAL GUC back on THIS backend BEFORE running
+          // the scoped query. The set_config and this read share one db.transaction,
+          // which a transaction pooler pins to a single backend — so a mismatch here
+          // means the context was genuinely lost (a torn transaction / pooler backend
+          // swap), not normal operation. Without this guard such an event runs the
+          // scoped read with an empty account_id and returns zero RLS-visible rows,
+          // manufacturing a phantom "no active subscription" from a credential that is
+          // in fact active. Convert that silent false into a loud, root-cause-bearing
+          // error so the caller can retry rather than permanently mis-decide.
+          await assertRlsContextApplied(scoped, context);
+          setup("completed");
+        } catch (error) {
+          setup("failed");
+          throw error;
         }
-        // Defense-in-depth: read the LOCAL GUC back on THIS backend BEFORE running
-        // the scoped query. The set_config and this read share one db.transaction,
-        // which a transaction pooler pins to a single backend — so a mismatch here
-        // means the context was genuinely lost (a torn transaction / pooler backend
-        // swap), not normal operation. Without this guard such an event runs the
-        // scoped read with an empty account_id and returns zero RLS-visible rows,
-        // manufacturing a phantom "no active subscription" from a credential that is
-        // in fact active. Convert that silent false into a loud, root-cause-bearing
-        // error so the caller can retry rather than permanently mis-decide.
-        await assertRlsContextApplied(scoped, context);
-        setup("completed");
-      } catch (error) {
-        setup("failed");
-        throw error;
-      }
-      const callback = startDatabaseTiming("scoped_callback");
-      let value: T;
-      try {
-        value = await fn(scoped);
-        callback("completed");
-      } catch (error) {
-        callback("failed");
-        throw error;
-      }
-      // A nested transaction is a savepoint, and SET LOCAL survives successful
-      // savepoint release. Restore the parent tenant and actor proof together;
-      // writer/protocol capabilities intentionally remain transaction-wide.
-      if (parentScope) await restoreRlsContextSettings(scoped, parentScope);
-      return value;
-    }, transactionConfig);
+        const callback = startDatabaseTiming("scoped_callback");
+        let value: T;
+        try {
+          value = await fn(scoped);
+          callback("completed");
+        } catch (error) {
+          callback("failed");
+          throw error;
+        }
+        // A nested transaction is a savepoint, and SET LOCAL survives successful
+        // savepoint release. Restore the parent tenant and actor proof together;
+        // writer/protocol capabilities intentionally remain transaction-wide.
+        if (parentScope) await restoreRlsContextSettings(scoped, parentScope);
+        return value;
+      },
+      transactionConfig,
+    );
   } catch (error) {
     // No-op after callback entry; only admission failures are counted here.
     admission("failed");