@lwelliott/cortex-cli 1.0.3

package/dist/services/schema-migration-service.js

@@ -0,0 +1,894 @@
+"use strict";
+// Schema Migration Service — Sprint 31: 9-Phase Graph Schema Overhaul
+// Implements SAD-0033: Schema Finalization — Drop entity_types Table, 18 Relation Types
+// Implements SAD-0012: Schema-to-Graph CLI Migration (extended for Sprint 31)
+// Implements FS-SS-031-0001 through FS-SS-031-0008 (all 8 Sprint 31 migration specs)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAvailablePhases = getAvailablePhases;
+exports.runPhase = runPhase;
+exports.runMigration = runMigration;
+exports.validatePreMigration = validatePreMigration;
+exports.validatePostMigration = validatePostMigration;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const child_process_1 = require("child_process");
+const retry_1 = require("../db/retry");
+const errors_1 = require("../utils/errors");
+// ─── Utility Functions ───
+function measureElapsed(fn) {
+    const start = process.hrtime.bigint();
+    fn();
+    const end = process.hrtime.bigint();
+    return Number((end - start) / 1000000n);
+}
+// ─── Canonical Schema Definitions (post-Sprint-31 / builtin:3.0) ───
+/** 18 canonical relation types (SAD-0033 §3, plan/project-schema.yaml) */
+const NEW_RELATION_TYPES = {
+    // 8 NEW types (Phase 4)
+    decomposed_to: { from: ['SAD'], to: ['AD', 'QA'], cardinality: 'one_to_many' },
+    decomposes: { from: ['AD', 'QA'], to: ['SAD'], cardinality: 'many_to_one' },
+    divided_from: { from: ['TC'], to: ['TS'], cardinality: 'many_to_one' },
+    divided_into: { from: ['TC'], to: ['TS'], cardinality: 'many_to_one' },
+    fulfilled_by: { from: ['US'], to: ['FR', 'NFR'], cardinality: 'many_to_many' },
+    fulfills: { from: ['FR', 'NFR'], to: ['US'], cardinality: 'many_to_many' },
+    realized_by: { from: ['FR'], to: ['FS'], cardinality: 'many_to_many' },
+    realizes: { from: ['FS'], to: ['FR'], cardinality: 'many_to_many' },
+};
+/** 9 surviving relation types with UPDATED definitions (Phase 5) */
+const SURVIVING_UPDATES = {
+    contained_in: { from: ['US', 'FR', 'NFR'], to: ['MDL'], cardinality: 'many_to_one' },
+    contains: { from: ['MDL'], to: ['US', 'FR', 'NFR'], cardinality: 'one_to_many' },
+    covered_by: { from: ['FS', 'NFS'], to: ['SAD', 'AD', 'QA'], cardinality: 'many_to_many' },
+    covers: { from: ['SAD', 'AD', 'QA'], to: ['FS', 'NFS'], cardinality: 'many_to_many' },
+    implemented_by: { from: ['SAD', 'AD', 'QA'], to: ['SRC'], cardinality: 'many_to_many' },
+    implements: { from: ['SRC'], to: ['SAD', 'AD', 'QA'], cardinality: 'many_to_many' },
+    verified_by: { from: ['FS', 'NFS'], to: ['TS'], cardinality: 'many_to_many' },
+    verifies: { from: ['TS'], to: ['FS', 'NFS'], cardinality: 'many_to_many' },
+    // depends_on: unchanged [MDL] → [MDL]; no update applied
+};
+/** depends_on + depended_on_by: unchanged from builtin:2.0 but listed for completeness */
+const UNCHANGED_SURVIVORS = ['depends_on', 'depended_on_by'];
+/** 17 relation types to DELETE in Phase 7 (SAD-0033 §3) */
+const REMOVED_RELATION_TYPES = [
+    'affected_by', 'affects', 'belongs_to', 'belongs_to_suite',
+    'decided_by', 'decides', 'decomposed_from', 'decomposes_to',
+    'governed_by', 'governs_inv', 'has_member', 'reviewed_by',
+    'reviews', 'traced_from', 'traces_to', 'validated_by', 'validates',
+];
+/** All 18 final relation type names */
+const FINAL_RELATION_TYPE_NAMES = [
+    ...Object.keys(NEW_RELATION_TYPES),
+    ...Object.keys(SURVIVING_UPDATES),
+    ...UNCHANGED_SURVIVORS,
+];
+// ─── Phase 1: Drop entity_types Table ───
+function phase1_execute(db) {
+    const details = { entityTypesTableDropped: 0, entitiesTableRecreated: 0 };
+    // Check if entity_types table exists
+    const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    if (tableExists) {
+        // SQLite does not support ALTER TABLE DROP CONSTRAINT.
+        // The entities table has a FK: type_name REFERENCES entity_types(name).
+        // We must recreate entities without the FK before dropping entity_types.
+        // (FK enforcement is already OFF for the entire migration.)
+        db.exec(`
+      CREATE TABLE entities_new (
+        id          TEXT PRIMARY KEY,
+        type_name   TEXT NOT NULL,
+        properties  TEXT NOT NULL DEFAULT '{}',
+        created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      INSERT INTO entities_new SELECT id, type_name, properties, created_at, updated_at FROM entities;
+      DROP TABLE entities;
+      ALTER TABLE entities_new RENAME TO entities;
+      CREATE INDEX idx_entities_type ON entities(type_name);
+    `);
+        details.entitiesTableRecreated = 1;
+        db.exec('DROP TABLE IF EXISTS entity_types');
+        details.entityTypesTableDropped = 1;
+    }
+    else {
+        details.entityTypesTableDropped = 0;
+        details.entitiesTableRecreated = 0;
+    }
+    return details;
+}
+function phase1_validatePre(db) {
+    const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    return !!tableExists;
+}
+function phase1_validatePost(db) {
+    const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    return !tableExists;
+}
+// ─── Phase 2: Delete TR Graph Entities and Relations ───
+function phase2_execute(db) {
+    const details = { trEntitiesDeleted: 0, trRelationsDeleted: 0, testReportRowsPreserved: 0 };
+    // Count TR entities
+    const trEntityCount = db.prepare("SELECT COUNT(*) as cnt FROM entities WHERE type_name = 'TR'").get().cnt;
+    if (trEntityCount === 0) {
+        return details; // Nothing to do — idempotent
+    }
+    // Delete all relations referencing TR entities
+    const relResult1 = db.prepare("DELETE FROM relations WHERE from_id IN (SELECT id FROM entities WHERE type_name = 'TR') OR to_id IN (SELECT id FROM entities WHERE type_name = 'TR')").run();
+    details.trRelationsDeleted = relResult1.changes;
+    // Also delete any relations referencing TR entities by ID
+    const trEntityIds = db.prepare("SELECT id FROM entities WHERE type_name = 'TR'").all();
+    for (const e of trEntityIds) {
+        db.prepare('DELETE FROM relations WHERE from_id = ? OR to_id = ?').run(e.id, e.id);
+    }
+    // Delete TR entities
+    const entityResult = db.prepare("DELETE FROM entities WHERE type_name = 'TR'").run();
+    details.trEntitiesDeleted = entityResult.changes;
+    // Count preserved test_reports rows
+    const testReportCount = db.prepare('SELECT COUNT(*) as cnt FROM test_reports').get().cnt;
+    details.testReportsRowsPreserved = testReportCount;
+    return details;
+}
+function phase2_validatePre(db) {
+    const trCount = db.prepare("SELECT COUNT(*) as cnt FROM entities WHERE type_name = 'TR'").get().cnt;
+    return trCount > 0;
+}
+function phase2_validatePost(db) {
+    const trCount = db.prepare("SELECT COUNT(*) as cnt FROM entities WHERE type_name = 'TR'").get().cnt;
+    return trCount === 0;
+}
+// ─── Phase 3: Migrate URD Documents to US/FR/NFR ───
+function determineUrdReplacementType(title, content) {
+    const titleLower = (title || '').toLowerCase();
+    const contentLower = (content || '').toLowerCase();
+    // NFR pattern: non-functional, performance, NFR prefix
+    if (titleLower.includes('non-functional') || titleLower.includes('non functional') ||
+        titleLower.startsWith('nfr-') || titleLower.includes('nfr ') ||
+        contentLower.includes('non-functional requirement') ||
+        titleLower.includes('performance') ||
+        titleLower.includes('latency') || titleLower.includes('throughput') ||
+        titleLower.includes('concurrency')) {
+        return 'NFR';
+    }
+    // FR pattern: functional requirement, FR prefix
+    if (titleLower.includes('functional requirement') ||
+        titleLower.startsWith('fr-') || titleLower.includes('fr ') ||
+        contentLower.includes('functional requirement') ||
+        titleLower.includes(' bug ') || titleLower.includes('fix') ||
+        titleLower.includes('error') || titleLower.includes('validation') ||
+        titleLower.includes('command') || titleLower.includes('search')) {
+        return 'FR';
+    }
+    // US pattern: user story, US prefix
+    if (titleLower.includes('user story') || titleLower.includes('userstory') ||
+        titleLower.startsWith('us-') || titleLower.includes('us ')) {
+        return 'US';
+    }
+    // Default: US as catch-all (most URD docs are user story level)
+    return 'US';
+}
+function phase3_execute(db, _projectRoot) {
+    const details = {
+        urdDocsMigrated: 0,
+        migratedToUS: 0,
+        migratedToFR: 0,
+        migratedToNFR: 0,
+    };
+    // Find all URD documents
+    const urdDocs = db.prepare("SELECT d.id, d.title, d.type FROM documents d WHERE d.type = 'URD'").all();
+    if (urdDocs.length === 0) {
+        return details; // Nothing to do — idempotent
+    }
+    // Delete any existing URD entities (cascading relations)
+    db.prepare("DELETE FROM relations WHERE from_id IN (SELECT id FROM entities WHERE type_name = 'URD') OR to_id IN (SELECT id FROM entities WHERE type_name = 'URD')").run();
+    const urdEntities = db.prepare("SELECT id FROM entities WHERE type_name = 'URD'").all();
+    for (const e of urdEntities) {
+        db.prepare('DELETE FROM relations WHERE from_id = ? OR to_id = ?').run(e.id, e.id);
+    }
+    db.prepare("DELETE FROM entities WHERE type_name = 'URD'").run();
+    // Get content for each URD doc and determine replacement type
+    for (const doc of urdDocs) {
+        const contentRow = db.prepare('SELECT content FROM document_contents WHERE document_id = ?').get(doc.id);
+        const replacementType = determineUrdReplacementType(doc.title, contentRow?.content ?? null);
+        // Generate new ID: TYPE-NNNN where NNNN is next sequential number
+        const maxIdRow = db.prepare("SELECT MAX(CAST(SUBSTR(id, INSTR(id, '-') + 1) AS INTEGER)) as maxNum FROM documents WHERE type = ?").get(replacementType);
+        const nextNum = ((maxIdRow?.maxNum ?? 0) + 1);
+        const newId = `${replacementType}-${String(nextNum).padStart(4, '0')}`;
+        // Update document type and ID
+        db.prepare('UPDATE documents SET type = ?, id = ? WHERE id = ?').run(replacementType, newId, doc.id);
+        // Update content FK
+        db.prepare('UPDATE document_contents SET document_id = ? WHERE document_id = ?').run(newId, doc.id);
+        details.urdDocsMigrated++;
+        if (replacementType === 'US')
+            details.migratedToUS++;
+        else if (replacementType === 'FR')
+            details.migratedToFR++;
+        else
+            details.migratedToNFR++;
+    }
+    return details;
+}
+function phase3_validatePre(db) {
+    const urdCount = db.prepare("SELECT COUNT(*) as cnt FROM documents WHERE type = 'URD'").get().cnt;
+    return urdCount > 0;
+}
+function phase3_validatePost(db) {
+    const urdCount = db.prepare("SELECT COUNT(*) as cnt FROM documents WHERE type = 'URD'").get().cnt;
+    return urdCount === 0;
+}
+// ─── Phase 4: Add 8 New Relation Type Definitions ───
+function phase4_execute(db) {
+    const details = { newRelationTypesAdded: 0, alreadyExisted: 0 };
+    const now = new Date().toISOString();
+    for (const [name, def] of Object.entries(NEW_RELATION_TYPES)) {
+        const existing = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (existing) {
+            details.alreadyExisted++;
+            continue;
+        }
+        db.prepare(`
+      INSERT INTO relation_types (name, from_types, to_types, cardinality, inverse_of, description, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(name, JSON.stringify(def.from), JSON.stringify(def.to), def.cardinality, null, '', now, now);
+        details.newRelationTypesAdded++;
+    }
+    return details;
+}
+function phase4_validatePre(db) {
+    // Valid if not all 8 new types exist yet
+    let missing = 0;
+    for (const name of Object.keys(NEW_RELATION_TYPES)) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (!exists)
+            missing++;
+    }
+    return missing > 0;
+}
+function phase4_validatePost(db) {
+    let allPresent = true;
+    for (const name of Object.keys(NEW_RELATION_TYPES)) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (!exists)
+            allPresent = false;
+    }
+    return allPresent;
+}
+// ─── Phase 5: Update 9 Surviving Relation Type Definitions ───
+function phase5_execute(db) {
+    const details = { relationTypesUpdated: 0 };
+    for (const [name, def] of Object.entries(SURVIVING_UPDATES)) {
+        const existing = db.prepare('SELECT name, from_types, to_types, cardinality FROM relation_types WHERE name = ?').get(name);
+        if (!existing)
+            continue;
+        const newFrom = JSON.stringify(def.from);
+        const newTo = JSON.stringify(def.to);
+        if (existing.from_types !== newFrom || existing.to_types !== newTo || existing.cardinality !== def.cardinality) {
+            db.prepare('UPDATE relation_types SET from_types = ?, to_types = ?, cardinality = ? WHERE name = ?').run(newFrom, newTo, def.cardinality, name);
+            details.relationTypesUpdated++;
+        }
+    }
+    return details;
+}
+function phase5_validatePre(_db) {
+    // Always allowed; idempotent
+    return true;
+}
+function phase5_validatePost(db) {
+    // Verify all surviving types match expected definitions
+    for (const [name, def] of Object.entries(SURVIVING_UPDATES)) {
+        const row = db.prepare('SELECT from_types, to_types FROM relation_types WHERE name = ?').get(name);
+        if (!row)
+            return false;
+        if (row.from_types !== JSON.stringify(def.from))
+            return false;
+        if (row.to_types !== JSON.stringify(def.to))
+            return false;
+    }
+    return true;
+}
+// ─── Phase 6: Post-Migration Traceability Rebuild ───
+function phase6_execute(db) {
+    const details = {
+        fulfilledByCreated: 0,
+        fulfillsCreated: 0,
+        realizedByCreated: 0,
+        realizesCreated: 0,
+        oldEdgesRead: 0,
+    };
+    const now = new Date().toISOString();
+    // Step 1: Read old decomposed_from / decomposes_to edges (these will be deleted in Phase 7)
+    // These represent: US → decomposes_to → FR/NFR
+    const oldDecomposeEdges = db.prepare(`
+    SELECT DISTINCT r.from_id, r.to_id,
+           e_from.type_name as from_type, e_to.type_name as to_type
+    FROM relations r
+    JOIN entities e_from ON r.from_id = e_from.id
+    JOIN entities e_to ON r.to_id = e_to.id
+    WHERE r.rel_type IN ('decomposed_from', 'decomposes_to')
+  `).all();
+    details.oldEdgesRead += oldDecomposeEdges.length;
+    // Build fulfilled_by/fulfills edges from decomposition data
+    const fulfilledPairs = new Set();
+    for (const edge of oldDecomposeEdges) {
+        let usId = null;
+        let frNfrId = null;
+        if (edge.from_type === 'US' && (edge.to_type === 'FR' || edge.to_type === 'NFR')) {
+            usId = edge.from_id;
+            frNfrId = edge.to_id;
+        }
+        else if (edge.to_type === 'US' && (edge.from_type === 'FR' || edge.from_type === 'NFR')) {
+            usId = edge.to_id;
+            frNfrId = edge.from_id;
+        }
+        if (usId && frNfrId) {
+            const pairKey = `fulfilled:${usId}->${frNfrId}`;
+            if (!fulfilledPairs.has(pairKey)) {
+                fulfilledPairs.add(pairKey);
+                // Check if fulfilled_by already exists
+                const existingFb = db.prepare("SELECT id FROM relations WHERE rel_type = 'fulfilled_by' AND from_id = ? AND to_id = ?").get(usId, frNfrId);
+                if (!existingFb) {
+                    db.prepare(`
+            INSERT INTO relations (rel_type, from_id, to_id, properties, created_at)
+            VALUES (?, ?, ?, ?, ?)
+          `).run('fulfilled_by', usId, frNfrId, '{}', now);
+                    details.fulfilledByCreated++;
+                }
+                // Check if fulfills already exists
+                const existingFl = db.prepare("SELECT id FROM relations WHERE rel_type = 'fulfills' AND from_id = ? AND to_id = ?").get(frNfrId, usId);
+                if (!existingFl) {
+                    db.prepare(`
+            INSERT INTO relations (rel_type, from_id, to_id, properties, created_at)
+            VALUES (?, ?, ?, ?, ?)
+          `).run('fulfills', frNfrId, usId, '{}', now);
+                    details.fulfillsCreated++;
+                }
+            }
+        }
+    }
+    // Step 2: Read old traced_from / traces_to edges
+    // These represent: FR → traced_from → FS (FR requirement traces from FS specification)
+    const oldTraceEdges = db.prepare(`
+    SELECT DISTINCT r.from_id, r.to_id,
+           e_from.type_name as from_type, e_to.type_name as to_type
+    FROM relations r
+    JOIN entities e_from ON r.from_id = e_from.id
+    JOIN entities e_to ON r.to_id = e_to.id
+    WHERE r.rel_type IN ('traced_from', 'traces_to')
+  `).all();
+    details.oldEdgesRead += oldTraceEdges.length;
+    // Build realized_by/realizes edges from traceability data
+    const realizedPairs = new Set();
+    for (const edge of oldTraceEdges) {
+        let frId = null;
+        let fsId = null;
+        if (edge.from_type === 'FR' && edge.to_type === 'FS') {
+            frId = edge.from_id;
+            fsId = edge.to_id;
+        }
+        else if (edge.to_type === 'FR' && edge.from_type === 'FS') {
+            frId = edge.to_id;
+            fsId = edge.from_id;
+        }
+        else if (edge.from_type === 'FR' && (edge.to_type === 'FS' || edge.to_type === 'NFS')) {
+            frId = edge.from_id;
+            fsId = edge.to_id;
+        }
+        else if (edge.to_type === 'FR' && (edge.from_type === 'FS' || edge.from_type === 'NFS')) {
+            frId = edge.to_id;
+            fsId = edge.from_id;
+        }
+        if (frId && fsId) {
+            const pairKey = `realized:${frId}->${fsId}`;
+            if (!realizedPairs.has(pairKey)) {
+                realizedPairs.add(pairKey);
+                // Check if realized_by already exists
+                const existingRb = db.prepare("SELECT id FROM relations WHERE rel_type = 'realized_by' AND from_id = ? AND to_id = ?").get(frId, fsId);
+                if (!existingRb) {
+                    db.prepare(`
+            INSERT INTO relations (rel_type, from_id, to_id, properties, created_at)
+            VALUES (?, ?, ?, ?, ?)
+          `).run('realized_by', frId, fsId, '{}', now);
+                    details.realizedByCreated++;
+                }
+                // Check if realizes already exists
+                const existingRl = db.prepare("SELECT id FROM relations WHERE rel_type = 'realizes' AND from_id = ? AND to_id = ?").get(fsId, frId);
+                if (!existingRl) {
+                    db.prepare(`
+            INSERT INTO relations (rel_type, from_id, to_id, properties, created_at)
+            VALUES (?, ?, ?, ?, ?)
+          `).run('realizes', fsId, frId, '{}', now);
+                    details.realizesCreated++;
+                }
+            }
+        }
+    }
+    return details;
+}
+function phase6_validatePre(db) {
+    // Check if all 8 new relation types exist (Phase 4 must have been run)
+    for (const name of Object.keys(NEW_RELATION_TYPES)) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (!exists)
+            return false;
+    }
+    return true;
+}
+function phase6_validatePost() {
+    // Success if no errors thrown
+    return true;
+}
+// ─── Phase 7: Remove 17 Old Relation Types ───
+function phase7_execute(db) {
+    const details = { relationTypesRemoved: 0, relationInstancesDeleted: 0, violatingRelationsDeleted: 0 };
+    // Step 0: Delete relation instances that violate the new schema type constraints.
+    // After Phase 5 updates the relation type definitions, some existing relation
+    // instances may have entity types that are no longer allowed.
+    const currentRelationTypes = db.prepare('SELECT name, from_types, to_types FROM relation_types').all();
+    for (const rt of currentRelationTypes) {
+        const allowedFrom = JSON.parse(rt.from_types);
+        const allowedTo = JSON.parse(rt.to_types);
+        // Delete relations where from_entity type is not in allowedFrom
+        const violatingFrom = db.prepare(`
+      DELETE FROM relations WHERE rel_type = ?
+        AND from_id IN (SELECT id FROM entities WHERE type_name NOT IN (${allowedFrom.map(() => '?').join(',')}))
+    `).run(rt.name, ...allowedFrom);
+        details.violatingRelationsDeleted += violatingFrom.changes;
+        // Delete relations where to_entity type is not in allowedTo
+        const violatingTo = db.prepare(`
+      DELETE FROM relations WHERE rel_type = ?
+        AND to_id IN (SELECT id FROM entities WHERE type_name NOT IN (${allowedTo.map(() => '?').join(',')}))
+    `).run(rt.name, ...allowedTo);
+        details.violatingRelationsDeleted += violatingTo.changes;
+    }
+    for (const typeName of REMOVED_RELATION_TYPES) {
+        // Step 1: Delete all relation instances of this type
+        const instResult = db.prepare('DELETE FROM relations WHERE rel_type = ?').run(typeName);
+        details.relationInstancesDeleted += instResult.changes;
+        // Step 2: Delete the relation type definition
+        const typeResult = db.prepare('DELETE FROM relation_types WHERE name = ?').run(typeName);
+        if (typeResult.changes > 0) {
+            details.relationTypesRemoved++;
+        }
+    }
+    return details;
+}
+function phase7_validatePre(db) {
+    let remaining = 0;
+    for (const name of REMOVED_RELATION_TYPES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (exists)
+            remaining++;
+    }
+    return remaining > 0;
+}
+function phase7_validatePost(db) {
+    for (const name of REMOVED_RELATION_TYPES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (exists)
+            return false;
+    }
+    return true;
+}
+// ─── Phase 8: YAML Finalization ───
+// generateYamlContent removed — YAML is now source-of-truth, read-only by migration
+function phase8_execute(db, projectRoot) {
+    const details = {};
+    // Step 1: Verify relation type count
+    const rtCount = db.prepare('SELECT COUNT(*) as cnt FROM relation_types').get().cnt;
+    details.relationTypeCount = rtCount;
+    // Step 2: Read plan/project-schema.yaml as source-of-truth
+    const planPath = (0, path_1.resolve)(projectRoot, 'plan', 'project-schema.yaml');
+    if (!(0, fs_1.existsSync)(planPath)) {
+        throw new errors_1.MigrationYamlWriteError('plan/project-schema.yaml', 'YAML schema file not found — cannot sync DB from YAML');
+    }
+    const yamlContent = (0, fs_1.readFileSync)(planPath, 'utf-8');
+    details.planYamlRead = planPath;
+    details.planYamlBytes = yamlContent.length;
+    // Step 3: Parse YAML and sync to DB (YAML is source-of-truth)
+    const yaml = require('yaml');
+    const schema = yaml.parse(yamlContent);
+    if (!schema || !schema.relation_types) {
+        throw new errors_1.MigrationValidationError('YAML schema missing relation_types key');
+    }
+    const updateStmt = db.prepare(`UPDATE relation_types SET from_types = ?, to_types = ?, cardinality = ?, updated_at = datetime('now') WHERE name = ?`);
+    let syncedCount = 0;
+    for (const [name, def] of Object.entries(schema.relation_types)) {
+        const fromTypes = JSON.stringify(def?.from ?? []);
+        const toTypes = JSON.stringify(def?.to ?? []);
+        const cardinality = def?.cardinality ?? 'many_to_many';
+        const result = updateStmt.run(fromTypes, toTypes, cardinality, name);
+        if (result.changes > 0)
+            syncedCount++;
+    }
+    details.relationTypesSynced = syncedCount;
+    // Step 4: Re-generate schema-types.ts (optional — skip if script unavailable)
+    const scriptPath = (0, path_1.resolve)(projectRoot, 'scripts', 'generate-schema-types.js');
+    if ((0, fs_1.existsSync)(scriptPath)) {
+        try {
+            const output = (0, child_process_1.execSync)(`node ${scriptPath}`, {
+                cwd: projectRoot,
+                encoding: 'utf-8',
+                timeout: 30_000,
+            });
+            details.scriptOutput = output.trim();
+        }
+        catch (err) {
+            // Script execution failure is non-fatal for yaml-finalization
+            const msg = err instanceof Error ? err.message : String(err);
+            details.scriptOutput = `Warning: generate-schema-types.js failed: ${msg}`;
+        }
+    }
+    else {
+        details.scriptOutput = 'generate-schema-types.js not found — skipped';
+    }
+    // Step 5: Update graph_schema metadata to builtin:3.0
+    const now = new Date().toISOString();
+    db.prepare('DELETE FROM graph_schema').run();
+    db.prepare('INSERT INTO graph_schema (source_file, version, bootstrapped_at, checksum) VALUES (?, ?, ?, ?)').run('builtin:3.0', 'builtin:3.0', now, null);
+    details.schemaVersion = 'builtin:3.0';
+    return details;
+}
+function phase8_validatePre(db) {
+    const rtCount = db.prepare('SELECT COUNT(*) as cnt FROM relation_types').get().cnt;
+    return rtCount === 18;
+}
+function phase8_validatePost(_db) {
+    return true; // Verified by Phase 9
+}
+// ─── Phase 9: Verification ───
+function phase9_execute(db) {
+    const details = {};
+    // Re-enable FK enforcement — it was disabled at the start of the migration
+    db.exec('PRAGMA foreign_keys = ON');
+    // Check 1: Relation type count
+    const rtCount = db.prepare('SELECT COUNT(*) as cnt FROM relation_types').get().cnt;
+    details.relationTypeCount = rtCount;
+    // Check 2: Verify no entity_types table
+    const etTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    details.entityTypesTableExists = etTable ? 'YES' : 'NO';
+    // Check 3: Count remaining relation instances
+    const relCount = db.prepare('SELECT COUNT(*) as cnt FROM relations').get().cnt;
+    details.remainingRelationInstances = relCount;
+    // Check 4: Verify no removed relation types exist
+    let removedStillPresent = 0;
+    for (const name of REMOVED_RELATION_TYPES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (exists)
+            removedStillPresent++;
+    }
+    details.removedTypesStillPresent = removedStillPresent;
+    // Check 5: Verify all final types exist
+    let finalTypesPresent = 0;
+    for (const name of FINAL_RELATION_TYPE_NAMES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (exists)
+            finalTypesPresent++;
+    }
+    details.finalTypesPresent = finalTypesPresent;
+    // Check 6: Count URD documents
+    const urdCount = db.prepare("SELECT COUNT(*) as cnt FROM documents WHERE type = 'URD'").get().cnt;
+    details.urdDocsRemaining = urdCount;
+    // Check 7: Count TR entities
+    const trCount = db.prepare("SELECT COUNT(*) as cnt FROM entities WHERE type_name = 'TR'").get().cnt;
+    details.trEntitiesRemaining = trCount;
+    // Check 8: Dangling relations
+    const danglingCount = db.prepare(`
+    SELECT COUNT(*) as cnt FROM relations r
+    LEFT JOIN entities e1 ON r.from_id = e1.id
+    LEFT JOIN entities e2 ON r.to_id = e2.id
+    WHERE e1.id IS NULL OR e2.id IS NULL
+  `).get().cnt;
+    details.danglingRelations = danglingCount;
+    // Overall pass/fail
+    const failed = [];
+    if (rtCount !== 18)
+        failed.push(`Relation type count ${rtCount} != 18`);
+    if (etTable)
+        failed.push('entity_types table still exists');
+    if (removedStillPresent > 0)
+        failed.push(`${removedStillPresent} removed types still present`);
+    if (finalTypesPresent !== 18)
+        failed.push(`Only ${finalTypesPresent}/18 final types present`);
+    if (urdCount > 0)
+        failed.push(`${urdCount} URD docs remaining`);
+    if (trCount > 0)
+        failed.push(`${trCount} TR entities remaining`);
+    if (danglingCount > 0)
+        failed.push(`${danglingCount} dangling relations`);
+    if (failed.length > 0) {
+        throw new errors_1.MigrationValidationError(`Verification failed: ${failed.join('; ')}`);
+    }
+    details.verdict = 'PASS';
+    return details;
+}
+function phase9_validatePre(_db) {
+    return true; // Always runnable
+}
+function phase9_validatePost(_db) {
+    return true;
+}
+// ─── Phase Registry ───
+const PHASES = [
+    {
+        name: 'entity-types-drop',
+        execute: (db, _) => {
+            const result = { phase: 'entity-types-drop', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase1_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase1_validatePre,
+        validatePost: phase1_validatePost,
+    },
+    {
+        name: 'tr-relations-cleanup',
+        execute: (db, _) => {
+            const result = { phase: 'tr-relations-cleanup', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase2_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase2_validatePre,
+        validatePost: phase2_validatePost,
+    },
+    {
+        name: 'urd-migration',
+        execute: (db, projectRoot) => {
+            const result = { phase: 'urd-migration', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase3_execute(db, projectRoot);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase3_validatePre,
+        validatePost: phase3_validatePost,
+    },
+    {
+        name: 'add-new-relations',
+        execute: (db, _) => {
+            const result = { phase: 'add-new-relations', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase4_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase4_validatePre,
+        validatePost: phase4_validatePost,
+    },
+    {
+        name: 'update-surviving-relations',
+        execute: (db, _) => {
+            const result = { phase: 'update-surviving-relations', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase5_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase5_validatePre,
+        validatePost: phase5_validatePost,
+    },
+    {
+        name: 'traceability-rebuild',
+        execute: (db, _) => {
+            const result = { phase: 'traceability-rebuild', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase6_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase6_validatePre,
+        validatePost: (_db) => phase6_validatePost(),
+    },
+    {
+        name: 'remove-old-relations',
+        execute: (db, _) => {
+            const result = { phase: 'remove-old-relations', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase7_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase7_validatePre,
+        validatePost: phase7_validatePost,
+    },
+    {
+        name: 'yaml-finalization',
+        execute: (db, projectRoot) => {
+            const result = { phase: 'yaml-finalization', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase8_execute(db, projectRoot);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase8_validatePre,
+        validatePost: phase8_validatePost,
+    },
+    {
+        name: 'verification',
+        execute: (db, _) => {
+            const result = { phase: 'verification', elapsedMs: 0, details: {} };
+            try {
+                result.elapsedMs = measureElapsed(() => {
+                    result.details = phase9_execute(db);
+                });
+            }
+            catch (err) {
+                result.error = err instanceof Error ? err.message : String(err);
+            }
+            return result;
+        },
+        validatePre: phase9_validatePre,
+        validatePost: phase9_validatePost,
+    },
+];
+const PHASE_NAME_MAP = new Map(PHASES.map(p => [p.name, p]));
+// ─── Public API ───
+function getAvailablePhases() {
+    return PHASES.map(p => p.name);
+}
+/**
+ * Run a single named phase. Throws if phase name is unknown.
+ */
+function runPhase(db, phaseName, projectRoot) {
+    const phase = PHASE_NAME_MAP.get(phaseName);
+    if (!phase) {
+        throw new Error(`Unknown migration phase: ${phaseName}. Valid phases: ${getAvailablePhases().join(', ')}`);
+    }
+    return phase.execute(db, projectRoot);
+}
+/**
+ * Run the full 9-phase Sprint 31 migration on the given database.
+ * Phases execute in order. Each phase runs in its own transaction.
+ * Idempotent: phases skip work when preconditions are already met.
+ *
+ * @param db - Database connection
+ * @param projectRoot - Project root directory (for YAML/script paths in Phase 8)
+ * @returns MigrationResult with phase details and elapsed times
+ */
+function runMigration(db, projectRoot) {
+    const phases = [];
+    const errors = [];
+    const totalStart = process.hrtime.bigint();
+    // SQLite schema migrations require FK enforcement to be OFF during the
+    // entire migration because we recreate tables, change IDs, and drop
+    // referenced tables. FK is re-enabled in Phase 9 (verification).
+    db.exec('PRAGMA foreign_keys = OFF');
+    // Phase ordering enforcement: check each phase's preconditions
+    // and skip if already applied
+    for (const phase of PHASES) {
+        const phaseName = phase.name;
+        // Check if phase needs to run (or is already applied)
+        // For destructive phases, validatePre checks if work needs to be done
+        // For additive phases, we check the post-condition instead
+        try {
+            // Run the phase in a transaction
+            (0, retry_1.withTransaction)(db, () => {
+                const result = phase.execute(db, projectRoot);
+                result.phase = phaseName; // Ensure phase name is set
+                phases.push(result);
+                if (result.error) {
+                    errors.push(`${phaseName}: ${result.error}`);
+                }
+                else {
+                    console.log(`Phase ${phaseName}: ${result.elapsedMs}ms`);
+                }
+                // Post-validation
+                if (!result.error && !phase.validatePost(db)) {
+                    const msg = `Post-validation failed for phase ${phaseName}`;
+                    result.error = msg;
+                    errors.push(msg);
+                }
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            phases.push({
+                phase: phaseName,
+                elapsedMs: 0,
+                details: {},
+                error: msg,
+            });
+            errors.push(`${phaseName}: ${msg}`);
+            console.error(`Phase ${phaseName} failed: ${msg}`);
+        }
+        // If a phase failed, stop further phases
+        if (phases[phases.length - 1].error) {
+            const totalElapsed = Number((process.hrtime.bigint() - totalStart) / 1000000n);
+            return { success: false, phases, totalElapsedMs: totalElapsed, errors };
+        }
+    }
+    const totalElapsed = Number((process.hrtime.bigint() - totalStart) / 1000000n);
+    console.log(`Total migration time: ${totalElapsed}ms`);
+    return {
+        success: errors.length === 0,
+        phases,
+        totalElapsedMs: totalElapsed,
+        errors,
+    };
+}
+/**
+ * Pre-migration validation: check that the database has the expected pre-migration state.
+ * (builtin:2.0 characteristics — entity_types table, 27+ relation types)
+ */
+function validatePreMigration(db) {
+    const entityTypeTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    if (entityTypeTable) {
+        const entityTypeCount = db.prepare('SELECT COUNT(*) as cnt FROM entity_types').get().cnt;
+        console.log(`Pre-migration: entity_types table present with ${entityTypeCount} types`);
+    }
+    else {
+        console.log('Pre-migration: entity_types table already dropped');
+    }
+    const relationTypeCount = db.prepare('SELECT COUNT(*) as cnt FROM relation_types').get().cnt;
+    console.log(`Pre-migration: ${relationTypeCount} relation types present`);
+}
+/**
+ * Post-migration validation: verify the database is in builtin:3.0 state.
+ */
+function validatePostMigration(db) {
+    // Verify entity_types table is dropped
+    const etTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entity_types'").get();
+    if (etTable) {
+        throw new errors_1.MigrationValidationError('Post-migration validation failed: entity_types table still exists');
+    }
+    // Verify relation type count
+    const rtCount = db.prepare('SELECT COUNT(*) as cnt FROM relation_types').get().cnt;
+    if (rtCount !== 18) {
+        throw new errors_1.MigrationValidationError(`Post-migration validation failed: expected 18 relation types, found ${rtCount}`);
+    }
+    // Verify no removed relation types exist
+    for (const removed of REMOVED_RELATION_TYPES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(removed);
+        if (exists) {
+            throw new errors_1.MigrationValidationError(`Post-migration validation failed: removed relation type "${removed}" still exists`);
+        }
+    }
+    // Verify all final types exist
+    for (const name of FINAL_RELATION_TYPE_NAMES) {
+        const exists = db.prepare('SELECT name FROM relation_types WHERE name = ?').get(name);
+        if (!exists) {
+            throw new errors_1.MigrationValidationError(`Post-migration validation failed: required relation type "${name}" not found`);
+        }
+    }
+    console.log('Post-migration validation: PASSED');
+}
+//# sourceMappingURL=schema-migration-service.js.map