@zq-silk/yui 0.14.2 → 0.15.0

package/dist/cli/upgradeCommand.js

@@ -1,23 +1,24 @@
-/** `yui upgrade` validates the exact storage contract supported by this release. */
-import { latestStorageVersionState } from "../storage/upgrade/recordVersions.js";
+/** `yui upgrade` plans or applies the supported linear storage migration chain. */
 import { runStorageUpgrade } from "../storage/upgrade/upgradeOrchestrator.js";
-import { usageError } from "../errors/cliError.js";
+import { ensureFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
+import { runtimeError, usageError } from "../errors/cliError.js";
+import { acquireHandoverLock, isForeignHandoverLockHeld, isHandoverLockHeld } from "../release/runtimeRelease.js";
 /**
  * Run the upgrade command. Parses the public `[--dry-run]` form plus the staged
  * updater's internal `--update-preflight` form, then returns rendered text,
  * structured data, and an exit code (0 for a safe result, 5 for a blocker).
  */
-export async function runUpgradeCommand(args, home) {
+export async function runUpgradeCommand(args, home, environment = process.env) {
     const mode = parseUpgradeArgs(args);
-    const result = await runStorageUpgrade({
-        home,
-        latest: latestStorageVersionState(),
-        mode
-    });
+    const result = mode === "execute"
+        ? await runInteractiveUpgrade(home, environment)
+        : mode === "update-apply"
+            ? await runUpdateOwnedUpgrade(home, environment)
+            : await runStorageUpgrade({ home, mode });
     return {
         output: renderUpgradeResult(result, mode),
         data: result,
-        exitCode: result.outcome === "blocked" ? 5 : 0
+        exitCode: result.outcome === "blocked" || result.outcome === "failed" ? 5 : 0
     };
 }
 function parseUpgradeArgs(args) {
@@ -26,37 +27,121 @@ function parseUpgradeArgs(args) {
     if (args.length === 1 && args[0] === "--dry-run")
         return "dry-run";
     // Intentionally omitted from public command help: this is the machine contract
-    // used by a staged `yui update`, not a replacement for user-facing dry-turn.
+    // used by a staged `yui update`, not a replacement for user-facing dry-run.
     if (args.length === 1 && args[0] === "--update-preflight")
         return "update-preflight";
+    if (args.length === 1 && args[0] === "--update-apply")
+        return "update-apply";
     throw usageError("Upgrade usage: yui upgrade [--dry-run]");
 }
+async function runInteractiveUpgrade(home, environment) {
+    const preflight = await runStorageUpgrade({ home, mode: "update-preflight" });
+    if (preflight.outcome !== "update-preflight"
+        || preflight.status === "already-current") {
+        return runStorageUpgrade({ home, mode: "execute" });
+    }
+    const handover = acquireHandoverLock(home);
+    let controllerWasRunning = false;
+    try {
+        const stopped = await stopFileTaskController(home, {
+            environment,
+            handoverOwnerPid: process.pid
+        });
+        controllerWasRunning = stopped.stopped;
+        const result = await runStorageUpgrade({ home, mode: "execute" });
+        if (controllerWasRunning
+            && (result.outcome === "upgraded" || result.outcome === "already-current")) {
+            try {
+                await ensureFileTaskController(home, {
+                    environment,
+                    handoverOwnerPid: process.pid
+                });
+            }
+            catch (error) {
+                throw runtimeError(`Storage reached version ${result.report.targetVersion}, but the current `
+                    + `Controller could not restart: ${messageOf(error)} Backup: `
+                    + `${result.report.backupPath ?? "none"}. Keep the Home quiesced, inspect `
+                    + "Controller ownership, and start only the current Yui Controller.");
+            }
+        }
+        return result;
+    }
+    finally {
+        handover.release();
+    }
+}
+async function runUpdateOwnedUpgrade(home, environment) {
+    const ownerText = environment.YUI_UPDATE_HANDOVER_OWNER_PID;
+    const ownerPid = ownerText === undefined ? Number.NaN : Number(ownerText);
+    if (!Number.isSafeInteger(ownerPid)
+        || ownerPid < 1
+        || process.ppid !== ownerPid
+        || !isHandoverLockHeld(home)
+        || isForeignHandoverLockHeld(home, ownerPid)) {
+        throw runtimeError("The internal update migration requires its direct parent to own the live "
+            + "Controller handover lock.");
+    }
+    return runStorageUpgrade({ home, mode: "execute" });
+}
 /** Render an {@link UpgradeResult} as concise, CLI-style text. */
 export function renderUpgradeResult(result, mode) {
     const header = versionHeader(result);
     switch (result.outcome) {
         case "already-current":
             return `${header}\nStorage is already at the current version; nothing to upgrade.`;
+        case "upgrade-plan":
+            return [
+                header,
+                `Upgrade plan: ${renderSteps(result.report.steps)}. Storage was not modified.`
+            ].join("\n");
+        case "upgraded":
+            return [
+                header,
+                `Storage upgraded through ${renderSteps(result.report.steps)}.`,
+                `Backup: ${result.report.backupPath ?? "none"}`
+            ].join("\n");
         case "update-preflight":
             return `${header}\nUpdate preflight: ${result.status} (${result.stepCount} steps). Storage was not modified.`;
         case "blocked": {
             return [
                 header,
-                `${mode === "dry-run" ? "Dry run" : mode === "update-preflight" ? "Update preflight" : "Upgrade"} blocked at ${result.stage}: ${result.message}`,
+                `${mode === "dry-run"
+                    ? "Dry run"
+                    : mode === "update-preflight"
+                        ? "Update preflight"
+                        : "Upgrade"} blocked at ${result.stage}: ${result.message}`,
                 `Action: ${result.action}`,
                 "The authoritative Home is unchanged."
             ].join("\n");
         }
+        case "failed":
+            return [
+                header,
+                `Upgrade failed at ${result.stage}: ${result.message}`,
+                `Action: ${result.action}`,
+                `Backup: ${result.backupPath ?? "none"}`,
+                result.sceneUnchanged
+                    ? "The authoritative Home was restored."
+                    : "The authoritative Home may have changed; keep it quiesced."
+            ].join("\n");
     }
 }
 function versionHeader(result) {
     const classification = result.classification;
-    const layout = classification.layoutVersion ?? classification.latestLayoutVersion;
-    const aggregate = classification.aggregateVersion ?? classification.latestAggregateVersion;
+    const storage = classification.storageVersion === undefined
+        ? "unknown"
+        : String(classification.storageVersion);
     const verdict = classification.classification.verdict;
-    const incompatible = classification.incompatibleComponent === undefined
-        ? ""
-        : ` incompatibleComponent=${classification.incompatibleComponent}`;
-    return `Storage: ${verdict} layout=${layout}/${classification.latestLayoutVersion} `
-        + `aggregate=${aggregate}/${classification.latestAggregateVersion}${incompatible}`;
+    return `Storage: ${verdict} version=${storage}/${classification.currentStorageVersion} `
+        + `minimum=${classification.minimumSupportedStorageVersion}`;
+}
+function renderSteps(steps) {
+    if (steps.length === 0)
+        return "no migrations";
+    return steps
+        .map(({ fromVersion, toVersion, name }) => `${fromVersion}->${toVersion} ${name}`)
+        .join(", ");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
 }

package/dist/commands/controllerCommands.js

@@ -201,7 +201,7 @@ export function renderRuntimeIdentitySection(input) {
         `  Entry digest    ${build.entryDigest}`,
         `  Source commit   ${build.sourceCommit}`,
         `  Node            ${build.nodeVersion} (${build.platform})`,
-        `  Storage         layout ${storage.logicalLayout} (manifest ${storage.manifestStatus}) · backend ${storage.configuredBackend} · worker ${storage.workerEnabled ? "on" : "off"}`,
+        `  Storage         version ${storage.storageVersion} (status ${storage.storageStatus}, minimum ${storage.minimumStorageVersion}) · backend ${storage.configuredBackend} · worker ${storage.workerEnabled ? "on" : "off"}`,
         `  Store files     state.json ${storage.physicalStateJson.present ? "present" : "absent"} · yui.db ${storage.physicalDatabase.present ? "present" : "absent"}${storage.physicalDatabase.wal ? " +WAL" : ""}${storage.physicalDatabase.present && storage.physicalDatabase.health !== UNSUPPORTED ? ` (${storage.physicalDatabase.health})` : ""}`
     ];
     for (const finding of storage.findings) {

package/dist/core/controllerServer.js

@@ -400,8 +400,8 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
                 homeFilesystemId,
                 controllerInstanceId,
                 version: YUI_VERSION,
-                storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-                aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+                storageVersion: yuiVersionIdentity().storageVersion,
+                minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
                 ...(status === undefined ? {} : { runtime: status(telemetry) })
             }
         });
@@ -675,7 +675,7 @@ export function buildRuntimeIdentityReceipt(input) {
         }
     })();
     return Object.freeze({
-        schemaVersion: 1,
+        schemaVersion: 2,
         version: YUI_VERSION,
         executablePath: process.execPath,
         args: process.argv.slice(1),
@@ -685,8 +685,8 @@ export function buildRuntimeIdentityReceipt(input) {
         cliRealpath: controllerCliRealpath(),
         controllerRealpath: realpathSync(fileURLToPath(import.meta.url)),
         controllerProtocolVersion: FILE_TASK_CONTROLLER_PROTOCOL_VERSION,
-        storageLayoutVersion: yuiVersionIdentity().storageLayoutVersion,
-        aggregateSchemaVersion: yuiVersionIdentity().aggregateSchemaVersion,
+        storageVersion: yuiVersionIdentity().storageVersion,
+        minimumStorageVersion: yuiVersionIdentity().minimumStorageVersion,
         storageBackend: input.storageBackend,
         workerEnabled: input.workerEnabled,
         pid: process.pid,

package/dist/doctor/doctor.js

@@ -34,7 +34,7 @@ export const STORAGE_DOCTOR_CHECK_NAMES = Object.freeze([
  * healthy only when schema, compatibility, and state are all `ok`. Any
  * `unsupported` (version mismatch / needs-new-version), `invalid` (corrupted /
  * unreadable), or `missing` (uninitialized) storage check is blocking — even
- * though `yui doctor` itself exits 0.
+ * and the machine-readable command exits non-zero.
  */
 export function summarizeStorageHealth(checks) {
     const names = new Set(STORAGE_DOCTOR_CHECK_NAMES);
@@ -56,14 +56,16 @@ export function buildDoctorReport(env, executor) {
 }
 /**
  * Read the physical-backend facts for a Home (Issue 01 observability). Every
- * field is best-effort read-only evidence: an unreadable database or manifest
- * yields `null` for that field, and the `storage state` check reports the
- * structural problem separately.
+ * field is best-effort read-only evidence: an unreadable database yields
+ * `null` for that field, and the `storage state` check reports the structural
+ * problem separately.
  */
 function inspectStorageDetails(home, env) {
     const schema = inspectStorageSchema(home);
-    const logicalLayout = schema.status === "current" || schema.status === "unsupported"
-        ? schema.currentLayoutVersion
+    const storageVersion = schema.status === "current"
+        || schema.status === "upgradeable"
+        || schema.status === "unsupported"
+        ? schema.currentVersion
         : null;
     const authoritativeBackend = "sqlite";
     const dbPath = join(home, CURRENT_DATABASE_FILENAME);
@@ -88,7 +90,8 @@ function inspectStorageDetails(home, env) {
         }
     }
     return {
-        logicalLayout,
+        storageVersion,
+        minimumSupportedVersion: schema.minimumSupportedVersion,
         authoritativeBackend,
         databasePath,
         journalMode,
@@ -216,13 +219,22 @@ function checkSchema(state) {
             return {
                 name: "storage schema",
                 status: "ok",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion}`
+            };
+        case "upgradeable":
+            return {
+                name: "storage schema",
+                status: "unsupported",
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} migration=available`
             };
         case "unsupported":
             return {
                 name: "storage schema",
                 status: "unsupported",
-                detail: `current=${state.currentVersion} latest=${state.latestVersion} direction=${state.direction}`
+                detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                    + `minimum=${state.minimumSupportedVersion} direction=${state.direction}`
             };
         case "invalid":
             return { name: "storage schema", status: "invalid", detail: state.detail };
@@ -251,9 +263,20 @@ function inspectCompatibility(home, homeCheck, schema) {
             check: {
                 name,
                 status: "unsupported",
-                detail: `unsupported contract: ${schema.incompatibleComponent} is ${schema.direction} `
-                    + `(current=${schema.currentVersion}, required=${schema.latestVersion}). `
-                    + "Preserve this Home and initialize a new Home."
+                detail: `storage version is ${schema.direction} `
+                    + `(current=${schema.currentVersion}, supported=`
+                    + `${schema.minimumSupportedVersion}..${schema.latestVersion}).`
+            }
+        };
+    }
+    if (schema.status === "upgradeable") {
+        return {
+            storageStatus: "upgradeable",
+            check: {
+                name,
+                status: "unsupported",
+                detail: `migration available from ${schema.currentVersion} to ${schema.latestVersion}; `
+                    + "run `yui upgrade` or `yui update`."
             }
         };
     }
@@ -262,8 +285,8 @@ function inspectCompatibility(home, homeCheck, schema) {
         check: {
             name,
             status: "ok",
-            detail: `current layout=${schema.currentLayoutVersion}/${schema.latestLayoutVersion} `
-                + `aggregate=${schema.currentAggregateSchemaVersion}/${schema.latestAggregateSchemaVersion}`
+            detail: `current=${schema.currentVersion}/${schema.latestVersion} `
+                + `minimum=${schema.minimumSupportedVersion}`
         }
     };
 }

package/dist/observability/runtimeIdentity.js

@@ -13,7 +13,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 import Database from "better-sqlite3";
-import { CURRENT_AGGREGATE_SCHEMA_VERSION, CURRENT_STORAGE_LAYOUT_VERSION } from "../storage/storageVersions.js";
+import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../storage/storageVersions.js";
+import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 export const UNSUPPORTED = "unsupported";
 /**
@@ -140,14 +141,7 @@ export function collectRuntimeBuildIdentity(ports) {
 export function createProductionStorageIdentityPorts(env = process.env) {
     return {
         env,
-        readText: (path) => {
-            try {
-                return readFileSync(path, "utf8");
-            }
-            catch {
-                return null;
-            }
-        },
+        inspectStorage: (home) => inspectStorageSchema(home),
         fileSize: (path) => {
             try {
                 return statSync(path).size;
@@ -181,36 +175,12 @@ export function createProductionStorageIdentityPorts(env = process.env) {
  * are never treated as an alternate authority or a repair source.
  */
 export function collectStorageIdentity(home, ports = createProductionStorageIdentityPorts()) {
-    const manifestPath = join(home, "schema.json");
-    const manifestText = ports.readText(manifestPath);
-    let manifestStatus = "uninitialized";
-    let logicalLayout = UNSUPPORTED;
-    let aggregateSchemaVersion = UNSUPPORTED;
-    if (manifestText !== null) {
-        manifestStatus = "current";
-        try {
-            const manifest = JSON.parse(manifestText);
-            if (typeof manifest.storageVersion === "number"
-                && Number.isFinite(manifest.storageVersion)) {
-                logicalLayout = manifest.storageVersion;
-            }
-            if (typeof manifest.aggregateSchemaVersion === "number"
-                && Number.isFinite(manifest.aggregateSchemaVersion)) {
-                aggregateSchemaVersion = manifest.aggregateSchemaVersion;
-            }
-            if (typeof logicalLayout !== "number"
-                || typeof aggregateSchemaVersion !== "number"
-                || logicalLayout !== CURRENT_STORAGE_LAYOUT_VERSION
-                || aggregateSchemaVersion !== CURRENT_AGGREGATE_SCHEMA_VERSION) {
-                manifestStatus = "unsupported";
-            }
-        }
-        catch {
-            manifestStatus = "invalid";
-            logicalLayout = UNSUPPORTED;
-            aggregateSchemaVersion = UNSUPPORTED;
-        }
-    }
+    const storage = ports.inspectStorage(home);
+    const storageVersion = storage.status === "current"
+        || storage.status === "upgradeable"
+        || storage.status === "unsupported"
+        ? storage.currentVersion
+        : UNSUPPORTED;
     const statePath = join(home, "state.json");
     const statePresent = ports.exists(statePath);
     const stateBytes = ports.fileSize(statePath);
@@ -223,7 +193,7 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
     const workerEnabled = resolveStoreWorkerEnabledForHome(home, ports.env);
     const dbHealth = dbPresent ? ports.probeDatabaseHealth(dbPath) : null;
     const findings = [];
-    if (manifestStatus === "current" && !dbPresent) {
+    if (storage.status === "current" && !dbPresent) {
         findings.push({
             code: "current-database-missing",
             severity: "contradiction",
@@ -231,20 +201,48 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
             remediation: "Preserve this Home for diagnosis and initialize a new Home."
         });
     }
-    if (manifestStatus === "unsupported") {
+    if (storage.status === "uninitialized") {
+        findings.push({
+            code: "storage-uninitialized",
+            severity: "needs-repair",
+            message: "Yui storage has not been initialized for this Home.",
+            remediation: "Run `yui setup` for a new, empty Home."
+        });
+    }
+    if (storage.status === "upgradeable") {
+        findings.push({
+            code: "storage-upgrade-required",
+            severity: "needs-repair",
+            message: `Storage version ${storage.currentVersion} requires migration to `
+                + `${CURRENT_STORAGE_VERSION}.`,
+            remediation: "Run `yui upgrade` or `yui update` before resuming writes."
+        });
+    }
+    if (storage.status === "unsupported") {
         findings.push({
             code: "unsupported-storage-contract",
             severity: "contradiction",
-            message: "The Home does not match this release's exact storage contract.",
-            remediation: "Open it read-only with its original Yui version, then let the Operator recreate unfinished work in a new Home."
+            message: `Storage version ${storage.currentVersion} is outside the supported migration range `
+                + `${MIN_SUPPORTED_STORAGE_VERSION}..${CURRENT_STORAGE_VERSION}.`,
+            remediation: storage.direction === "newer"
+                ? "Use a newer Yui release."
+                : "Use a Yui release whose migration floor includes this Home."
         });
     }
-    if (manifestStatus === "invalid") {
+    if (storage.status === "invalid") {
         findings.push({
-            code: "invalid-storage-manifest",
+            code: "invalid-storage",
             severity: "contradiction",
-            message: "schema.json is invalid.",
-            remediation: "Preserve this Home for diagnosis and initialize a new Home."
+            message: storage.detail,
+            remediation: "Preserve this Home for diagnosis and restore a known-good backup."
+        });
+    }
+    if (ports.exists(join(home, "schema.json"))) {
+        findings.push({
+            code: "ignored-legacy-storage-manifest",
+            severity: "warning",
+            message: "schema.json is legacy metadata and is not a storage authority.",
+            remediation: "A successful storage upgrade removes it automatically."
         });
     }
     if (dbPresent && dbHealth !== null && dbHealth !== "ok") {
@@ -274,9 +272,9 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
     }
     return {
         home,
-        manifestStatus,
-        logicalLayout,
-        aggregateSchemaVersion,
+        storageStatus: storage.status,
+        storageVersion,
+        minimumStorageVersion: MIN_SUPPORTED_STORAGE_VERSION,
         configuredBackend,
         workerEnabled,
         physicalStateJson: {

package/dist/release/runtimeRelease.js

@@ -484,7 +484,7 @@ function validatePointer(value) {
 function validateRuntimeIdentity(value) {
     if (value === null
         || typeof value !== "object"
-        || value.schemaVersion !== 1
+        || value.schemaVersion !== 2
         || typeof value.version !== "string"
         || typeof value.executablePath !== "string"
         || value.executablePath === ""
@@ -492,6 +492,11 @@ function validateRuntimeIdentity(value) {
         || typeof value.buildId !== "string"
         || typeof value.cliRealpath !== "string"
         || typeof value.controllerRealpath !== "string"
+        || !isPositiveInteger(value.controllerProtocolVersion)
+        || !isPositiveInteger(value.storageVersion)
+        || !isPositiveInteger(value.minimumStorageVersion)
+        || value.minimumStorageVersion
+            > value.storageVersion
         || typeof value.pid !== "number"
         || typeof value.processStartIdentity !== "string"
         || (value.mode !== "primary"
@@ -520,6 +525,9 @@ function isHandoverPhase(value) {
 function isStringArray(value) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
 function isEexist(error) {
     return isNodeError(error) && error.code === "EEXIST";
 }

package/dist/runtime/exactControlPlane.js

@@ -73,7 +73,7 @@ export function extractExactControlArgument(args) {
 }
 /**
  * One read-only gate shared by every managed Task control command. It verifies
- * the frozen executable/CLI/Home/digest, protocol and scalar-storage identity,
+ * the frozen executable/CLI/Home/digest, protocol and storage identity,
  * on-disk schema, and any live Controller before command routing may construct
  * a writable store. Package version alone may advance at the same managed path
  * so an existing Session can cross an explicitly compatible in-place update.
@@ -92,15 +92,10 @@ export async function assertExactControlPlanePreflight(input, options = {}) {
     if (storage.status !== "current") {
         throw new Error(`Exact control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== descriptor.identity.storageLayoutVersion) {
-        throw new Error("Exact control-plane storage layout does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== descriptor.identity.aggregateSchemaVersion) {
-        throw new Error("Exact control-plane aggregate schema does not match its frozen descriptor "
-            + `(expected ${descriptor.identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== descriptor.identity.storageVersion) {
+        throw new Error("Exact control-plane storage version does not match its frozen descriptor "
+            + `(expected ${descriptor.identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     // A frozen descriptor authenticates the command that created it; it no
     // longer pins the Home's deployment pointer for the lifetime of a Session.
@@ -133,15 +128,10 @@ export async function assertCompatibleControlPlanePreflight(input, options = {})
     if (storage.status !== "current") {
         throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
     }
-    if (storage.currentLayoutVersion !== identity.storageLayoutVersion) {
-        throw new Error("Managed control-plane storage layout is incompatible "
-            + `(expected ${identity.storageLayoutVersion}, found `
-            + `${storage.currentLayoutVersion ?? "unknown"}).`);
-    }
-    if (storage.currentAggregateSchemaVersion !== identity.aggregateSchemaVersion) {
-        throw new Error("Managed control-plane aggregate schema is incompatible "
-            + `(expected ${identity.aggregateSchemaVersion}, found `
-            + `${storage.currentAggregateSchemaVersion ?? "unknown"}).`);
+    if (storage.currentVersion !== identity.storageVersion) {
+        throw new Error("Managed control-plane storage version is incompatible "
+            + `(expected ${identity.storageVersion}, found `
+            + `${storage.currentVersion ?? "unknown"}).`);
     }
     if (options.checkController !== false) {
         const call = options.callController ?? defaultCallController;
@@ -162,29 +152,31 @@ export function assertControllerStatusIdentity(status, expected = yuiVersionIden
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
     assertControllerField(status.version, expected.version, "version");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
+    assertControllerField(status.minimumStorageVersion, expected.minimumStorageVersion, "minimum storage migration version");
 }
 function validateVersionIdentity(value) {
     if (!isRecord(value))
         throw new Error("Yui version identity is invalid.");
     const version = requireText(value.version, "Yui version");
     const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
-    const storageLayoutVersion = requireVersion(value.storageLayoutVersion, "Storage layout version");
-    const aggregateSchemaVersion = requireVersion(value.aggregateSchemaVersion, "Aggregate schema version");
+    const storageVersion = requireVersion(value.storageVersion, "Storage version");
+    const minimumStorageVersion = requireVersion(value.minimumStorageVersion, "Minimum storage migration version");
+    if (minimumStorageVersion > storageVersion) {
+        throw new Error("Minimum storage migration version cannot exceed the current storage version.");
+    }
     return {
         version,
         controllerProtocolVersion,
-        storageLayoutVersion,
-        aggregateSchemaVersion
+        storageVersion,
+        minimumStorageVersion
     };
 }
 /** Managed continuity is a protocol/storage contract, not a package pin. */
 function assertContinuityIdentity(label, expected, actual) {
     for (const field of [
         "controllerProtocolVersion",
-        "storageLayoutVersion",
-        "aggregateSchemaVersion"
+        "storageVersion"
     ]) {
         if (expected[field] !== actual[field]) {
             throw new Error(`${label} ${field} does not match the frozen control plane `
@@ -200,8 +192,7 @@ function assertControllerContinuityIdentity(status, expected) {
         throw new Error("Controller version is invalid at the managed continuity gate.");
     }
     assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
-    assertControllerField(status.storageLayoutVersion, expected.storageLayoutVersion, "storage layout");
-    assertControllerField(status.aggregateSchemaVersion, expected.aggregateSchemaVersion, "aggregate schema");
+    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
 }
 function assertControllerField(actual, expected, label) {
     if (actual !== expected) {

package/dist/storage/currentTaskStore.js

@@ -2,12 +2,11 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { StorageRecordError } from "./taskStore.js";
 import { readSqliteHomeIdentity, SqliteTaskStore } from "./sqliteStore.js";
-import { ensureStorageSchema, inspectStorageSchema } from "./storageSchema.js";
-export const CURRENT_DATABASE_FILENAME = "yui.db";
+import { CURRENT_DATABASE_FILENAME, inspectStorageSchema } from "./storageSchema.js";
+export { CURRENT_DATABASE_FILENAME } from "./storageSchema.js";
 /** Initialize a new Home, or open an existing Home at the exact current contract. */
 export function initializeCurrentTaskStore(home) {
     if (inspectStorageSchema(home).status === "uninitialized") {
-        ensureStorageSchema(home);
         return new SqliteTaskStore(home);
     }
     return openCurrentTaskStore(home);
@@ -16,7 +15,10 @@ export function initializeCurrentTaskStore(home) {
 export function openCurrentTaskStore(home) {
     const schema = inspectStorageSchema(home);
     if (schema.status !== "current") {
-        throw new StorageRecordError("This Home does not use the current storage contract. Preserve it for read-only history and initialize a new Home.");
+        throw new StorageRecordError(schema.status === "upgradeable"
+            ? `This Home uses storage version ${schema.currentVersion}; run \`yui upgrade\` `
+                + `to reach ${schema.latestVersion}.`
+            : "This Home does not use a supported storage contract.");
     }
     if (!existsSync(join(home, CURRENT_DATABASE_FILENAME))) {
         throw new StorageRecordError("The current Home is incomplete: yui.db is missing. Preserve it for diagnosis and initialize a new Home.");