Module migrations 

SQL schema setup for WaveStore, FileStore, and the saga log.

objects.db uses a flat schema: run_object_schema defines the final table set directly in one idempotent CREATE TABLE IF NOT EXISTS batch. It replaced an 11-step incremental migration chain (run_forge_v1 … run_forge_v11) — see docs/specs/SPEC_SCHEMA_FLATTENING_2026_05_19.md. The chain was pure historical accretion: per-version data dirs mean every new version is born with a fresh objects.db and ran the whole chain top-to-bottom anyway, so the intermediate states were never reachable in production.

filestore.db and sagas.db were already single-DDL stores; they keep their existing schema functions and gain only the user_version tripwire (stamp_and_check_version).

Constants

DEAD_TABLE_DROPS 🔒

Tables retained by the old chain only for a downgrade path the flatten abandons. Dropped from any legacy DB by the adopt step; never created by the flat schema. db_workflow_* data was already copied into db_drone_* by the old v10 migration, so dropping loses nothing.

FILESTORE_SCHEMA_VERSION

user_version value stamped into filestore.db.

LEGACY_INDEX_DROPS 🔒

Legacy index names that must be dropped after their table is renamed — ALTER TABLE … RENAME keeps indexes attached but under their old names, which would collide with the flat DDL’s CREATE INDEX. The flat DDL recreates each under the new name.

LEGACY_TABLE_RENAMES 🔒

Legacy objects.db table names retired by the de-forge rename, paired with their replacement. adopt_legacy_table_names renames any of these it finds — the single surviving piece of the old migration chain (it also subsumes the v11 db_identities/db_memories rename).

OBJECT_SCHEMA_VERSION

user_version value stamped into objects.db after run_object_schema. The flat schema reset the counter to 1 (the pre-flatten chain never set user_version, so legacy files read 0). Bumped per additive migration: v1 — flat schema baseline v2 — db_agent_definitions.updated_at v3 — db_agent_definitions.user_hidden (Phase 2 hide templates, SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md Q2 Decision Y) v4 — db_agents consolidation table (Phase 3a; dual-write only, reads still on db_agent_definitions / db_agent_instances)

SAGA_LOG_SCHEMA_VERSION

user_version value stamped into sagas.db.

WSTORE_OTYPES 🔒

Object type table names matching the db_<otype> convention.

Functions

adopt_legacy_table_names 🔒

Rename any pre-flatten objects.db tables to their de-forged names and drop the dead workflow/sentinel tables. Idempotent — on a fresh or already-flat database every check is a no-op.

check_schema_compat

PRAGMA user_version tripwire (AUDIT_SQLITE_SYSTEMS §8.5).

run_filestore_migrations

Initialize the FileStore schema. Creates the wave_file and file_data tables. Already a flat single-DDL store — unaffected by the objects.db flattening.

run_object_schema

Initialize (or re-validate) the full objects.db schema.

run_saga_log_migrations

Initialize the saga durability schema (saga + saga_step tables and their indexes). See docs/specs/SPEC_SAGA_DURABILITY_2026-05-01.md §2.2. Already a flat single-DDL store.

stamp_version

Stamp the database’s user_version PRAGMA to current. Called AFTER run_*_schema succeeds, paired with a prior check_schema_compat that gated the migrations on the caller-binary speaking a compatible (or newer) schema version.