@wopr-network/platform-core 0.1.0

package/src/auth/user-role-repository.test.ts

@@ -0,0 +1,149 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { DrizzleUserRoleRepository } from "./user-role-repository.js";
+
+describe("DrizzleUserRoleRepository", () => {
+  let db: PlatformDb;
+  let pool: PGlite;
+  let repo: DrizzleUserRoleRepository;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    repo = new DrizzleUserRoleRepository(db);
+  });
+
+  describe("grantRole", () => {
+    it("assigns a role and subsequent lookup returns it", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", "admin-1");
+      const roles = await repo.listRolesByUser("user-1");
+      expect(roles).toHaveLength(1);
+      expect(roles[0]).toEqual({ tenantId: "tenant-1", role: "user" });
+    });
+  });
+
+  describe("revokeRole", () => {
+    it("removes a granted role so it is no longer returned", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", "admin-1");
+      const removed = await repo.revokeRole("user-1", "tenant-1");
+      expect(removed).toBe(true);
+      const roles = await repo.listRolesByUser("user-1");
+      expect(roles).toHaveLength(0);
+    });
+
+    it("returns false when revoking a non-existent role", async () => {
+      const removed = await repo.revokeRole("user-1", "tenant-1");
+      expect(removed).toBe(false);
+    });
+  });
+
+  describe("listRolesByUser", () => {
+    it("returns only the specified user's roles across tenants", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", null);
+      await repo.grantRole("user-1", "tenant-2", "tenant_admin", null);
+      await repo.grantRole("user-2", "tenant-1", "user", null);
+
+      const roles = await repo.listRolesByUser("user-1");
+      expect(roles).toHaveLength(2);
+      const tenantIds = roles.map((r) => r.tenantId).sort();
+      expect(tenantIds).toEqual(["tenant-1", "tenant-2"]);
+    });
+
+    it("returns empty array for user with no roles", async () => {
+      const roles = await repo.listRolesByUser("nobody");
+      expect(roles).toEqual([]);
+    });
+  });
+
+  describe("listUsersByRole", () => {
+    it("returns all users with a given role in a tenant", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", null);
+      await repo.grantRole("user-2", "tenant-1", "user", null);
+      await repo.grantRole("user-3", "tenant-1", "tenant_admin", null);
+
+      const users = await repo.listUsersByRole("user", "tenant-1");
+      expect(users).toHaveLength(2);
+      const userIds = users.map((u) => u.userId).sort();
+      expect(userIds).toEqual(["user-1", "user-2"]);
+    });
+
+    it("does not return users from other tenants", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", null);
+      await repo.grantRole("user-2", "tenant-2", "user", null);
+
+      const users = await repo.listUsersByRole("user", "tenant-1");
+      expect(users).toHaveLength(1);
+      expect(users[0].userId).toBe("user-1");
+    });
+  });
+
+  describe("isPlatformAdmin", () => {
+    it("returns true for a user with platform_admin role in sentinel tenant", async () => {
+      await repo.grantRole("admin-1", "*", "platform_admin", null);
+      expect(await repo.isPlatformAdmin("admin-1")).toBe(true);
+    });
+
+    it("returns false for a user with no roles", async () => {
+      expect(await repo.isPlatformAdmin("nobody")).toBe(false);
+    });
+
+    it("returns false for a tenant_admin in the sentinel tenant", async () => {
+      await repo.grantRole("user-1", "*", "tenant_admin", null);
+      expect(await repo.isPlatformAdmin("user-1")).toBe(false);
+    });
+
+    it("returns false for a platform_admin in a regular tenant", async () => {
+      await repo.grantRole("user-1", "tenant-1", "platform_admin", null);
+      expect(await repo.isPlatformAdmin("user-1")).toBe(false);
+    });
+  });
+
+  describe("idempotent grant", () => {
+    it("granting the same role twice does not error or duplicate", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", "admin-1");
+      await repo.grantRole("user-1", "tenant-1", "user", "admin-1");
+
+      const roles = await repo.listRolesByUser("user-1");
+      expect(roles).toHaveLength(1);
+    });
+
+    it("granting a different role to same user+tenant upserts", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", "admin-1");
+      await repo.grantRole("user-1", "tenant-1", "tenant_admin", "admin-2");
+
+      const roles = await repo.listRolesByUser("user-1");
+      expect(roles).toHaveLength(1);
+      expect(roles[0].role).toBe("tenant_admin");
+    });
+  });
+
+  describe("getTenantIdByUserId", () => {
+    it("returns the tenant ID for a user with a role", async () => {
+      await repo.grantRole("user-1", "tenant-1", "user", null);
+      const tenantId = await repo.getTenantIdByUserId("user-1");
+      expect(tenantId).toBe("tenant-1");
+    });
+
+    it("returns null for a user with no roles", async () => {
+      const tenantId = await repo.getTenantIdByUserId("nobody");
+      expect(tenantId).toBeNull();
+    });
+
+    it("excludes platform admin sentinel tenant", async () => {
+      await repo.grantRole("admin-1", "*", "platform_admin", null);
+      const tenantId = await repo.getTenantIdByUserId("admin-1");
+      expect(tenantId).toBeNull();
+    });
+  });
+});

package/src/auth/user-role-repository.ts

@@ -0,0 +1,67 @@
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { userRoles } from "../db/schema/user-roles.js";
+
+export interface IUserRoleRepository {
+  getTenantIdByUserId(userId: string): Promise<string | null>;
+  grantRole(userId: string, tenantId: string, role: string, grantedBy: string | null): Promise<void>;
+  revokeRole(userId: string, tenantId: string): Promise<boolean>;
+  listRolesByUser(userId: string): Promise<Array<{ tenantId: string; role: string }>>;
+  listUsersByRole(role: string, tenantId: string): Promise<Array<{ userId: string; role: string }>>;
+  isPlatformAdmin(userId: string): Promise<boolean>;
+}
+
+export class DrizzleUserRoleRepository implements IUserRoleRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getTenantIdByUserId(userId: string): Promise<string | null> {
+    const rows = await this.db
+      .select({ tenantId: userRoles.tenantId })
+      .from(userRoles)
+      .where(eq(userRoles.userId, userId))
+      .limit(1);
+    const tenantId = rows[0]?.tenantId ?? null;
+    // Exclude platform-admin sentinel value
+    return tenantId === "*" ? null : tenantId;
+  }
+
+  async grantRole(userId: string, tenantId: string, role: string, grantedBy: string | null): Promise<void> {
+    await this.db
+      .insert(userRoles)
+      .values({ userId, tenantId, role, grantedBy, grantedAt: Date.now() })
+      .onConflictDoUpdate({
+        target: [userRoles.userId, userRoles.tenantId],
+        set: { role, grantedBy, grantedAt: Date.now() },
+      });
+  }
+
+  async revokeRole(userId: string, tenantId: string): Promise<boolean> {
+    const result = await this.db
+      .delete(userRoles)
+      .where(and(eq(userRoles.userId, userId), eq(userRoles.tenantId, tenantId)))
+      .returning({ userId: userRoles.userId });
+    return result.length > 0;
+  }
+
+  async listRolesByUser(userId: string): Promise<Array<{ tenantId: string; role: string }>> {
+    return this.db
+      .select({ tenantId: userRoles.tenantId, role: userRoles.role })
+      .from(userRoles)
+      .where(eq(userRoles.userId, userId));
+  }
+
+  async listUsersByRole(role: string, tenantId: string): Promise<Array<{ userId: string; role: string }>> {
+    return this.db
+      .select({ userId: userRoles.userId, role: userRoles.role })
+      .from(userRoles)
+      .where(and(eq(userRoles.role, role), eq(userRoles.tenantId, tenantId)));
+  }
+
+  async isPlatformAdmin(userId: string): Promise<boolean> {
+    const rows = await this.db
+      .select({ userId: userRoles.userId })
+      .from(userRoles)
+      .where(and(eq(userRoles.userId, userId), eq(userRoles.tenantId, "*"), eq(userRoles.role, "platform_admin")));
+    return rows.length > 0;
+  }
+}

package/src/billing/drizzle-webhook-seen-repository.ts

@@ -0,0 +1,34 @@
+import { and, eq, lt } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+import { webhookSeenEvents } from "../db/schema/index.js";
+import type { WebhookSeenEvent } from "../credits/repository-types.js";
+import type { IWebhookSeenRepository } from "./webhook-seen-repository.js";
+
+export class DrizzleWebhookSeenRepository implements IWebhookSeenRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async isDuplicate(eventId: string, source: string): Promise<boolean> {
+    const row = (
+      await this.db
+        .select()
+        .from(webhookSeenEvents)
+        .where(and(eq(webhookSeenEvents.eventId, eventId), eq(webhookSeenEvents.source, source)))
+    )[0];
+    return row !== undefined;
+  }
+
+  async markSeen(eventId: string, source: string): Promise<WebhookSeenEvent> {
+    const seenAt = Date.now();
+    await this.db.insert(webhookSeenEvents).values({ eventId, source, seenAt }).onConflictDoNothing();
+    return { eventId, source, seenAt };
+  }
+
+  async purgeExpired(ttlMs: number): Promise<number> {
+    const cutoff = Date.now() - ttlMs;
+    const result = await this.db
+      .delete(webhookSeenEvents)
+      .where(lt(webhookSeenEvents.seenAt, cutoff))
+      .returning({ id: webhookSeenEvents.eventId });
+    return result.length;
+  }
+}

package/src/billing/index.ts

@@ -0,0 +1,22 @@
+export type {
+  SavedPaymentMethod,
+  CheckoutOpts,
+  CheckoutSession,
+  ChargeOpts,
+  ChargeResult,
+  SetupResult,
+  PortalOpts,
+  WebhookResult,
+  IPaymentProcessor,
+  Invoice,
+} from "./payment-processor.js";
+export { PaymentMethodOwnershipError } from "./payment-processor.js";
+export type { IWebhookSeenRepository } from "./webhook-seen-repository.js";
+export { noOpReplayGuard } from "./webhook-seen-repository.js";
+export { DrizzleWebhookSeenRepository } from "./drizzle-webhook-seen-repository.js";
+
+// Stripe
+export * from "./stripe/index.js";
+
+// PayRam
+export * from "./payram/index.js";

package/src/billing/payment-processor.test.ts

@@ -0,0 +1,93 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type {
+  ChargeOpts,
+  ChargeResult,
+  CheckoutOpts,
+  CheckoutSession,
+  IPaymentProcessor,
+  PortalOpts,
+  SavedPaymentMethod,
+  SetupResult,
+  WebhookResult,
+} from "./payment-processor.js";
+
+describe("IPaymentProcessor types", () => {
+  it("CheckoutOpts has required fields", () => {
+    expectTypeOf<CheckoutOpts>().toHaveProperty("tenant");
+    expectTypeOf<CheckoutOpts>().toHaveProperty("amount");
+    expectTypeOf<CheckoutOpts>().toHaveProperty("successUrl");
+    expectTypeOf<CheckoutOpts>().toHaveProperty("cancelUrl");
+  });
+
+  it("CheckoutSession has id and url", () => {
+    expectTypeOf<CheckoutSession>().toHaveProperty("id");
+    expectTypeOf<CheckoutSession>().toHaveProperty("url");
+  });
+
+  it("ChargeResult has success field", () => {
+    expectTypeOf<ChargeResult>().toHaveProperty("success");
+  });
+
+  it("WebhookResult uses Credit for credited field", () => {
+    expectTypeOf<WebhookResult>().toHaveProperty("handled");
+    expectTypeOf<WebhookResult>().toHaveProperty("eventType");
+  });
+
+  it("SavedPaymentMethod has id, label, isDefault", () => {
+    expectTypeOf<SavedPaymentMethod>().toHaveProperty("id");
+    expectTypeOf<SavedPaymentMethod>().toHaveProperty("label");
+    expectTypeOf<SavedPaymentMethod>().toHaveProperty("isDefault");
+  });
+
+  it("IPaymentProcessor has all required methods", () => {
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("name");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("createCheckoutSession");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("handleWebhook");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("supportsPortal");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("setupPaymentMethod");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("listPaymentMethods");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("detachPaymentMethod");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("charge");
+  });
+
+  it("createPortalSession is required on IPaymentProcessor", () => {
+    // Implementations that don't support portal must still implement createPortalSession (and throw)
+    const processor: IPaymentProcessor = {
+      name: "test",
+      createCheckoutSession: async () => ({ id: "s", url: "u" }),
+      handleWebhook: async () => ({ handled: true, eventType: "test" }),
+      supportsPortal: () => false,
+      createPortalSession: async () => {
+        throw new Error("Billing portal not supported");
+      },
+      setupPaymentMethod: async () => ({ clientSecret: "cs" }),
+      listPaymentMethods: async () => [],
+      detachPaymentMethod: async () => undefined,
+      charge: async () => ({ success: true }),
+      getCustomerEmail: async () => "",
+      updateCustomerEmail: async () => undefined,
+      listInvoices: async () => [],
+    };
+    expectTypeOf(processor).toMatchTypeOf<IPaymentProcessor>();
+  });
+
+  it("PortalOpts has tenant and returnUrl", () => {
+    expectTypeOf<PortalOpts>().toHaveProperty("tenant");
+    expectTypeOf<PortalOpts>().toHaveProperty("returnUrl");
+  });
+
+  it("SetupResult has clientSecret", () => {
+    expectTypeOf<SetupResult>().toHaveProperty("clientSecret");
+  });
+
+  it("ChargeOpts has tenant, amount, source", () => {
+    expectTypeOf<ChargeOpts>().toHaveProperty("tenant");
+    expectTypeOf<ChargeOpts>().toHaveProperty("amount");
+    expectTypeOf<ChargeOpts>().toHaveProperty("source");
+  });
+
+  it("IPaymentProcessor has getCustomerEmail and updateCustomerEmail", () => {
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("getCustomerEmail");
+    expectTypeOf<IPaymentProcessor>().toHaveProperty("updateCustomerEmail");
+  });
+});

package/src/billing/payment-processor.ts

@@ -0,0 +1,150 @@
+import type { Credit } from "../credits/credit.js";
+
+/** Thrown when a tenant tries to detach a payment method they don't own. */
+export class PaymentMethodOwnershipError extends Error {
+  readonly code = "PAYMENT_METHOD_NOT_OWNED" as const;
+  constructor() {
+    super("Payment method does not belong to this tenant");
+    this.name = "PaymentMethodOwnershipError";
+  }
+}
+
+/** A saved payment method on file for a tenant (processor-agnostic). */
+export interface SavedPaymentMethod {
+  /** Processor-specific payment method ID (e.g. Stripe pm_xxx, PayRam wallet address). */
+  id: string;
+  /** Human-readable label (e.g. "Visa ending 4242", "ETH wallet"). */
+  label: string;
+  /** Whether this is the tenant's default payment method. */
+  isDefault: boolean;
+}
+
+/** Options for creating a checkout session. */
+export interface CheckoutOpts {
+  /** Internal tenant ID. */
+  tenant: string;
+  /** Amount to charge. Required when no priceId is provided; may be omitted when priceId resolves the amount. */
+  amount?: Credit;
+  /** URL to redirect to after successful checkout. */
+  successUrl: string;
+  /** URL to redirect to if the user cancels checkout. */
+  cancelUrl: string;
+  /** Processor-specific price ID (e.g. Stripe price_xxx). Processors that don't use price IDs may ignore this. */
+  priceId?: string;
+}
+
+/** Returned after creating a checkout session. */
+export interface CheckoutSession {
+  /** Processor-specific session ID (for idempotency / correlation). */
+  id: string;
+  /** URL to redirect the user to for payment. */
+  url: string;
+}
+
+/** Options for charging a saved payment method off-session. */
+export interface ChargeOpts {
+  /** Internal tenant ID. */
+  tenant: string;
+  /** Amount to charge. */
+  amount: Credit;
+  /** Descriptive source tag for ledger entries (e.g. "auto_topup_usage"). */
+  source: string;
+}
+
+/** Result of an off-session charge attempt. */
+export interface ChargeResult {
+  success: boolean;
+  /** Processor-specific payment reference (e.g. Stripe PaymentIntent ID). */
+  paymentReference?: string;
+  error?: string;
+}
+
+/** Result of setting up a payment method for future use. */
+export interface SetupResult {
+  /** Processor-specific client secret for frontend completion (e.g. Stripe SetupIntent). */
+  clientSecret: string;
+}
+
+/** Options for creating a billing portal session. */
+export interface PortalOpts {
+  /** Internal tenant ID. */
+  tenant: string;
+  /** URL to redirect to when the user is done managing billing. */
+  returnUrl: string;
+}
+
+/** Result of processing an incoming webhook from a payment processor. */
+export interface WebhookResult {
+  handled: boolean;
+  /** Processor-specific event type or status string. */
+  eventType: string;
+  tenant?: string;
+  /** Credits to grant to the tenant's ledger. */
+  credited?: Credit;
+  /** Bot IDs reactivated after credit purchase (WOP-447). */
+  reactivatedBots?: string[];
+  /** True when this event was a duplicate / replay. */
+  duplicate?: boolean;
+}
+
+/**
+ * Processor-agnostic payment interface.
+ *
+ * Each payment processor (Stripe, PayRam, future processors) implements
+ * this interface. The platform layer programs against IPaymentProcessor
+ * and never imports processor-specific types.
+ */
+export interface IPaymentProcessor {
+  /** Human-readable processor name (e.g. "stripe", "payram"). */
+  readonly name: string;
+
+  /** Create a checkout session for a one-time credit purchase. */
+  createCheckoutSession(opts: CheckoutOpts): Promise<CheckoutSession>;
+
+  /** Process an incoming webhook payload. */
+  handleWebhook(payload: Buffer, signature: string): Promise<WebhookResult>;
+
+  /** Whether this processor supports a self-service billing portal. */
+  supportsPortal(): boolean;
+
+  /**
+   * Create a billing portal session (only if supportsPortal() is true).
+   * Implementations that return false from supportsPortal() must throw rather than leaving this undefined.
+   */
+  createPortalSession(opts: PortalOpts): Promise<{ url: string }>;
+
+  /** Save a payment method for future off-session charges. */
+  setupPaymentMethod(tenant: string): Promise<SetupResult>;
+
+  /** List saved payment methods for a tenant. */
+  listPaymentMethods(tenant: string): Promise<SavedPaymentMethod[]>;
+
+  /** Charge a saved payment method off-session. */
+  charge(opts: ChargeOpts): Promise<ChargeResult>;
+
+  /** Detach a payment method from the tenant's account. */
+  detachPaymentMethod(tenant: string, paymentMethodId: string): Promise<void>;
+
+  /** Get the billing email for a tenant's customer account. Returns "" if no customer exists. */
+  getCustomerEmail(tenantId: string): Promise<string>;
+
+  /** Update the billing email for a tenant's customer account. */
+  updateCustomerEmail(tenantId: string, email: string): Promise<void>;
+
+  /** List invoices for a tenant. Returns an empty array if no customer exists. */
+  listInvoices(tenantId: string): Promise<Invoice[]>;
+}
+
+/** A past invoice for a tenant (processor-agnostic). */
+export interface Invoice {
+  /** Processor-specific invoice ID (e.g. Stripe in_xxx). */
+  id: string;
+  /** ISO 8601 date string for when the invoice was created. */
+  date: string;
+  /** Invoice total in cents. */
+  amountCents: number;
+  /** Invoice status (e.g. "paid", "open", "void", "uncollectible"). */
+  status: string;
+  /** URL to download the invoice PDF. Empty string if unavailable. */
+  downloadUrl: string;
+}

package/src/billing/payram/cents-credits-boundary.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * Regression tests for PayRam cents/credits boundary (WOP-1058).
+ *
+ * Verifies that the USD-to-cents conversion in checkout and
+ * the cents-to-credits flow in the webhook maintain correct units.
+ *
+ * If any of these tests fail after a rename/refactor, a _cents field was
+ * incorrectly changed to store Credit raw units (nanodollars) instead of
+ * USD cents. See src/monetization/credits/credit-ledger.ts for naming convention.
+ */
+describe("WOP-1058: PayRam cents/credits boundary", () => {
+  it("USD to cents conversion is correct (mirrors checkout.ts pattern)", () => {
+    // This mirrors the conversion in payram/checkout.ts: Math.round(opts.amountUsd * 100)
+    const amountUsd = 25;
+    const amountUsdCents = Math.round(amountUsd * 100);
+    expect(amountUsdCents).toBe(2500);
+    // Must NOT be nanodollar scale
+    expect(amountUsdCents).toBeLessThan(1_000_000);
+  });
+
+  it("minimum payment amount converts to valid cents", () => {
+    const MIN_PAYMENT_USD = 10;
+    const cents = Math.round(MIN_PAYMENT_USD * 100);
+    expect(cents).toBe(1000);
+    expect(Number.isInteger(cents)).toBe(true);
+    // Sanity: $10 is 1000 cents, NOT 10_000_000_000 nanodollars
+    expect(cents).toBeLessThan(1_000_000);
+  });
+
+  it("fractional USD amounts round correctly to cents", () => {
+    // Edge case: floating point conversion
+    const amountUsd = 10.99;
+    const cents = Math.round(amountUsd * 100);
+    expect(cents).toBe(1099);
+    expect(cents).toBeLessThan(1_000_000);
+  });
+
+  it("amountUsdCents stored in charge record equals USD * 100 (not nanodollars)", () => {
+    // The core invariant: payram/checkout.ts stores Math.round(amountUsd * 100)
+    // as amountUsdCents. This test proves the conversion stays at cent scale.
+    const testCases: Array<{ usd: number; expectedCents: number }> = [
+      { usd: 10, expectedCents: 1000 },
+      { usd: 25, expectedCents: 2500 },
+      { usd: 50, expectedCents: 5000 },
+      { usd: 100, expectedCents: 10000 },
+    ];
+
+    for (const { usd, expectedCents } of testCases) {
+      const amountUsdCents = Math.round(usd * 100);
+      expect(amountUsdCents).toBe(expectedCents);
+      // CREDIT SCALE = 1_000_000_000. If this value approaches that, unit confusion occurred.
+      expect(amountUsdCents).toBeLessThan(1_000_000);
+    }
+  });
+
+  it("creditedCents in webhook equals amountUsdCents from charge store (1:1 for PayRam)", () => {
+    // payram/webhook.ts: const creditCents = charge.amountUsdCents;
+    // The credited amount always equals the stored USD cents — no bonus tiers for PayRam.
+    const chargeAmountUsdCents = 2500; // $25.00
+    const creditCents = chargeAmountUsdCents; // 1:1 for PayRam
+    expect(creditCents).toBe(2500);
+    // creditedCents must be 2500 (cents), not 25_000_000_000 (nanodollars)
+    expect(creditCents).toBeLessThan(1_000_000);
+  });
+
+  it("cents-to-nanodollar scale difference is preserved as a sanity constant", () => {
+    // Credit.SCALE = 1_000_000_000 nanodollars per dollar
+    // 1 USD cent = 10_000_000 nanodollars (SCALE / 100)
+    // This test documents the relationship so future developers understand the gap.
+    const CREDIT_SCALE = 1_000_000_000;
+    const CENTS_PER_DOLLAR = 100;
+    const NANODOLLARS_PER_CENT = CREDIT_SCALE / CENTS_PER_DOLLAR;
+
+    expect(NANODOLLARS_PER_CENT).toBe(10_000_000);
+
+    // $25 in cents = 2500. $25 in nanodollars = 25_000_000_000.
+    // These are 10_000_000x apart — confirming that mixing the two is catastrophic.
+    const twentyFiveDollarsInCents = 2500;
+    const twentyFiveDollarsInNanodollars = 25 * CREDIT_SCALE;
+    expect(twentyFiveDollarsInNanodollars / twentyFiveDollarsInCents).toBe(NANODOLLARS_PER_CENT);
+  });
+});