@zq-silk/yui 0.11.2 → 0.12.0

package/dist/storage/sqliteStore.js

@@ -55,7 +55,7 @@ import { assertHomeWritable } from "./upgradeFence.js";
 import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_PENDING_WAKEUP_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveRunKey, executionLaneActiveRunKeyParts, StorageConflictError, StorageCancelledError, StorageRecordError, FileTaskStore, storedCapabilityGrant, storedPublicationReference, storedReleaseWorkflow, isValidCapabilityGrantTransition, isValidReleaseWorkflowTransition, validateYuiConfig } from "./taskStore.js";
 import { publicationExternalKey } from "../task/publicationReference.js";
 import { gateArtifactKey, validateGateArtifact } from "../verification/gateArtifact.js";
-import { migrateSqliteSchema, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
+import { migrateSqliteSchema, SqliteSchemaMigrationError, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
 import { inspectStorageSchema } from "./storageSchema.js";
 /** Read the immutable Home identity without opening a writable Store connection. */
 export function readSqliteHomeIdentity(rootDir, databaseFilename = "yui.db") {
@@ -143,16 +143,29 @@ export class SqliteTaskStore {
         this.#migration = _options.migration ?? false;
         mkdirSync(rootDir, { recursive: true, mode: 0o700 });
         const filename = _options.databaseFilename ?? "yui.db";
-        this.#db = new Database(join(rootDir, filename));
-        // §4.1 / §9: WAL, no fsync weakening, FKs on, busy timeout for CLI contention.
-        this.#db.pragma("journal_mode = WAL");
-        this.#db.pragma("synchronous = FULL");
-        this.#db.pragma("foreign_keys = ON");
-        this.#db.pragma("busy_timeout = 5000");
-        this.#db.pragma("wal_autocheckpoint = 1000");
-        migrateSqliteSchema(this.#db);
-        this.#seedHomeMeta();
-        this.#seedConfig();
+        const databasePath = join(rootDir, filename);
+        const databaseExisted = existsSync(databasePath);
+        if (this.#migration && filename === "yui.db") {
+            throw new SqliteSchemaMigrationError("offline migration mode cannot open the authoritative yui.db", "admission");
+        }
+        this.#db = new Database(databasePath);
+        try {
+            // §4.1 / §9: WAL, no fsync weakening, FKs on, busy timeout for CLI contention.
+            this.#db.pragma("journal_mode = WAL");
+            this.#db.pragma("synchronous = FULL");
+            this.#db.pragma("foreign_keys = ON");
+            this.#db.pragma("busy_timeout = 5000");
+            this.#db.pragma("wal_autocheckpoint = 1000");
+            migrateSqliteSchema(this.#db, {
+                mode: this.#migration || !databaseExisted ? "apply" : "validate"
+            });
+            this.#seedHomeMeta();
+            this.#seedConfig();
+        }
+        catch (error) {
+            this.#db.close();
+            throw error;
+        }
     }
     rootDirectory() { return this.#rootDir; }
     /** Close the underlying database connection. */
@@ -596,7 +609,43 @@ export class SqliteTaskStore {
         return this.#getPayload("projects", "id = ?", [id]);
     }
     removeProject(id) {
-        return this.#mutate(() => this.#db.prepare("DELETE FROM projects WHERE id = ?").run(id).changes > 0);
+        return this.#mutate(() => {
+            if (this.listTasks().some((task) => task.projectBindings.some((binding) => binding.projectId === id))) {
+                throw new StorageRecordError(`Project is still used by a Task: ${id}`);
+            }
+            return this.#db.prepare("DELETE FROM projects WHERE id = ?").run(id).changes > 0;
+        });
+    }
+    summarizeProjectReferences(projectId) {
+        const boundTasks = this.listTasks().filter((task) => task.projectBindings.some((binding) => binding.projectId === projectId));
+        const activeTasks = boundTasks.filter((task) => task.status === "active");
+        const unresolvedWorkItemRefs = [];
+        const activeRunRefs = [];
+        const unresolvedIntegrationRefs = [];
+        for (const task of activeTasks) {
+            for (const workItem of this.listWorkItems(task.id)) {
+                if (workItem.status !== "completed" && workItem.status !== "retired") {
+                    unresolvedWorkItemRefs.push(`${task.id}/${workItem.id}`);
+                }
+            }
+            for (const run of this.listAgentRuns(task.id)) {
+                if (run.status === "active")
+                    activeRunRefs.push(`${task.id}/${run.id}`);
+            }
+            for (const attempt of this.listIntegrationAttempts(task.id)) {
+                if (attempt.status === "running" || attempt.status === "blocked") {
+                    unresolvedIntegrationRefs.push(`${task.id}/${attempt.id}`);
+                }
+            }
+        }
+        return {
+            projectId,
+            boundTaskIds: boundTasks.map(({ id }) => id),
+            activeTaskIds: activeTasks.map(({ id }) => id),
+            unresolvedWorkItemRefs,
+            activeRunRefs,
+            unresolvedIntegrationRefs
+        };
     }
     // -- agent profiles ---------------------------------------------------------
     saveAgentProfile(profile) {
@@ -2012,15 +2061,6 @@ export class SqliteTaskStore {
     clearLeaderFailure(taskId) {
         this.#clearProjection(taskId, "leader-failure");
     }
-    getOperatorNotification(taskId) {
-        return this.#getProjection(taskId, "operator-notification");
-    }
-    saveOperatorNotification(notification) {
-        this.#saveProjection(notification.taskId, "operator-notification", notification);
-    }
-    clearOperatorNotification(taskId) {
-        this.#clearProjection(taskId, "operator-notification");
-    }
     // -- pending wakeups (leader-role work-mailbox projection, mirrors taskStore.ts) --
     getPendingWakeup(taskId) {
         return pendingWakeupProjection(this.getWorkMailbox({ kind: "role", taskId, roleName: "leader" }));

package/dist/storage/storeRpc.js

@@ -97,7 +97,6 @@ const READ_ONLY_STORE_METHODS = new Set([
     "getPendingWakeup",
     "listPendingWakeups",
     "getLeaderFailure",
-    "getOperatorNotification",
     "listTelemetry",
     "countTelemetry",
     "hasOutboxEntry",

package/dist/storage/taskStore.js

@@ -31,7 +31,6 @@ import { validateIntegrationQueueEntry } from "../integration/integrationQueueEn
 import { CURRENT_DURABLE_JOB_SCHEMA_VERSION, validDurableJobTransition, validateDurableJob } from "../job/durableJob.js";
 import { validateGlobalRole, validateTaskRole } from "../role/role.js";
 import { CURRENT_LEADER_FAILURE_SCHEMA_VERSION } from "../scheduler/leaderFailure.js";
-import { CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION } from "../scheduler/operatorNotification.js";
 import { CURRENT_TASK_WAKE_SCHEMA_VERSION, validateTaskWake } from "../scheduler/taskWake.js";
 import { validateTask } from "../task/task.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
@@ -46,7 +45,7 @@ import { CURRENT_AGGREGATE_SCHEMA_VERSION, requireCompatibleStorageSchema, requi
 export const STORAGE_STATE_FILE = "state.json";
 /** The root StorageState schema is the persisted aggregate document version. */
 export const CURRENT_STORAGE_STATE_SCHEMA_VERSION = CURRENT_AGGREGATE_SCHEMA_VERSION;
-export const CURRENT_CONFIG_SCHEMA_VERSION = 2;
+export const CURRENT_CONFIG_SCHEMA_VERSION = 3;
 export const CURRENT_HOME_IDENTITY_SCHEMA_VERSION = 1;
 export const CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION = 3;
 /**
@@ -58,7 +57,7 @@ export const CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION = 3;
  * below, but are not independent record-axis families.
  */
 export const CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION = 2;
-export const CURRENT_PROJECT_SCHEMA_VERSION = 4;
+export const CURRENT_PROJECT_SCHEMA_VERSION = 5;
 export const CURRENT_AGENT_PROFILE_SCHEMA_VERSION = 2;
 export const CURRENT_GLOBAL_ROLE_SCHEMA_VERSION = 3;
 export const CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION = 3;
@@ -113,7 +112,7 @@ export function executionLaneActiveRunKeyParts(key) {
     }
 }
 /** The schema version of each persisted `state.json#/tasks/*` aggregate. */
-export const CURRENT_STORED_TASK_SCHEMA_VERSION = 17;
+export const CURRENT_STORED_TASK_SCHEMA_VERSION = 18;
 /**
  * Persisted nested-record versions consumed by this store's strict parser.
  * Keep these named at the storage boundary so the upgrade record-axis map can
@@ -279,6 +278,37 @@ export class FileTaskStore {
             return this.#remove((state) => state.projects, id);
         });
     }
+    summarizeProjectReferences(projectId) {
+        const boundTasks = this.listTasks().filter((task) => task.projectBindings.some((binding) => binding.projectId === projectId));
+        const activeTasks = boundTasks.filter((task) => task.status === "active");
+        const unresolvedWorkItemRefs = [];
+        const activeRunRefs = [];
+        const unresolvedIntegrationRefs = [];
+        for (const task of activeTasks) {
+            for (const workItem of this.listWorkItems(task.id)) {
+                if (workItem.status !== "completed" && workItem.status !== "retired") {
+                    unresolvedWorkItemRefs.push(`${task.id}/${workItem.id}`);
+                }
+            }
+            for (const run of this.listAgentRuns(task.id)) {
+                if (run.status === "active")
+                    activeRunRefs.push(`${task.id}/${run.id}`);
+            }
+            for (const attempt of this.listIntegrationAttempts(task.id)) {
+                if (attempt.status === "running" || attempt.status === "blocked") {
+                    unresolvedIntegrationRefs.push(`${task.id}/${attempt.id}`);
+                }
+            }
+        }
+        return {
+            projectId,
+            boundTaskIds: boundTasks.map(({ id }) => id),
+            activeTaskIds: activeTasks.map(({ id }) => id),
+            unresolvedWorkItemRefs,
+            activeRunRefs,
+            unresolvedIntegrationRefs
+        };
+    }
     saveAgentProfile(profile) {
         const stored = identified(profile, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, "id", profile.id, "Agent Profile");
         validateAgentProfile(stored);
@@ -1699,22 +1729,16 @@ export class FileTaskStore {
         this.saveWorkMailbox(consumePendingBatch(mailbox, "normal"));
     }
     getLeaderFailure(taskId) { return optional(this.#state().tasks[taskId]?.leaderFailure ?? undefined); }
-    saveLeaderFailure(value) { this.#saveSingleton(value.taskId, "leaderFailure", value, "Leader failure"); }
-    clearLeaderFailure(taskId) { this.#clearSingleton(taskId, "leaderFailure"); }
-    getOperatorNotification(taskId) { return optional(this.#state().tasks[taskId]?.operatorNotification ?? undefined); }
-    saveOperatorNotification(value) { this.#saveSingleton(value.taskId, "operatorNotification", value, "Operator notification"); }
-    clearOperatorNotification(taskId) { this.#clearSingleton(taskId, "operatorNotification"); }
-    #saveSingleton(taskId, key, value, label) {
-        const schemaVersion = key === "leaderFailure"
-            ? CURRENT_LEADER_FAILURE_SCHEMA_VERSION
-            : CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION;
-        const stored = identified(value, schemaVersion, "taskId", taskId, label);
-        this.#requireTaskForWrite(taskId);
-        this.#mutate((state) => { state.tasks[taskId][key] = stored; });
+    saveLeaderFailure(value) {
+        const stored = identified(value, CURRENT_LEADER_FAILURE_SCHEMA_VERSION, "taskId", value.taskId, "Leader failure");
+        this.#requireTaskForWrite(value.taskId);
+        this.#mutate((state) => { state.tasks[value.taskId].leaderFailure = stored; });
     }
-    #clearSingleton(key, field) {
-        this.#mutate((state) => { if (state.tasks[key] !== undefined)
-            state.tasks[key][field] = null; });
+    clearLeaderFailure(taskId) {
+        this.#mutate((state) => {
+            if (state.tasks[taskId] !== undefined)
+                state.tasks[taskId].leaderFailure = null;
+        });
     }
     #saveTaskRecord(taskId, key, value, label) {
         const record = versioned(value, CURRENT_MESSAGE_SCHEMA_VERSION, label);
@@ -1983,8 +2007,7 @@ function emptyStoredTask(task) {
         capabilityGrants: {},
         releaseWorkflows: {},
         publicationReferences: {},
-        leaderFailure: null,
-        operatorNotification: null
+        leaderFailure: null
     };
 }
 function emptyTaskIdHighWaterMarks() {
@@ -2202,8 +2225,7 @@ function parseStoredTask(value, taskId) {
         "capabilityGrants",
         "releaseWorkflows",
         "publicationReferences",
-        "leaderFailure",
-        "operatorNotification"
+        "leaderFailure"
     ], `Task aggregate ${taskId}`);
     parseMap(aggregate.changeSets, (record, key) => {
         const changeSet = identifiedChangeSet(record, key);
@@ -2403,14 +2425,8 @@ function parseStoredTask(value, taskId) {
         }
         return reference;
     }, "publicationReferences");
-    for (const [key, label] of [["leaderFailure", "Leader failure"], ["operatorNotification", "Operator notification"]]) {
-        const record = aggregate[key];
-        if (record !== null) {
-            const schemaVersion = key === "leaderFailure"
-                ? CURRENT_LEADER_FAILURE_SCHEMA_VERSION
-                : CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION;
-            identified(record, schemaVersion, "taskId", taskId, label);
-        }
+    if (aggregate.leaderFailure !== null) {
+        identified(aggregate.leaderFailure, CURRENT_LEADER_FAILURE_SCHEMA_VERSION, "taskId", taskId, "Leader failure");
     }
     validateTaskIdHighWaterCoverage(aggregate, taskId);
     return aggregate;

package/dist/storage/upgrade/recordVersions.js

@@ -18,7 +18,6 @@
 import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storageVersions.js";
 import { CURRENT_AGENT_RUN_SCHEMA_VERSION, CURRENT_ACTIVE_RUN_POINTER_SCHEMA_VERSION, CURRENT_AGENT_PROFILE_SCHEMA_VERSION, CURRENT_CAPABILITY_GRANT_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_CONFIGURED_AGENT_SCHEMA_VERSION, CURRENT_CHANGE_SET_SCHEMA_VERSION, CURRENT_CONTEXT_SNAPSHOT_SCHEMA_VERSION, CURRENT_DECISION_SCHEMA_VERSION, CURRENT_EVENT_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SCHEMA_VERSION, CURRENT_GLOBAL_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_INPUT_REQUEST_SCHEMA_VERSION, CURRENT_INTEGRATION_ATTEMPT_SCHEMA_VERSION, CURRENT_INTEGRATION_QUEUE_SCHEMA_VERSION, CURRENT_MANAGED_WORKSPACE_SCHEMA_VERSION, CURRENT_MESSAGE_SCHEMA_VERSION, CURRENT_MILESTONE_SCHEMA_VERSION, CURRENT_PUBLICATION_REFERENCE_SCHEMA_VERSION, CURRENT_PROJECT_SCHEMA_VERSION, CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION, CURRENT_REVIEW_ROUND_SCHEMA_VERSION, CURRENT_STORED_TASK_SCHEMA_VERSION, CURRENT_TASK_BRIEF_SCHEMA_VERSION, CURRENT_TASK_ROLE_SCHEMA_VERSION, CURRENT_TASK_ROLE_SESSION_SET_SCHEMA_VERSION, CURRENT_TASK_SCHEMA_VERSION, CURRENT_WORK_ITEM_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION } from "../taskStore.js";
 import { CURRENT_LEADER_FAILURE_SCHEMA_VERSION } from "../../scheduler/leaderFailure.js";
-import { CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION } from "../../scheduler/operatorNotification.js";
 import { CURRENT_TASK_WAKE_SCHEMA_VERSION } from "../../scheduler/taskWake.js";
 import { CURRENT_DURABLE_JOB_SCHEMA_VERSION } from "../../job/durableJob.js";
 function descriptor(version, path) {
@@ -118,7 +117,9 @@ function getCurrentRecordDescriptors() {
             releaseWorkflow: descriptor(CURRENT_RELEASE_WORKFLOW_SCHEMA_VERSION, "state.json#/tasks/*/releaseWorkflows"),
             publicationReference: descriptor(CURRENT_PUBLICATION_REFERENCE_SCHEMA_VERSION, "state.json#/tasks/*/publicationReferences"),
             leaderFailure: descriptor(CURRENT_LEADER_FAILURE_SCHEMA_VERSION, "state.json#/tasks/*/leaderFailure"),
-            operatorNotification: descriptor(CURRENT_OPERATOR_NOTIFICATION_SCHEMA_VERSION, "state.json#/tasks/*/operatorNotification"),
+            // Historical family retained in the version graph so StoredTask v17
+            // Homes can migrate; current v18 aggregates never store this field.
+            operatorNotification: descriptor(1, "state.json#/tasks/*/operatorNotification"),
             workMailbox: descriptor(CURRENT_WORK_MAILBOX_SCHEMA_VERSION, "state.json#/mailboxes")
         });
     }

package/dist/storage/upgrade/sqliteMigrationTarget.js

@@ -149,6 +149,12 @@ export function createSqliteMigrationTarget(options) {
             }
             const stamp = now().toISOString().replace(/[:.]/g, "-");
             let backupPath;
+            const schemaPath = join(home, STORAGE_SCHEMA_FILE);
+            const sourceSchemaText = readFileSync(schemaPath, "utf8");
+            const receiptPath = migrationReceiptPath(home);
+            const sourceReceiptText = existsSync(receiptPath)
+                ? readFileSync(receiptPath, "utf8")
+                : null;
             // Phase 1: back up any existing yui.db, then promote the sidecar.
             try {
                 if (existsSync(committedDbPath)) {
@@ -185,7 +191,7 @@ export function createSqliteMigrationTarget(options) {
             // Phase 2: advance schema.json to layout 7 in the same critical section.
             try {
                 if (stagedSchemaManifest !== null) {
-                    writeTextFileAtomically(join(home, STORAGE_SCHEMA_FILE), `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
+                    writeTextFileAtomically(schemaPath, `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
                 }
                 // Certify the dual-copy state (Issue 01): the 6→7 migration retains
                 // state.json read-only, so the Home legitimately holds both copies.
@@ -204,9 +210,22 @@ export function createSqliteMigrationTarget(options) {
                 }
             }
             catch (error) {
-                // The database is promoted but schema.json could not be advanced.
-                // Attempt to restore the original database; if that fails, the Home
-                // is ambiguous and must be recovered manually.
+                // A sidecar or receipt writer can fail after an atomic rename. Restore
+                // the exact source metadata as well as the database before claiming the
+                // layout switch did not commit.
+                let rollbackError;
+                try {
+                    writeTextFileAtomically(schemaPath, sourceSchemaText);
+                    if (sourceReceiptText === null) {
+                        rmSync(receiptPath, { force: true });
+                    }
+                    else {
+                        writeTextFileAtomically(receiptPath, sourceReceiptText);
+                    }
+                }
+                catch (restoreError) {
+                    rollbackError = restoreError;
+                }
                 try {
                     if (backupPath !== undefined && existsSync(backupPath)) {
                         removeSqliteFileSet(committedDbPath);
@@ -216,14 +235,17 @@ export function createSqliteMigrationTarget(options) {
                         removeSqliteFileSet(committedDbPath);
                     }
                 }
-                catch {
+                catch (restoreError) {
+                    rollbackError ??= restoreError;
+                }
+                if (rollbackError !== undefined) {
                     throw new AmbiguousSwitchError({
                         homePath: home,
                         backupPath: backupPath ?? committedDbPath,
                         stagingPath: stagedDbPath,
-                        detail: `SQLite database was promoted but schema.json could not be advanced (${messageOf(error)}), ` +
-                            `and the automatic rollback also failed. The database is at ${committedDbPath}; ` +
-                            `recover by advancing schema.json storageVersion to ${latest.layout} or restoring the backup.`
+                        detail: `SQLite database was promoted but schema.json or its receipt could not be durably advanced (${messageOf(error)}), ` +
+                            `and the database/metadata rollback also failed (${messageOf(rollbackError)}). ` +
+                            `Inspect ${committedDbPath}, ${schemaPath}, ${receiptPath}, and the backup before recovery.`
                     });
                 }
                 throw error;

package/dist/storage/upgrade/sqliteRecordMigrationTarget.js

@@ -38,7 +38,7 @@ import { AmbiguousSwitchError } from "../migration/index.js";
 import { describeActiveRuntime, homeRuntimeIsActive, inspectHomeRuntime, inspectSourceVersionState, inspectSnapshotVersionState } from "./homeMigrationTarget.js";
 import { writeSwitchProgress } from "./switchProgress.js";
 import { moveSqliteFileSet, removeSqliteFileSet } from "./sqliteFileSet.js";
-import { COMMITTED_DATABASE_FILENAME, STAGED_DATABASE_FILENAME, copySqlitePassthroughState, computeDbFamilyChecksums, computeStateFamilyChecksums, populateSqliteFromState, readStateFromSqlite } from "./sqliteStateMigration.js";
+import { COMMITTED_DATABASE_FILENAME, STAGED_DATABASE_FILENAME, copySqlitePassthroughState, computeDbFamilyChecksums, computeStateFamilyChecksums, populateSqliteFromState, readMigrationSourceStateFromSqlite } from "./sqliteStateMigration.js";
 /** Build the SQLite-backed record-migration target. */
 export function createSqliteRecordMigrationTarget(options) {
     const home = options.home;
@@ -70,7 +70,7 @@ export function createSqliteRecordMigrationTarget(options) {
         readSource() {
             const manifestRaw = readFileSync(join(home, STORAGE_SCHEMA_FILE), "utf8");
             const schemaManifest = parseJsonObject(manifestRaw, STORAGE_SCHEMA_FILE);
-            const state = readStateFromSqlite(home);
+            const state = readMigrationSourceStateFromSqlite(home);
             return Object.freeze({ schemaManifest, state });
         },
         writeFreshOutput(snapshot) {
@@ -129,6 +129,8 @@ export function createSqliteRecordMigrationTarget(options) {
             }
             const stamp = now().toISOString().replace(/[:.]/g, "-");
             let backupPath;
+            const schemaPath = join(home, STORAGE_SCHEMA_FILE);
+            const sourceSchemaText = readFileSync(schemaPath, "utf8");
             // Phase 1: back up the existing yui.db, then promote the sidecar.
             try {
                 if (existsSync(committedDbPath)) {
@@ -167,13 +169,20 @@ export function createSqliteRecordMigrationTarget(options) {
             // critical section. The layout version is unchanged.
             try {
                 if (stagedSchemaManifest !== null) {
-                    writeTextFileAtomically(join(home, STORAGE_SCHEMA_FILE), `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
+                    writeTextFileAtomically(schemaPath, `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
                 }
             }
             catch (error) {
-                // The database is promoted but schema.json could not be advanced.
-                // Attempt to restore the original database; if that fails, the Home
-                // is ambiguous and must be recovered manually.
+                // A durable writer can report an fsync failure after its atomic rename,
+                // so "write threw" does not prove schema.json stayed old. Restore both
+                // the exact source sidecar and database before claiming no switch.
+                let rollbackError;
+                try {
+                    writeTextFileAtomically(schemaPath, sourceSchemaText);
+                }
+                catch (restoreError) {
+                    rollbackError = restoreError;
+                }
                 try {
                     if (backupPath !== undefined && existsSync(backupPath)) {
                         removeSqliteFileSet(committedDbPath);
@@ -183,15 +192,18 @@ export function createSqliteRecordMigrationTarget(options) {
                         removeSqliteFileSet(committedDbPath);
                     }
                 }
-                catch {
+                catch (restoreError) {
+                    rollbackError ??= restoreError;
+                }
+                if (rollbackError !== undefined) {
                     writeInterruptedMarker(home, backupPath ?? committedDbPath, stagedDbPath, now);
                     throw new AmbiguousSwitchError({
                         homePath: home,
                         backupPath: backupPath ?? committedDbPath,
                         stagingPath: stagedDbPath,
-                        detail: `SQLite database was promoted but schema.json could not be advanced (${messageOf(error)}), ` +
-                            `and the automatic rollback also failed. The database is at ${committedDbPath}; ` +
-                            `recover by advancing schema.json recordVersions or restoring the backup.`
+                        detail: `SQLite database was promoted but schema.json could not be durably advanced (${messageOf(error)}), ` +
+                            `and the database/schema rollback also failed (${messageOf(rollbackError)}). ` +
+                            `Inspect ${committedDbPath}, ${schemaPath}, and the backup before recovery.`
                     });
                 }
                 throw error;
@@ -214,7 +226,7 @@ export function createSqliteRecordMigrationTarget(options) {
     function readSourceFresh() {
         const manifestRaw = readFileSync(join(home, STORAGE_SCHEMA_FILE), "utf8");
         const schemaManifest = parseJsonObject(manifestRaw, STORAGE_SCHEMA_FILE);
-        const state = readStateFromSqlite(home);
+        const state = readMigrationSourceStateFromSqlite(home);
         return Object.freeze({ schemaManifest, state });
     }
     /**

package/dist/storage/upgrade/sqliteStateMigration.js

@@ -22,6 +22,7 @@
  * dropped, duplicated, or mutated record.
  */
 import { createHash } from "node:crypto";
+import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import Database from "better-sqlite3";
 import { mailboxTargetKey } from "../../coordination/workMailbox.js";
@@ -33,6 +34,50 @@ import { CURRENT_STORED_TASK_SCHEMA_VERSION } from "../taskStore.js";
 export const STAGED_DATABASE_FILENAME = "yui.db.staged";
 /** The committed database filename. */
 export const COMMITTED_DATABASE_FILENAME = "yui.db";
+/** Disposable, schema-current snapshot used to reconstruct an older source. */
+export const MIGRATION_SOURCE_DATABASE_FILENAME = "yui.db.migration-source";
+/**
+ * Reconstruct a migration snapshot without advancing the authoritative DB.
+ *
+ * `VACUUM INTO` takes a consistent SQLite snapshot, including committed WAL
+ * state, without writing the source. Pending physical migrations are then
+ * applied only to that disposable copy before the current reader enumerates
+ * record families that may not exist in the older source schema.
+ */
+export function readMigrationSourceStateFromSqlite(home) {
+    const sourcePath = join(home, COMMITTED_DATABASE_FILENAME);
+    const snapshotPath = join(home, MIGRATION_SOURCE_DATABASE_FILENAME);
+    if (existsSync(snapshotPath)) {
+        throw new Error(`Refusing to overwrite an existing SQLite migration-source snapshot: ${snapshotPath}. `
+            + "Discard it and retry.");
+    }
+    try {
+        const source = new Database(sourcePath, { readonly: true });
+        try {
+            source.prepare("VACUUM INTO ?").run(snapshotPath);
+        }
+        finally {
+            source.close();
+        }
+        // Physical migration 14 rewrites the WorkMailbox family while adding its
+        // current columns. Preserve the source rows before applying it so the
+        // logical record migration still sees and transforms v1 exactly once.
+        const sourceMailboxes = readWorkMailboxesFromSqlite(snapshotPath);
+        const stagedStore = new SqliteTaskStore(home, {
+            databaseFilename: MIGRATION_SOURCE_DATABASE_FILENAME,
+            migration: true
+        });
+        stagedStore.close();
+        const state = readStateFromSqlite(home, MIGRATION_SOURCE_DATABASE_FILENAME);
+        state.mailboxes = sourceMailboxes;
+        return state;
+    }
+    finally {
+        rmSync(snapshotPath, { force: true });
+        rmSync(`${snapshotPath}-wal`, { force: true });
+        rmSync(`${snapshotPath}-shm`, { force: true });
+    }
+}
 /**
  * Preserve SQLite-owned durable state that intentionally sits outside the
  * state.json-shaped Task aggregate snapshot. Volatile coordination locks and
@@ -351,9 +396,6 @@ export function populateSqliteFromState(home, state, databaseFilename) {
                 if (stored.leaderFailure !== null) {
                     store.saveLeaderFailure(stored.leaderFailure);
                 }
-                if (stored.operatorNotification !== null) {
-                    store.saveOperatorNotification(stored.operatorNotification);
-                }
                 // Per-task ID high-water marks.
                 for (const [kind, highWater] of Object.entries(stored.idHighWaterMarks)) {
                     if (typeof highWater === "number" && Number.isFinite(highWater)) {
@@ -595,6 +637,20 @@ function readWorkMailboxRows(db) {
     const hasInputDelivery = db.prepare("PRAGMA table_info(mailboxes)").all().some(({ name }) => name === "input_delivery");
     return db.prepare(`SELECT target_kind, task_id, role_name, next_sequence, processing, pending${hasInputDelivery ? ", input_delivery" : ""} FROM mailboxes ORDER BY target_key`).all();
 }
+function readWorkMailboxesFromSqlite(dbPath) {
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const mailboxes = {};
+        for (const row of readWorkMailboxRows(db)) {
+            const mailbox = rowToMailbox(row);
+            mailboxes[mailboxTargetKey(mailbox.target)] = mailbox;
+        }
+        return mailboxes;
+    }
+    finally {
+        db.close();
+    }
+}
 /**
  * Compute per-family checksums from the SQLite database. The database is
  * opened read-only; this is the independent verification read.
@@ -692,8 +748,8 @@ export function verifySqliteChecksums(state, home, databaseFilename) {
  *
  * The database is opened read-only; this function never writes.
  */
-export function readStateFromSqlite(home) {
-    const dbPath = join(home, COMMITTED_DATABASE_FILENAME);
+export function readStateFromSqlite(home, databaseFilename = COMMITTED_DATABASE_FILENAME) {
+    const dbPath = join(home, databaseFilename);
     const db = new Database(dbPath, { readonly: true });
     try {
         const manifest = readStorageSchemaManifest(home);
@@ -737,7 +793,7 @@ export function readStateFromSqlite(home) {
         const tasks = state.tasks;
         const taskRows = db.prepare("SELECT task_id, payload, brief FROM task_records").all();
         for (const row of taskRows) {
-            tasks[row.task_id] = {
+            const aggregate = {
                 schemaVersion: storedTaskVersion,
                 task: JSON.parse(row.payload),
                 brief: row.brief === null ? null : JSON.parse(row.brief),
@@ -761,12 +817,14 @@ export function readStateFromSqlite(home) {
                 events: {},
                 wakes: {},
                 leaderFailure: null,
-                operatorNotification: null,
                 idHighWaterMarks: {},
                 capabilityGrants: {},
                 releaseWorkflows: {},
                 publicationReferences: {}
             };
+            if (storedTaskVersion <= 17)
+                aggregate.operatorNotification = null;
+            tasks[row.task_id] = aggregate;
         }
         // Per-task record families, keyed by their state.json map keys.
         loadTaskPayloadMap(db, "task_roles", tasks, "roles", (record) => record.name);
@@ -808,7 +866,7 @@ export function readStateFromSqlite(home) {
             if (row.kind === "leader-failure") {
                 stored.leaderFailure = JSON.parse(row.payload);
             }
-            else {
+            else if (storedTaskVersion <= 17) {
                 stored.operatorNotification = JSON.parse(row.payload);
             }
         }

package/dist/task/completionReadiness.js

@@ -4,6 +4,7 @@ import { deltaRecheckBlocksAcceptance } from "../review/reviewRound.js";
 import { isSemanticReviewRound } from "../review/reviewOutcomeClassifier.js";
 import { reviewFindingLedgerWriteFailedFromEvents } from "../review/reviewFindingLedger.js";
 import { resolveRecordedTaskFinalReviewContract } from "../review/taskFinalReviewContractRebind.js";
+import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
 import { blockingProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 const ACTIVE_JOB_STATUSES = new Set([
     "queued",
@@ -22,7 +23,8 @@ export function projectCompletionReadiness(facts, options = {}) {
     const advisories = [];
     const { task } = facts;
     const findingsGate = options.findingsGate ?? true;
-    const taskFinalReviewRequired = resolveRecordedTaskFinalReviewContract(task.id, facts.workItems, facts.reviewRounds, facts.taskFinalReviewContractEvents) !== undefined;
+    const taskFinalReviewContract = resolveRecordedTaskFinalReviewContract(task.id, facts.workItems, facts.reviewRounds, facts.taskFinalReviewContractEvents)?.effective;
+    const taskFinalReviewRequired = taskFinalReviewContract !== undefined;
     // A pending/running Task-final Review must be resumed or blocked first.
     for (const round of facts.reviewRounds) {
         if ((round.scope ?? "work-item") !== "task")
@@ -43,11 +45,13 @@ export function projectCompletionReadiness(facts, options = {}) {
     // escalations remain audit evidence, but a later completed full Review (or
     // accepted delta) supersedes them instead of blocking completion forever.
     const latestCompletedTaskReview = facts.reviewRounds
-        .filter((round) => ((round.scope ?? "work-item") === "task" && isSemanticReviewRound(round, {
-        listAgentRuns: () => facts.agentRuns,
-        listReviewFindings: () => facts.reviewFindings,
-        listEvents: () => facts.events
-    })))
+        .filter((round) => ((round.scope ?? "work-item") === "task"
+        && (taskFinalReviewContract === undefined || sameTaskFinalReviewContract(round.taskFinalReviewContract, taskFinalReviewContract))
+        && isSemanticReviewRound(round, {
+            listAgentRuns: () => facts.agentRuns,
+            listReviewFindings: () => facts.reviewFindings,
+            listEvents: () => facts.events
+        })))
         .slice()
         .sort((left, right) => (left.createdAt.localeCompare(right.createdAt)
         || left.id.localeCompare(right.id, undefined, { numeric: true })))