@mndrk/agx 2.0.26 → 2.0.32

package/cloud-runtime/standalone/docs/LIMITS.md

@@ -1,63 +0,0 @@
-# Operational Limits and Non-Goals
-
-This document defines hard architectural constraints for agx-cloud. Exceeding these limits requires an architecture review — they are not targets to optimize toward, but ceilings that protect system integrity.
-
-## Concurrency Model
-
-**Constraint: Single-coordinator, single-writer.**
-
-agx-cloud uses SQLite in WAL (Write-Ahead Logging) mode as its primary datastore. SQLite permits concurrent readers but only a single writer at any given moment. The system assumes:
-
-- **One coordinator process** owns the database and serializes all writes.
-- Workers (agents) communicate intent through the coordinator; they never write to SQLite directly.
-- There is no multi-master replication, no write sharding, and no distributed consensus.
-
-This is a deliberate choice, not a limitation to work around. Single-writer simplifies reasoning about state transitions, eliminates write conflicts, and keeps the operational surface small.
-
-## Write QPS Ceiling
-
-**Constraint: ~50 writes per second.**
-
-SQLite in WAL mode on modern hardware sustains roughly 50–200 write transactions per second depending on disk, transaction size, and fsync policy. agx-cloud targets **~50 write QPS** as its operational ceiling to leave headroom for:
-
-- Burst absorption (task creation spikes, bulk status updates)
-- Checkpoint overhead (WAL → main database merges)
-- Co-located read latency (writers block checkpoint, checkpoint blocks readers beyond a threshold)
-
-If sustained write load approaches this ceiling, the correct response is to investigate write batching or queue coalescing — not to add more writer processes.
-
-## Max Worker Count
-
-**Constraint: 10 concurrent workers per coordinator.**
-
-Each active worker generates write traffic (status updates, checkpoints, log entries, artifact records). At an estimated 2–5 writes/sec per active worker, 10 workers approach the ~50 QPS ceiling. The recommended cap:
-
-| Workers | Est. Write QPS | Headroom |
-|---------|---------------|----------|
-| 5       | 10–25         | Comfortable |
-| 10      | 20–50         | At ceiling |
-| 20+     | 40–100+       | Unsafe — expect SQLITE_BUSY |
-
-Beyond 10 concurrent workers, `SQLITE_BUSY` errors and increased retry latency become likely. Do not raise this limit without migrating the write path.
-
-## Non-Goals
-
-The following are explicitly **not goals** of the current architecture:
-
-- **Multi-master / multi-coordinator writes** — No plan to support multiple processes writing to the same database.
-- **Horizontal write scaling** — Write throughput scales vertically (faster disk, batching), not horizontally (more writers).
-- **Sub-millisecond write latency** — SQLite write latency is typically 1–20ms. The system does not optimize for sub-ms writes.
-- **Thousands of concurrent workers** — The coordinator model assumes a small fleet (≤10). Large fan-out requires a different data layer.
-- **Geographic distribution** — Single-node, single-file database. No cross-region replication.
-
-## When to Revisit
-
-Re-evaluate this architecture if any of the following thresholds are crossed:
-
-1. **Sustained write QPS > 40** — Approaching the ceiling; investigate batching first, then consider migration.
-2. **Worker count > 10 needed regularly** — The coordinator bottleneck will surface as increased latency and retries.
-3. **Database file > 1 GB** — Query planning and checkpoint duration may degrade. Consider archival or partitioning.
-4. **Multi-node deployment required** — SQLite is single-node. Any HA or multi-region requirement forces a datastore change (e.g., PostgreSQL, Turso/libSQL).
-5. **Write contention errors (`SQLITE_BUSY`) in production logs** — Immediate signal that the single-writer model is under pressure.
-
-Migration path: the most likely evolution is PostgreSQL for the write path, retaining SQLite for local/edge read caches if needed.

package/cloud-runtime/standalone/docs/architecture/ADR-001-hybrid-to-full-sqlite.md

@@ -1,345 +0,0 @@
-# ADR-001: Hybrid-to-Full-SQLite Architecture Migration
-
-**Status:** Accepted
-**Date:** 2026-02-21
-**Author:** Flint
-**Stakeholders:** Jewel (queue), Cody (queries/validation), Jane (schema), Flint (tests)
-
----
-
-## Context
-
-agx-cloud originally ran on **Postgres-only** (via `pg` + `pg-boss` for job queues). As the system evolved toward a single-binary, edge-deployable architecture, the team evaluated whether Postgres remained the right choice.
-
-### 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.
-
-## Decision
-
-**Fully migrate from Postgres to SQLite** across all data layers, executed in six phases.
-
-### 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.
-- **Transactional claim pattern**: find candidate jobs → mark active within a single transaction (no advisory locks needed).
-- **Exponential backoff retry** with configurable `retryLimit`, `retryDelay`, and `retryBackoff`.
-- **Job lifecycle**: `pending → active → completed | failed | retry`.
-- **Index**: `(queue, status, start_after, priority DESC, created_at ASC)` for efficient polling.
-
-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.
-
-## 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) |
-
-## 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 local development — `better-sqlite3` is synchronous, no connection setup.
-
-**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`).
-
-## Reopen Criteria
-
-This decision should be revisited if any of the following occur:
-
-1. **Write concurrency** becomes a bottleneck — multiple concurrent writers consistently hit `SQLITE_BUSY` despite `busy_timeout` tuning.
-2. **Data volume** exceeds SQLite practical limits — single-file database approaches multi-GB and query latency degrades.
-3. **Multi-node deployment** is required — SQLite cannot serve as a shared database across multiple application instances without an external replication layer (e.g., LiteFS, Turso).
-4. **Regulatory/compliance** requirements mandate a database with specific audit, encryption-at-rest, or role-based access features beyond SQLite's capabilities.
-5. **Advanced query patterns** are needed — heavy use of CTEs with recursive mutations, window functions over JSONB, or full-text search at scale where Postgres significantly outperforms.
-
-## Cody's Revisit Checklist
-
-Before re-introducing Postgres (or any external database), the team must complete:
-
-- [ ] **Portability audit** — Inventory all SQLite-specific patterns (PRAGMAs, `json_each()`, `RETURNING`, type conventions). Estimate migration effort to target database.
-- [ ] **Transaction semantics test** — Verify the target database handles the application's transaction patterns (single-writer assumption, busy-wait behavior, implicit vs. explicit transactions) without behavioral regressions.
-- [ ] **Migration safety plan** — Define rollback strategy, data verification checksums, dual-write period, and cutover criteria. No data loss is acceptable.
-- [ ] **Reliability SLO proof** — Demonstrate the target database meets or exceeds current SQLite reliability (WAL durability, crash recovery, backup via `.backup()`). Provide 30-day production metrics.
-- [ ] **Security/compliance parity** — Confirm the target database provides equivalent or better security posture: encryption at rest, access control, audit logging. Document any gaps.
-- [ ] **Runbook readiness** — Operational runbooks must exist for: provisioning, backup/restore, monitoring, alerting, scaling, incident response, and version upgrades. No deployment without runbooks.
-
----
-
-## Backend and API Layer Changes
-
-This section inventories every backend service and API route affected by the migration, documents Postgres-to-SQLite transaction semantics differences, and notes API routes with changed behavior.
-
-### Connection Management
-
-**Current (Postgres):** `lib/db-adapter.ts` creates a `pg.Pool` with `DATABASE_URL`, connection pooling, and `search_path=agx,public`. Every query goes through `pool.query()`.
-
-**Post-migration (SQLite):** Connection pooling is removed entirely. `better-sqlite3` operates synchronously with a single file handle per process. WAL mode allows concurrent reads during a single writer. No connection string, no search path — the database is a local file.
-
-| 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 behavior, but `BEGIN` acquires a shared lock; `BEGIN IMMEDIATE` acquires a write lock | Must use `BEGIN IMMEDIATE` for any transaction that will write, to avoid `SQLITE_BUSY` upgrade failures |
-| **Isolation level** | Read Committed (default) | Serializable (only level available) | Stricter — no dirty reads possible, but write contention increases |
-| **Concurrent writes** | Multiple writers, row-level locking | Single writer at a time; others wait up to `busy_timeout` | `busy_timeout = 5000` absorbs typical contention; sustained parallel writes will queue |
-| **Advisory locks** | `pg_advisory_lock()` used by pg-boss | Not available | Replaced by SQLiteQueueAdapter's transactional claim pattern |
-| **RETURNING clause** | Full support on INSERT/UPDATE/DELETE | Supported since SQLite 3.35.0 | No change needed — minimum version enforced at startup |
-| **ON CONFLICT (upsert)** | `ON CONFLICT … DO UPDATE SET` | Same syntax supported | No change needed |
-| **SAVEPOINT / nested tx** | Full support | Supported via `SAVEPOINT`/`RELEASE` | No change needed |
-| **`IS NOT DISTINCT FROM`** | Native operator | Not supported | Must rewrite to `(col = ? OR (col IS NULL AND ? IS NULL))` or use `IS` operator |
-| **`= ANY($1)` (array param)** | Native array parameter | Not supported | Must rewrite to `IN (?, ?, …)` with expanded params or use `json_each()` |
-| **`@>` (array contains)** | Native array containment | Not supported | Must rewrite to subquery against `json_each()` |
-| **`ILIKE`** | Case-insensitive LIKE | Not supported | Must rewrite to `LIKE` with `COLLATE NOCASE` or `lower()` |
-| **`NULLS FIRST/LAST`** | Native in `ORDER BY` | Supported since SQLite 3.30.0 | No change needed |
-
-### Affected Backend Services
-
-Every service below calls `createAdminDbClient()` from `lib/db-adapter.ts` and will require adapter changes:
-
-| Service File | DB Operations | Migration Notes |
-|-------------|---------------|-----------------|
-| `lib/db.ts` | ~40 call sites — CRUD for tasks, projects, learnings, comments, logs, costs, user settings, workflows, graphs, runs | Central data layer; every query pattern must be validated against SQLite compatibility matrix |
-| `lib/db-adapter.ts` | `QueryBuilder` with Postgres-specific SQL generation (`$1` params, `= ANY()`, `@>`, `IS NOT DISTINCT FROM`, `ILIKE`) | **Primary migration target** — must produce SQLite-compatible SQL |
-| `lib/db-server.ts` | Thin wrapper returning `createAdminDbClient()` | Minimal change — swap underlying adapter |
-| `lib/db-client.ts` | Client-side stub (no real DB calls) | No change needed |
-| `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 — no PG-specific patterns |
-| `lib/security.ts` | API key management, rate limiting (4 call sites) | Rate limit `rpc` uses `ON CONFLICT … DO UPDATE` — compatible |
-| `lib/device-flow.ts` | OAuth device flow token storage (3 call sites) | Standard CRUD — no PG-specific patterns |
-| `lib/notifications/index.ts` | Notification delivery tracking (5 call sites) | Standard CRUD — no PG-specific patterns |
-| `lib/orchestrator/activities.ts` | Task orchestration state transitions (4 call sites) | Standard CRUD — no PG-specific patterns |
-| `lib/orchestrator/events.ts` | Event emission to DB (1 call site) | Standard CRUD — no PG-specific patterns |
-| `src/graph/task-lifecycle.ts` | Graph execution lifecycle (1 call site) | Standard CRUD — no PG-specific patterns |
-| `src/graph/store.ts` | Graph state persistence | Uses `pool.query` directly — must be routed through adapter |
-
-### Affected API Routes
-
-All routes below use `createAdminDbClient()` or functions from `lib/db.ts`:
-
-| API Route | Operations | Behavior Changes |
-|-----------|-----------|-----------------|
-| `app/api/tasks/route.ts` | List, create, search tasks | Search uses `or()` filter with `ILIKE` — must rewrite to case-insensitive `LIKE` |
-| `app/api/tasks/[id]/route.ts` | Get, update, delete task | Uses `contains()` filter (`@>`) — must rewrite to `json_each()` |
-| `app/api/tasks/[id]/comments/route.ts` | List, add comments | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/comments/[commentId]/route.ts` | Delete comment | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/logs/route.ts` | List, add logs | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/logs/stream/route.ts` | SSE log streaming (polling) | Polls DB — polling interval may need tuning for SQLite read perf |
-| `app/api/tasks/[id]/history/route.ts` | Task run history | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/heartbeat/route.ts` | Agent heartbeat updates | High-frequency writes — verify `busy_timeout` handles contention |
-| `app/api/tasks/[id]/costs/route.ts` | Cost tracking | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/graph/start/route.ts` | Start graph execution | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/graph/pause/route.ts` | Pause graph | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/graph/resume/route.ts` | Resume graph | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/graph/stop/route.ts` | Stop graph | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/graph/restart/route.ts` | Restart graph | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/nodes/[nodeId]/verify/route.ts` | Node verification | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/nodes/[nodeId]/start/route.ts` | Start node execution | Standard CRUD — no behavior change |
-| `app/api/tasks/[id]/nodes/[nodeId]/resume/route.ts` | Resume node | Standard CRUD — no behavior change |
-| `app/api/tasks/stream/route.ts` | SSE task list streaming | Polls DB — same tuning note as log streaming |
-| `app/api/tasks/assign-orphans/route.ts` | Orphan task assignment | Standard CRUD — no behavior change |
-| `app/api/queue/route.ts` | Queue dispatch | Already migrated to SQLiteQueueAdapter — no change |
-| `app/api/queue/complete/route.ts` | Queue job completion | Uses `lib/db` functions — standard CRUD |
-| `app/api/projects/route.ts` | List, create projects | Standard CRUD — no behavior change |
-| `app/api/projects/[id]/route.ts` | Get, update, delete project | Standard CRUD — no behavior change |
-| `app/api/projects/[id]/migrate-v1/route.ts` | V1 migration | Standard CRUD — no behavior change |
-| `app/api/projects/[id]/migrate-v2/route.ts` | V2 migration | Standard CRUD — no behavior change |
-| `app/api/learnings/route.ts` | CRUD for learnings | Standard CRUD — no behavior change |
-| `app/api/user-settings/route.ts` | User preferences | Standard CRUD — no behavior change |
-| `app/api/logs/stream/route.ts` | Global log streaming | Polls DB — same tuning note |
-| `app/api/orchestrator/tasks/[taskId]/start/route.ts` | Orchestrator task start | Standard CRUD — no behavior change |
-| `app/api/orchestrator/tasks/[taskId]/cancel/route.ts` | Orchestrator cancel | Standard CRUD — no behavior change |
-| `app/api/orchestrator/tasks/[taskId]/signal/route.ts` | Orchestrator signal | Standard CRUD — no behavior change |
-| `app/api/orchestrator/tasks/[taskId]/status/route.ts` | Orchestrator status | Read-only — no behavior change |
-
-### QueryBuilder Postgres-Specific Patterns Requiring Migration
-
-The `QueryBuilder` in `lib/db-adapter.ts` uses these Postgres-specific patterns that must change:
-
-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. **JSON column encoding**: `JSON.stringify()` already used — compatible with SQLite `TEXT` + `json_valid()`
-7. **`RETURNING` clause**: Compatible — no change needed (SQLite ≥ 3.35.0)
-8. **`ON CONFLICT … DO UPDATE`**: Compatible — no change needed
-
----
-
-## 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. The SQLite equivalent eliminates schema namespacing (no `agx.` prefix) and replaces Postgres-specific constructs:
-
-#### Structural Changes
-
-| Postgres Feature | SQLite Equivalent | Tables Affected |
-|-----------------|-------------------|-----------------|
-| `agx.` schema prefix | Flat namespace (no schemas) | All 22 tables |
-| `gen_random_uuid()` default | Application-generated UUIDs (via `crypto.randomUUID()`) | All tables with `id uuid DEFAULT gen_random_uuid()` |
-| `pgcrypto` extension | Not needed — UUIDs generated in application layer | Global |
-| `SERIAL` / `BIGSERIAL` | `INTEGER PRIMARY KEY AUTOINCREMENT` | None currently (all PKs are UUIDs) |
-| `inet` type | `TEXT` | `task_audit_log.ip_address` |
-| `text[]` arrays | `TEXT` (JSON-encoded array) | `stage_prompts.outputs`, `tasks.depends_on` |
-| `uuid[]` arrays | `TEXT` (JSON-encoded array) | `tasks.depends_on` |
-| Partial unique indexes (`WHERE` clause) | Supported since SQLite 3.15.0 | `task_templates` (public/user slug indexes), `tasks` (queue index), `projects` (workflow index) |
-| `GIN` indexes on `jsonb` | Not available — use expression indexes or `json_each()` queries | `tasks.stage_decisions` |
-| `CHECK` constraints with `ANY(ARRAY[...])` | `CHECK(col IN (...))` | 10 tables with enum-like constraints |
-
-#### Trigger Migration
-
-Postgres uses PL/pgSQL trigger functions; SQLite uses inline trigger bodies:
-
-| Postgres Trigger | SQLite Equivalent |
-|-----------------|-------------------|
-| `update_updated_at()` function + per-table triggers | `CREATE TRIGGER <name> BEFORE UPDATE ON <table> FOR EACH ROW BEGIN UPDATE <table> SET updated_at = datetime('now') WHERE rowid = NEW.rowid; END;` |
-| `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 | Rewritten as application-layer logic or inline SQL |
-
-#### Foreign Key Cascade Behavior
-
-All foreign key relationships (`ON DELETE CASCADE`, `ON DELETE SET NULL`) are preserved identically in SQLite. The `PRAGMA foreign_keys = ON` setting (enforced at connection init) ensures SQLite honors these constraints — they are off by default in SQLite, unlike Postgres.
-
-#### Index Translation
-
-Most Postgres B-tree indexes translate directly. Notable exceptions:
-
-- **GIN index** on `tasks.stage_decisions` → Dropped. Replaced by application-layer filtering or `json_each()` subqueries.
-- **Partial indexes** (e.g., `idx_tasks_queue WHERE status = 'queued'`) → Supported in SQLite; syntax is identical.
-- **Composite primary keys** (e.g., `graph_nodes(graph_id, node_id)`, `graph_edges(graph_id, from_id, to_id, type)`) → Supported; no change needed.
-
-### Migration Scripts
-
-No standalone migration script directory exists yet. Migration scripts will be created during **Phase 3** (owner: Jane). The planned approach:
-
-1. **DDL generation**: Translate `001_agx_board_schema.sql` to SQLite-compatible DDL (removing schema prefixes, PL/pgSQL functions, DO blocks, `pg_constraint` checks).
-2. **Data export**: `COPY` from Postgres tables to CSV/JSON, then `INSERT` into SQLite.
-3. **Verification**: Row-count and checksum comparison between source and target.
-
-Reference files for Phase 3:
-- Source schema: `docker/postgres/init/001_agx_board_schema.sql`
-- Type mapping: See "Type Semantics" table in this ADR
-- Runtime contract: `src/db/init.ts` (PRAGMA application), `src/db/checks.ts` (version/extension validation)
-
-### SQLite-Specific Constraints
-
-1. **Single-writer**: Only one write transaction at a time. Concurrent writers wait up to `busy_timeout` (5000ms). The application's write patterns (task updates, log appends) are sequential per-task, so this is not a practical limitation.
-2. **No concurrent schema changes**: DDL statements (`ALTER TABLE`, `CREATE INDEX`) acquire an exclusive lock. Must be run during maintenance windows.
-3. **No `ALTER TABLE DROP COLUMN`**: Supported only since SQLite 3.35.0 (enforced by startup check).
-4. **JSON not indexed natively**: Unlike Postgres `GIN` on `jsonb`, SQLite requires expression indexes (`CREATE INDEX ... ON table(json_extract(col, '$.key'))`) for indexed JSON access.
-5. **No `LISTEN/NOTIFY`**: SSE streaming routes (`logs/stream`, `tasks/stream`) already use polling; no change needed.
-6. **Max database size**: 281 TB theoretical; practical limit is filesystem-dependent. Current dataset (~84 tasks, ~4k graph nodes) is well within bounds.
-
----
-
-## Frontend Impact
-
-### No Client-Side Behavioral Changes
-
-The frontend is fully decoupled from the database layer. All data access flows through REST API routes (`/api/tasks`, `/api/projects`, `/api/learnings`, etc.) via standard `fetch()` calls in React hooks:
-
-- `hooks/useProjects.ts` — CRUD via `/api/projects`
-- `hooks/useProviders.ts` — Read-only via `/api/providers`
-- `lib/storage/` — `LocalThreadAdapter` uses `localStorage` for chat threads (completely independent of the server database)
-
-**Key observation:** Frontend hooks consume JSON responses from API routes. The API response shapes are defined by the `DbAdapter` interface (`lib/db-adapter.interface.ts`), which remains stable across the migration. The frontend never constructs SQL, never references database-specific types, and never depends on Postgres or SQLite behavior.
-
-### What the Frontend Will NOT Notice
-
-- Type changes (`uuid` → `TEXT`, `timestamptz` → `TEXT ISO 8601`) — the API layer already serializes these as strings.
-- `boolean` stored as `INTEGER(0/1)` — the API layer converts to JS `true`/`false`.
-- `jsonb` → `TEXT` — already `JSON.parse()`'d in the adapter before reaching API responses.
-- Array columns (`depends_on`, `outputs`) stored as JSON text — already deserialized by the adapter.
-
-### Potential Observability Differences
-
-- **SSE polling latency**: Log and task streaming routes poll the database. SQLite read performance under WAL is comparable to Postgres for the current dataset size, but latency characteristics differ (no connection pool overhead, but single-file I/O). Monitor P99 response times during Phase 5 shadow-read validation.
-- **Concurrent request handling**: Under high concurrent load, SQLite's single-writer model may increase response times for write-heavy API routes (e.g., `/api/tasks/[id]/heartbeat`). This is mitigated by `busy_timeout` and is unlikely at current scale.
-
----
-
-## 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 init / PRAGMAs: `src/db/init.ts`
-- DB validation: `src/db/checks.ts`
-- DB backup/restore: `src/db/backup.ts`
-- Frontend hooks: `hooks/useProjects.ts`, `hooks/useProviders.ts`
-- Thread storage (client-side): `lib/storage/`