Payments bulldozer txn rework

.vscode/settings.json

@@ -7,10 +7,6 @@
   "typescript.tsdk": "node_modules/typescript/lib",
   "editor.tabSize": 2,
   "cSpell.words": [
-    "glassmorphic",
-    "sparkline",
-    "Clickhouse",
-    "pushable",
     "autoupdate",
     "backlinks",
     "Cancelation",
@@ -19,14 +15,15 @@
     "chinthakagodawita",
     "Ciphertext",
     "cjsx",
+    "Clickhouse",
     "clsx",
-    "dbgenerated",
     "cmdk",
     "codegen",
     "crockford",
     "Crudl",
     "ctsx",
     "datapoints",
+    "dbgenerated",
     "deindent",
     "Deindentable",
     "deindented",
@@ -42,6 +39,7 @@
     "fkey",
     "frontends",
     "geoip",
+    "glassmorphic",
     "healthcheck",
     "hookform",
     "hostable",
@@ -51,6 +49,7 @@
     "JWTs",
     "katex",
     "localstack",
+    "ltree",
     "lucide",
     "Luma",
     "midfix",
@@ -64,6 +63,7 @@
     "nicified",
     "nicify",
     "oidc",
+    "onnotice",
     "openapi",
     "opentelemetry",
     "otel",
@@ -81,6 +81,7 @@
     "Prefetchers",
     "Proxied",
     "psql",
+    "pushable",
     "qrcode",
     "QSTASH",
     "quetzallabs",
@@ -89,6 +90,7 @@
     "retryable",
     "RPID",
     "simplewebauthn",
+    "sparkline",
     "spoofable",
     "stackable",
     "stackauth",
@@ -109,6 +111,7 @@
     "Unmigrated",
     "unsubscribers",
     "upsert",
+    "upserted",
     "Upvotes",
     "upvoting",
     "webapi",

AGENTS.md

@@ -7,7 +7,7 @@ This file provides guidance to coding agents when working with code in this repo
 ### Essential Commands
 - **Install dependencies**: `pnpm install`
 - **Run tests**: `pnpm test run` (uses Vitest). You can filter with `pnpm test run <file-filters>`. The `run` is important to not trigger watch mode
-- **Lint code**: `pnpm lint`. `pnpm lint --fix` will fix some of the linting errors, prefer that over fixing them manually.
+- **Lint code**: `pnpm lint`. `pnpm lint --fix` will fix some of the linting errors, prefer that over fixing them manually. Use `pnpm -C <package> lint` to lint a specific package.
 - **Type check**: `pnpm typecheck`
 
 #### Extra commands
@@ -108,6 +108,7 @@ To see all development ports, refer to the index.html of `apps/dev-launchpad/pub
 - Any design components you add or modify in the dashboard, update the Playground page accordingly to showcase the changes.
 - Unless very clearly equivalent from types, prefer explicit null/undefinedness checks over boolean checks, eg. `foo == null` instead of `!foo`.
 - Ensure **aggressively** that all code has low coupling and high cohesion. This is really important as it makes sure our code remains consistent and maintainable. Eagerly refactor things into better abstractions and look out for them actively.
+- Always let me know about the tradeoffs and decisions you make while implementing a non-trivial change.
 - Whenever you change the URL of a page in the docs (or remove one), add a redirect in the docs-mintlify/docs.json file to make sure we don't lose any SEO juice.
 - When you made frontend (or docs, dashboard, demo, etc.) changes, and you have a browser MCP in your list of MCP tools, make sure to test the changes in the browser MCP.
 

apps/backend/package.json

@@ -11,7 +11,7 @@
     "with-env:dev": "dotenv -c development --",
     "with-env:prod": "dotenv -c production --",
     "with-env:test": "dotenv -c test --",
-    "dev": "BACKEND_PORT=${STACK_DEV_FALLBACK_BACKEND:+${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}10} && BACKEND_PORT=${BACKEND_PORT:-${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02} && concurrently -n \"dev,codegen,prisma-studio,email-queue,cron-jobs\" -k \"next dev --port $BACKEND_PORT ${STACK_BACKEND_DEV_EXTRA_ARGS:-}\" \"pnpm run codegen:watch\" \"pnpm run prisma-studio\" \"pnpm run run-email-queue\" \"pnpm run run-cron-jobs\"",
+    "dev": "BACKEND_PORT=${STACK_DEV_FALLBACK_BACKEND:+${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}10} && BACKEND_PORT=${BACKEND_PORT:-${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02} && concurrently -n \"dev,codegen,prisma-studio,email-queue,cron-jobs,bulldozer-studio\" -k \"next dev --port $BACKEND_PORT ${STACK_BACKEND_DEV_EXTRA_ARGS:-}\" \"pnpm run codegen:watch\" \"pnpm run prisma-studio\" \"pnpm run run-email-queue\" \"pnpm run run-cron-jobs\" \"pnpm run run-bulldozer-studio\"",
     "dev:inspect": "STACK_BACKEND_DEV_EXTRA_ARGS=\"--inspect\" pnpm run dev",
     "dev:profile": "STACK_BACKEND_DEV_EXTRA_ARGS=\"--experimental-cpu-prof\" pnpm run dev",
     "build": "pnpm run codegen && next build",
@@ -48,7 +48,8 @@
     "run-cron-jobs": "pnpm run with-env:dev tsx scripts/run-cron-jobs.ts",
     "run-cron-jobs:test": "pnpm run with-env:test tsx scripts/run-cron-jobs.ts",
     "verify-data-integrity": "pnpm run with-env:dev tsx scripts/verify-data-integrity/index.ts",
-    "run-email-queue": "pnpm run with-env:dev tsx scripts/run-email-queue.ts"
+    "run-email-queue": "pnpm run with-env:dev tsx scripts/run-email-queue.ts",
+    "run-bulldozer-studio": "pnpm run with-env:dev tsx watch --clear-screen=false scripts/run-bulldozer-studio.ts"
   },
   "prisma": {
     "seed": "pnpm run db-seed-script"
@@ -94,6 +95,7 @@
     "chokidar-cli": "^3.0.0",
     "dotenv": "^16.4.5",
     "dotenv-cli": "^7.3.0",
+    "elkjs": "^0.11.1",
     "emailable": "^3.1.1",
     "freestyle-sandboxes": "^0.1.6",
     "jiti": "^2.6.1",

apps/backend/prisma.config.ts

@@ -10,5 +10,13 @@ export default defineConfig({
   datasource: {
     url: env('STACK_DATABASE_CONNECTION_STRING'),
   },
+  experimental: {
+    externalTables: true,
+  },
+  tables: {
+    external: [
+      "public.BulldozerStorageEngine",
+    ],
+  },
 })
 

apps/backend/prisma/migrations/20260323120000_add_bulldozer_data/migration.sql

@@ -0,0 +1,31 @@
+-- CreateTable
+CREATE TABLE "BulldozerStorageEngine" (
+    "id" UUID NOT NULL DEFAULT gen_random_uuid(),
+    "keyPath" JSONB[] NOT NULL,
+    "keyPathParent" JSONB[] GENERATED ALWAYS AS (
+      CASE
+        WHEN cardinality("keyPath") = 0 THEN NULL
+        ELSE "keyPath"[1:cardinality("keyPath") - 1]
+      END
+    ) STORED,
+    "value" JSONB NOT NULL,
+
+    CONSTRAINT "BulldozerStorageEngine_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "BulldozerStorageEngine_keyPath_key" UNIQUE ("keyPath"),
+    CONSTRAINT "BulldozerStorageEngine_keyPathParent_fkey"
+      FOREIGN KEY ("keyPathParent")
+      REFERENCES "BulldozerStorageEngine"("keyPath")
+      ON DELETE CASCADE
+);
+
+-- Seed root hierarchy rows used by all tables.
+INSERT INTO "BulldozerStorageEngine" ("id", "keyPath", "value")
+VALUES
+  ('00000000-0000-0000-0000-000000000100'::uuid, ARRAY[]::jsonb[], 'null'::jsonb);
+
+INSERT INTO "BulldozerStorageEngine" ("id", "keyPath", "value")
+VALUES
+  ('00000000-0000-0000-0000-000000000101'::uuid, ARRAY[to_jsonb('table'::text)]::jsonb[], 'null'::jsonb);
+
+-- CreateIndex
+CREATE INDEX "BulldozerStorageEngine_keyPathParent_idx" ON "BulldozerStorageEngine"("keyPathParent");

apps/backend/prisma/migrations/20260323120000_add_bulldozer_data/tests/ltree-queries.ts

@@ -0,0 +1,113 @@
+import type { Sql } from "postgres";
+import { expect } from "vitest";
+
+export const postMigration = async (sql: Sql) => {
+  await sql`
+    INSERT INTO "BulldozerStorageEngine" ("id", "keyPath", "value")
+    VALUES
+      ('00000000-0000-0000-0000-000000000001'::uuid, ARRAY[to_jsonb('root'::text)]::jsonb[], '{"node":"root"}'::jsonb),
+      ('00000000-0000-0000-0000-000000000002'::uuid, ARRAY[to_jsonb('root'::text), to_jsonb('branch'::text)]::jsonb[], '{"node":"branch"}'::jsonb),
+      ('00000000-0000-0000-0000-000000000003'::uuid, ARRAY[to_jsonb('root'::text), to_jsonb('branch'::text), to_jsonb('leaf'::text)]::jsonb[], '{"node":"leaf"}'::jsonb),
+      ('00000000-0000-0000-0000-000000000004'::uuid, ARRAY[to_jsonb('root'::text), to_jsonb('other'::text)]::jsonb[], '{"node":"other"}'::jsonb)
+  `;
+
+  const exactRows = await sql`
+    SELECT "value"
+    FROM "BulldozerStorageEngine"
+    WHERE "keyPath" = ARRAY[to_jsonb('root'::text), to_jsonb('branch'::text), to_jsonb('leaf'::text)]::jsonb[]
+  `;
+
+  expect(exactRows).toHaveLength(1);
+  expect(exactRows[0].value).toEqual({ node: "leaf" });
+
+  const nestedRows = await sql`
+    SELECT array_to_string(ARRAY(SELECT x #>> '{}' FROM unnest("keyPath") AS x), '.') AS "keyPath"
+    FROM "BulldozerStorageEngine"
+    WHERE "keyPath"[1:cardinality(ARRAY[to_jsonb('root'::text), to_jsonb('branch'::text)]::jsonb[])] = ARRAY[to_jsonb('root'::text), to_jsonb('branch'::text)]::jsonb[]
+    ORDER BY "keyPath"
+  `;
+
+  expect(nestedRows.map((row) => row.keyPath)).toEqual([
+    "root.branch",
+    "root.branch.leaf",
+  ]);
+
+  const directChildrenRows = await sql`
+    SELECT array_to_string(ARRAY(SELECT x #>> '{}' FROM unnest("keyPath") AS x), '.') AS "keyPath"
+    FROM "BulldozerStorageEngine"
+    WHERE "keyPathParent" = ARRAY[to_jsonb('root'::text)]::jsonb[]
+    ORDER BY "keyPath"
+  `;
+
+  expect(directChildrenRows.map((row) => row.keyPath)).toEqual([
+    "root.branch",
+    "root.other",
+  ]);
+
+  const indexRows = await sql`
+    SELECT "indexname"
+    FROM pg_indexes
+    WHERE schemaname = 'public'
+      AND tablename = 'BulldozerStorageEngine'
+      AND indexname IN (
+        'BulldozerStorageEngine_keyPath_key',
+        'BulldozerStorageEngine_keyPathParent_idx'
+      )
+    ORDER BY "indexname"
+  `;
+
+  expect(indexRows.map((row) => row.indexname)).toEqual([
+    "BulldozerStorageEngine_keyPathParent_idx",
+    "BulldozerStorageEngine_keyPath_key",
+  ]);
+
+  const seededRootRows = await sql`
+    SELECT array_to_string(ARRAY(SELECT x #>> '{}' FROM unnest("keyPath") AS x), '.') AS "keyPath"
+    FROM "BulldozerStorageEngine"
+    WHERE "keyPath" IN (ARRAY[]::jsonb[], ARRAY[to_jsonb('table'::text)]::jsonb[])
+    ORDER BY cardinality("keyPath")
+  `;
+
+  expect(seededRootRows.map((row) => row.keyPath)).toEqual([
+    "",
+    "table",
+  ]);
+
+  const generatedColumnRows = await sql`
+    SELECT attname
+    FROM pg_attribute
+    WHERE attrelid = 'public."BulldozerStorageEngine"'::regclass
+      AND attname = 'keyPathParent'
+      AND attgenerated = 's'
+  `;
+
+  expect(generatedColumnRows).toHaveLength(1);
+
+  const fkConstraintRows = await sql`
+    SELECT conname
+    FROM pg_constraint
+    WHERE conrelid = 'public."BulldozerStorageEngine"'::regclass
+      AND conname = 'BulldozerStorageEngine_keyPathParent_fkey'
+  `;
+
+  expect(fkConstraintRows).toHaveLength(1);
+
+  await expect(sql`
+    INSERT INTO "BulldozerStorageEngine" ("id", "keyPath", "keyPathParent", "value")
+    VALUES (
+      '00000000-0000-0000-0000-000000000005'::uuid,
+      ARRAY[to_jsonb('root'::text), to_jsonb('mismatch'::text)]::jsonb[],
+      ARRAY[]::jsonb[],
+      '{"node":"invalid"}'::jsonb
+    )
+  `).rejects.toThrow('cannot insert a non-DEFAULT value into column "keyPathParent"');
+
+  await expect(sql`
+    INSERT INTO "BulldozerStorageEngine" ("id", "keyPath", "value")
+    VALUES (
+      '00000000-0000-0000-0000-000000000006'::uuid,
+      ARRAY[to_jsonb('missing-parent'::text), to_jsonb('child'::text)]::jsonb[],
+      '{"node":"invalid-fk"}'::jsonb
+    )
+  `).rejects.toThrow('BulldozerStorageEngine_keyPathParent_fkey');
+};