@zq-silk/yui 0.11.3 → 0.12.1

package/dist/cli/updatePorts.js

@@ -34,10 +34,13 @@ import { accessSync, constants, existsSync, mkdtempSync, readFileSync, realpathS
 import { tmpdir } from "node:os";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import Database from "better-sqlite3";
 import { runtimeError } from "../errors/cliError.js";
 import { isConcreteVersion } from "../domain/validation.js";
 import { STORAGE_DOCTOR_CHECK_NAMES } from "../doctor/doctor.js";
+import { acquireHandoverLock } from "../release/runtimeRelease.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
+import { placeUpgradeFence } from "../storage/upgradeFence.js";
 import { correlateUpgradeReceipt } from "../storage/upgrade/upgradeOrchestrator.js";
 import { readSwitchProgress } from "../storage/upgrade/switchProgress.js";
 const PACKAGE_NAME = "@zq-silk/yui";
@@ -91,8 +94,29 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
     // deliberately not persisted as a retry or recovery protocol.
     let verifiedActivatedBinary;
     let verifiedActivatedVersion;
+    let storageFenceOwnerPid;
     const stopReplacementController = (home, pid) => (stopReplacementControllerForUpdate(home, pid, environment, run));
     return {
+        beginControllerHandover(home) {
+            return acquireHandoverLock(home).release;
+        },
+        beginStorageWriteFence(home) {
+            const release = placeUpgradeFence(home, {
+                reason: "update storage activation in progress",
+                createdAt: new Date().toISOString(),
+                ownerPid: process.pid
+            });
+            storageFenceOwnerPid = process.pid;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                release();
+                released = true;
+                if (storageFenceOwnerPid === process.pid)
+                    storageFenceOwnerPid = undefined;
+            };
+        },
         stage(version) {
             // A caller that names a version (the release workflow, which freezes the
             // exact version in its plan) installs THAT version — never a moving
@@ -151,7 +175,10 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                 env: {
                     ...environment,
                     YUI_HOME: home,
-                    YUI_UPDATE_EXTERNALLY_QUIESCED: "1"
+                    YUI_UPDATE_EXTERNALLY_QUIESCED: "1",
+                    ...(storageFenceOwnerPid === undefined
+                        ? {}
+                        : { YUI_UPDATE_HANDOVER_OWNER_PID: String(storageFenceOwnerPid) })
                 },
                 shell: false
             });
@@ -219,6 +246,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             // on-disk schema and report `switched: false` so the caller re-probes the
             // real state instead of giving a recovery instruction from a stale receipt.
             const schema = inspectStorageSchema(home);
+            const sqliteSchemaHead = inspectSqliteSchemaHead(home);
             // A crash mid-switch leaves a durable progress marker. A marker of ANY phase
             // — `backing-up`, `promoting`, or `interrupted` — is only actionable as an
             // interrupted switch when the FILESYSTEM still corroborates it: the backup
@@ -243,6 +271,7 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                         switched: false,
                         interrupted: true,
                         schemaCurrent: false,
+                        ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead }),
                         ...(progress.backupPath === undefined ? {} : { backupPath: progress.backupPath })
                     };
                 }
@@ -252,12 +281,17 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
             }
             const correlation = correlateUpgradeReceipt(home);
             if (!correlation.corresponds) {
-                return { switched: false, schemaCurrent: schema.status === "current" };
+                return {
+                    switched: false,
+                    schemaCurrent: schema.status === "current",
+                    ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead })
+                };
             }
             const receipt = correlation.receipt;
             return {
                 switched: true,
                 schemaCurrent: schema.status === "current",
+                ...(sqliteSchemaHead === undefined ? {} : { sqliteSchemaHead }),
                 ...(receipt.backupPath === undefined ? {} : { backupPath: receipt.backupPath })
             };
         },
@@ -291,6 +325,39 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
         }
     };
 }
+/**
+ * Read the generic durable SQLite ledger without asking the old parent binary
+ * to understand the staged release's migration registry. The staged preflight
+ * supplies the validated source and target heads used to interpret this value.
+ */
+function inspectSqliteSchemaHead(home) {
+    const path = join(home, "yui.db");
+    if (!existsSync(path))
+        return undefined;
+    const db = new Database(path, { readonly: true, fileMustExist: true });
+    try {
+        db.pragma("query_only = ON");
+        const rows = db.prepare("SELECT version, checksum FROM schema_migrations ORDER BY version").all();
+        if (rows.length === 0)
+            throw new Error("SQLite migration ledger is empty.");
+        for (let index = 0; index < rows.length; index += 1) {
+            const row = rows[index];
+            if (row.version !== index + 1
+                || typeof row.checksum !== "string"
+                || row.checksum.length === 0) {
+                throw new Error("SQLite migration ledger is not a contiguous checksummed prefix.");
+            }
+        }
+        const head = rows.at(-1);
+        return {
+            version: head.version,
+            checksum: head.checksum
+        };
+    }
+    finally {
+        db.close();
+    }
+}
 const UPDATE_CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
 const UPDATE_CLIENT_RUNTIME_PATH = fileURLToPath(new URL("../controller/clientRuntime.js", import.meta.url));
 const UPDATE_CONTROLLER_RECONCILIATION_PATH = fileURLToPath(new URL("../controller/updateReconciliation.js", import.meta.url));
@@ -581,7 +648,17 @@ function runControllerCommand(home, environment, spawn, method, cliBinary) {
     const args = cliBinary === undefined
         ? [UPDATE_CLI_PATH, "--json", "controller", method]
         : ["--json", "controller", method];
-    const result = spawn(command, args, { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+    const result = spawn(command, args, {
+        cwd: process.cwd(),
+        env: {
+            ...environment,
+            YUI_HOME: home,
+            // 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)
+        },
+        shell: false
+    });
     if (result.error !== undefined || result.status !== 0) {
         const error = new Error(`Controller ${method} failed (exit ${result.status ?? "null"}).`);
         const code = controllerErrorCodeFromResult(result);
@@ -828,11 +905,14 @@ function interpretPreflight(result) {
         ...(data.sceneUnchanged === true ? { sceneUnchanged: true } : {})
     };
 }
-/** Strictly parse the three green states of the internal update preflight. */
+/** Strictly parse the green states of the internal update preflight. */
 function parseUpdatePreflightResult(data) {
     const status = data.status;
     const stepCount = data.stepCount;
-    if ((status !== "already-current" && status !== "compatible" && status !== "migration-required")
+    if ((status !== "already-current"
+        && status !== "compatible"
+        && status !== "in-place-migration"
+        && status !== "migration-required")
         || !Number.isSafeInteger(stepCount)
         || stepCount < 0) {
         return null;
@@ -857,11 +937,57 @@ function parseUpdatePreflightResult(data) {
         return { status };
     const evidence = status === "compatible"
         ? `${stepCount} compatible step(s) classified and the compatible source validated in memory`
-        : `${stepCount} offline migration step(s) classified and the offline runtime inventory confirmed clear`;
+        : status === "in-place-migration"
+            ? `${stepCount} SQLite migration step(s) classified for one in-place transaction and the offline runtime inventory confirmed clear`
+            : `${stepCount} offline migration step(s) classified and the offline runtime inventory confirmed clear`;
+    const summary = `${evidence}. `
+        + "No staged Home or staged-output loader validation was performed during update preflight.";
+    if (status === "in-place-migration") {
+        const sqliteMigration = parseSqliteMigrationBoundary(data.sqliteMigration, stepCount);
+        if (sqliteMigration === null)
+            return null;
+        return {
+            status,
+            summary,
+            sqliteMigration
+        };
+    }
     return {
         status,
-        summary: `${evidence}. `
-            + "No staged Home or staged-output loader validation was performed during update preflight."
+        summary
+    };
+}
+function parseSqliteMigrationBoundary(value, stepCount) {
+    if (!isRecord(value))
+        return null;
+    const currentVersion = value.currentVersion;
+    const currentChecksum = value.currentChecksum;
+    const targetVersion = value.targetVersion;
+    const targetChecksum = value.targetChecksum;
+    const pendingVersions = value.pendingVersions;
+    if (!Number.isSafeInteger(currentVersion)
+        || currentVersion < 1
+        || typeof currentChecksum !== "string"
+        || currentChecksum.length === 0
+        || !Number.isSafeInteger(targetVersion)
+        || targetVersion <= currentVersion
+        || typeof targetChecksum !== "string"
+        || targetChecksum.length === 0
+        || !Array.isArray(pendingVersions)
+        || pendingVersions.length !== stepCount
+        || targetVersion !== currentVersion + stepCount
+        || pendingVersions.some((version, index) => !Number.isSafeInteger(version) || version !== currentVersion + index + 1)) {
+        return null;
+    }
+    return {
+        current: {
+            version: currentVersion,
+            checksum: currentChecksum
+        },
+        target: {
+            version: targetVersion,
+            checksum: targetChecksum
+        }
     };
 }
 function parseUpdateBlockers(value) {
@@ -933,6 +1059,9 @@ function interpretActivation(result) {
     if (outcome === "already-current")
         return { status: "already-current" };
     if (outcome === "upgraded") {
+        if (data.migrationMode === "in-place" && data.backupPath === undefined) {
+            return { status: "migrated-in-place" };
+        }
         const backupPath = data.backupPath;
         if (typeof backupPath !== "string"
             || backupPath.length === 0

package/dist/cli/upgradeCommand.js

@@ -35,6 +35,9 @@ export async function runUpgradeCommand(args, home, options = {}) {
         ...(options.controllerLifecycle === undefined
             ? {}
             : { controllerLifecycle: options.controllerLifecycle }),
+        ...(options.externalUpgradeFenceOwnerPid === undefined
+            ? {}
+            : { externalUpgradeFenceOwnerPid: options.externalUpgradeFenceOwnerPid }),
         ...(options.now === undefined ? {} : { now: options.now })
     });
     return {
@@ -68,28 +71,35 @@ export function renderUpgradeResult(result, mode) {
                 ? "four-state classification"
                 : result.status === "compatible"
                     ? "four-state classification plus compatible-source validation"
-                    : "four-state classification plus a clear offline runtime inventory";
+                    : result.status === "in-place-migration"
+                        ? "SQLite ledger classification plus a clear offline runtime inventory"
+                        : "four-state classification plus a clear offline runtime inventory";
             return `${header}\nUpdate preflight: ${result.status} (${result.stepCount} step(s)); `
                 + `${evidence}. No staged Home was created, `
                 + "no staged-output loader validation was performed, and storage was not switched.";
         }
         case "dry-run": {
-            const steps = result.report.outcome === "dry-run" ? result.report.steps.length : 0;
+            const steps = result.classification.sqliteMigration?.pendingVersions.length
+                ?? (result.report.outcome === "dry-run" ? result.report.steps.length : 0);
             return `${header}\nDry run: validated ${steps} migration step(s) through the loader gate. `
                 + "Staged output discarded; storage was not switched.";
         }
         case "upgraded":
-            return `${header}\nUpgraded storage. Original Home backed up at `
-                + `${result.backupPath ?? "(unspecified)"}.`;
+            return result.migrationMode === "in-place"
+                ? `${header}\nUpgraded SQLite in place in one transaction; no database rebuild or backup copy was created.`
+                : `${header}\nUpgraded storage. Original Home backed up at `
+                    + `${result.backupPath ?? "(unspecified)"}.`;
         case "blocked": {
             // Most blockers guarantee the source is untouched. A partial switch or a
             // post-switch ambiguity explicitly carries the committed boundary and
             // named recovery evidence; never print a false unchanged claim there.
-            const unchangedNote = result.switchCommitted === true
-                ? "The storage switch committed, but post-switch completion is ambiguous; the old Controller was not restored (see Action and recovery evidence)."
-                : result.stage === "switch-ambiguous"
-                    ? "The switch did not complete and could not be rolled back; the authoritative Home is NOT intact (see Action)."
-                    : "Storage was not switched; the authoritative Home is unchanged.";
+            const unchangedNote = result.storageCommitted === true
+                ? "The SQLite transaction committed in place; the old Controller was not restored (see Action)."
+                : result.switchCommitted === true
+                    ? "The storage switch committed, but post-switch completion is ambiguous; the old Controller was not restored (see Action and recovery evidence)."
+                    : result.stage === "switch-ambiguous"
+                        ? "The switch did not complete and could not be rolled back; the authoritative Home is NOT intact (see Action)."
+                        : "Storage was not switched; the authoritative Home is unchanged.";
             return [
                 header,
                 `${mode === "dry-run" ? "Dry run" : mode === "update-preflight" ? "Update preflight" : "Upgrade"} blocked at ${result.stage}: ${result.message}`,