@zq-silk/yui 0.11.3 → 0.12.1

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;
 /**
@@ -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
@@ -1730,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);
@@ -2014,8 +2007,7 @@ function emptyStoredTask(task) {
         capabilityGrants: {},
         releaseWorkflows: {},
         publicationReferences: {},
-        leaderFailure: null,
-        operatorNotification: null
+        leaderFailure: null
     };
 }
 function emptyTaskIdHighWaterMarks() {
@@ -2233,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);
@@ -2434,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/homeClassification.js

@@ -30,6 +30,7 @@ import { classifyStorage } from "../migration/index.js";
 import { inspectStorageSchema } from "../storageSchema.js";
 import { FileTaskStore, STORAGE_STATE_FILE, StorageRecordError } from "../taskStore.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
+import { inspectSqliteSchemaMigrations } from "../sqliteSchema.js";
 import { inspectSourceVersionState } from "./homeMigrationTarget.js";
 import { readMigrationReceipt } from "./migrationReceipt.js";
 /**
@@ -111,6 +112,44 @@ export function classifyHome(options) {
             };
         }
     }
+    // Once the logical Home axes are current, the SQLite ledger is the only
+    // remaining upgrade coordinate. A valid applied prefix with pending entries
+    // is upgradeable in place, not corruption and not a reason to rebuild the
+    // database. Ordinary store opens still validate-and-refuse this state; only
+    // the explicit updater is allowed to apply it.
+    if (schema.status === "current"
+        && schema.currentLayoutVersion >= 7
+        && isFullyCurrent(source, latest)) {
+        let sqliteMigration;
+        try {
+            sqliteMigration = inspectLayout7SqliteMigrations(home);
+        }
+        catch (error) {
+            return {
+                ...base,
+                classification: {
+                    verdict: "CORRUPTED",
+                    status: "unsupported",
+                    detail: error instanceof Error ? error.message : String(error)
+                },
+                layoutVersion: schema.currentLayoutVersion,
+                aggregateVersion: schema.currentAggregateSchemaVersion
+            };
+        }
+        if (sqliteMigration.pendingVersions.length > 0) {
+            return {
+                ...base,
+                classification: {
+                    verdict: "MIGRATABLE",
+                    status: "migration-required",
+                    stepCount: sqliteMigration.pendingVersions.length
+                },
+                layoutVersion: schema.currentLayoutVersion,
+                aggregateVersion: schema.currentAggregateSchemaVersion,
+                sqliteMigration
+            };
+        }
+    }
     // The reference graph can only be validated by the strict loader, which only
     // understands the current versions. So run it exactly when every axis is
     // already current (the plan would be a no-op); a throw there is genuine
@@ -136,6 +175,19 @@ export function classifyHome(options) {
             : { incompatibleComponent: incompatibleComponentOf(schema) })
     };
 }
+function inspectLayout7SqliteMigrations(home) {
+    const db = new Database(join(home, "yui.db"), {
+        readonly: true,
+        fileMustExist: true
+    });
+    try {
+        db.pragma("query_only = ON");
+        return inspectSqliteSchemaMigrations(db);
+    }
+    finally {
+        db.close();
+    }
+}
 /**
  * Load a Home whose every axis is already current through the strict store
  * gate to detect real structural/reference corruption. This is only ever

package/dist/storage/upgrade/offlineUpgradeInventory.js

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import Database from "better-sqlite3";
 import { scanControllerResourceInventory } from "../../controller/resourceInventoryLinux.js";
 import { STORAGE_STATE_FILE } from "../taskStore.js";
+import { SQLITE_LAYOUT_VERSION } from "../sqliteSchema.js";
+import { inspectStorageSchema } from "../storageSchema.js";
 /** Pure blocker policy shared by synthetic tests and the real read-only scan. */
 export function classifyOfflineUpgradeFacts(facts) {
     const blockers = [];
@@ -45,14 +48,13 @@ export async function inspectOfflineUpgradeInventory(home, environment = process
     const raw = readRawFacts(home, inventory);
     return classifyOfflineUpgradeFacts(raw);
 }
-function readRawFacts(home, inventory) {
+function readRawFacts(home, inventory, state = readDurableStateObject(home), conservativeDurableSessions = false) {
     const runs = [];
     const sessions = [];
     const inFlight = [];
     const pendingCompletions = [];
     const lifecycle = [];
     const unknownRuntime = [];
-    const state = readStateObject(home);
     // Failure to enumerate processes, panes, or sockets means absence cannot be
     // proven. Ownership-load warnings are expected for an old record shape and
     // are handled by the raw durable scan plus unowned live-pane check below.
@@ -61,6 +63,8 @@ function readRawFacts(home, inventory) {
     }
     for (const [taskId, aggregateValue] of Object.entries(record(state.tasks))) {
         const aggregate = record(aggregateValue);
+        if (text(record(aggregate.task).status) === "retired")
+            continue;
         for (const runValue of Object.values(record(aggregate.agentRuns))) {
             const run = record(runValue);
             const roleName = text(run.roleName);
@@ -75,6 +79,7 @@ function readRawFacts(home, inventory) {
                 roleName,
                 set: record(setValue),
                 inventory,
+                conservativeDurableSessions,
                 sessions,
                 inFlight,
                 pendingCompletions
@@ -86,6 +91,7 @@ function readRawFacts(home, inventory) {
             roleName,
             set: record(setValue),
             inventory,
+            conservativeDurableSessions,
             sessions,
             inFlight,
             pendingCompletions
@@ -97,7 +103,7 @@ function readRawFacts(home, inventory) {
         const kind = text(target.kind);
         if (kind !== "role-runtime" && kind !== "global-role-runtime")
             continue;
-        if (mailbox.pending === null && mailbox.processing === null)
+        if (!mailboxHasRuntimeWork(mailbox))
             continue;
         lifecycle.push({
             ...(text(target.taskId) === undefined ? {} : { taskId: text(target.taskId) }),
@@ -170,7 +176,7 @@ function isUndeterminableNativeInventoryWarning(warning) {
         || warning.startsWith("Cannot inspect Unix sockets");
 }
 function collectSessionSet(options) {
-    const { taskId, roleName, set, inventory } = options;
+    const { taskId, roleName, set, inventory, conservativeDurableSessions } = options;
     const currentSessions = Object.entries(record(set.sessions));
     const activeAgentId = text(set.activeAgentId);
     const historyValue = set.history;
@@ -199,7 +205,7 @@ function collectSessionSet(options) {
         };
         options.sessions.push({
             ...base,
-            processState: processState(inventory, base)
+            processState: processState(inventory, base, conservativeDurableSessions)
         });
     }
     const flight = record(set.inFlight);
@@ -245,12 +251,22 @@ function activeCurrentSession(sessions, taskId, roleName) {
     return current.find(({ active }) => active === true)
         ?? (current.length === 1 ? current[0] : undefined);
 }
-function processState(inventory, session) {
+function processState(inventory, session, conservativeDurableSessions) {
     const matching = inventory.resources.filter((resource) => (resource.kind === "agent-session" && resourceMatchesSession(resource, session)));
     if (matching.some((resource) => resource.processes.length > 0))
         return "live";
     if (matching.some((resource) => resource.paneDead === false))
         return "unknown";
+    // The final SQLite gate runs after BEGIN IMMEDIATE, so no older writer can
+    // commit another Session record behind it. Treat every current non-terminal
+    // durable Session as active even when the earlier native-process snapshot
+    // did not contain it; this closes the inventory-scan -> transaction race.
+    if (conservativeDurableSessions
+        && !session.history
+        && session.status !== "stopped"
+        && session.status !== "broken") {
+        return "unknown";
+    }
     return "stopped";
 }
 function resourceMatchesSession(resource, session) {
@@ -272,13 +288,135 @@ function resourceMatchesSession(resource, session) {
         return false;
     return true;
 }
-function readStateObject(home) {
+function readDurableStateObject(home) {
+    const databasePath = join(home, "yui.db");
+    const schema = inspectStorageSchema(home);
+    const sqliteIsAuthoritative = (schema.status === "current" || schema.status === "unsupported")
+        && schema.currentLayoutVersion >= SQLITE_LAYOUT_VERSION;
+    if (sqliteIsAuthoritative && existsSync(databasePath)) {
+        return readSqliteStateObject(databasePath);
+    }
     const path = join(home, STORAGE_STATE_FILE);
     if (!existsSync(path))
         return {};
     const parsed = JSON.parse(readFileSync(path, "utf8"));
     return record(parsed);
 }
+/**
+ * Read only the durable runtime families needed by the offline gate. This raw
+ * adapter deliberately does not open SqliteTaskStore: a valid pending schema
+ * prefix is exactly the state the explicit upgrader must be able to inspect.
+ */
+function readSqliteStateObject(databasePath) {
+    const db = new Database(databasePath, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma("query_only = ON");
+        return readSqliteStateObjectFromDatabase(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Re-check the authoritative SQLite runtime families on an already-open
+ * connection. The in-place upgrader calls this inside its write transaction,
+ * after every older writer has either committed or rolled back.
+ */
+export function inspectSqliteDurableUpgradeInventory(home, db) {
+    return classifyOfflineUpgradeFacts(readRawFacts(home, { resources: [], warnings: [] }, readSqliteStateObjectFromDatabase(db), true));
+}
+function readSqliteStateObjectFromDatabase(db) {
+    const taskRows = db.prepare("SELECT task_id, status FROM tasks_catalog").all();
+    // Explicit retirement is the only isolation boundary for anomalous
+    // historical runtime state. Completed/archived/draft Tasks still fail
+    // closed if they retain an active Run or unfinished lifecycle record.
+    const retiredTaskIds = new Set(taskRows.filter(({ status }) => status === "retired").map(({ task_id }) => task_id));
+    const tasks = Object.fromEntries(taskRows
+        .filter(({ task_id }) => !retiredTaskIds.has(task_id))
+        .map(({ task_id, status }) => [task_id, {
+            task: { status },
+            agentRuns: {},
+            roleSessionSets: {}
+        }]));
+    const taskAggregate = (taskId) => {
+        const existing = tasks[taskId];
+        if (existing !== undefined)
+            return existing;
+        const created = { task: {}, agentRuns: {}, roleSessionSets: {} };
+        tasks[taskId] = created;
+        return created;
+    };
+    for (const row of db.prepare("SELECT task_id, run_id, role_name, status, payload FROM agent_runs").all()) {
+        if (retiredTaskIds.has(row.task_id))
+            continue;
+        const aggregate = taskAggregate(row.task_id);
+        record(aggregate.agentRuns)[row.run_id] = {
+            ...parseJsonRecord(row.payload, "agent_runs.payload"),
+            id: row.run_id,
+            roleName: row.role_name,
+            status: row.status
+        };
+    }
+    for (const row of db.prepare("SELECT task_id, role_name, payload FROM role_session_sets").all()) {
+        if (retiredTaskIds.has(row.task_id))
+            continue;
+        const aggregate = taskAggregate(row.task_id);
+        record(aggregate.roleSessionSets)[row.role_name] = parseJsonRecord(row.payload, "role_session_sets.payload");
+    }
+    const globalRoleSessionSets = {};
+    for (const row of db.prepare("SELECT name, payload FROM global_role_session_sets").all()) {
+        globalRoleSessionSets[row.name] = parseJsonRecord(row.payload, "global_role_session_sets.payload");
+    }
+    const mailboxColumns = new Set(db.pragma("table_info(mailboxes)").map(({ name }) => name));
+    const hasInputDelivery = mailboxColumns.has("input_delivery");
+    const mailboxes = {};
+    for (const row of db.prepare(`SELECT target_key, target_kind, task_id, role_name, processing, pending${hasInputDelivery ? ", input_delivery" : ""} FROM mailboxes`).all()) {
+        if (row.task_id !== null && retiredTaskIds.has(row.task_id))
+            continue;
+        mailboxes[row.target_key] = {
+            target: {
+                kind: row.target_kind,
+                ...(row.task_id === null ? {} : { taskId: row.task_id }),
+                ...(row.role_name === null ? {} : { roleName: row.role_name })
+            },
+            processing: parseNullableJson(row.processing, "mailboxes.processing"),
+            pending: parseNullableJson(row.pending, "mailboxes.pending"),
+            inputDelivery: parseNullableJson(row.input_delivery ?? null, "mailboxes.input_delivery")
+        };
+    }
+    return { tasks, globalRoleSessionSets, mailboxes };
+}
+function mailboxHasRuntimeWork(mailbox) {
+    if (mailbox.processing !== null && mailbox.processing !== undefined)
+        return true;
+    if (mailbox.inputDelivery !== null && mailbox.inputDelivery !== undefined)
+        return true;
+    if (mailbox.pending === null || mailbox.pending === undefined)
+        return false;
+    const pending = record(mailbox.pending);
+    if (Object.hasOwn(pending, "normal") || Object.hasOwn(pending, "userCorrection")) {
+        return pending.normal !== null || pending.userCorrection !== null;
+    }
+    // Pre-v14 mailboxes store one pending batch directly.
+    return Object.keys(pending).length > 0;
+}
+function parseJsonRecord(raw, label) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${label} is not a JSON object.`);
+    }
+    return parsed;
+}
+function parseNullableJson(raw, label) {
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON.`, { cause: error });
+    }
+}
 function countPendingInbox(home) {
     return [join(home, "runtime", "inbox"), join(home, "runtime", "inbox-invalid")]
         .reduce((total, directory) => total + countDirectory(directory), 0);

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 });
     }
     /**