chore: scaffold PYRE MVP monorepo (structure + docs)

pnpm + TypeScript workspace per design doc §13:
- apps/{web,api,worker} skeletons (Next.js 16, Fastify 5, BullMQ)
- packages/{core,solana,prometheus,db,config} (core has real types/DTOs;
  solana/prometheus are stubs)
- programs/pyre-core placeholder (future Anchor, v1.0)
- docs/: PYRE_MVP_DESIGN (canonical), ARCHITECTURE, SECURITY, TOKEN_CLASSIFICATION
- CLAUDE.md, README, .env.example (no private-key var by design)

Skeleton + docs only — no Solana/business logic yet. All workspaces typecheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/db/README.md

@@ -0,0 +1,44 @@
+# @pyre/db
+
+Database schema, migrations, and table definitions for PYRE (PostgreSQL).
+
+## Purpose
+
+Per §13: the schema, migrations, and table definitions. Uses `pg` for
+connectivity. Connection details come from `DATABASE_URL` via `@pyre/config` —
+**never** hardcode credentials.
+
+## Tables (§15)
+
+### Initial MVP tables
+
+- `wallet_scans` — id, wallet, status, created_at, completed_at, summary_json
+- `token_accounts` — id, scan_id, wallet, ata, mint, token_program, raw_balance,
+  ui_balance, decimals, symbol, name, classification, warnings_json,
+  estimated_rent_lamports, created_at
+- `cleanup_receipts` — id, wallet, scan_id, tx_signature, rent_returned_lamports,
+  closed_accounts_count, burned_tokens_count, status, created_at, receipt_json
+- `prometheus_generations` — id, receipt_id, input_json, output_json, status,
+  risk_flags_json, created_at, approved_at, rejected_at
+- `spawn_records` — id, generation_id, spawn_name, ticker, mint, metadata_uri,
+  pumpfun_url, launch_tx, status, created_at
+
+### Future tables
+
+- `token_classifications`
+- `burn_events`
+- `close_account_events`
+- `spawn_candidates`
+- `system_events`
+
+## Status
+
+**Skeleton.** Exports table-name constants and a connection-factory stub. No
+queries, no schema DDL, no migrations yet.
+
+## TODO
+
+- Implement the `createPool()` connection factory (read `DATABASE_URL` via
+  `@pyre/config`).
+- Add SQL migrations under `migrations/` and a migration runner.
+- Add typed table definitions and a query layer.

packages/db/migrations/README.md

@@ -0,0 +1,15 @@
+# Migrations
+
+SQL migrations for the PYRE PostgreSQL database.
+
+**Empty for now** (skeleton). Migration files and a runner will be added here.
+
+## Convention (TODO)
+
+- One forward migration per file, ordered/timestamped (e.g.
+  `0001_init.sql`, `0002_<change>.sql`).
+- The first migration creates the initial MVP tables listed in the package
+  README (§15): `wallet_scans`, `token_accounts`, `cleanup_receipts`,
+  `prometheus_generations`, `spawn_records`.
+- A migration runner (in `@pyre/db`) applies pending migrations against
+  `DATABASE_URL`.

packages/db/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@pyre/db",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"lint: ok (placeholder)\"",
+    "test": "echo \"test: ok (placeholder)\""
+  },
+  "dependencies": {
+    "@pyre/config": "workspace:*",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.10",
+    "typescript": "^5.7.2"
+  }
+}

packages/db/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @pyre/db — database schema, migrations, and table definitions (SKELETON).
+ *
+ * Responsibilities (§13): database schema, migrations, table definitions.
+ * Schema reference: §15 (MVP Database Schema) of `docs/PYRE_MVP_DESIGN.md`.
+ *
+ * No queries are implemented here yet — only table-name constants and a
+ * connection-factory stub.
+ */
+import type { Pool } from "pg";
+
+/**
+ * Canonical table names. Centralized so query/migration code references a single
+ * source of truth.
+ */
+export const TABLES = {
+  // Initial MVP tables (§15)
+  WALLET_SCANS: "wallet_scans",
+  TOKEN_ACCOUNTS: "token_accounts",
+  CLEANUP_RECEIPTS: "cleanup_receipts",
+  PROMETHEUS_GENERATIONS: "prometheus_generations",
+  SPAWN_RECORDS: "spawn_records",
+
+  // Future tables (§15)
+  TOKEN_CLASSIFICATIONS: "token_classifications",
+  BURN_EVENTS: "burn_events",
+  CLOSE_ACCOUNT_EVENTS: "close_account_events",
+  SPAWN_CANDIDATES: "spawn_candidates",
+  SYSTEM_EVENTS: "system_events",
+} as const;
+
+export type TableName = (typeof TABLES)[keyof typeof TABLES];
+
+/**
+ * Connection-factory stub.
+ *
+ * TODO: create and cache a `pg` Pool from DATABASE_URL (resolved via
+ * `@pyre/config` — never hardcode credentials). Then add a migration runner and
+ * typed table-definition / query layer. No queries are implemented yet.
+ */
+export function createPool(): Pool {
+  // TODO: const { databaseUrl } = loadConfig(); return new Pool({ connectionString: databaseUrl });
+  throw new Error("not implemented");
+}

packages/db/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}