Module agents_consolidate 

Phase 3a — one-shot backfill from db_agent_definitions + db_agent_instances into the new consolidated db_agents table.

See docs/specs/SPEC_AGENT_CONCEPT_CONSOLIDATION_2026_05_24.md.

Phase 3a is write-only: this migration populates db_agents so a later Phase 3b PR can flip readers over with full confidence the data is there. Phase 3c drops the old tables.

Marker-file gated (<data_dir>/migration_agents_consolidate_v1.flag) so the backfill only runs once per data dir. Idempotent on second run (marker check short-circuits).

Algorithm (per spec §“What db_agent_instances rows become”):

1. For each db_agent_definitions WHERE is_seeded = 1: INSERT a template projection (is_template = 1, bindings empty).

2. For each db_agent_definitions WHERE is_seeded = 0: INSERT a user-clone projection (is_template = 0, parent_template_id = parent_id).

3. For each db_agent_instances row whose definition_id points at a TEMPLATE: INSERT a new user-clone projection keyed by instance.id, parent_template_id = definition_id, name + bindings from the instance.

4. For each db_agent_instances row whose definition_id points at an already-user-cloned definition: UPDATE the existing user-clone projection (keyed by the definition id from pass 2) to fold in the instance’s bindings. If multiple instances point at the same user-clone, the most-recent (created_at DESC) wins and a warning is logged.

Continuation rows (parent_instance_id non-empty) are skipped — the consolidated model has no place for them; they were the pre-Option-E continuation chain.

Structs

ConsolidateStats

Backfill statistics — useful for logs + tests.

DefRow 🔒

Snapshot of one db_agent_definitions row, narrow projection matching what the backfill needs.

InstanceRow 🔒

Snapshot of one db_agent_instances row plus the LEFT-JOINed definition fields the backfill copies into db_agents.

Constants

CONSOLIDATE_MARKER

Marker filename. Lives in the data dir (one level above the db/ subdir that holds objects.db).

Functions

consolidate_looks_incomplete

True when the backfill’s source tables have data but its target (db_agents) doesn’t — i.e. a marker (or a db_migrations stamp) claims this migration ran, but the data it’s supposed to have produced isn’t there. Used to stop trusting marker/stamp existence as proof of effect (see docs/specs/SPEC_MIGRATION_SYSTEM_HARDENING_2026_08_03.md Phase 0a/0b) — a stale marker (rebuilt/restored objects.db sitting next to an old flag file, or m0000_bootstrap stamping from a copied flag file with no matching data) is now detectable instead of silently trusted.

run_consolidate_migration

Run the one-shot consolidation backfill, gated by the marker file.

table_row_count_if_exists 🔒

SELECT COUNT(*) FROM <table>, or 0 if the table doesn’t exist at all — distinct from a genuinely empty table, which also counts as 0 here on purpose (both mean “no source rows to backfill”).