@timurproko/a1 0.2.7-dev.1255 → 0.2.7-dev.1264

package/dist/features/owned-ui/settings-model-dialog.js

@@ -0,0 +1,194 @@
+import { DIALOG_BACK_SHORTCUT_HINT, DIALOG_CLOSE_SHORTCUT_HINT } from "../../contracts/presentation/index.js";
+import { LineInput, ShortcutRegistry, assertNoShortcutConflicts, configureDialogChoiceCapacity, configureDialogTextRows, handleLineInputKey, humanizeLabel, renderSteppedDialogPanel, } from "../../ui/components/index.js";
+import { changeFailure, structuredValue } from "./settings-edits.js";
+import { SETTINGS_APP_ID } from "./settings-route.js";
+const MODEL_SCOPE = `${SETTINGS_APP_ID}-models`;
+const MODEL_LEVEL_SCOPE = `${SETTINGS_APP_ID}-model-levels`;
+const MODEL_SHORTCUTS = new ShortcutRegistry();
+MODEL_SHORTCUTS.declare({ key: "edit", scope: MODEL_SCOPE, description: "Search models", section: "Choose", hint: { keys: "Type", does: "search" } }, "edit-filter");
+MODEL_SHORTCUTS.declare({ key: "up", scope: MODEL_SCOPE, description: "Previous model", section: "Choose" }, "previous");
+MODEL_SHORTCUTS.declare({ key: "down", scope: MODEL_SCOPE, description: "Next model", section: "Choose" }, "next");
+MODEL_SHORTCUTS.declare({ key: "enter", scope: MODEL_SCOPE, description: "Select model", section: "Choose", hint: { keys: "Enter", does: "select" } }, "select");
+MODEL_SHORTCUTS.declare({ key: "escape", scope: MODEL_SCOPE, description: "Close selector", section: "Choose", hint: { keys: DIALOG_CLOSE_SHORTCUT_HINT.key, does: DIALOG_CLOSE_SHORTCUT_HINT.action } }, "close");
+MODEL_SHORTCUTS.declare({ key: "up", scope: MODEL_LEVEL_SCOPE, description: "Previous level", section: "Choose", hint: { keys: "↑↓", does: "navigate" } }, "previous");
+MODEL_SHORTCUTS.declare({ key: "down", scope: MODEL_LEVEL_SCOPE, description: "Next level", section: "Choose", hint: { keys: "↑↓", does: "navigate" } }, "next");
+MODEL_SHORTCUTS.declare({ key: "enter", scope: MODEL_LEVEL_SCOPE, description: "Select level", section: "Choose", hint: { keys: "Enter", does: "select" } }, "select");
+MODEL_SHORTCUTS.declare({ key: "escape", scope: MODEL_LEVEL_SCOPE, description: "Return to models", section: "Choose", hint: { keys: DIALOG_BACK_SHORTCUT_HINT.key, does: DIALOG_BACK_SHORTCUT_HINT.action } }, "back");
+assertNoShortcutConflicts(MODEL_SHORTCUTS.assemble());
+/**
+ * One key in the default-model selector or the two-step thinking-level dialog. `key` is the
+ * named key for `data`; typed text that names no shortcut edits the search.
+ */
+export function modelDialogKey(open, data, key, actions) {
+    if (open.modelDialog === "default" || open.step === "model") {
+        const flags = filteredModelFlags(open);
+        const action = MODEL_SHORTCUTS.resolve(key, MODEL_SCOPE) ?? "edit-filter";
+        if (action === "close") {
+            actions.close();
+            return { consumed: true };
+        }
+        if (action === "previous" || action === "next") {
+            open.index = Math.min(Math.max(0, flags.length - 1), Math.max(0, open.index + (action === "next" ? 1 : -1)));
+            return { consumed: true };
+        }
+        if (action === "select") {
+            const selected = flags[open.index];
+            if (selected === undefined)
+                return { consumed: true, render: false };
+            if (open.modelDialog === "default")
+                selectDefaultModel(open, selected.key, actions);
+            else {
+                open.modelIndex = open.index;
+                open.modelKey = selected.key;
+                open.step = "level";
+                const options = modelLevelOptions(open, selected);
+                const current = structuredValue(open.entry, open.record)[selected.key];
+                open.index = Math.max(0, options.findIndex(option => option.value === current));
+            }
+            return { consumed: true };
+        }
+        if (open.filter === null)
+            return { consumed: true, render: false };
+        handleLineInputKey(open.filter, data);
+        open.index = 0;
+        return { consumed: true };
+    }
+    const selected = open.entry.flags.find(flag => flag.key === open.modelKey);
+    const choices = selected === undefined ? [] : modelLevelOptions(open, selected);
+    const action = MODEL_SHORTCUTS.resolve(key, MODEL_LEVEL_SCOPE);
+    if (action === "back") {
+        returnToModels(open);
+        return { consumed: true };
+    }
+    if (action === "previous" || action === "next") {
+        open.index = Math.min(Math.max(0, choices.length - 1), Math.max(0, open.index + (action === "next" ? 1 : -1)));
+        return { consumed: true };
+    }
+    if (action === "select") {
+        const choice = choices[open.index];
+        if (selected === undefined || choice === undefined)
+            return { consumed: true, render: false };
+        const previous = { ...open.record };
+        open.record[selected.key] = choice.value;
+        const forward = { ...open.record };
+        actions.save(open, previous, forward);
+        returnToModels(open);
+        return { consumed: true };
+    }
+    return { consumed: true, render: false };
+}
+export function modelDialogLines(open, width, height, theme) {
+    if (open.modelDialog === "default") {
+        const flags = filteredModelFlags(open);
+        const current = typeof open.entry.rawValue === "string" ? open.entry.rawValue : null;
+        const rows = flags.length === 0
+            ? [{ label: "No models found", value: "" }]
+            : flags.map(flag => ({
+                ...modelLabelParts(flag.label ?? humanizeLabel(flag.key)),
+                ...(flag.key === current ? { successSuffix: "✓" } : {}),
+                value: "",
+            }));
+        const description = open.error ?? "Select the model used for new sessions";
+        const visible = dialogWindow(rows, open.index, configureDialogChoiceCapacity(height, true, configureDialogTextRows(description, width)));
+        return renderSteppedDialogPanel({
+            title: "Default Model", description, input: open.filter ?? new LineInput(""),
+            rows: visible.rows, index: visible.index, hint: MODEL_SHORTCUTS.hintEntries(MODEL_SCOPE),
+        }, width, theme);
+    }
+    if (open.step === "model") {
+        const flags = filteredModelFlags(open);
+        const stored = structuredValue(open.entry, open.record);
+        const allRows = flags.length === 0
+            ? [{ label: "No models found", value: "" }]
+            : flags.map(flag => ({
+                ...modelLabelParts(flag.label ?? humanizeLabel(flag.key)),
+                value: stored[flag.key] === undefined ? "" : String(stored[flag.key]),
+            }));
+        const description = "Select a model to configure";
+        const visible = dialogWindow(allRows, open.index, configureDialogChoiceCapacity(height, true, configureDialogTextRows(description, width)));
+        return renderSteppedDialogPanel({
+            title: "Thinking Level",
+            step: 1,
+            steps: 2,
+            description,
+            ...(open.filter === null ? {} : { input: open.filter }),
+            rows: visible.rows,
+            index: visible.index,
+            hint: MODEL_SHORTCUTS.hintEntries(MODEL_SCOPE),
+        }, width, theme);
+    }
+    const selected = open.entry.flags.find(flag => flag.key === open.modelKey);
+    const current = selected === undefined ? undefined : structuredValue(open.entry, open.record)[selected.key];
+    const allRows = (selected === undefined ? [] : modelLevelOptions(open, selected)).map(choice => ({
+        label: choice.value === current ? `✓ ${choice.label}` : choice.label,
+        value: choice.description,
+    }));
+    const description = `Select default thinking level for ${selected?.label ?? open.modelKey ?? "model"}`;
+    const visible = dialogWindow(allRows, open.index, configureDialogChoiceCapacity(height, false, configureDialogTextRows(description, width)));
+    return renderSteppedDialogPanel({
+        title: "Thinking Level",
+        step: 2,
+        steps: 2,
+        description,
+        rows: visible.rows,
+        index: visible.index,
+        hint: MODEL_SHORTCUTS.hintEntries(MODEL_LEVEL_SCOPE),
+    }, width, theme);
+}
+/** The rows a dialog of `maximum` rows shows, centred on `index` where the list allows. */
+export function dialogWindow(rows, index, maximum) {
+    if (rows.length <= maximum)
+        return { rows, index: Math.min(Math.max(0, rows.length - 1), Math.max(0, index)) };
+    const start = Math.min(rows.length - maximum, Math.max(0, index - Math.floor(maximum / 2)));
+    return { rows: rows.slice(start, start + maximum), index: index - start };
+}
+// Concurrency: the dialog closes at once; a refused save reopens it with the reason.
+function selectDefaultModel(open, model, actions) {
+    open.error = null;
+    actions.close();
+    void actions.session.change(open.entry.backend, open.entry.id, model).then(outcome => {
+        const failure = changeFailure(outcome);
+        if (failure !== null) {
+            open.error = `Could not save: ${failure}`;
+            actions.reopen(open);
+        }
+    });
+}
+function returnToModels(open) {
+    open.step = "model";
+    open.modelKey = null;
+    open.index = open.modelIndex;
+}
+function filteredModelFlags(open) {
+    const needle = open.filter?.value.trim().toLowerCase() ?? "";
+    return open.entry.flags.filter(flag => needle.length === 0
+        || (flag.label ?? humanizeLabel(flag.key)).toLowerCase().includes(needle)
+        || flag.description.toLowerCase().includes(needle)
+        || flag.key.toLowerCase().includes(needle));
+}
+function modelLevelOptions(open, selected) {
+    const fallback = String(selected.fallback);
+    const supported = (selected.choices ?? [])
+        .filter(choice => choice !== fallback)
+        .map(choice => ({ value: choice, label: choice, description: thinkingLevelDescription(choice) }));
+    return structuredValue(open.entry, open.record)[selected.key] === undefined
+        ? supported
+        : [...supported, { value: fallback, label: "(clear override)", description: "Revert to global default" }];
+}
+function modelLabelParts(label) {
+    const match = /^(.*?)(\s+\[[^\]]+\])$/u.exec(label);
+    return match === null ? { label } : { label: match[1] ?? label, labelSuffix: match[2] ?? "" };
+}
+function thinkingLevelDescription(level) {
+    switch (level) {
+        case "default": return "global default";
+        case "off": return "No reasoning";
+        case "minimal": return "Very brief reasoning (~1k tokens)";
+        case "low": return "Light reasoning (~2k tokens)";
+        case "medium": return "Moderate reasoning (~8k tokens)";
+        case "high": return "Deep reasoning (~16k tokens)";
+        case "xhigh": return "Extra-high reasoning (~32k tokens)";
+        case "max": return "Maximum reasoning";
+        default: return "";
+    }
+}

package/dist/foundation/release/automatic-update.js

@@ -13,6 +13,7 @@ import { readCertifiedReleaseManifest, resolveReleaseEntryPoint } from "./releas
 import { acquireUpdateExecutionLease, readUpdateExecutionOwner } from "./update-execution-lease.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { runSelfUpdate, UPDATE_ALREADY_RUNNING_EXIT_CODE } from "./update.js";
+import { errorMessage, samePath } from "./managed-path.js";
 const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
 const AUTOMATIC_UPDATE_RETRY_MS = 24 * 60 * 60_000;
 const AUTOMATIC_UPDATE_STATE_FILENAME = "automatic-update.json";
@@ -406,14 +407,6 @@ function validateState(value) {
         throw new Error("invalid automatic update state");
     }
 }
-function samePath(left, right) {
-    const canonicalLeft = resolve(left);
-    const canonicalRight = resolve(right);
-    return process.platform === "win32"
-        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
-        : canonicalLeft === canonicalRight;
-}
 function hasCode(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/dependency-layer.js

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, posix, relative, resolve, sep } from "node:path";
+import { dirname, posix, resolve, sep } from "node:path";
 import { mapWithConcurrency } from "./concurrency.js";
 import { assertImmutableFileMode } from "./immutable-platform.js";
 import { readDependencyCertification, writeDependencyCertification as writeLayerCertification } from "./dependency-certification.js";
 export { dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath } from "./dependency-certification.js";
 import { digestManifestFiles, releaseFileIdentity, resolveWithin } from "./release.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { isDirectChild } from "./managed-path.js";
 const LAYER_IO_CONCURRENCY = 32;
 export const DEPENDENCY_LAYER_SCHEMA = PRODUCT_IDENTITY.evidence.dependencyLayerSchema;
 export const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
@@ -460,7 +461,6 @@ function isKnownRuntimePath(path) {
 }
 function isJavaScriptModule(path) { return /\.(?:js|mjs|cjs)$/.test(path); }
 function assertDirectChild(parent, child) {
-    const path = relative(parent, child);
-    if (path.length === 0 || path === ".." || path.startsWith(`..${sep}`) || path.includes(sep))
+    if (!isDirectChild(parent, child))
         throw new Error(`dependency layer escapes managed storage: ${child}`);
 }

package/dist/foundation/release/latest-release.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { gt, prerelease, valid as validSemver } from "semver";
 import lockfile from "proper-lockfile";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { errorMessage } from "./managed-path.js";
 const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 export const UPDATE_CHECK_INTERVAL_MS = 15 * 60_000;
 const STARTUP_FETCH_TIMEOUT_MS = 3_000;
@@ -255,4 +256,3 @@ function parseVersion(value, source) {
         throw new Error(`${source} did not provide a valid semantic version`);
     return parsed;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/managed-path.d.ts

@@ -0,0 +1,10 @@
+/** Whether two paths name the same location; Windows paths compare without case. */
+export declare function samePath(left: string, right: string): boolean;
+/**
+ * Whether `child` is exactly one non-empty segment below `parent`.
+ * Invariant: release storage operations act only on such paths, never on the root itself, another drive, a nested descendant,
+ * or anything reached through `..`. `path.relative` already ignores case on Windows.
+ */
+export declare function isDirectChild(parent: string, child: string): boolean;
+/** The message of a thrown value, whatever was thrown. */
+export declare function errorMessage(error: unknown): string;

package/dist/foundation/release/managed-path.js

@@ -0,0 +1,26 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/** Whether two paths name the same location; Windows paths compare without case. */
+export function samePath(left, right) {
+    const canonicalLeft = resolve(left);
+    const canonicalRight = resolve(right);
+    return process.platform === "win32"
+        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
+        : canonicalLeft === canonicalRight;
+}
+/**
+ * Whether `child` is exactly one non-empty segment below `parent`.
+ * Invariant: release storage operations act only on such paths, never on the root itself, another drive, a nested descendant,
+ * or anything reached through `..`. `path.relative` already ignores case on Windows.
+ */
+export function isDirectChild(parent, child) {
+    const fromParent = relative(resolve(parent), resolve(child));
+    return fromParent.length > 0
+        && fromParent !== ".."
+        && !fromParent.startsWith(`..${sep}`)
+        && !isAbsolute(fromParent)
+        && !fromParent.includes(sep);
+}
+/** The message of a thrown value, whatever was thrown. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/foundation/release/release-gc.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ReleaseStateStore, } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
@@ -15,6 +15,7 @@ import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { collectCompileCaches, startupCompileCachePath } from "../startup/index.js";
 import { readLaunchContext } from "../launch-context/index.js";
 import { processIsAlive } from "./process-liveness.js";
+import { errorMessage, isDirectChild } from "./managed-path.js";
 const DEFAULT_CANDIDATE_AGE_MS = 60 * 60 * 1_000;
 const DEFAULT_LIMITS = { maxItems: 8, maxDurationMs: 2_000, concurrency: 1 };
 const DEFAULT_WORKER_DURATION_MS = 10 * 60 * 1_000;
@@ -638,12 +639,6 @@ async function protectedCompileCachePaths(dataDir, state) {
     }
     return paths;
 }
-function assertDirectChild(parent, child) {
-    const fromParent = relative(parent, child);
-    if (fromParent.length === 0 || fromParent === ".." || fromParent.startsWith(`..${sep}`) || isAbsolute(fromParent) || fromParent.includes(sep)) {
-        throw new Error(`cleanup path is not a direct child of its managed root: ${child}`);
-    }
-}
 function normalizeLimits(input) {
     const limits = { ...DEFAULT_LIMITS, ...input };
     for (const [name, value] of Object.entries(limits)) {
@@ -748,4 +743,7 @@ function artifactName(path) { return path.split(sep).at(-1) ?? "artifact"; }
 function certificationReleaseId(path) {
     return /^certification-(.+)\.json$/.exec(artifactName(path))?.[1] ?? null;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function assertDirectChild(parent, child) {
+    if (!isDirectChild(parent, child))
+        throw new Error(`cleanup path is not a direct child of its managed root: ${child}`);
+}

package/dist/foundation/release/restart-certification.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { lstat, readFile, realpath, stat } from "node:fs/promises";
-import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { PRIVATE_LAUNCH_CONTRACT, launchContractTarget } from "../launch-context/index.js";
 import { DEPENDENCY_LAYER_MANIFEST, dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath, readCertifiedDependencyLayer } from "./dependency-layer.js";
@@ -9,6 +9,7 @@ import { immutablePlatformPolicy } from "./immutable-platform.js";
 import { PRODUCT_PACKAGE_NAME } from "./release.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
+import { isDirectChild } from "./managed-path.js";
 const RESTART_SEAL_VERSION = 1;
 const REQUIRED_LAUNCH_ENTRIES = ["bin/ui.js"];
 /** Build compact restart authority after complete content verification established read-only payload files. */
@@ -219,9 +220,7 @@ async function observedRealpath(path, onEvent) {
     return await realpath(path);
 }
 function assertDirectChild(parent, child, expectedName, kind) {
-    const fromParent = relative(parent, child);
-    if (isAbsolute(fromParent) || fromParent === ".." || fromParent.startsWith(`..${sep}`) || fromParent.includes(sep)
-        || basename(child) !== expectedName) {
+    if (!isDirectChild(parent, child) || basename(child) !== expectedName) {
         throw new Error(`restart ${kind} is outside its managed store: ${child}`);
     }
 }

package/dist/foundation/release/update-activation.js

@@ -8,6 +8,7 @@ import { ReleaseStateStore } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
 import { materializeRelease } from "./release-store.js";
 import { warmMaterializedRelease } from "./warmup.js";
+import { errorMessage } from "./managed-path.js";
 /**
  * The one activation contract an installed tree can offer the updater that installed it.
  * The updater knows nothing else about the tree: the manifest names the contracts the tree
@@ -211,4 +212,3 @@ function summarize(text) {
     const lines = text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
     return lines.length === 0 ? "" : `: ${lines.slice(0, 4).join(" | ")}`;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/update-execution-lease.js

@@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path";
 import lockfile from "proper-lockfile";
 import { processIsAlive } from "./process-liveness.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
+import { samePath } from "./managed-path.js";
 const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
 const LEASE_SCHEMA = 1;
 const MAX_LEASE_BYTES = 8_192;
@@ -146,13 +147,6 @@ async function foreignActiveTransaction(dataDir, owner, requested) {
         && samePath(requested.packageRoot, owner.packageRoot);
     return matches ? null : transaction;
 }
-function samePath(left, right) {
-    const canonicalLeft = resolve(left);
-    const canonicalRight = resolve(right);
-    return process.platform === "win32"
-        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
-        : canonicalLeft === canonicalRight;
-}
 function currentProcessStartIdentity() {
     return `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
 }

package/dist/foundation/release/update-installer.d.ts

@@ -0,0 +1,45 @@
+import type { ProductPaths } from "../lifecycle/index.js";
+import type { UpdateRecoveryState, UpdateTransaction } from "./update-transaction.js";
+import { type ProtectedPackageReplacementResult } from "./update-recovery.js";
+/** The approved release protected replacement restores when the new package cannot launch. */
+export interface UpdatePriorRelease {
+    readonly releaseId: string;
+    readonly releaseRoot: string;
+    readonly contentDigest: string;
+}
+/** What an update knows about the release that was active when it began. */
+export interface UpdatePriorReleaseProtection {
+    /** The active release to roll back to, or null when none was recorded. */
+    readonly priorActiveReleaseId: string | null;
+    /** The approved record for a release id, or undefined when it cannot protect replacement. */
+    approvedRelease(releaseId: string | null): UpdatePriorRelease | undefined;
+}
+export interface UpdatePackageReplacementInput {
+    readonly globalRoot: string;
+    readonly npmCliRoot: string;
+    readonly npmCli?: string;
+    readonly packageRoot: string;
+    readonly transaction: UpdateTransaction;
+    readonly priorRelease: UpdatePriorRelease;
+    readonly output: {
+        stderr(message: string): void;
+    };
+    readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
+}
+/**
+ * The update steps that touch npm and release storage. Every update runs all of them in the same
+ * order; a test replaces a step's behaviour, never which steps run.
+ */
+export interface UpdateInstaller {
+    /** Resolve npm's CLI entry before anything changes; a throw stops the update with nothing changed. */
+    preflight(npmCliRoot: string): Promise<string | undefined>;
+    /** Make sure an approved release can launch while npm replaces the package. */
+    protectPriorRelease(packageRoot: string): Promise<UpdatePriorReleaseProtection>;
+    replacePackage(input: UpdatePackageReplacementInput): Promise<ProtectedPackageReplacementResult>;
+    /** Return to the prior release after a failure, describing what happened. "rolled back" means it did. */
+    rollback(priorReleaseId: string | null): Promise<string>;
+    /** Release cleanup committed after activation and before success is reported. */
+    maintenance(): Promise<void>;
+}
+/** The production installer: npm preflight, recovery release, protected replacement, rollback and release cleanup. */
+export declare function createProtectedUpdateInstaller(paths: ProductPaths, environment: NodeJS.ProcessEnv): UpdateInstaller;

package/dist/foundation/release/update-installer.js

@@ -0,0 +1,57 @@
+import { certifyMaterializedRelease } from "./bootstrap.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
+import { ReleaseStateStore } from "./release-state.js";
+import { materializeRelease, readMaterializedRelease } from "./release-store.js";
+import { resolveNpmCli, runProtectedPackageReplacement } from "./update-recovery.js";
+/** The production installer: npm preflight, recovery release, protected replacement, rollback and release cleanup. */
+export function createProtectedUpdateInstaller(paths, environment) {
+    const dataDir = paths.dataDir;
+    return {
+        preflight: async (npmCliRoot) => await resolveNpmCli(npmCliRoot, environment),
+        protectPriorRelease: async (packageRoot) => await protectPriorRelease(dataDir, packageRoot),
+        replacePackage: async (input) => await runProtectedPackageReplacement({ ...input, dataDir, environment }),
+        rollback: async (priorReleaseId) => await rollbackPriorRelease(dataDir, priorReleaseId),
+        maintenance: async () => { await scheduleReleaseCleanup(dataDir, paths); },
+    };
+}
+async function protectPriorRelease(dataDir, packageRoot) {
+    const releaseStateStore = new ReleaseStateStore(dataDir);
+    let state = await releaseStateStore.read();
+    let priorActiveReleaseId = state.references.active;
+    if (priorActiveReleaseId === null || state.releases[priorActiveReleaseId]?.approval !== "approved") {
+        // Invariant: protected replacement needs an immutable launch authority that npm cannot rename.
+        const recoveryRelease = await materializeRelease(packageRoot, dataDir);
+        await releaseStateStore.recordCandidate(recoveryRelease);
+        const diagnostics = await certifyMaterializedRelease(recoveryRelease, dataDir);
+        await releaseStateStore.approve(recoveryRelease.releaseId, diagnostics);
+        await releaseStateStore.activate(recoveryRelease.releaseId);
+        state = await releaseStateStore.read();
+        priorActiveReleaseId = recoveryRelease.releaseId;
+    }
+    const releases = state.releases;
+    return {
+        priorActiveReleaseId,
+        approvedRelease: releaseId => {
+            const record = releaseId === null ? undefined : releases[releaseId];
+            return record?.approval === "approved" ? record : undefined;
+        },
+    };
+}
+async function rollbackPriorRelease(dataDir, priorReleaseId) {
+    if (!priorReleaseId)
+        return "no prior release was available for rollback";
+    const stateStore = new ReleaseStateStore(dataDir);
+    const state = await stateStore.read();
+    const prior = state.releases[priorReleaseId];
+    if (!prior || prior.approval !== "approved")
+        return "prior release is not a verified rollback candidate";
+    if (state.references.active !== priorReleaseId) {
+        if (state.references.rollback === priorReleaseId)
+            await stateStore.rollback();
+        else
+            throw new Error(`prior release ${priorReleaseId} is not the recorded rollback release`);
+    }
+    // Invariant: rollback selects only a prior release whose retained content still verifies.
+    await readMaterializedRelease(prior.releaseRoot);
+    return "rolled back";
+}

package/dist/foundation/release/update-recovery.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { processIsAlive } from "./process-liveness.js";
 import { PRIVATE_LAUNCH_CONTRACT, assertCurrentLaunchContract } from "../launch-context/index.js";
+import { isDirectChild, samePath } from "./managed-path.js";
 export const UPDATE_RECOVERY_SCHEMA = "a1-update-recovery-v1";
 const WORKER_TIMEOUT_MS = 15 * 60 * 1_000;
 const POLL_MS = 50;
@@ -429,9 +430,6 @@ async function writeDurableJson(path, value) {
     await rename(temporary, path);
 }
 async function readJson(path) { return JSON.parse(await readFile(path, "utf8")); }
-function samePath(left, right) {
-    return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
-}
 function sameSegment(left, right, platform) {
     return platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
 }
@@ -443,11 +441,6 @@ function containedBy(parent, child) {
     return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);
 }
 function assertDirectChild(parent, child) {
-    const expectedParent = resolve(parent);
-    const actualParent = dirname(resolve(child));
-    const matches = process.platform === "win32"
-        ? actualParent.toLowerCase() === expectedParent.toLowerCase()
-        : actualParent === expectedParent;
-    if (!matches)
+    if (!isDirectChild(parent, child))
         throw new Error(`update recovery path is outside its managed root: ${child}`);
 }

package/dist/foundation/release/update.d.ts

@@ -3,7 +3,8 @@ import { type RegistryFetcher } from "./latest-release.js";
 import { type UpdateActivationPhase, type UpdateMaterializationProgress } from "./update-activation.js";
 import { type UpdateRecoveryState, type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
 import { type UpdateExecutionOwner } from "./update-execution-lease.js";
-import { resolveNpmCli, type ProtectedPackageReplacementResult } from "./update-recovery.js";
+import { type UpdateInstaller } from "./update-installer.js";
+export type { UpdateInstaller, UpdatePackageReplacementInput, UpdatePriorRelease, UpdatePriorReleaseProtection, } from "./update-installer.js";
 export declare const PRODUCT_PACKAGE: string;
 export type { UpdateChannel } from "./types.js";
 export interface ProcessRequest {
@@ -76,12 +77,8 @@ export interface SelfUpdateOptions {
     fetcher?: RegistryFetcher;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
-    /** Test seam for protected global package replacement. */
-    packageReplacement?: (input: UpdatePackageReplacementInput) => Promise<ProtectedPackageReplacementResult>;
-    /** Test seam for proving replacement-authority preflight ordering. */
-    npmCliResolver?: typeof resolveNpmCli;
-    /** Test or embedding seam for post-activation release maintenance. */
-    maintenance?: () => Promise<void>;
+    /** The npm and release-storage steps; defaults to protected replacement of the managed package. */
+    installer?: UpdateInstaller;
     progress?: boolean;
     onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
     now?: () => number;
@@ -107,22 +104,6 @@ export interface UpdateTransactionJournal {
     finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
     clearCompleted(): Promise<void>;
 }
-export interface UpdatePackageReplacementInput {
-    readonly dataDir: string;
-    readonly globalRoot: string;
-    readonly npmCliRoot: string;
-    readonly npmCli?: string;
-    readonly packageRoot: string;
-    readonly transaction: UpdateTransaction;
-    readonly priorRelease: {
-        readonly releaseId: string;
-        readonly releaseRoot: string;
-        readonly contentDigest: string;
-    };
-    readonly output: UpdateOutput;
-    readonly environment: NodeJS.ProcessEnv;
-    readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
-}
 /**
  * The package tree is checked for holders by renaming it and renaming it back, because on
  * Windows that is the one operation that fails while any file under it is open. A holder is