@zq-silk/yui 0.11.2 → 0.12.0

package/dist/storage/migration/productionRegistry.js

@@ -18,6 +18,8 @@ const PROJECT_FROM_VERSION = 2;
 const PROJECT_TO_VERSION = 3;
 const PROJECT_KNOWLEDGE_PROPOSALS_FROM_VERSION = 3;
 const PROJECT_KNOWLEDGE_PROPOSALS_TO_VERSION = 4;
+const PROJECT_LIFECYCLE_FROM_VERSION = 4;
+const PROJECT_LIFECYCLE_TO_VERSION = 5;
 const TASK_FROM_VERSION = 3;
 const TASK_TO_VERSION = 4;
 const TASK_INTENT_FROM_VERSION = 4;
@@ -77,6 +79,8 @@ const STORED_TASK_JOB_CALLER_KEY_HASHES_FROM_VERSION = 15;
 const STORED_TASK_JOB_CALLER_KEY_HASHES_TO_VERSION = 16;
 const STORED_TASK_WAKES_FROM_VERSION = 16;
 const STORED_TASK_WAKES_TO_VERSION = 17;
+const STORED_TASK_EVENT_NOTICES_FROM_VERSION = 17;
+const STORED_TASK_EVENT_NOTICES_TO_VERSION = 18;
 const TASK_WAKE_FROM_VERSION = 0;
 const TASK_WAKE_TO_VERSION = 1;
 const STORED_TASK_PUBLICATION_REFERENCES_FROM_VERSION = 16;
@@ -95,6 +99,8 @@ const PUBLICATION_REFERENCE_FROM_VERSION = 0;
 const PUBLICATION_REFERENCE_TO_VERSION = 1;
 const CONFIG_FROM_VERSION = 1;
 const CONFIG_TO_VERSION = 2;
+const CONFIG_REVIEW_CONTROLS_FROM_VERSION = 2;
+const CONFIG_REVIEW_CONTROLS_TO_VERSION = 3;
 /**
  * Build the authoritative production graph. Transition intent and executable
  * transforms are registered together here; compatible loading and offline
@@ -144,7 +150,9 @@ export function createProductionStorageRegistry() {
     })
         .registerOfflineMigration(projectOwnershipStep())
         .registerOfflineMigration(configV2Step())
+        .registerOfflineMigration(configReviewControlsRemovalStep())
         .registerCompatible(projectKnowledgeProposalsStep())
+        .registerCompatible(projectLifecycleStep())
         .registerOfflineMigration(taskWorkspaceIdentityStep())
         .registerOfflineMigration(taskIntentStep())
         .registerOfflineMigration(recordFamilyStep("workItem", WORK_ITEM_FROM_VERSION, WORK_ITEM_TO_VERSION, "workItems"))
@@ -177,6 +185,7 @@ export function createProductionStorageRegistry() {
         .registerCompatible(storedTaskDurableJobsStep())
         .registerCompatible(storedTaskJobCallerKeyHashesStep())
         .registerCompatible(storedTaskWakesAndPublicationReferencesStep())
+        .registerOfflineMigration(storedTaskEventNoticesStep())
         .registerCompatible(taskWakeIntroductionStep())
         .registerCompatible(durableJobIntroductionStep())
         .registerOfflineMigration(capabilityGrantIntroductionStep())
@@ -243,6 +252,61 @@ function migrateConfigV1ToV2(snapshot) {
         }
     };
 }
+/** Removes retired Core controls for the Leader-owned Delta decision. */
+function configReviewControlsRemovalStep() {
+    return {
+        axis: "record",
+        recordKind: "config",
+        fromVersion: CONFIG_REVIEW_CONTROLS_FROM_VERSION,
+        toVersion: CONFIG_REVIEW_CONTROLS_TO_VERSION,
+        preconditions: requireConfigV2,
+        transform: migrateConfigV2ToV3,
+        declaredEffects: []
+    };
+}
+function requireConfigV2(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.config !== CONFIG_REVIEW_CONTROLS_FROM_VERSION) {
+        throw new Error(`Record config migration requires manifest version ${CONFIG_REVIEW_CONTROLS_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const config = asObject(snapshot.state.config, "Yui config");
+    if (config.schemaVersion !== CONFIG_REVIEW_CONTROLS_FROM_VERSION) {
+        throw new Error(`Yui config must use schemaVersion ${CONFIG_REVIEW_CONTROLS_FROM_VERSION} before migration.`);
+    }
+}
+function migrateConfigV2ToV3(snapshot) {
+    requireConfigV2(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...versions, config: CONFIG_REVIEW_CONTROLS_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const config = asObject(snapshot.state.config, "Yui config");
+    const review = config.review === undefined
+        ? undefined
+        : asObject(config.review, "Yui review config");
+    const migratedReview = review === undefined
+        ? undefined
+        : (() => {
+            const { deltaRecheck: _retiredSwitch, deltaRecheckMaxChangedLines: _retiredLineThreshold, deltaRecheckMaxChangedFiles: _retiredFileThreshold, ...retained } = review;
+            return retained;
+        })();
+    return {
+        schemaManifest,
+        state: {
+            ...snapshot.state,
+            config: {
+                ...config,
+                schemaVersion: CONFIG_REVIEW_CONTROLS_TO_VERSION,
+                ...(migratedReview === undefined ? {} : { review: migratedReview })
+            }
+        }
+    };
+}
 function workItemExecutionGroupHistoryStep() {
     return {
         axis: "record",
@@ -1238,6 +1302,324 @@ function normalizeStoredTaskV16ToV17(snapshot) {
         state: { ...snapshot.state, tasks: nextTasks }
     };
 }
+/** StoredTask v18 retires the mutable OperatorNotification projection. */
+function storedTaskEventNoticesStep() {
+    return {
+        axis: "record",
+        recordKind: "storedTask",
+        fromVersion: STORED_TASK_EVENT_NOTICES_FROM_VERSION,
+        toVersion: STORED_TASK_EVENT_NOTICES_TO_VERSION,
+        preconditions: requireStoredTaskV17OperatorNoticeShape,
+        transform: normalizeStoredTaskV17ToV18,
+        declaredEffects: ["operator-mailbox-event-references"]
+    };
+}
+const STORED_TASK_V17_FIELDS = [
+    "schemaVersion",
+    "task",
+    "idHighWaterMarks",
+    "brief",
+    "changeSets",
+    "integrationAttempts",
+    "integrationQueue",
+    "durableJobs",
+    "roles",
+    "managedWorkspaces",
+    "roleSessionSets",
+    "jobCallerKeyHashes",
+    "workItems",
+    "contextSnapshots",
+    "agentRuns",
+    "reviewRounds",
+    "activeRuns",
+    "messages",
+    "inputRequests",
+    "decisions",
+    "milestones",
+    "events",
+    "wakes",
+    "capabilityGrants",
+    "releaseWorkflows",
+    "publicationReferences",
+    "leaderFailure",
+    "operatorNotification"
+];
+function requireStoredTaskV17OperatorNoticeShape(snapshot) {
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (versions.storedTask !== STORED_TASK_EVENT_NOTICES_FROM_VERSION) {
+        throw new Error(`Record storedTask compatible step requires manifest version ${STORED_TASK_EVENT_NOTICES_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        if (task.schemaVersion !== STORED_TASK_EVENT_NOTICES_FROM_VERSION) {
+            throw new Error(`Task aggregate ${taskId} must use schemaVersion ${STORED_TASK_EVENT_NOTICES_FROM_VERSION}.`);
+        }
+        const allowed = new Set(STORED_TASK_V17_FIELDS);
+        const unknown = Object.keys(task).find((key) => !allowed.has(key));
+        if (unknown !== undefined) {
+            throw new Error(`Task aggregate ${taskId} has an unknown v17 field: ${unknown}.`);
+        }
+        const missing = STORED_TASK_V17_FIELDS.find((key) => !Object.hasOwn(task, key));
+        if (missing !== undefined) {
+            throw new Error(`Task aggregate ${taskId} is missing v17 field: ${missing}.`);
+        }
+        if (task.operatorNotification !== null) {
+            requireLegacyOperatorNotice(task.operatorNotification, taskId);
+        }
+    }
+}
+function requireLegacyOperatorNotice(value, taskId) {
+    const notice = asObject(value, `Operator notification ${taskId}`);
+    if (notice.schemaVersion !== 1 || notice.taskId !== taskId) {
+        throw new Error(`Operator notification identity is invalid: ${taskId}.`);
+    }
+    if (notice.type === "leader-recovery-failed") {
+        requireLegacyNoticeText(notice.message, `Operator notification message ${taskId}`);
+    }
+    else if (notice.type === "leader-stalled") {
+        requireLegacyNoticeText(notice.message, `Operator notification message ${taskId}`);
+        requireLegacyNoticeText(notice.runId, `Operator notification Run ${taskId}`);
+        requireLegacyNoticeTimestamp(notice.progressAt, `Operator notification progress ${taskId}`);
+        requireLegacyNoticeText(notice.evidenceKey, `Operator notification evidence ${taskId}`);
+        if (notice.classification !== "truly-stalled") {
+            throw new Error(`Operator notification classification is invalid: ${taskId}.`);
+        }
+    }
+    else if (notice.type === "task-terminal") {
+        if (notice.status !== "completed" && notice.status !== "retired") {
+            throw new Error(`Operator notification Task status is invalid: ${taskId}.`);
+        }
+        if (!["user", "operator", "leader"].includes(String(notice.by))) {
+            throw new Error(`Operator notification Task actor is invalid: ${taskId}.`);
+        }
+        requireLegacyNoticeText(notice.summary, `Operator notification summary ${taskId}`);
+    }
+    else {
+        throw new Error(`Operator notification type is invalid: ${taskId}.`);
+    }
+    requireLegacyNoticeTimestamp(notice.createdAt, `Operator notification createdAt ${taskId}`);
+    requireLegacyNoticeTimestamp(notice.updatedAt, `Operator notification updatedAt ${taskId}`);
+}
+function requireLegacyNoticeText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return value;
+}
+function requireLegacyNoticeTimestamp(value, label) {
+    const timestamp = requireLegacyNoticeText(value, label);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        throw new Error(`${label} is invalid.`);
+    return timestamp;
+}
+function normalizeStoredTaskV17ToV18(snapshot) {
+    requireStoredTaskV17OperatorNoticeShape(snapshot);
+    const versions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: {
+            ...versions,
+            storedTask: STORED_TASK_EVENT_NOTICES_TO_VERSION
+        }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const tasks = asObject(snapshot.state.tasks, "state tasks");
+    const nextTasks = {};
+    const legacyNotices = new Map();
+    for (const [taskId, rawTask] of Object.entries(tasks)) {
+        const task = asObject(rawTask, `Task aggregate ${taskId}`);
+        legacyNotices.set(taskId, task.operatorNotification === null
+            ? null
+            : asObject(task.operatorNotification, `Operator notification ${taskId}`));
+        const nextTask = {
+            ...task,
+            schemaVersion: STORED_TASK_EVENT_NOTICES_TO_VERSION,
+            events: { ...asObject(task.events, `Task events ${taskId}`) },
+            idHighWaterMarks: {
+                ...asObject(task.idHighWaterMarks, `Task id high-water marks ${taskId}`)
+            }
+        };
+        delete nextTask.operatorNotification;
+        nextTasks[taskId] = nextTask;
+    }
+    const eventByTask = new Map();
+    const eventRefForTask = (taskId) => {
+        const existing = eventByTask.get(taskId);
+        if (existing !== undefined)
+            return { type: "event", taskId, id: existing };
+        const task = asObject(nextTasks[taskId], `Task aggregate ${taskId}`);
+        const events = asObject(task.events, `Task events ${taskId}`);
+        const marks = asObject(task.idHighWaterMarks, `Task id high-water marks ${taskId}`);
+        let sequence = Number(marks.event ?? 0) + 1;
+        if (!Number.isSafeInteger(sequence) || sequence < 1) {
+            throw new Error(`Task event high-water mark is invalid: ${taskId}.`);
+        }
+        while (events[`event-${sequence}`] !== undefined)
+            sequence += 1;
+        const eventId = `event-${sequence}`;
+        const notice = legacyNotices.get(taskId) ?? null;
+        const migrated = migratedOperatorNoticeEvent(taskId, eventId, notice, task);
+        events[eventId] = migrated;
+        marks.event = sequence;
+        eventByTask.set(taskId, eventId);
+        return { type: "event", taskId, id: eventId };
+    };
+    const mailboxes = asObject(snapshot.state.mailboxes, "state mailboxes");
+    const nextMailboxes = {};
+    for (const [key, rawMailbox] of Object.entries(mailboxes)) {
+        const mailbox = asObject(rawMailbox, `WorkMailbox ${key}`);
+        const target = asObject(mailbox.target, `WorkMailbox target ${key}`);
+        nextMailboxes[key] = target.kind === "operator"
+            ? rewriteLegacyOperatorMailbox(mailbox, key, eventRefForTask)
+            : { ...mailbox };
+    }
+    for (const [taskId, notice] of legacyNotices) {
+        if (notice !== null)
+            eventRefForTask(taskId);
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, tasks: nextTasks, mailboxes: nextMailboxes }
+    };
+}
+function migratedOperatorNoticeEvent(taskId, eventId, notice, taskAggregate) {
+    const task = asObject(taskAggregate.task, `Task ${taskId}`);
+    const timestamp = String(notice?.updatedAt ?? task.updatedAt ?? task.createdAt ?? "");
+    if (!Number.isFinite(Date.parse(timestamp))) {
+        throw new Error(`Legacy Operator notice timestamp is invalid: ${taskId}.`);
+    }
+    const type = notice?.type;
+    if (notice !== null && type === "task-terminal") {
+        const status = String(notice.status ?? "");
+        if (status !== "completed" && status !== "retired") {
+            throw new Error(`Legacy terminal Operator notice status is invalid: ${taskId}.`);
+        }
+        return {
+            schemaVersion: 2,
+            id: eventId,
+            taskId,
+            type: `task.${status}`,
+            payload: {
+                status,
+                by: String(notice.by ?? "operator"),
+                summary: String(notice.summary ?? "Task reached a terminal state."),
+                migratedFrom: "operator-notification"
+            },
+            createdAt: timestamp
+        };
+    }
+    if (notice !== null && type === "leader-stalled") {
+        return {
+            schemaVersion: 2,
+            id: eventId,
+            taskId,
+            type: "run.stalled",
+            payload: {
+                runId: String(notice.runId ?? "unknown"),
+                roleName: "leader",
+                progressAt: String(notice.progressAt ?? timestamp),
+                classification: "truly-stalled",
+                evidenceKey: String(notice.evidenceKey ?? "legacy-operator-notification"),
+                migratedFrom: "operator-notification"
+            },
+            createdAt: timestamp
+        };
+    }
+    return {
+        schemaVersion: 2,
+        id: eventId,
+        taskId,
+        type: "leader.attention-required",
+        payload: {
+            reason: type === "leader-recovery-failed"
+                ? "leader-recovery-failed"
+                : "legacy-operator-mailbox",
+            message: String(notice?.message ?? "Inspect the migrated Operator notice."),
+            migratedFrom: notice === null ? "operator-mailbox" : "operator-notification"
+        },
+        createdAt: timestamp
+    };
+}
+function rewriteLegacyOperatorMailbox(mailbox, key, eventRefForTask) {
+    const rewriteRef = (rawRef) => {
+        const ref = asObject(rawRef, `WorkMailbox ${key} entity ref`);
+        if (ref.type === "input" || ref.type === "event")
+            return { ...ref };
+        const taskId = ref.type === "task" ? ref.id : ref.taskId;
+        if (typeof taskId !== "string" || taskId.trim().length === 0) {
+            throw new Error(`Legacy Operator mailbox ref has no Task identity: ${key}.`);
+        }
+        return eventRefForTask(taskId);
+    };
+    const rewriteBatch = (rawBatch, label) => {
+        const batch = asObject(rawBatch, label);
+        if (!Array.isArray(batch.refs))
+            throw new Error(`${label} refs must be an array.`);
+        const sourceRefs = batch.refs.map((rawRef) => asObject(rawRef, `${label} entity ref`));
+        const semanticTaskIds = new Set(sourceRefs.flatMap((ref) => ((ref.type === "input" || ref.type === "event") && typeof ref.taskId === "string"
+            ? [ref.taskId]
+            : [])));
+        const refs = [];
+        const seen = new Set();
+        for (const sourceRef of sourceRefs) {
+            const referencedTaskId = sourceRef.type === "task" ? sourceRef.id : sourceRef.taskId;
+            if (sourceRef.type !== "input"
+                && sourceRef.type !== "event"
+                && typeof referencedTaskId === "string"
+                && semanticTaskIds.has(referencedTaskId)) {
+                continue;
+            }
+            const ref = rewriteRef(sourceRef);
+            const identity = `${String(ref.type)}\0${String(ref.taskId ?? "")}\0${String(ref.id)}`;
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            refs.push(ref);
+        }
+        return { ...batch, refs };
+    };
+    const rewriteProcessing = (raw) => {
+        if (raw === null)
+            return null;
+        const processing = asObject(raw, `WorkMailbox ${key} processing`);
+        return {
+            ...processing,
+            batch: rewriteBatch(processing.batch, `WorkMailbox ${key} processing batch`),
+            ...(processing.executionRef === undefined
+                ? {}
+                : { executionRef: rewriteRef(processing.executionRef) })
+        };
+    };
+    const rewriteDelivery = (raw) => {
+        if (raw === null)
+            return null;
+        const delivery = asObject(raw, `WorkMailbox ${key} input delivery`);
+        return {
+            ...delivery,
+            batch: rewriteBatch(delivery.batch, `WorkMailbox ${key} input delivery batch`),
+            executionRef: rewriteRef(delivery.executionRef)
+        };
+    };
+    const pending = asObject(mailbox.pending, `WorkMailbox ${key} pending lanes`);
+    return {
+        ...mailbox,
+        processing: rewriteProcessing(mailbox.processing),
+        pending: {
+            ...pending,
+            normal: pending.normal === null
+                ? null
+                : rewriteBatch(pending.normal, `WorkMailbox ${key} normal batch`),
+            userCorrection: pending.userCorrection === null
+                ? null
+                : rewriteBatch(pending.userCorrection, `WorkMailbox ${key} correction batch`)
+        },
+        inputDelivery: rewriteDelivery(mailbox.inputDelivery)
+    };
+}
 /**
  * The taskWake record family is introduced alongside StoredTask v17. The
  * compatible step supplies the empty map and high-water mark; this step only
@@ -2761,6 +3143,91 @@ function normalizeProjectV3ToV4(snapshot) {
         state: { ...snapshot.state, projects: nextProjects }
     };
 }
+/**
+ * Project v5 adds the lifecycle status (`active`/`retired`) plus the
+ * retirement audit record. Historical Projects are all active; the step only
+ * defaults the new field, so it is a compatible adjacent migration.
+ */
+function projectLifecycleStep() {
+    return {
+        kind: "compatible",
+        axis: "record",
+        recordKind: "project",
+        fromVersion: PROJECT_LIFECYCLE_FROM_VERSION,
+        toVersion: PROJECT_LIFECYCLE_TO_VERSION,
+        defaults: [
+            "status defaults to active on every Project"
+        ],
+        validateSource: (snapshot) => requireProjectV4Shape(snapshot),
+        normalize: (snapshot) => normalizeProjectV4ToV5(snapshot)
+    };
+}
+function requireProjectV4Shape(snapshot) {
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    if (manifestVersions.project !== PROJECT_LIFECYCLE_FROM_VERSION) {
+        throw new Error(`Record project compatible step requires manifest version ${PROJECT_LIFECYCLE_FROM_VERSION}.`);
+    }
+    if (snapshot.state === null)
+        return;
+    const projects = snapshot.state.projects;
+    if (projects === undefined)
+        return;
+    const map = asObject(projects, "project map");
+    const allowed = new Set(PROJECT_V4_FIELDS);
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        if (project.schemaVersion !== PROJECT_LIFECYCLE_FROM_VERSION) {
+            throw new Error(`Project ${projectId} must use schemaVersion ${PROJECT_LIFECYCLE_FROM_VERSION}.`);
+        }
+        const unknown = Object.keys(project).find((key) => !allowed.has(key));
+        if (unknown !== undefined) {
+            throw new Error(`Project ${projectId} has an unknown v4 field: ${unknown}.`);
+        }
+    }
+}
+function normalizeProjectV4ToV5(snapshot) {
+    requireProjectV4Shape(snapshot);
+    const manifestVersions = asObject(snapshot.schemaManifest.recordVersions, "schema manifest recordVersions");
+    const schemaManifest = {
+        ...snapshot.schemaManifest,
+        recordVersions: { ...manifestVersions, project: PROJECT_LIFECYCLE_TO_VERSION }
+    };
+    if (snapshot.state === null)
+        return { schemaManifest, state: null };
+    const projects = snapshot.state.projects;
+    if (projects === undefined) {
+        return { schemaManifest, state: { ...snapshot.state } };
+    }
+    const map = asObject(projects, "project map");
+    const nextProjects = {};
+    for (const [projectId, rawProject] of Object.entries(map)) {
+        const project = asObject(rawProject, `Project ${projectId}`);
+        nextProjects[projectId] = {
+            ...project,
+            schemaVersion: PROJECT_LIFECYCLE_TO_VERSION,
+            status: "active"
+        };
+    }
+    return {
+        schemaManifest,
+        state: { ...snapshot.state, projects: nextProjects }
+    };
+}
+const PROJECT_V4_FIELDS = [
+    "schemaVersion",
+    "id",
+    "name",
+    "aliases",
+    "path",
+    "ownership",
+    "remoteUrl",
+    "stableBranch",
+    "developmentBranch",
+    "knowledge",
+    "knowledgeProposals",
+    "createdAt",
+    "updatedAt"
+];
 /**
  * Task v4 adds the optional durable workspace identity. Historical Tasks have
  * no identity; they keep working against their existing (legacy) refs until the

package/dist/storage/sqliteSchema.js

@@ -327,7 +327,8 @@ CREATE TABLE IF NOT EXISTS events (
 );
 CREATE INDEX IF NOT EXISTS idx_events_type_time ON events(task_id, type, occurred_at);
 
--- Per-task scheduler projections (leaderFailure, operatorNotification).
+-- Per-task scheduler projections. operator-notification is a retired legacy
+-- kind retained only so old layout-7 Homes can be read by the upgrade path.
 CREATE TABLE IF NOT EXISTS task_projections (
   task_id    TEXT NOT NULL,
   kind       TEXT NOT NULL CHECK (kind IN ('leader-failure','operator-notification')),
@@ -986,10 +987,13 @@ const SCHEMA_MIGRATIONS_SQL = `
  * layout migrations.  A database with any sqlite_master object is therefore
  * diagnosed as corrupt/partially initialized and left untouched.
  */
-function ensureMigrationLedger(db) {
+function ensureMigrationLedger(db, mode) {
     const objects = db.prepare("SELECT type, name FROM sqlite_master WHERE name IS NOT NULL").all();
     const ledger = objects.find(({ name }) => name === "schema_migrations");
     if (ledger === undefined) {
+        if (mode === "validate") {
+            throw new SqliteSchemaMigrationError("schema_migrations ledger is missing from an existing database");
+        }
         if (objects.length !== 0) {
             throw new SqliteSchemaMigrationError("schema_migrations ledger is missing from a non-empty database");
         }
@@ -1134,19 +1138,25 @@ function validatePendingProjectionBackfillSources(db) {
     }
 }
 /**
- * Apply pending migrations idempotently inside transactions.
+ * Apply or validate schema migrations without letting an ordinary open mutate
+ * an existing authoritative database.
  *
- * Each migration runs in its own transaction: the DDL and the
+ * In `apply` mode each migration runs in its own transaction: the DDL and the
  * `schema_migrations` bookkeeping commit atomically, so a crash mid-migration
- * rolls back and the next open re-applies cleanly. Re-running on a current
- * database performs no work (every version is already recorded).
+ * rolls back and the disposable staged database can be rebuilt cleanly.
+ * `validate` mode rejects a pending version before executing any migration.
  */
-export function migrateSqliteSchema(db) {
-    const ledgerWasCreated = ensureMigrationLedger(db);
+export function migrateSqliteSchema(db, options) {
+    const ledgerWasCreated = ensureMigrationLedger(db, options.mode);
     // Validate the complete ledger before touching any pending migration.  This
     // prevents a manually altered or partially recorded ledger from silently
     // skipping the partial-index/projection migrations added after a valid Home.
     const applied = validateAppliedMigrations(db, ledgerWasCreated);
+    const pending = MIGRATIONS.filter((migration) => !applied.has(migration.version));
+    if (options.mode === "validate" && pending.length > 0) {
+        throw new SqliteSchemaMigrationError(`pending SQLite schema migration ${pending[0].version}; `
+            + "run the offline staged upgrade before opening this database", "admission");
+    }
     const newlyApplied = [];
     for (const migration of MIGRATIONS) {
         if (applied.has(migration.version))