1.7 KiB
1.7 KiB
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
- Use SF query/writer helpers when operating inside the SF extension.
- Use
node:sqlitedirectly only for isolated tooling or package code that cannot import the SF extension runtime. - Prefer read-only SQLite handles for monitors and inspection overlays.
- Do not keep compatibility code for retired JSON or sidecar DB stores unless an explicit migration command owns it.
- Add behavior tests before changing persistence semantics.
Verification
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