singularity-forge/docs/dev/SQLITE-MIGRATION.md

# SQLite Runtime Baseline

**Status:** complete for the Node 26.1 runtime baseline.

SF uses built-in `node:sqlite` and the project-local `.sf/sf.db` as the
canonical structured store for planning state, UOK execution state, learning
outcomes, schedules, memory extraction queues, and generated projections.

## Runtime Rule

- **Node baseline:** 26.1+
- **Canonical database:** `.sf/sf.db`
- **SQLite binding:** built-in `node:sqlite`
- **Sidecar stores:** not allowed for active SF state

Runtime code must not introduce `sql.js`, `better-sqlite3`, `sqlite3` CLI
shell-outs, or JSON fallback databases for DB-owned state. If a feature needs
ordering, validation, joins, leases, TTLs, or history, put it in `.sf/sf.db`.

## Current Surfaces

- **Learning outcomes:** `llm_task_outcomes`
- **UOK execution graphs:** `uok_execution_graphs`, `uok_graph_nodes`,
  `uok_graph_progress`
- **UOK coordination:** `uok_kv`, `uok_stream_entries`, `uok_queue_items`
- **Memory extraction:** `threads`, `stage1_outputs`, `jobs`
- **Schedules:** `schedule_entries`

## Development Rules

1. Use SF query/writer helpers when operating inside the SF extension.
2. Use `node:sqlite` directly only for isolated tooling or package code that
   cannot import the SF extension runtime.
3. Prefer read-only SQLite handles for monitors and inspection overlays.
4. Do not keep compatibility code for retired JSON or sidecar DB stores unless
   an explicit migration command owns it.
5. Add behavior tests before changing persistence semantics.

## Verification

```bash
npm run typecheck:extensions
npx vitest run --config vitest.config.ts \
  src/resources/extensions/sf/learning/*.test.mjs \
  src/resources/extensions/sf/tests/uok-*.test.mjs
```