@wopr-network/platform-core 1.39.4 → 1.39.6

package/dist/fleet/instance.test.js

@@ -0,0 +1,343 @@
+import { PassThrough } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Instance } from "./instance.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeProfile(overrides = {}) {
+    return {
+        id: "bot-1",
+        tenantId: "tenant-1",
+        name: "test-bot",
+        description: "A test bot",
+        image: "ghcr.io/wopr-network/test:latest",
+        env: {},
+        restartPolicy: "unless-stopped",
+        releaseChannel: "stable",
+        updatePolicy: "manual",
+        ...overrides,
+    };
+}
+/** Build a mock Docker.Container with sensible defaults */
+function mockContainer(state = { Running: true, Status: "running" }) {
+    return {
+        start: vi.fn().mockResolvedValue(undefined),
+        stop: vi.fn().mockResolvedValue(undefined),
+        restart: vi.fn().mockResolvedValue(undefined),
+        remove: vi.fn().mockResolvedValue(undefined),
+        inspect: vi.fn().mockResolvedValue({
+            Id: "abc123",
+            Name: "/wopr-test-bot",
+            Created: "2026-01-01T00:00:00Z",
+            State: {
+                Running: state.Running ?? true,
+                Status: state.Status ?? "running",
+                StartedAt: "2026-01-01T00:00:00Z",
+                Health: { Status: "healthy" },
+            },
+            NetworkSettings: { Ports: {} },
+        }),
+        logs: vi.fn(),
+        stats: vi.fn().mockResolvedValue({
+            cpu_stats: { cpu_usage: { total_usage: 200 }, system_cpu_usage: 1000, online_cpus: 2 },
+            precpu_stats: { cpu_usage: { total_usage: 100 }, system_cpu_usage: 500 },
+            memory_stats: { usage: 100 * 1024 * 1024, limit: 512 * 1024 * 1024 },
+        }),
+        exec: vi.fn(),
+    };
+}
+function mockDocker(container) {
+    return {
+        getContainer: vi.fn().mockReturnValue(container),
+        pull: vi.fn(),
+        modem: {
+            followProgress: vi.fn((_stream, cb) => cb(null)),
+            demuxStream: vi.fn(),
+        },
+    };
+}
+function mockEventEmitter() {
+    return { emit: vi.fn() };
+}
+function mockMetricsTracker() {
+    return { reset: vi.fn(), getMetrics: vi.fn().mockReturnValue(null) };
+}
+function buildInstance(overrides = {}) {
+    const container = mockContainer();
+    const docker = mockDocker(container);
+    const emitter = mockEventEmitter();
+    const metrics = mockMetricsTracker();
+    const profile = makeProfile();
+    const instance = new Instance({
+        docker,
+        profile,
+        containerId: "abc123",
+        containerName: "wopr-test-bot",
+        url: "http://wopr-test-bot:7437",
+        eventEmitter: emitter,
+        botMetricsTracker: metrics,
+        ...overrides,
+    });
+    return { instance, container, docker, emitter, metrics };
+}
+function buildRemoteInstance() {
+    const container = mockContainer();
+    const docker = mockDocker(container);
+    return new Instance({
+        docker,
+        profile: makeProfile(),
+        containerId: "remote:node-3",
+        containerName: "wopr-test-bot",
+        url: "remote://node-3/wopr-test-bot",
+    });
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("Instance", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    // -----------------------------------------------------------------------
+    // P0: Remote guard
+    // -----------------------------------------------------------------------
+    describe("remote instances", () => {
+        const ops = [
+            "start",
+            "stop",
+            "restart",
+            "remove",
+            "pullImage",
+            "logs",
+            "logStream",
+            "getVolumeUsage",
+            "status",
+            "containerState",
+        ];
+        for (const op of ops) {
+            it(`${op}() throws on remote instance`, async () => {
+                const remote = buildRemoteInstance();
+                const args = op === "logStream" ? [{}] : [];
+                await expect(remote[op](...args)).rejects.toThrow("not supported on remote instances");
+            });
+        }
+        it("emitCreated() works on remote instances (no Docker)", () => {
+            const emitter = mockEventEmitter();
+            const docker = mockDocker(mockContainer());
+            const remote = new Instance({
+                docker,
+                profile: makeProfile(),
+                containerId: "remote:node-5",
+                containerName: "wopr-test-bot",
+                url: "remote://node-5/wopr-test-bot",
+                eventEmitter: emitter,
+            });
+            expect(() => remote.emitCreated()).not.toThrow();
+            expect(emitter.emit.mock.calls[0][0]).toMatchObject({ type: "bot.created" });
+        });
+    });
+    // -----------------------------------------------------------------------
+    // restart()
+    // -----------------------------------------------------------------------
+    describe("restart()", () => {
+        it("restarts a running container and emits event", async () => {
+            const { instance, container, emitter } = buildInstance();
+            await instance.restart();
+            expect(container.inspect).toHaveBeenCalled();
+            expect(container.restart).toHaveBeenCalled();
+            expect(emitter.emit.mock.calls[0][0]).toMatchObject({ type: "bot.restarted" });
+        });
+        it("rejects when container is in paused state", async () => {
+            const container = mockContainer({ Running: false, Status: "paused" });
+            const docker = mockDocker(container);
+            const instance = new Instance({
+                docker,
+                profile: makeProfile(),
+                containerId: "abc123",
+                containerName: "wopr-test-bot",
+                url: "http://wopr-test-bot:7437",
+            });
+            await expect(instance.restart()).rejects.toThrow(/Cannot restart.*paused/);
+        });
+        it("accepts stopped/exited/dead states", async () => {
+            for (const status of ["stopped", "exited", "dead"]) {
+                const container = mockContainer({ Running: false, Status: status });
+                const docker = mockDocker(container);
+                const instance = new Instance({
+                    docker,
+                    profile: makeProfile(),
+                    containerId: "abc123",
+                    containerName: "wopr-test-bot",
+                    url: "http://wopr-test-bot:7437",
+                });
+                await expect(instance.restart()).resolves.toBeUndefined();
+            }
+        });
+        it("resets metrics tracker on restart", async () => {
+            const { instance, metrics } = buildInstance();
+            await instance.restart();
+            expect(metrics.reset).toHaveBeenCalledWith("bot-1");
+        });
+    });
+    // -----------------------------------------------------------------------
+    // pullImage()
+    // -----------------------------------------------------------------------
+    describe("pullImage()", () => {
+        it("pulls image without auth when no env vars set", async () => {
+            const { instance, docker } = buildInstance();
+            const pullMock = docker.pull;
+            pullMock.mockResolvedValue("stream");
+            await instance.pullImage();
+            expect(pullMock).toHaveBeenCalledWith("ghcr.io/wopr-network/test:latest", {});
+        });
+        it("pulls image with auth when registry env vars are set", async () => {
+            process.env.REGISTRY_USERNAME = "user";
+            process.env.REGISTRY_PASSWORD = "pass";
+            process.env.REGISTRY_SERVER = "ghcr.io";
+            try {
+                const { instance, docker } = buildInstance();
+                const pullMock = docker.pull;
+                pullMock.mockResolvedValue("stream");
+                await instance.pullImage();
+                expect(pullMock).toHaveBeenCalledWith("ghcr.io/wopr-network/test:latest", {
+                    authconfig: { username: "user", password: "pass", serveraddress: "ghcr.io" },
+                });
+            }
+            finally {
+                delete process.env.REGISTRY_USERNAME;
+                delete process.env.REGISTRY_PASSWORD;
+                delete process.env.REGISTRY_SERVER;
+            }
+        });
+    });
+    // -----------------------------------------------------------------------
+    // logs()
+    // -----------------------------------------------------------------------
+    describe("logs()", () => {
+        it("returns demuxed log output", async () => {
+            const { instance, container } = buildInstance();
+            // Build a Docker multiplexed frame: 8-byte header + payload
+            const payload = Buffer.from("hello from container\n");
+            const header = Buffer.alloc(8);
+            header.writeUInt8(1, 0); // stdout stream
+            header.writeUInt32BE(payload.length, 4);
+            const frame = Buffer.concat([header, payload]);
+            container.logs.mockResolvedValue(frame);
+            const result = await instance.logs(50);
+            expect(result).toBe("hello from container\n");
+            expect(container.logs).toHaveBeenCalledWith(expect.objectContaining({ stdout: true, stderr: true, tail: 50, timestamps: true }));
+        });
+    });
+    // -----------------------------------------------------------------------
+    // getVolumeUsage()
+    // -----------------------------------------------------------------------
+    describe("getVolumeUsage()", () => {
+        it("returns parsed df output for a running container", async () => {
+            const { instance, container } = buildInstance();
+            const dfOutput = "Filesystem      1B-blocks      Used Available Use% Mounted on\n/dev/sda1  1073741824 536870912 536870912  50% /data\n";
+            const mockStream = new PassThrough();
+            const execObj = {
+                start: vi.fn((_opts, cb) => {
+                    cb(null, mockStream);
+                    mockStream.end(dfOutput);
+                }),
+            };
+            container.exec.mockResolvedValue(execObj);
+            const result = await instance.getVolumeUsage();
+            expect(result).toEqual({
+                totalBytes: 1073741824,
+                usedBytes: 536870912,
+                availableBytes: 536870912,
+            });
+        });
+        it("returns null when container is not running", async () => {
+            const container = mockContainer({ Running: false, Status: "stopped" });
+            const docker = mockDocker(container);
+            const instance = new Instance({
+                docker,
+                profile: makeProfile(),
+                containerId: "abc123",
+                containerName: "wopr-test-bot",
+                url: "http://wopr-test-bot:7437",
+            });
+            const result = await instance.getVolumeUsage();
+            expect(result).toBeNull();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // status()
+    // -----------------------------------------------------------------------
+    describe("status()", () => {
+        it("returns BotStatus with stats for running container", async () => {
+            const { instance } = buildInstance();
+            const st = await instance.status();
+            expect(st.id).toBe("bot-1");
+            expect(st.state).toBe("running");
+            expect(st.containerId).toBe("abc123");
+            expect(st.stats).toBeDefined();
+            expect(st.stats?.cpuPercent).toBeGreaterThanOrEqual(0);
+            expect(st.stats?.memoryUsageMb).toBe(100);
+            expect(st.health).toBe("healthy");
+        });
+        it("returns offline status when container is gone", async () => {
+            const container = mockContainer();
+            container.inspect.mockRejectedValue(new Error("No such container"));
+            const docker = mockDocker(container);
+            const instance = new Instance({
+                docker,
+                profile: makeProfile(),
+                containerId: "abc123",
+                containerName: "wopr-test-bot",
+                url: "http://wopr-test-bot:7437",
+            });
+            const st = await instance.status();
+            expect(st.state).toBe("stopped");
+            expect(st.containerId).toBeNull();
+            expect(st.stats).toBeNull();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // Concurrency lock
+    // -----------------------------------------------------------------------
+    describe("withLock serialization", () => {
+        it("serializes concurrent restart calls", async () => {
+            const callOrder = [];
+            const container = mockContainer();
+            const docker = mockDocker(container);
+            // Make restart take some time
+            container.inspect.mockImplementation(async () => {
+                callOrder.push("inspect-start");
+                await new Promise((r) => setTimeout(r, 50));
+                callOrder.push("inspect-end");
+                return {
+                    Id: "abc123",
+                    Name: "/wopr-test-bot",
+                    Created: "2026-01-01T00:00:00Z",
+                    State: { Running: true, Status: "running", StartedAt: "2026-01-01T00:00:00Z" },
+                };
+            });
+            container.restart.mockImplementation(async () => {
+                callOrder.push("restart");
+            });
+            const instance = new Instance({
+                docker,
+                profile: makeProfile(),
+                containerId: "abc123",
+                containerName: "wopr-test-bot",
+                url: "http://wopr-test-bot:7437",
+            });
+            // Fire two concurrent restarts
+            const p1 = instance.restart();
+            const p2 = instance.restart();
+            // Advance timers to let both complete
+            await vi.advanceTimersByTimeAsync(200);
+            await Promise.all([p1, p2]);
+            // Should see two full cycles without interleaving
+            expect(callOrder).toEqual(["inspect-start", "inspect-end", "restart", "inspect-start", "inspect-end", "restart"]);
+        });
+    });
+});

package/dist/node-agent/types.d.ts

@@ -46,9 +46,9 @@ export declare const commandSchema: z.ZodObject<{
     type: z.ZodEnum<{
         "bot.logs": "bot.logs";
         "bot.start": "bot.start";
-        "bot.restart": "bot.restart";
         "bot.remove": "bot.remove";
         "bot.stop": "bot.stop";
+        "bot.restart": "bot.restart";
         "bot.update": "bot.update";
         "bot.export": "bot.export";
         "bot.import": "bot.import";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.39.4",
+  "version": "1.39.6",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/credits/README.md

@@ -0,0 +1,106 @@
+# Double-Entry Credit Ledger
+
+A production double-entry accounting system for prepaid credit management. Every mutation posts a balanced journal entry where `sum(debits) === sum(credits)`. A tenant's "credit balance" is the balance of their `unearned_revenue` liability account.
+
+## Accounting Model
+
+```
+ASSETS (1000s)          — Cash, Stripe Receivable
+LIABILITIES (2000:tid)  — Unearned Revenue per tenant (the "credit balance")
+EQUITY (3000s)          — Retained Earnings
+REVENUE (4000s)         — Bot Runtime, Adapter Usage, Addon, Storage, Onboarding, Expired Credits
+EXPENSES (5000s)        — Signup Grant, Admin Grant, Promo, Referral, Affiliate, Bounty, Dividend, Correction
+```
+
+### Transaction Flows
+
+| Operation | Debit | Credit | Effect |
+|-----------|-------|--------|--------|
+| Purchase | Cash (1000) | Unearned Revenue (2000:tid) | Tenant buys credits |
+| Usage | Unearned Revenue (2000:tid) | Revenue (4000-4050) | Credits consumed, revenue recognized |
+| Grant | Expense (5000-5070) | Unearned Revenue (2000:tid) | Free credits issued |
+| Refund | Unearned Revenue (2000:tid) | Cash (1000) | Money returned to tenant |
+| Expiry | Unearned Revenue (2000:tid) | Revenue: Expired (4060) | Unused credits recognized as revenue |
+
+The accounting equation holds at all times: `Assets = Liabilities + Equity + Revenue - Expenses`.
+
+## Safety Guarantees
+
+### Double-Entry Invariant
+Every journal entry requires at least 2 lines. `sum(debits) === sum(credits)` is verified with **BigInt arithmetic** before the database transaction begins. The `trialBalance()` method independently verifies `total_debits === total_credits` across all journal lines using BigInt aggregation.
+
+### Transaction Isolation (TOCTOU-Safe)
+All balance mutations use PostgreSQL `SELECT ... FOR UPDATE` row locks on both the `accounts` and `account_balances` rows. The balance check happens **inside** the transaction **after** acquiring locks, preventing time-of-check-to-time-of-use races under concurrent debit operations.
+
+### Deadlock Prevention
+Journal lines are sorted by `accountCode` before lock acquisition, establishing a consistent global lock ordering. This eliminates deadlocks when concurrent transactions touch overlapping accounts.
+
+### Overflow Protection
+- `Credit.fromRaw()` throws `RangeError` if the value exceeds `Number.MAX_SAFE_INTEGER` (~$9M in nanodollars)
+- `Credit.add()`, `subtract()`, `multiply()` all throw `RangeError` on overflow
+- Aggregate queries (`trialBalance`, `lifetimeSpend`, `sumPurchasesForPeriod`) use BigInt to prevent silent precision loss
+- Tiered observability warnings at $10K / $100K / $1M balances
+
+### Idempotency
+Journal entries support an optional `referenceId` with a unique constraint (partial index, NULL-safe). Callers use domain-specific prefixes to prevent double-posting:
+- `pi_<stripe_id>` — Stripe purchases
+- `runtime:<date>:<tenantId>` — Daily bot runtime billing
+- `runtime-tier:<date>:<tenantId>` — Resource tier surcharges
+- `runtime-storage:<date>:<tenantId>` — Storage tier surcharges
+- `runtime-addon:<date>:<tenantId>` — Infrastructure addon charges
+- `expiry:<entryId>` — Credit expiry clawbacks
+
+### Credit Expiry (Allowlist-Gated)
+Only entry types listed in `EXPIRABLE_CREDIT_TYPES` can be returned by `expiredCredits()`. The constant is typed as `as const satisfies readonly CreditType[]` — adding a new `CreditType` without updating the allowlist produces a compile error.
+
+## Value Object: `Credit`
+
+All amounts are stored as **nanodollars** (1 dollar = 1,000,000,000 raw units). The `Credit` class enforces integer-only arithmetic:
+
+```typescript
+Credit.fromDollars(0.001)  // 1,000,000 raw units
+Credit.fromCents(500)       // 5,000,000,000 raw units
+Credit.fromRaw(n)           // throws TypeError if not integer, RangeError if > MAX_SAFE_INTEGER
+
+credit.toCentsRounded()     // for display / API responses
+credit.toCentsFloor()       // for Stripe charges (never overcharge)
+credit.toRaw()              // for database storage
+```
+
+No floating-point arithmetic in storage or ledger paths. `Math.round()` is used only at input boundaries (`fromDollars`, `fromCents`, `multiply`).
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `ledger.ts` | `DrizzleLedger` — the core double-entry engine |
+| `credit.ts` | `Credit` value object with overflow protection |
+| `credit-expiry-cron.ts` | Sweeps expired grants, debits remaining balance |
+| `../monetization/credits/runtime-cron.ts` | Daily bot billing with per-charge-type idempotency |
+| `../gateway/credit-gate.ts` | Pre/post-call balance checks for the API gateway |
+| `../db/schema/ledger.ts` | Drizzle schema: accounts, journal_entries, journal_lines, account_balances |
+
+## Interface: `ILedger`
+
+```typescript
+post(input: PostEntryInput): Promise<JournalEntry>          // The primitive — posts a balanced entry
+credit(tenantId, amount, type, opts?): Promise<JournalEntry> // Add credits (DR source, CR liability)
+debit(tenantId, amount, type, opts?): Promise<JournalEntry>  // Deduct credits (DR liability, CR revenue)
+debitCapped(tenantId, maxAmount, type, opts?)                 // Atomic balance-capped debit (single txn)
+balance(tenantId): Promise<Credit>                            // Tenant's credit balance
+trialBalance(): Promise<TrialBalance>                         // Verify the books balance
+```
+
+## Audit History
+
+Audited 2026-03-16. Seven issues identified and resolved:
+
+| # | Issue | Fix |
+|---|-------|-----|
+| #86 | Runtime cron `continue` skipped surcharges on crash retry | Per-charge-type independent idempotency |
+| #87 | Credit expiry cron TOCTOU race on balance read | `debitCapped()` — atomic single-transaction balance read + debit |
+| #88 | `Credit.add()/subtract()/multiply()` bypassed overflow checks | `Number.isSafeInteger()` guard on all arithmetic results |
+| #89 | Potential deadlock from unsorted lock acquisition | Sort lines by `accountCode` before `FOR UPDATE` |
+| #90 | `expiredCredits()` used denylist (fragile to new types) | Allowlist `EXPIRABLE_CREDIT_TYPES` with compile-time safety |
+| #91 | Missing concurrency and edge-case tests | 6 new tests: race, corruption, deadlock, overflow, expiry |
+| #92 | `post()` pre-check used JS number (overflow-prone) | BigInt accumulators + guarded error formatting |

package/src/credits/credit-expiry-cron.test.ts

@@ -104,6 +104,42 @@ describe("runCreditExpiryCron", () => {
     expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
   });
 
+  it("skips expiry when balance has been fully consumed before cron runs", async () => {
+    // Simulate: grant expires but tenant spent everything before cron ran
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:fully-consumed",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
+    // Tenant spends entire balance before expiry cron runs
+    await ledger.debit("tenant-1", Credit.fromCents(500), "bot_runtime", { description: "Full spend" });
+
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    // Zero balance — nothing to expire
+    expect(result.processed).toBe(0);
+
+    const balance = await ledger.balance("tenant-1");
+    expect(balance.toCents()).toBe(0);
+  });
+
+  it("only expires remaining balance when usage reduced it between grant and expiry", async () => {
+    // Grant $5, spend $3 before cron, cron should only expire remaining $2
+    await ledger.credit("tenant-1", Credit.fromCents(500), "promo", {
+      description: "Promo",
+      referenceId: "promo:partial-concurrent",
+      expiresAt: "2026-01-10T00:00:00Z",
+    });
+    await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", { description: "Partial spend" });
+
+    const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+    expect(result.processed).toBe(1);
+    expect(result.expired).toContain("tenant-1");
+
+    // $5 granted - $3 used - $2 expired = $0
+    const balance = await ledger.balance("tenant-1");
+    expect(balance.toCents()).toBe(0);
+  });
+
   it("does not return unknown entry type even with expiresAt metadata", async () => {
     // Simulate a hypothetical new entry type that has expiresAt in metadata.
     // With the old denylist approach, this would be incorrectly returned.

package/src/credits/ledger.test.ts

@@ -53,6 +53,24 @@ describe("DrizzleLedger", () => {
       ).rejects.toThrow("Unbalanced");
     });
 
+    it("throws Unbalanced entry (not RangeError) when BigInt totals exceed MAX_SAFE_INTEGER", async () => {
+      // Two debit lines each at MAX_SAFE_INTEGER raw — their BigInt sum exceeds MAX_SAFE_INTEGER.
+      // Before the fix, Credit.fromRaw(Number(totalDebit)) would throw RangeError, masking the real error.
+      const big = Credit.fromRaw(Number.MAX_SAFE_INTEGER);
+      const small = Credit.fromRaw(1);
+      await expect(
+        ledger.post({
+          entryType: "purchase",
+          tenantId: "t1",
+          lines: [
+            { accountCode: "1000", amount: big, side: "debit" },
+            { accountCode: "1000", amount: big, side: "debit" },
+            { accountCode: "2000:t1", amount: small, side: "credit" },
+          ],
+        }),
+      ).rejects.toThrow("Unbalanced entry");
+    });
+
     it("rejects zero-amount lines", async () => {
       await expect(
         ledger.post({
@@ -260,6 +278,25 @@ describe("DrizzleLedger", () => {
     it("rejects zero amount", async () => {
       await expect(ledger.debit("t1", Credit.ZERO, "bot_runtime")).rejects.toThrow("must be positive");
     });
+
+    it("concurrent debits do not overdraft", async () => {
+      // Balance is $10.00 from beforeEach credit.
+      // Two concurrent $8 debits — only one should succeed.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+        ledger.debit("t1", Credit.fromCents(800), "bot_runtime"),
+      ]);
+
+      const successes = results.filter((r) => r.status === "fulfilled");
+      const failures = results.filter((r) => r.status === "rejected");
+      expect(successes).toHaveLength(1);
+      expect(failures).toHaveLength(1);
+      expect((failures[0] as PromiseRejectedResult).reason).toBeInstanceOf(InsufficientBalanceError);
+
+      // Balance should be $2.00, not -$6.00
+      const bal = await ledger.balance("t1");
+      expect(bal.toCentsRounded()).toBe(200);
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -334,6 +371,27 @@ describe("DrizzleLedger", () => {
       expect(tb.balanced).toBe(true);
       expect(tb.totalDebits.equals(tb.totalCredits)).toBe(true);
     });
+
+    it("detects imbalance from direct DB corruption", async () => {
+      await ledger.credit("t1", Credit.fromCents(100), "purchase");
+
+      // Corrupt the ledger: insert an unmatched debit line directly into journal_lines.
+      const entryRows = await pool.query<{ id: string }>("SELECT id FROM journal_entries LIMIT 1");
+      const accountRows = await pool.query<{ id: string }>("SELECT id FROM accounts WHERE code = '1000' LIMIT 1");
+      const entryId = entryRows.rows[0].id;
+      const accountId = accountRows.rows[0].id;
+
+      // Insert an unmatched debit line worth 999 raw units — no corresponding credit
+      await pool.query(
+        `INSERT INTO journal_lines (id, journal_entry_id, account_id, amount, side)
+         VALUES ('corrupt-line-1', $1, $2, 999, 'debit')`,
+        [entryId, accountId],
+      );
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(false);
+      expect(tb.difference.toRaw()).toBe(999);
+    });
   });
 
   // -----------------------------------------------------------------------
@@ -601,4 +659,59 @@ describe("DrizzleLedger", () => {
       expect(tb.balanced).toBe(true);
     });
   });
+
+  // -----------------------------------------------------------------------
+  // deadlock prevention — concurrent multi-line entries
+  // -----------------------------------------------------------------------
+
+  describe("deadlock prevention", () => {
+    it("concurrent multi-line entries with overlapping accounts succeed", async () => {
+      // Fund two tenants
+      await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+      await ledger.credit("t2", Credit.fromCents(1000), "purchase");
+
+      // Two entries that touch accounts in potentially reverse order.
+      // Both touch account 4000 (revenue), creating a potential lock conflict.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(50), "bot_runtime"),
+        ledger.debit("t2", Credit.fromCents(30), "bot_runtime"),
+      ]);
+
+      // Both should succeed — lock ordering prevents deadlock
+      expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+
+      // Verify balances are correct
+      expect((await ledger.balance("t1")).toCentsRounded()).toBe(950);
+      expect((await ledger.balance("t2")).toCentsRounded()).toBe(970);
+
+      // Revenue account should reflect both debits
+      expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(80);
+
+      // Trial balance must still be balanced
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
+
+    it("concurrent multi-line entries on same tenant serialize correctly", async () => {
+      await ledger.credit("t1", Credit.fromCents(1000), "purchase");
+
+      // Two debits on the same tenant, touching overlapping accounts.
+      const results = await Promise.allSettled([
+        ledger.debit("t1", Credit.fromCents(100), "bot_runtime"),
+        ledger.debit("t1", Credit.fromCents(200), "adapter_usage"),
+      ]);
+
+      expect(results.every((r) => r.status === "fulfilled")).toBe(true);
+
+      // Balance: $10 - $1 - $2 = $7
+      expect((await ledger.balance("t1")).toCentsRounded()).toBe(700);
+
+      // Revenue accounts
+      expect((await ledger.accountBalance("4000")).toCentsRounded()).toBe(100); // bot_runtime
+      expect((await ledger.accountBalance("4010")).toCentsRounded()).toBe(200); // adapter_usage
+
+      const tb = await ledger.trialBalance();
+      expect(tb.balanced).toBe(true);
+    });
+  });
 });