@zq-silk/yui 0.14.1 → 0.15.0

package/dist/cli/updateCommand.js

@@ -5,9 +5,9 @@ import { runUpdate } from "./updateOrchestrator.js";
  * Run `yui update` as a side-by-side, recoverable orchestration.
  *
  * The new package is staged beside the live install and used to run a read-only
- * preflight against the target Home. Only the exact current storage contract is
- * accepted; the exact Controller handoff then promotes and verifies the binary
- * without changing the Home. Older Homes remain untouched.
+ * preflight against the target Home. A current Home proceeds directly; a Home
+ * inside the staged release's supported range is migrated after the exact
+ * Controller handoff and before post-update verification.
  *
  * Returns a process exit code: 0 on success or already-current, 5 on abort.
  */
@@ -27,15 +27,23 @@ export function renderUpdateResult(result) {
             case "already-current":
                 return "Yui is already up to date; nothing to install.";
             case "updated":
-                return `Updated Yui to ${result.version}; the current Home was not modified.`;
+                return result.backupPath === undefined
+                    ? `Updated Yui to ${result.version}; storage was already current.`
+                    : `Updated Yui to ${result.version} and migrated storage. Backup: ${result.backupPath}`;
             case "aborted":
                 return [
                     `Update aborted during ${result.phase}: ${result.message}`,
-                    result.recoverable
-                        ? "The current install and Home remain usable."
-                        : result.phase === "activate-binary"
-                            ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
-                            : "Manual recovery is required (see below).",
+                    result.phase === "migrate-storage"
+                        || (result.phase === "post-verify" && result.recoverable)
+                        ? "The target binary is installed; the Home remains quiesced pending successful verification."
+                        : result.recoverable
+                            ? "The current install and Home remain usable."
+                            : result.phase === "activate-binary"
+                                ? "The Home was unchanged, but binary health is unknown; do not assume the current install is usable."
+                                : "Manual recovery is required (see below).",
+                    ...(result.backupPath === undefined
+                        ? []
+                        : [`Storage backup: ${result.backupPath}`]),
                     `Action: ${result.action}`
                 ].join("\n");
         }

package/dist/cli/updateOrchestrator.js

@@ -1,10 +1,10 @@
 /**
- * Side-by-side `yui update` orchestration for the current storage contract.
+ * Side-by-side `yui update` orchestration for the supported storage range.
  *
- * The staged binary may only prove that the target Home already implements the
- * exact current contract. Updating never rewrites, normalizes, migrates, or
- * repairs storage. An older Home stays untouched so an Operator can inspect it
- * with its original Yui version and create a new current Task explicitly.
+ * The staged binary proves either an exact-current Home or a complete
+ * migration path before the exact Controller is stopped. The replacement is
+ * then activated, any required storage migration is applied, and the result is
+ * verified before the Controller is restarted.
  */
 export function runUpdate(ports, options) {
     let staged;
@@ -63,6 +63,26 @@ function runStagedUpdate(ports, staged, home) {
             ...(preflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
         };
     }
+    if (preflight.status === "migration-ready" && ports.migrateStorage === undefined) {
+        return {
+            outcome: "aborted",
+            phase: "preflight",
+            message: "The staged binary requires a storage migration, but no migration operation is available.",
+            action: "Use the complete Yui updater or run the staged release's `yui upgrade` explicitly.",
+            recoverable: true,
+            version: staged.version
+        };
+    }
+    if (preflight.status === "migration-ready" && !hasCompleteControllerLifecycle(ports)) {
+        return {
+            outcome: "aborted",
+            phase: "preflight",
+            message: "Storage migration requires a complete, fenced Controller handoff.",
+            action: "Provide status, exact stop, replacement start, and exact restore operations.",
+            recoverable: true,
+            version: staged.version
+        };
+    }
     let releaseHandover;
     try {
         releaseHandover = ports.beginControllerHandover?.(home);
@@ -81,13 +101,13 @@ function runStagedUpdate(ports, staged, home) {
         const captured = captureControllerLifecycle(ports, staged.version, home);
         if ("outcome" in captured)
             return captured;
-        return activateAndVerify(ports, staged, home, captured.lifecycle);
+        return activateAndVerify(ports, staged, home, captured.lifecycle, preflight);
     }
     finally {
         releaseHandover?.();
     }
 }
-function activateAndVerify(ports, staged, home, lifecycle) {
+function activateAndVerify(ports, staged, home, lifecycle, preflight) {
     try {
         ports.activateBinary(staged);
     }
@@ -101,18 +121,46 @@ function activateAndVerify(ports, staged, home, lifecycle) {
             version: staged.version
         });
     }
+    let migration;
+    if (preflight.status === "migration-ready") {
+        try {
+            migration = ports.migrateStorage(staged, home);
+            if (!isStorageMigrationResult(migration)) {
+                throw new Error("Storage migration returned a malformed result.");
+            }
+        }
+        catch (error) {
+            return {
+                outcome: "aborted",
+                phase: "migrate-storage",
+                message: `Storage migration failed: ${messageOf(error)}`,
+                action: "The target Yui binary is installed and the Home remains quiesced. "
+                    + "Resolve the reported problem, rerun `yui upgrade`, then verify "
+                    + "`yui doctor` before starting the Controller.",
+                recoverable: true,
+                version: staged.version
+            };
+        }
+    }
     try {
         ports.verify(staged, home);
     }
     catch (error) {
-        return restoreControllerOrReport(ports, home, lifecycle, {
+        const storageMigrated = preflight.status === "migration-ready";
+        const failure = {
             outcome: "aborted",
             phase: "post-verify",
             message: `Post-update health check failed: ${messageOf(error)}`,
             action: binaryHealthUncertainAction(),
-            recoverable: false,
-            version: staged.version
-        });
+            recoverable: storageMigrated,
+            version: staged.version,
+            ...(migration?.backupPath === undefined
+                ? {}
+                : { backupPath: migration.backupPath })
+        };
+        return storageMigrated
+            ? failure
+            : restoreControllerOrReport(ports, home, lifecycle, failure);
     }
     if (lifecycle.ensureRunning) {
         try {
@@ -120,6 +168,7 @@ function activateAndVerify(ports, staged, home, lifecycle) {
         }
         catch (error) {
             const unknownActive = isUnknownActiveControllerFailure(error);
+            const storageMigrated = preflight.status === "migration-ready";
             const failure = {
                 outcome: "aborted",
                 phase: "post-verify",
@@ -128,19 +177,28 @@ function activateAndVerify(ports, staged, home, lifecycle) {
                     : "The replacement Controller could not start after activation and verification"}: ${messageOf(error)}.`,
                 action: unknownActive
                     ? unknownActiveControllerAction(home)
-                    : lifecycle.wasRunning
-                        ? "Keep the Home quiesced and restore the captured Controller identity before retrying."
-                        : "Verify the activated binary, then start the Controller explicitly.",
-                recoverable: false,
+                    : storageMigrated
+                        ? "Keep the Home quiesced, verify the activated binary, then start the current Controller explicitly."
+                        : lifecycle.wasRunning
+                            ? "Keep the Home quiesced and restore the captured Controller identity before retrying."
+                            : "Verify the activated binary, then start the Controller explicitly.",
+                recoverable: storageMigrated && !unknownActive,
                 version: staged.version,
-                controllerOwnershipUnknown: true
+                ...(migration?.backupPath === undefined
+                    ? {}
+                    : { backupPath: migration.backupPath }),
+                ...(unknownActive ? { controllerOwnershipUnknown: true } : {})
             };
-            return unknownActive
+            return unknownActive || storageMigrated
                 ? failure
                 : restoreControllerOrReport(ports, home, lifecycle, failure);
         }
     }
-    return { outcome: "updated", version: staged.version, path: "current-fast" };
+    return {
+        outcome: "updated",
+        version: staged.version,
+        ...(migration?.backupPath === undefined ? {} : { backupPath: migration.backupPath })
+    };
 }
 function captureControllerLifecycle(ports, version, home) {
     const supplied = [
@@ -186,7 +244,7 @@ function captureControllerLifecycle(ports, version, home) {
         return { lifecycle: { ensureRunning: true, wasRunning: false } };
     }
     if (!isPositivePid(status.pid) || !isControllerIdentity(status.identity)) {
-        return malformedControllerResult(version, "The running Controller did not expose an exact PID and launch identity.");
+        return malformedControllerResult(version, "The running Controller did not expose an exact PID and runtime generation identity.");
     }
     let stopped;
     try {
@@ -257,6 +315,16 @@ function isControllerLifecycleStatus(value) {
 function isControllerStopResult(value) {
     return isRecord(value) && typeof value.stopped === "boolean";
 }
+function hasCompleteControllerLifecycle(ports) {
+    return ports.controllerStatus !== undefined
+        && ports.stopController !== undefined
+        && ports.startController !== undefined
+        && ports.restoreController !== undefined;
+}
+function isStorageMigrationResult(value) {
+    return isRecord(value)
+        && (value.backupPath === undefined || typeof value.backupPath === "string");
+}
 function isPositivePid(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }

package/dist/cli/updatePorts.js

@@ -7,10 +7,10 @@
  * `npm install --global --prefix <tmp>`, so the live global install is never
  * touched until the binary-activation step. Preflight invokes the STAGED binary's
  * internal `yui upgrade --update-preflight` contract so the target version
- * proves that the Home already implements the exact current contract. After
- * the parent stops the exact old Controller, only the binary is promoted;
- * update never rewrites or switches storage. Post-verify invokes the actually
- * activated global binary.
+ * proves that the Home is current or has a complete supported migration path.
+ * After the parent stops the exact old Controller, the binary is promoted,
+ * required migrations run through that same staged artifact, and the activated
+ * binary verifies the resulting current Home.
  *
  * Two hardening guarantees this module enforces:
  *
@@ -147,13 +147,26 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             const result = run("npm", ["install", "--global", spec], { cwd: process.cwd(), env: environment, shell: false, stdio: "inherit" });
             assertSpawnOk(result, "activate the new binary");
         },
+        migrateStorage(staged, home) {
+            const result = run(staged.binaryPath, ["--json", "upgrade", "--update-apply"], {
+                cwd: process.cwd(),
+                env: {
+                    ...environment,
+                    YUI_HOME: home,
+                    YUI_UPDATE_HANDOVER_OWNER_PID: String(process.pid)
+                },
+                shell: false
+            });
+            return interpretStorageMigration(result);
+        },
         verify(staged, home) {
             // Verify the ACTUALLY-ACTIVATED global binary, not the staging path (P1-3).
             const activeBinary = resolveGlobalBinary(environment, run);
             if (activeBinary === null || !existsSync(activeBinary)) {
                 throw runtimeError("Post-update health check failed: could not locate the activated global `yui` binary.");
             }
-            // 1) Health check the unchanged current Home through the activated binary.
+            // 1) Health check the current (possibly just migrated) Home through the
+            // activated binary.
             // POST-VERIFY PARSES THE MACHINE-READABLE RESULT FIRST, THEN THE EXIT STATUS
             // (R2-F2). `yui --json doctor` deliberately sets a non-zero exit when storage
             // is unhealthy, so interpreting the exit status before the envelope would
@@ -514,6 +527,9 @@ function runControllerCommand(home, environment, spawn, method, cliBinary) {
         env: {
             ...environment,
             YUI_HOME: home,
+            // Lifecycle capture needs the schema-independent resource inventory,
+            // not the optional current-schema identity health verdict.
+            YUI_STATUS_IDENTITY: "0",
             // This exact lifecycle child is part of the update process that owns
             // the handover lock. Managed Sessions never receive this bypass.
             YUI_UPDATE_HANDOVER_OWNER_PID: String(process.pid)
@@ -693,7 +709,7 @@ function assertActivatedControllerIdentity(identity, activatedBinary, activatedV
     if (identity.executablePath !== process.execPath
         || identity.args.length !== 1
         || identity.args[0] !== expectedEntrypoint) {
-        throw new Error("Replacement Controller launch identity does not match the activated global binary "
+        throw new Error("Replacement Controller runtime generation identity does not match the activated global binary "
             + "runtime/entrypoint; refusing readiness.");
     }
 }
@@ -782,19 +798,69 @@ function interpretPreflight(result) {
         ...(data.sceneUnchanged === true ? { sceneUnchanged: true } : {})
     };
 }
-/** Only the exact current storage contract is a green update preflight. */
+/** Accept either an exact current Home or a complete supported migration path. */
 function parseUpdatePreflightResult(data) {
-    if (data.status !== "already-current" || data.stepCount !== 0)
+    if ((data.status !== "already-current" && data.status !== "migration-ready")
+        || !Number.isSafeInteger(data.stepCount)
+        || !Array.isArray(data.steps)
+        || data.steps.length !== data.stepCount)
         return null;
     const homeClassification = data.classification;
     if (!isRecord(homeClassification) || !isRecord(homeClassification.classification))
         return null;
     const classification = homeClassification.classification;
-    if (classification.verdict !== "USABLE"
-        || classification.status !== "current") {
+    if (data.status === "already-current") {
+        if (data.stepCount !== 0
+            || classification.verdict !== "USABLE"
+            || classification.status !== "current")
+            return null;
+        return { status: "already-current", stepCount: 0 };
+    }
+    if (data.stepCount <= 0
+        || classification.verdict !== "MIGRATABLE"
+        || classification.status !== "migration-ready"
+        || !data.steps.every(isStorageMigrationStep))
         return null;
+    return { status: "migration-ready", stepCount: data.stepCount };
+}
+function interpretStorageMigration(result) {
+    const data = parseSuccessEnvelopeData(result);
+    if (data === null) {
+        throw runtimeError("The staged binary did not return a successful storage migration result "
+            + `(exit ${result.status ?? "null"}${result.signal === null ? "" : `, signal ${result.signal}`}).`);
+    }
+    if (data.outcome === "blocked" || data.outcome === "failed") {
+        const message = typeof data.message === "string"
+            ? data.message
+            : "The staged binary refused the storage migration.";
+        const action = typeof data.action === "string" ? ` Action: ${data.action}` : "";
+        const backup = typeof data.backupPath === "string"
+            ? ` Backup: ${data.backupPath}`
+            : "";
+        throw runtimeError(`${message}${action}${backup}`);
     }
-    return { status: "already-current" };
+    if (result.status !== 0) {
+        throw runtimeError(`The staged binary returned outcome=${String(data.outcome)} but exited `
+            + `with status ${result.status ?? "null"}.`);
+    }
+    if (data.outcome === "already-current")
+        return {};
+    if (data.outcome !== "upgraded" || !isRecord(data.report)) {
+        throw runtimeError(`The staged binary returned unexpected storage migration outcome=${String(data.outcome)}.`);
+    }
+    const backupPath = data.report.backupPath;
+    if (typeof backupPath !== "string" || backupPath.length === 0) {
+        throw runtimeError("The staged binary did not report the required storage backup path.");
+    }
+    return { backupPath };
+}
+function isStorageMigrationStep(value) {
+    return isRecord(value)
+        && Number.isSafeInteger(value.fromVersion)
+        && Number.isSafeInteger(value.toVersion)
+        && value.toVersion === value.fromVersion + 1
+        && typeof value.name === "string"
+        && value.name.length > 0;
 }
 function parseUpdateBlockers(value) {
     if (value === undefined)
@@ -806,7 +872,7 @@ function parseUpdateBlockers(value) {
         if (!isRecord(item) || typeof item.reason !== "string" || item.reason.length === 0) {
             return undefined;
         }
-        const optional = ["taskId", "roleName", "turnId", "nativeSessionId", "launchId"];
+        const optional = ["taskId", "roleName", "turnId", "nativeSessionId", "runtimeGenerationId"];
         if (optional.some((key) => item[key] !== undefined && typeof item[key] !== "string")) {
             return undefined;
         }
@@ -817,7 +883,7 @@ function parseUpdateBlockers(value) {
             ...(typeof item.nativeSessionId === "string"
                 ? { nativeSessionId: item.nativeSessionId }
                 : {}),
-            ...(typeof item.launchId === "string" ? { launchId: item.launchId } : {}),
+            ...(typeof item.runtimeGenerationId === "string" ? { runtimeGenerationId: item.runtimeGenerationId } : {}),
             reason: item.reason
         });
     }

package/dist/cli/upgradeCommand.js

@@ -1,26 +1,24 @@
-/**
- * `yui upgrade` is now a read-only storage admission diagnostic. This release
- * opens only its exact current contract and never rewrites an historical Home.
- */
-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) {
@@ -29,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: already-current (0 steps). Storage was not modified.`;
+            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);
 }