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

package/dist/foundation/release/{cohort-state.js → release-state.js}

@@ -3,7 +3,7 @@ import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+export const RELEASE_STATE_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
 const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
 /** How long a release stays on disk after its approval, so processes started from it keep their files. */
 export const RELEASE_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
@@ -51,8 +51,8 @@ export function withinRetention(release, now, retentionMs = RELEASE_RETENTION_MS
     const at = stamp === null ? Number.NaN : Date.parse(stamp);
     return Number.isFinite(at) && now - at < retentionMs;
 }
-/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
-export class CohortStateStore {
+/** Serializes validated release-state revisions under a lock and commits each update atomically. */
+export class ReleaseStateStore {
     path;
     constructor(dataDir) {
         this.path = resolve(dataDir, "release-state.json");
@@ -317,7 +317,7 @@ export class CohortStateStore {
 }
 export function emptyState() {
     return {
-        schema: RELEASE_COHORT_SCHEMA,
+        schema: RELEASE_STATE_SCHEMA,
         revision: 0,
         releases: {},
         references: { active: null, pending: null, approved: null, rollback: null, retention: [] },
@@ -430,11 +430,11 @@ function normalizeState(value) {
     };
 }
 function validateState(state) {
-    if (!state || state.schema !== RELEASE_COHORT_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0
+    if (!state || state.schema !== RELEASE_STATE_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0
         || !state.releases || typeof state.releases !== "object" || !state.references || !Array.isArray(state.references.retention)
         || !state.cleanup || typeof state.cleanup.pending !== "object" || !Array.isArray(state.cleanup.diagnostics)
         || !Array.isArray(state.cleanup.workerRuns)) {
-        throw new Error("invalid release cohort state");
+        throw new Error("invalid release state");
     }
     for (const run of state.cleanup.workerRuns) {
         if (!run || typeof run.runId !== "string" || run.runId.length === 0
@@ -469,9 +469,9 @@ function validateReleaseRecord(releaseId, release) {
 function validateTransition(current, next) {
     validateState(next);
     if (next.schema !== current.schema)
-        throw new Error("release cohort schema cannot change during a state update");
+        throw new Error("release schema cannot change during a state update");
     if (next.revision !== current.revision)
-        throw new Error("release cohort revision is controlled by the state store");
+        throw new Error("release revision is controlled by the state store");
 }
 function boundedError(error) {
     return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 1_000);

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

@@ -4,10 +4,11 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { PRODUCT_TEXT } from "../../product-identity.js";
 import { certifyMaterializedRelease } from "./bootstrap.js";
-import { CohortStateStore } from "./cohort-state.js";
+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
@@ -27,7 +28,7 @@ const ACTIVATION_LINE_LIMIT = 64 * 1_024;
  * its activation entry, and what an updater runs in-process for a tree older than the contract.
  */
 export async function activateInstalledRelease(request, callbacks) {
-    const stateStore = new CohortStateStore(request.dataDir);
+    const stateStore = new ReleaseStateStore(request.dataDir);
     let total = 0;
     let completed = 0;
     const candidate = await materializeRelease(request.packageRoot, request.dataDir, {
@@ -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.d.ts

@@ -1,8 +1,7 @@
 import type { UpdateChannel } from "./types.js";
 import { type UpdateTransaction } from "./update-transaction.js";
-export declare const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
 declare const LEASE_SCHEMA = 1;
-export type UpdateExecutionMode = "manual" | "automatic";
+type UpdateExecutionMode = "manual" | "automatic";
 export interface UpdateExecutionOwner {
     readonly schema: typeof LEASE_SCHEMA;
     readonly ownerId: string;
@@ -14,7 +13,7 @@ export interface UpdateExecutionOwner {
     readonly mode: UpdateExecutionMode;
     readonly acquiredAt: string;
 }
-export type UpdateExecutionLeaseResult = {
+type UpdateExecutionLeaseResult = {
     readonly status: "acquired";
     readonly owner: UpdateExecutionOwner;
     release(): Promise<void>;

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

@@ -4,7 +4,8 @@ import { dirname, resolve } from "node:path";
 import lockfile from "proper-lockfile";
 import { processIsAlive } from "./process-liveness.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
-export const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
+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-launch.d.ts

@@ -1,4 +1,4 @@
-import type { CohortState, ReleaseRecord } from "./cohort-state.js";
+import type { ReleaseState, ReleaseRecord } from "./release-state.js";
 import type { UpdateTransaction } from "./update-transaction.js";
 /** Keep interactive launches on the last successful release until the update commits success. */
-export declare function selectUpdateLaunchRelease(state: CohortState, transaction: UpdateTransaction | null): ReleaseRecord | null;
+export declare function selectUpdateLaunchRelease(state: ReleaseState, transaction: UpdateTransaction | null): ReleaseRecord | null;

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
@@ -135,8 +116,6 @@ export declare const UPDATE_ALREADY_RUNNING_EXIT_CODE = 75;
 export declare function isPackageLockError(error: unknown): boolean;
 /** What the user reads when the package stayed held for the whole patience window. */
 export declare function lockedPackageDiagnostic(packageRoot: string, waitedMs: number, attempts: number, error: unknown): string;
-/** Bound on the child diagnostics an update keeps: enough for npm's failure reason, never a log. */
-export declare const CHILD_DIAGNOSTIC_LIMIT = 8000;
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, _output?: UpdateOutput, patience?: UpdateUnlockPatience): UpdateLifecycleCoordinator;
 /** Renders the terminal-only update meter; the visual preview shares this exact frame. */