@opengeni/db 1.0.2 → 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.0.2",
+  "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.0.2",
-    "@opengeni/codex": "1.0.2",
-    "@opengeni/config": "1.0.2",
-    "@opengeni/contracts": "1.0.2",
-    "@opengeni/network": "1.0.2",
-    "@opengeni/observability": "1.0.2",
+    "@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/artifact-catalog.ts

@@ -2,7 +2,13 @@ import type { ArtifactCatalogKind, ArtifactCatalogListQuery } from "@opengeni/co
 import { sql, type SQL } from "drizzle-orm";
 import { withRlsContext, type Database } from "./database";
 
-export type ArtifactCatalogPosition = { key: string; kind: ArtifactCatalogKind; id: string };
+export type ArtifactCatalogPosition = {
+  key: string;
+  kind: ArtifactCatalogKind;
+  id: string;
+  /** Legacy cursor frontiers did not carry this bit. */
+  pinned?: boolean | undefined;
+};
 /** Internal candidates are NOT an authorized public projection. */
 export type ArtifactCatalogCandidate = {
   id: string;
@@ -16,8 +22,22 @@ export type ArtifactCatalogCandidate = {
   source_session_id: string | null;
   version_id: string | null;
   sort_key: string;
+  pinned?: boolean;
 };
 
+/** API callers must first verify publish permission and domain-specific read authority. */
+export async function updateArtifactPin(
+  db: Database,
+  scope: { accountId: string; workspaceId: string },
+  input: { kind: ArtifactCatalogKind; artifactId: string; pinned: boolean },
+): Promise<void> {
+  await withRlsContext(db, scope, async (tx) => {
+    await tx.execute(sql`select opengeni_private.update_artifact_pin(
+      ${scope.accountId}::uuid, ${scope.workspaceId}::uuid,
+      ${input.kind}::text, ${input.artifactId}::text, ${input.pinned}::boolean)`);
+  });
+}
+
 /** Called only after immutable bytes have been retained by explicit publication. */
 export async function recordSandboxFilePublication(
   db: Database,
@@ -84,7 +104,7 @@ export async function listArtifactCatalogCandidates(
     branches.push(sql`
     SELECT p.file_id::text AS id, p.kind, p.title, 'active'::text AS status,
       p.published_at AS created_at, p.published_at AS updated_at, p.source_session_id, NULL::text AS version_id, 'sandbox_file'::text AS origin
-    FROM opengeni_private.list_sandbox_file_publications(${scope.accountId}::uuid, ${scope.workspaceId}::uuid,
+    FROM opengeni_private.list_sandbox_file_publications_pinned(${scope.accountId}::uuid, ${scope.workspaceId}::uuid,
       ${JSON.stringify({ sourceSessionId: source, q: query.q, kinds: publishedKinds, sort: query.sort, snapshotAt: input.snapshotAt, after: input.after, limit: input.limit })}::jsonb) p`);
   if (!branches.length) return [];
   const sort =
@@ -95,22 +115,28 @@ export async function listArtifactCatalogCandidates(
         : sql`to_char(updated_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US')`;
   const descending = query.sort !== "title";
   const position = input.after;
-  const keyset = !position
+  const secondaryKeyset = !position
     ? sql`true`
     : sql`(
     sort_key COLLATE "C" ${descending ? sql`<` : sql`>`} ${position.key} COLLATE "C"
     OR (sort_key = ${position.key} AND (kind COLLATE "C", id COLLATE "C") > (${position.kind}, ${position.id})))`;
+  const keyset = !position
+    ? sql`true`
+    : sql`(pinned < ${position.pinned ?? false}::boolean OR
+        (pinned = ${position.pinned ?? false}::boolean AND ${secondaryKeyset}))`;
   return withRlsContext(
     db,
     scope,
     async (tx) => {
       const result = await tx.execute(sql`
       WITH candidates AS (${sql.join(branches, sql` UNION ALL `)}),
-      ordered AS (SELECT *, ${sort} AS sort_key FROM candidates
+      ordered AS (SELECT candidates.*, ${sort} AS sort_key, (pins.artifact_id IS NOT NULL) AS pinned
+        FROM candidates LEFT JOIN opengeni_private.list_artifact_pins(${scope.accountId}::uuid, ${scope.workspaceId}::uuid) pins
+          ON pins.kind = candidates.kind AND pins.artifact_id = candidates.id
         WHERE status = ${query.status} AND created_at <= ${input.snapshotAt}::timestamptz
           ${query.q ? sql`AND strpos(lower(title), lower(${query.q})) > 0` : sql``})
       SELECT * FROM ordered WHERE ${keyset}
-      ORDER BY sort_key COLLATE "C" ${descending ? sql`DESC` : sql`ASC`}, kind COLLATE "C", id COLLATE "C"
+      ORDER BY pinned DESC, sort_key COLLATE "C" ${descending ? sql`DESC` : sql`ASC`}, kind COLLATE "C", id COLLATE "C"
       LIMIT ${input.limit}`);
       return (
         Array.isArray(result) ? result : (result as { rows: ArtifactCatalogCandidate[] }).rows

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;
+}