@mndrk/agx 2.0.26 → 2.0.33

package/cloud-runtime/standalone/docs/decisions/sqlite-migration-adr.md

@@ -1,327 +0,0 @@
-# ADR: Full Migration from Postgres to SQLite
-
-**Status**: Accepted
-**Date**: 2026-02-21
-**Author**: Flint
-**Reviewers**: Jewel, Cody
-**Stakeholders**: Jewel (queue), Cody (queries/validation), Jane (schema), Flint (tests)
-
----
-
-## Context
-
-AGX Cloud originally used a hybrid architecture: Postgres for the application database and `pg-boss` for the job queue. This introduced operational overhead — a managed Postgres instance for what is fundamentally a single-node, single-tenant dashboard app.
-
-### Original Hybrid Model Rationale
-
-The project first moved to a **hybrid Postgres + SQLite** model:
-
-- **Postgres** retained for the main 18-table application schema (tasks, projects, graphs, workflows, learnings, etc.) — leveraging `JSONB`, `uuid[]`, triggers, and `gen_random_uuid()`.
-- **SQLite** adopted for ancillary stores (participants, attachments, message history) where embedded, zero-config storage was sufficient.
-- **pg-boss** used for durable job queues on top of Postgres.
-
-This hybrid approach let the team start de-risking SQLite adoption incrementally while keeping the battle-tested Postgres schema intact.
-
-### Jewel's pg-boss Blocker Analysis
-
-Jewel identified **pg-boss as the critical blocker** preventing full Postgres removal:
-
-1. **Operational overhead** — pg-boss requires a live Postgres connection, periodic maintenance (`maintenance` cron), and schema migrations on its internal tables.
-2. **Deployment coupling** — Every agx-cloud deployment needed a Postgres instance, even for single-user or edge scenarios where a full RDBMS is unnecessary.
-3. **Transactional semantics mismatch** — pg-boss's internal polling and advisory-lock mechanism added latency and complexity that a simpler embedded queue could avoid.
-4. **Dependency weight** — `pg-boss@12.9.0` + `pg@8.16.3` pulled in connection pooling, type parsing, and protocol handling that the application didn't need if the queue moved to SQLite.
-
-The core insight: if the queue layer could run on SQLite, the *only* remaining Postgres dependency would be the application schema — and that could be migrated on a known timeline.
-
-### How the Blocker Was Resolved: SQLiteQueueAdapter
-
-Jewel implemented `lib/queue/sqlite-adapter.ts` — a custom `QueueAdapter` backed by `better-sqlite3`:
-
-- **WAL mode** for concurrent reads during writes.
-- **Job claiming via polling** — replaces `SKIP LOCKED` with `UPDATE ... WHERE status = 'pending' AND start_after <= ? LIMIT 1` inside an exclusive transaction. WAL mode ensures readers aren't blocked during the brief write lock.
-- **Exponential backoff retry** with configurable `retryLimit`, `retryDelay`, and `retryBackoff`.
-- **Job lifecycle**: `pending → active → completed | failed | retry`.
-- **Worker ID tracking** — each adapter instance generates a UUID, recorded on claimed jobs for observability.
-- **Index**: `(queue, status, start_after, priority DESC, created_at ASC)` for efficient polling.
-- **No external dependencies** — uses `better-sqlite3` (already in the dependency tree for the app DB migration).
-
-The temporal service compatibility layer (`lib/temporal/service.ts`) was updated to route through this adapter, preserving API-route compatibility.
-
-**Result:** pg-boss fully replaced. The queue entry point (`lib/queue/boss.ts`) now returns `SQLiteQueueAdapter` by default.
-
----
-
-## Decision
-
-**Fully migrate from Postgres to SQLite** across all data layers. AGX Cloud runs on SQLite only (`better-sqlite3`), zero external infrastructure.
-
----
-
-## Migration Spec
-
-Full specification: [`planning/pg-to-sqlite-migration-spec-v2.md`](../../planning/pg-to-sqlite-migration-spec-v2.md)
-Short version: [`docs/migration-spec.md`](../migration-spec.md)
-
-### Phases
-
-| Phase | Owner | Description | Status |
-|-------|-------|-------------|--------|
-| 0 | Jewel | Queue layer → SQLiteQueueAdapter | **Complete** |
-| 1 | Jewel | DbAdapter interface (pluggable PG/SQLite) | Pending |
-| 2 | Cody | Query compatibility matrix (ILIKE→LIKE, JSONB→json_each, etc.) | Pending |
-| 3 | Jane | Schema & data migration (18 tables → SQLite DDL) | Pending |
-| 4 | Flint | Parity test harness (CRUD, filters, concurrency, edge cases) | Pending |
-| 5 | Cody | Shadow-read validation (48-72h dual-run) | Pending |
-| 6 | All | Cleanup: remove `pg`, `pg-boss`, `@types/pg` after 30-day soak | Pending |
-
-### Key Technical Contracts
-
-**SQLite Runtime (per connection):**
-```sql
-PRAGMA journal_mode = WAL;
-PRAGMA foreign_keys = ON;
-PRAGMA busy_timeout = 5000;
-PRAGMA synchronous = NORMAL;
-PRAGMA cache_size = -16000;
-```
-
-**Type Semantics (PG → SQLite):**
-
-| PG Type | SQLite | Encoding |
-|---------|--------|----------|
-| `uuid` | `TEXT` | Lowercase hex with hyphens |
-| `timestamptz` | `TEXT` | ISO 8601 UTC with `Z` suffix |
-| `boolean` | `INTEGER` | `0`/`1` with CHECK constraint |
-| `jsonb` | `TEXT` | `JSON.stringify`, validated with `json_valid()` |
-| `uuid[]` / `text[]` | `TEXT` | JSON array |
-| `numeric(12,6)` | `REAL` | IEEE 754 (acceptable precision loss for costs) |
-
----
-
-## Backend and API Layer Changes
-
-### Connection Management
-
-| Concern | Postgres (current) | SQLite (target) |
-|---------|-------------------|-----------------|
-| Connection model | Pool of N TCP connections | Single file handle, synchronous |
-| Concurrency | Multiple concurrent writers | Single writer + concurrent readers (WAL) |
-| Schema isolation | `search_path=agx,public` | Not applicable (single namespace) |
-| Parameterization | `$1, $2, …` positional params | `?, ?, …` positional params |
-| Startup cost | TCP handshake + auth per connection | `ffi` open, ~1ms |
-
-### Transaction Semantics Differences
-
-| Behavior | Postgres | SQLite | Migration Impact |
-|----------|----------|--------|------------------|
-| **Implicit transactions** | Each statement auto-commits; explicit `BEGIN`/`COMMIT` for multi-statement | Same, but `BEGIN IMMEDIATE` needed for write transactions | Must use `BEGIN IMMEDIATE` to avoid `SQLITE_BUSY` upgrade failures |
-| **Isolation level** | Read Committed (default) | Serializable (only level available) | Stricter — no dirty reads, but write contention increases |
-| **Concurrent writes** | Multiple writers, row-level locking | Single writer; others wait up to `busy_timeout` | `busy_timeout = 5000` absorbs typical contention |
-| **Advisory locks** | `pg_advisory_lock()` used by pg-boss | Not available | Replaced by SQLiteQueueAdapter's transactional claim pattern |
-| **RETURNING clause** | Full support | Supported since SQLite 3.35.0 | No change needed |
-| **ON CONFLICT (upsert)** | `ON CONFLICT … DO UPDATE SET` | Same syntax | No change needed |
-| **`IS NOT DISTINCT FROM`** | Native operator | Not supported | Rewrite to `(col = ? OR (col IS NULL AND ? IS NULL))` |
-| **`= ANY($1)`** | Native array parameter | Not supported | Rewrite to `IN (?, ?, …)` or `json_each()` |
-| **`ILIKE`** | Case-insensitive LIKE | Not supported | Rewrite to `LIKE` with `COLLATE NOCASE` or `lower()` |
-
-### QueryBuilder Migration Patterns
-
-The `QueryBuilder` in `lib/db-adapter.ts` requires these changes:
-
-1. **Parameterized queries**: `$1, $2, …` → `?, ?, …`
-2. **Array containment**: `@> $N` → subquery with `json_each()`
-3. **Array membership**: `= ANY($N)` → `IN (?, ?, …)` with param expansion
-4. **`IS NOT DISTINCT FROM`** → `(col = ? OR (col IS NULL AND ? IS NULL))`
-5. **`ILIKE`** in `or()` filter → `LIKE` with `COLLATE NOCASE`
-6. **`RETURNING` clause**: Compatible — no change needed (SQLite ≥ 3.35.0)
-7. **`ON CONFLICT … DO UPDATE`**: Compatible — no change needed
-
-### Affected Backend Services
-
-| Service File | DB Operations | Migration Notes |
-|-------------|---------------|-----------------|
-| `lib/db.ts` | ~40 call sites — CRUD for tasks, projects, learnings, comments, logs, costs, settings, workflows, graphs, runs | Central data layer; every query must pass SQLite compatibility |
-| `lib/db-adapter.ts` | `QueryBuilder` with PG-specific SQL generation | **Primary migration target** |
-| `lib/db-server.ts` | Thin wrapper returning `createAdminDbClient()` | Swap underlying adapter |
-| `lib/task-context.ts` | Task context resolution (3 call sites) | Standard CRUD — no PG-specific patterns |
-| `lib/dependency-manager.ts` | Task dependency graph queries (5 call sites) | Standard CRUD |
-| `lib/security.ts` | API key management, rate limiting (4 call sites) | `ON CONFLICT … DO UPDATE` — compatible |
-| `lib/orchestrator/activities.ts` | Task orchestration state transitions (4 call sites) | Standard CRUD |
-| `src/graph/store.ts` | Graph state persistence | Uses `pool.query` directly — must route through adapter |
-
----
-
-## Data Layer Changes
-
-### Schema Differences: Postgres → SQLite
-
-The Postgres schema (`docker/postgres/init/001_agx_board_schema.sql`) defines 22 tables across the `agx` schema. Key structural changes:
-
-| Postgres Feature | SQLite Equivalent | Tables Affected |
-|-----------------|-------------------|-----------------|
-| `agx.` schema prefix | Flat namespace (no schemas) | All 22 tables |
-| `gen_random_uuid()` default | `crypto.randomUUID()` in application | All tables with UUID PKs |
-| `text[]` / `uuid[]` arrays | `TEXT` (JSON-encoded array) | `stage_prompts.outputs`, `tasks.depends_on` |
-| `GIN` indexes on `jsonb` | Expression indexes or `json_each()` queries | `tasks.stage_decisions` |
-| `CHECK` with `ANY(ARRAY[...])` | `CHECK(col IN (...))` | 10 tables with enum-like constraints |
-| Partial unique indexes | Supported since SQLite 3.15.0 | `task_templates`, `tasks`, `projects` |
-
-### Trigger Migration
-
-| Postgres Trigger | SQLite Equivalent |
-|-----------------|-------------------|
-| `update_updated_at()` function + per-table triggers | Inline `BEFORE UPDATE` trigger with `datetime('now')` |
-| `increment_task_version()` | Inline: `SET version = OLD.version + 1` |
-| `increment_graph_version()` | Inline: `SET graph_version = OLD.graph_version + 1` |
-| `check_rate_limit()` PL/pgSQL function | Application-layer logic |
-
-### SQLite-Specific Constraints
-
-1. **Single-writer**: Only one write transaction at a time. Concurrent writers wait up to `busy_timeout` (5000ms). Current write patterns are sequential per-task.
-2. **No concurrent schema changes**: DDL acquires exclusive lock. Run during maintenance windows.
-3. **JSON not indexed natively**: Requires expression indexes for indexed JSON access.
-4. **No `LISTEN/NOTIFY`**: SSE streaming routes already use polling — no change needed.
-5. **Max database size**: 281 TB theoretical. Current dataset (~84 tasks, ~4k graph nodes) is well within bounds.
-
----
-
-## Frontend Impact
-
-The frontend is fully decoupled from the database layer. All data access flows through REST API routes via `fetch()` calls in React hooks (`hooks/useProjects.ts`, `hooks/useProviders.ts`, etc.).
-
-**No client-side behavioral changes.** The API response shapes are defined by the `DbAdapter` interface (`lib/db-adapter.interface.ts`), which remains stable. Type changes (`uuid` → TEXT, `timestamptz` → TEXT, `boolean` → INTEGER) are serialized identically in API responses.
-
-**Observability differences to monitor:**
-- SSE polling latency — SQLite read performance under WAL is comparable for current dataset size but has different I/O characteristics.
-- Concurrent write-heavy routes (e.g., `/api/tasks/[id]/heartbeat`) may see increased latency under `busy_timeout` contention.
-
----
-
-## Consequences
-
-**Positive:**
-- Single-binary deployment — no external database process required
-- Simpler ops — no connection pooling, no Postgres upgrades, no pg-boss maintenance
-- Edge-deployable — SQLite works anywhere, including resource-constrained environments
-- Faster cold starts (no connection handshake), simpler backup (copy one file)
-
-**Negative / Risks:**
-- Write concurrency limited to single-writer (mitigated by `busy_timeout` + WAL)
-- JSON query performance may regress vs. native JSONB (mitigated by expression indexes)
-- Loss of Postgres-specific features (advisory locks, `LISTEN/NOTIFY`, full-text with `tsvector`)
-- Ecosystem tooling (ORMs, migration frameworks) has stronger Postgres support
-- No built-in replication — backup strategy relies on file copies or Litestream
-
----
-
-## Reopen Criteria
-
-The team should reconsider adding Postgres back if **any** of the following thresholds are crossed:
-
-| Trigger | Threshold | Measurement |
-|---------|-----------|-------------|
-| **Write concurrency** | >10 concurrent writers sustained for >1 min, causing >5% of writes to hit busy timeout | Application logs: count of `SQLITE_BUSY` errors per minute |
-| **Database size** | Single SQLite file exceeds 10 GB | `PRAGMA page_count * page_size` |
-| **Query latency p99** | Any critical-path query exceeds 500ms at p99 over a 1-hour window | Application-level query timing metrics |
-| **Multi-node requirement** | Product requires >1 instance serving writes to the same database | Architecture review |
-| **Compliance mandate** | Regulatory requirement demands RDBMS certification SQLite lacks | Security/compliance audit |
-| **Data loss incident** | Unrecoverable data loss attributable to SQLite limitations | Incident post-mortem |
-
-If a trigger is crossed, open a new ADR referencing this one and run Cody's revisit checklist below before proceeding.
-
----
-
-## Cody's Revisit Checklist
-
-Before re-introducing Postgres (or any external database), **all six items must pass**.
-
-### 1. Portability Audit
-
-**Question**: Can the application run on both SQLite and Postgres without conditional code paths proliferating?
-
-**Pass criteria**:
-- [ ] All SQL queries routed through an adapter interface (no raw driver calls outside `lib/db.ts` and `lib/queue/`)
-- [ ] Branch prototype runs full test suite against both backends with ≤5 adapter-level `if` blocks
-- [ ] No SQLite-specific PRAGMAs leak into shared application code
-
-**Fail if**: >20% of query callsites need backend-specific branches, or adapter layer exceeds 500 LOC of conditional logic.
-
-### 2. Transaction Semantics Test
-
-**Question**: Does the replacement backend preserve the transaction guarantees the app depends on?
-
-**Pass criteria**:
-- [ ] All existing `db.transaction()` calls pass under the new backend without modification
-- [ ] Concurrency stress test (50 concurrent job claims, 100 concurrent task updates) completes with zero lost updates
-- [ ] WAL-equivalent read-during-write behavior verified (readers never block >100ms)
-
-**Fail if**: Any transaction block requires restructuring, or stress test shows data anomalies.
-
-### 3. Migration Safety Plan
-
-**Question**: Can we migrate live data without downtime or data loss?
-
-**Pass criteria**:
-- [ ] Written migration runbook with step-by-step commands
-- [ ] Migration executed on production data copy (full round-trip with row count and checksum verification)
-- [ ] Rollback procedure documented and tested: new backend → SQLite within 15 minutes
-- [ ] Migration time for current data volume <10 minutes
-
-**Fail if**: Any data type loses fidelity, or rollback takes >30 minutes.
-
-### 4. Reliability SLO Proof
-
-**Question**: Does the new backend meet or exceed SQLite's reliability?
-
-**Pass criteria**:
-- [ ] 7-day soak test on staging: zero unplanned restarts, zero data corruption
-- [ ] Backup and restore tested: point-in-time recovery to within 1 minute
-- [ ] Availability ≥99.9% during soak test
-- [ ] Connection pool behavior documented (max connections, timeout handling, leak detection)
-
-**Fail if**: Any data corruption during soak test, or availability below 99.9%.
-
-### 5. Security / Compliance Parity
-
-**Question**: Does the new backend maintain the same security posture?
-
-**Pass criteria**:
-- [ ] Encryption at rest: database files encrypted or on encrypted volume
-- [ ] Access control: credentials rotated, not hardcoded, in secrets manager
-- [ ] Network exposure: if network-accessible, TLS enforced and IP-restricted
-- [ ] Audit logging: all DDL and privileged access logged
-
-**Fail if**: New backend introduces network attack surface without compensating controls.
-
-### 6. Runbook Readiness
-
-**Question**: Can any team member operate the new backend without specialized expertise?
-
-**Pass criteria**:
-- [ ] Runbook covers: provisioning, connection config, backup/restore, monitoring, common failures
-- [ ] New operator completes runbook end-to-end in <2 hours
-- [ ] Monitoring dashboards for: connection count, query latency, disk usage, replication lag
-- [ ] On-call escalation path documented
-
-**Fail if**: Runbook requires >4 hours for a new operator, or no monitoring at launch.
-
----
-
-## References
-
-- Migration spec v2: `planning/pg-to-sqlite-migration-spec-v2.md`
-- Migration spec (short): `docs/migration-spec.md`
-- SQLiteQueueAdapter: `lib/queue/sqlite-adapter.ts`
-- Queue adapter interface: `lib/queue/adapter.ts`
-- Queue entry point: `lib/queue/boss.ts`
-- Temporal compat layer: `lib/temporal/service.ts`
-- PG schema: `docker/postgres/init/001_agx_board_schema.sql`
-- Current PG adapter: `lib/db-adapter.ts`
-- DB adapter interface: `lib/db-adapter.interface.ts`
-- DB init / PRAGMAs: `src/db/init.ts`
-- DB validation: `src/db/checks.ts`
-- Frontend hooks: `hooks/useProjects.ts`, `hooks/useProviders.ts`
-
----
-
-*This ADR supersedes the hybrid Postgres+SQLite architecture. If reopened, file a new ADR and reference this document.*

package/cloud-runtime/standalone/docs/error-code-mapping.md

@@ -1,74 +0,0 @@
-# PostgreSQL ↔ SQLite Error Code Mapping
-
-Maps database error codes between PostgreSQL and SQLite for consistent error handling in the agx-cloud application layer.
-
----
-
-## Error Code Table
-
-| Error Type | PostgreSQL Code | PostgreSQL Name | SQLite Extended Code | SQLite Constant | Detection Strategy |
-|---|---|---|---|---|---|
-| **Unique violation** | `23505` | `unique_violation` | `2067` (SQLITE_CONSTRAINT_UNIQUE) | `SQLITE_CONSTRAINT_UNIQUE` | Check `code` or `message.includes('UNIQUE constraint')` |
-| **Foreign key violation** | `23503` | `foreign_key_violation` | `787` (SQLITE_CONSTRAINT_FOREIGNKEY) | `SQLITE_CONSTRAINT_FOREIGNKEY` | Check `code` or `message.includes('FOREIGN KEY constraint')` |
-| **Not-null violation** | `23502` | `not_null_violation` | `1299` (SQLITE_CONSTRAINT_NOTNULL) | `SQLITE_CONSTRAINT_NOTNULL` | Check `code` or `message.includes('NOT NULL constraint')` |
-| **Check constraint** | `23514` | `check_violation` | `275` (SQLITE_CONSTRAINT_CHECK) | `SQLITE_CONSTRAINT_CHECK` | Check `code` or `message.includes('CHECK constraint')` |
-| **Primary key violation** | `23505` | `unique_violation` | `1555` (SQLITE_CONSTRAINT_PRIMARYKEY) | `SQLITE_CONSTRAINT_PRIMARYKEY` | PG uses same code as unique; SQLite distinguishes |
-| **Database locked** | N/A (uses row-level locks) | N/A | `5` (SQLITE_BUSY) | `SQLITE_BUSY` | Retry with backoff |
-| **Table locked** | `55P03` | `lock_not_available` | `6` (SQLITE_LOCKED) | `SQLITE_LOCKED` | Retry with backoff |
-| **Read-only database** | `25006` | `read_only_sql_transaction` | `8` (SQLITE_READONLY) | `SQLITE_READONLY` | Application error |
-| **Data too long** | `22001` | `string_data_right_truncation` | N/A | N/A | SQLite has no length limits on TEXT |
-| **Invalid JSON** | `22P02` | `invalid_text_representation` | `1` (SQLITE_ERROR) | `SQLITE_ERROR` | `json()` function raises generic error |
-
----
-
-## Unified Error Handling (TypeScript)
-
-```typescript
-type DbErrorKind =
-  | "UNIQUE_VIOLATION"
-  | "FK_VIOLATION"
-  | "NOT_NULL_VIOLATION"
-  | "CHECK_VIOLATION"
-  | "BUSY"
-  | "UNKNOWN";
-
-function classifyDbError(err: any): DbErrorKind {
-  // PostgreSQL (node-postgres)
-  if (err.code === "23505") return "UNIQUE_VIOLATION";
-  if (err.code === "23503") return "FK_VIOLATION";
-  if (err.code === "23502") return "NOT_NULL_VIOLATION";
-  if (err.code === "23514") return "CHECK_VIOLATION";
-  if (err.code === "55P03") return "BUSY";
-
-  // SQLite (better-sqlite3 / sqlite3)
-  const msg = String(err.message || "");
-  if (err.code === "SQLITE_CONSTRAINT_UNIQUE" || msg.includes("UNIQUE constraint"))
-    return "UNIQUE_VIOLATION";
-  if (err.code === "SQLITE_CONSTRAINT_PRIMARYKEY" || msg.includes("PRIMARY KEY"))
-    return "UNIQUE_VIOLATION";
-  if (err.code === "SQLITE_CONSTRAINT_FOREIGNKEY" || msg.includes("FOREIGN KEY"))
-    return "FK_VIOLATION";
-  if (err.code === "SQLITE_CONSTRAINT_NOTNULL" || msg.includes("NOT NULL"))
-    return "NOT_NULL_VIOLATION";
-  if (err.code === "SQLITE_CONSTRAINT_CHECK" || msg.includes("CHECK constraint"))
-    return "CHECK_VIOLATION";
-  if (err.code === "SQLITE_BUSY" || err.code === "SQLITE_LOCKED")
-    return "BUSY";
-
-  return "UNKNOWN";
-}
-```
-
----
-
-## Key Differences
-
-1. **Locking model:** PG uses row-level MVCC locks; SQLite uses database-level locks. `SQLITE_BUSY` errors require retry logic with exponential backoff (WAL mode reduces frequency).
-
-2. **Unique vs Primary Key:** PG reports both as `23505`. SQLite distinguishes `SQLITE_CONSTRAINT_UNIQUE` (2067) from `SQLITE_CONSTRAINT_PRIMARYKEY` (1555). The unified handler above maps both to `UNIQUE_VIOLATION`.
-
-3. **Extended error codes:** SQLite extended codes must be enabled via `PRAGMA extended_result_codes = ON;` (or the driver equivalent). Without this, all constraint errors return generic code `19` (SQLITE_CONSTRAINT).
-
-4. **Error messages:** SQLite error messages include the constraint name/column, making message-based detection reliable as a fallback.
-
-5. **FOREIGN KEY enforcement:** SQLite requires `PRAGMA foreign_keys = ON;` per connection. Without it, FK violations are silently ignored.

package/cloud-runtime/standalone/docs/migration-plan.md

@@ -1,120 +0,0 @@
-# PG → SQLite Data Migration Plan
-
-## Schema Mapping
-
-Both schemas already exist and are in sync:
-- **PG**: `docker/postgres/init/001_agx_board_schema.sql` (26 tables in `agx` schema)
-- **SQLite**: `db/sqlite/001_agx_board_schema.sql` (26 tables, no schema prefix)
-
-### Type Mapping (applied during migration)
-
-| PG Type | SQLite Type | Conversion |
-|---------|-------------|------------|
-| `uuid` | `TEXT` | Pass-through (already lowercase hex) |
-| `timestamptz` | `TEXT` | `to_char(col, 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')` or JS `new Date(v).toISOString()` |
-| `boolean` | `INTEGER` | `true→1, false→0` |
-| `jsonb` | `JSON` (TEXT) | `JSON.stringify()` — already text in pg result |
-| `uuid[]` | `JSON` (TEXT) | `JSON.stringify(array)` |
-| `text[]` | `JSON` (TEXT) | `JSON.stringify(array)` |
-| `numeric(12,6)` | `REAL` | `parseFloat()` |
-| `inet` | `TEXT` | Pass-through |
-| `integer` | `INTEGER` | Pass-through |
-| `text` | `TEXT` | Pass-through |
-
-### FK Dependency Order (insert order)
-
-Tables must be inserted in this order to satisfy FK constraints:
-
-1. `device_codes` (no FK deps)
-2. `learnings` (no FK deps)
-3. `user_secrets` (no FK deps)
-4. `user_settings` (no FK deps)
-5. `rate_limits` (no FK deps)
-6. `task_templates` (no FK deps)
-7. `workflows` (no FK deps)
-8. `agents` (no FK deps)
-9. `projects` (→ workflows)
-10. `project_repos` (→ projects)
-11. `stage_prompts` (→ workflows)
-12. `tasks` (→ projects)
-13. `execution_graphs` (→ tasks)
-14. `graph_nodes` (→ execution_graphs)
-15. `graph_edges` (→ execution_graphs)
-16. `graph_events` (→ execution_graphs)
-17. `graph_migration_backups` (no FK deps, but logically after tasks)
-18. `task_audit_log` (→ tasks)
-19. `task_comments` (→ tasks)
-20. `task_logs` (→ tasks)
-21. `task_costs` (→ tasks)
-22. `task_run_history` (→ tasks)
-23. `task_workflow_events` (→ tasks)
-24. `workflow_instances` (→ workflows, projects)
-25. `workflow_nodes` (→ workflows)
-26. `workflow_transitions` (→ workflow_nodes, workflows)
-
-### JSON Columns Requiring `json_valid()` Verification
-
-| Table | Column | Default |
-|-------|--------|---------|
-| `workflows` | `definition` | `{}` |
-| `projects` | `metadata` | `{}` |
-| `stage_prompts` | `outputs` | NULL |
-| `stage_prompts` | `swarm_models` | NULL |
-| `user_settings` | `models` | `{}` |
-| `tasks` | `depends_on` | `[]` |
-| `tasks` | `swarm_models` | NULL |
-| `tasks` | `stage_decisions` | `{}` |
-| `tasks` | `run_index` | `[]` |
-| `tasks` | `open_blockers` | `[]` |
-| `task_audit_log` | `payload` | — |
-| `task_workflow_events` | `payload` | `{}` |
-| `workflow_instances` | `input` | `{}` |
-| `workflow_instances` | `output` | NULL |
-| `workflow_nodes` | `metadata` | `{}` |
-| `workflow_transitions` | `metadata` | `{}` |
-| `agents` | `config` | `{}` |
-| `execution_graphs` | `policy` | `{}` |
-| `execution_graphs` | `done_criteria` | `{}` |
-| `graph_nodes` | `config` | `{}` |
-| `graph_nodes` | `output` | NULL |
-| `graph_nodes` | `metrics` | NULL |
-| `graph_edges` | `data_mapping` | NULL |
-| `graph_events` | `payload` | `{}` |
-| `graph_migration_backups` | `task_snapshot` | — |
-
-### Tables Estimated to Need Streaming (>1K rows potential)
-
-| Table | Likely Large | Reason |
-|-------|-------------|--------|
-| `tasks` | Yes | Core entity, grows unbounded |
-| `task_logs` | Yes | Multiple logs per task |
-| `task_comments` | Moderate | Multiple per task |
-| `task_costs` | Moderate | Per-stage per task |
-| `task_audit_log` | Yes | Every action logged |
-| `task_run_history` | Moderate | Per retry |
-| `graph_events` | Yes | Event sourced, many per graph |
-| `graph_nodes` | Moderate | Multiple per graph |
-| `graph_edges` | Moderate | Multiple per graph |
-| All others | Small | Config/reference tables |
-
-**Streaming threshold**: 500 rows. Tables above this use cursor-based streaming.
-
-## Migration Window Strategy
-
-**Recommended: Brief pause (30s–2min)**
-
-1. Stop all agx daemon workers and API servers
-2. Run migration script (streams PG → SQLite)
-3. Run verification (row counts, checksums, FK integrity, JSON validity)
-4. If verification passes: start services with `DB_BACKEND=sqlite`
-5. If verification fails: restart services with PG (no data lost)
-
-**Rollback plan**: PG schema is never modified. The migration is read-only on PG. If SQLite verification fails, simply delete the `.db` file and restart with PG.
-
-## Verification Checklist
-
-- [ ] Per-table row count: `PG count = SQLite count`
-- [ ] Per-table deterministic checksum: `MD5(sorted rows) matches`
-- [ ] `PRAGMA foreign_key_check` returns empty (no FK violations)
-- [ ] `json_valid(col)` for every non-NULL JSON column value
-- [ ] `PRAGMA integrity_check` returns `ok`