@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/foundation/release/release-store.d.ts

@@ -31,12 +31,24 @@ export interface CertifiedReleaseRecord {
     /** Absent on records written before releases declared a handoff contract. */
     readonly launchContract?: string;
 }
+/** Reports that installed package bytes cannot safely reproduce an approved release. */
+export declare class ReleaseRepairUnavailableError extends Error {
+    readonly code: "RELEASE_REPAIR_UNAVAILABLE";
+    constructor(message: string, options?: ErrorOptions);
+}
 /** Process-authority compatibility controls for metadata-only release loading. */
 export type ReadCertifiedReleaseManifestOptions = ReadCertifiedDependencyLayerOptions;
 export declare function materializeRelease(packageRoot: string, dataDir: string, options?: MaterializeReleaseOptions): Promise<MaterializedRelease>;
 /** Consume proof that this exact object was freshly materialized or fully verified in this process. */
 export declare function consumeMaterializationProof(release: MaterializedRelease): boolean;
 export declare function readMaterializedRelease(releaseRoot: string, selectedStoreRoot?: string): Promise<MaterializedRelease>;
+/** Fast presence check before trusted certification permits a release to skip full verification. */
+export declare function assertCertifiedFilesPresent(releaseRoot: string): Promise<void>;
+/**
+ * Restore changed or missing product payload files from the installed package without replacing the
+ * immutable release directory. Dependency layers retain their own verification and repair policy.
+ */
+export declare function repairMaterializedRelease(packageRoot: string, releaseRoot: string): Promise<MaterializedRelease>;
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must

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

@@ -10,6 +10,14 @@ import { dependencyReference, materializeDependencyLayer, readCertifiedDependenc
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
+/** Reports that installed package bytes cannot safely reproduce an approved release. */
+export class ReleaseRepairUnavailableError extends Error {
+    code = "RELEASE_REPAIR_UNAVAILABLE";
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "ReleaseRepairUnavailableError";
+    }
+}
 export async function materializeRelease(packageRoot, dataDir, options = {}) {
     const payload = await discoverReleasePayload(packageRoot, {
         onSourceRead: (path, bytes) => options.onOperation?.({ operation: "source-read", path, bytes }),
@@ -71,7 +79,7 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
         const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
         if (await lstat(releaseRoot).catch(() => null)) {
             await rm(candidate, { recursive: true, force: true });
-            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+            return certificationReadyRelease(await verifyOrRepairMaterializedRelease(payload.packageRoot, releaseRoot, identity));
         }
         await writeFile(resolve(candidate, RELEASE_MANIFEST_FILENAME), JSON.stringify(identity, null, 2), { mode: 0o400, flag: "wx" });
         try {
@@ -81,7 +89,7 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             if (!await lstat(releaseRoot).catch(() => null))
                 throw error;
             await rm(candidate, { recursive: true, force: true });
-            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+            return certificationReadyRelease(await verifyOrRepairMaterializedRelease(payload.packageRoot, releaseRoot, identity));
         }
         return certificationReadyRelease({ ...identity, releaseRoot: await realpath(releaseRoot) });
     }
@@ -102,6 +110,61 @@ export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
     return certificationReadyRelease(await verifyMaterializedRelease(canonical, manifest, selectedStoreRoot));
 }
+/** Fast presence check before trusted certification permits a release to skip full verification. */
+export async function assertCertifiedFilesPresent(releaseRoot) {
+    const canonical = await realpath(releaseRoot);
+    const manifest = await readReleaseManifest(canonical);
+    await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+        const metadata = await lstat(resolveWithin(canonical, file.path));
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new Error(`certified release file is missing: ${file.path}`);
+    });
+}
+/**
+ * Restore changed or missing product payload files from the installed package without replacing the
+ * immutable release directory. Dependency layers retain their own verification and repair policy.
+ */
+export async function repairMaterializedRelease(packageRoot, releaseRoot) {
+    const canonical = await realpath(releaseRoot);
+    let manifest;
+    let payload;
+    try {
+        manifest = await readReleaseManifest(canonical);
+        payload = await discoverReleasePayload(packageRoot);
+        assertCurrentLaunchContract(payload);
+    }
+    catch (error) {
+        throw repairUnavailable("release repair metadata is unavailable", error);
+    }
+    if (payload.packageVersion !== manifest.packageVersion) {
+        throw repairUnavailable(`installed package version ${payload.packageVersion} does not match release ${manifest.packageVersion}`);
+    }
+    const payloadPaths = new Set(payload.paths.filter(path => !path.startsWith("node_modules/")));
+    try {
+        await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
+            const destination = resolveWithin(canonical, file.path);
+            if (!await certifiedFileDiffers(destination, file))
+                return;
+            if (!payloadPaths.has(file.path))
+                throw repairUnavailable(`installed package does not carry ${file.path}`);
+            const source = resolveWithin(payload.packageRoot, file.path);
+            const sourceMetadata = await lstat(source);
+            if (!sourceMetadata.isFile() || sourceMetadata.isSymbolicLink())
+                throw repairUnavailable(`installed package file is not regular: ${file.path}`);
+            const bytes = payload.cachedFiles.get(file.path) ?? await readFile(source);
+            if (bytes.length !== file.bytes || createHash("sha256").update(bytes).digest("hex") !== file.sha256) {
+                throw repairUnavailable(`installed package bytes do not match release file ${file.path}`);
+            }
+            await replaceReleaseFile(destination, bytes, file);
+        });
+        return await verifyMaterializedRelease(canonical, manifest);
+    }
+    catch (error) {
+        if (error instanceof ReleaseRepairUnavailableError)
+            throw error;
+        throw repairUnavailable("release repair could not restore the certified payload", error);
+    }
+}
 /**
  * Load metadata for a release whose bytes were already certified by the
  * current parent process or an authenticated live supervisor. Callers must
@@ -197,6 +260,65 @@ async function verifyFile(root, file, options) {
     if (digest !== file.sha256)
         throw new Error(`release file digest mismatch: ${file.path}`);
 }
+async function verifyOrRepairMaterializedRelease(packageRoot, releaseRoot, expected) {
+    try {
+        return await verifyMaterializedRelease(releaseRoot, expected);
+    }
+    catch {
+        await repairMaterializedRelease(packageRoot, releaseRoot);
+        return await verifyMaterializedRelease(releaseRoot, expected);
+    }
+}
+async function readReleaseManifest(releaseRoot) {
+    const manifest = JSON.parse(await readFile(resolveWithin(releaseRoot, RELEASE_MANIFEST_FILENAME), "utf8"));
+    validateManifest(manifest);
+    if (releaseRoot.split(sep).at(-1) !== manifest.releaseId)
+        throw new Error(`release directory does not match identity ${manifest.releaseId}`);
+    return manifest;
+}
+async function certifiedFileDiffers(path, file) {
+    const metadata = await lstat(path).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (metadata === null || !metadata.isFile() || metadata.isSymbolicLink() || metadata.size !== file.bytes)
+        return true;
+    if ((metadata.mode & 0o222) !== 0 || ((metadata.mode & 0o111) !== 0) !== file.executable)
+        return true;
+    return createHash("sha256").update(await readFile(path)).digest("hex") !== file.sha256;
+}
+async function replaceReleaseFile(path, bytes, file) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = resolve(dirname(path), `.a1-repair-${randomUUID()}`);
+    const mode = file.executable ? 0o500 : 0o400;
+    let existing = null;
+    try {
+        await writeFile(temporary, bytes, { flag: "wx", mode: 0o600 });
+        existing = await lstat(path).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (existing !== null) {
+            if (!existing.isFile() || existing.isSymbolicLink())
+                throw repairUnavailable(`release file cannot be safely replaced: ${file.path}`);
+            // Platform: Windows refuses rename-over for a read-only destination.
+            await chmod(path, 0o600);
+        }
+        await rename(temporary, path);
+        await chmod(path, mode);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => { });
+        if (existing !== null)
+            await chmod(path, mode).catch(() => { });
+        throw error;
+    }
+}
+function repairUnavailable(message, cause) {
+    return new ReleaseRepairUnavailableError(message, cause === undefined ? {} : { cause });
+}
 function certificationReadyRelease(release) {
     certificationReady.add(release);
     return release;

package/dist/foundation/release/update-execution-lease.d.ts

@@ -0,0 +1,48 @@
+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";
+export interface UpdateExecutionOwner {
+    readonly schema: typeof LEASE_SCHEMA;
+    readonly ownerId: string;
+    readonly pid: number;
+    readonly pidStartIdentity: string;
+    readonly packageRoot: string;
+    readonly channel: UpdateChannel;
+    readonly targetVersion: string;
+    readonly mode: UpdateExecutionMode;
+    readonly acquiredAt: string;
+}
+export type UpdateExecutionLeaseResult = {
+    readonly status: "acquired";
+    readonly owner: UpdateExecutionOwner;
+    release(): Promise<void>;
+} | {
+    readonly status: "busy";
+    readonly owner: UpdateExecutionOwner;
+}
+/** A dead owner whose active transaction names another target; only a manual update may settle it. */
+ | {
+    readonly status: "interrupted";
+    readonly owner: UpdateExecutionOwner;
+    readonly transaction: UpdateTransaction;
+};
+/**
+ * Serializes every package replacement for one A1 data root. A dead owner is moved aside before a
+ * new exclusive create, so concurrent recovery attempts cannot both acquire the installation.
+ */
+export declare function acquireUpdateExecutionLease(input: {
+    readonly dataDir: string;
+    readonly packageRoot: string;
+    readonly channel: UpdateChannel;
+    readonly targetVersion: string;
+    readonly mode: UpdateExecutionMode;
+}): Promise<UpdateExecutionLeaseResult>;
+export declare function readUpdateExecutionOwner(dataDir: string): Promise<UpdateExecutionOwner | null>;
+/**
+ * Removes a dead owner's lease once its transaction has been settled. A lease that another owner
+ * holds by now, or whose process turned out to be alive, is left alone.
+ */
+export declare function reclaimDeadLease(dataDir: string, owner: UpdateExecutionOwner): Promise<void>;
+export {};

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

@@ -0,0 +1,161 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import { processIsAlive } from "./process-cleanup.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+export const UPDATE_EXECUTION_LEASE_FILENAME = "update-execution.json";
+const LEASE_SCHEMA = 1;
+const MAX_LEASE_BYTES = 8_192;
+/**
+ * Serializes every package replacement for one A1 data root. A dead owner is moved aside before a
+ * new exclusive create, so concurrent recovery attempts cannot both acquire the installation.
+ */
+export async function acquireUpdateExecutionLease(input) {
+    const path = resolve(input.dataDir, UPDATE_EXECUTION_LEASE_FILENAME);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const releaseAcquisition = await lockfile.lock(path, {
+        realpath: false,
+        stale: 60_000,
+        update: 20_000,
+        retries: { retries: 20, factor: 1.2, minTimeout: 20, maxTimeout: 100, randomize: true },
+    });
+    const owner = {
+        schema: LEASE_SCHEMA,
+        ownerId: randomUUID(),
+        pid: process.pid,
+        pidStartIdentity: currentProcessStartIdentity(),
+        packageRoot: resolve(input.packageRoot),
+        channel: input.channel,
+        targetVersion: input.targetVersion,
+        mode: input.mode,
+        acquiredAt: new Date().toISOString(),
+    };
+    try {
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            try {
+                const file = await open(path, "wx", 0o600);
+                try {
+                    await file.writeFile(`${JSON.stringify(owner)}\n`);
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                return {
+                    status: "acquired",
+                    owner,
+                    release: async () => await releaseLease(path, owner),
+                };
+            }
+            catch (error) {
+                if (!hasCode(error, "EEXIST"))
+                    throw error;
+            }
+            const existing = await readUpdateExecutionOwner(input.dataDir);
+            if (existing === null)
+                continue;
+            // Security: an uninspectable or reused pid stays conservative. A process known to be absent is
+            // reclaimed only when its durable transaction agrees with both owners; a transaction that names
+            // another target is handed to a manual caller to settle, while automatic work fails closed.
+            if (processIsAlive(existing.pid))
+                return { status: "busy", owner: existing };
+            const foreign = await foreignActiveTransaction(input.dataDir, existing, input);
+            if (foreign !== null) {
+                return input.mode === "manual"
+                    ? { status: "interrupted", owner: existing, transaction: foreign }
+                    : { status: "busy", owner: existing };
+            }
+            const stale = `${path}.stale-${existing.ownerId}-${randomUUID()}`;
+            try {
+                await rename(path, stale);
+                await rm(stale, { force: true });
+            }
+            catch (error) {
+                if (!hasCode(error, "ENOENT"))
+                    throw error;
+            }
+        }
+        const existing = await readUpdateExecutionOwner(input.dataDir);
+        if (existing !== null)
+            return { status: "busy", owner: existing };
+        throw new Error("could not acquire update execution lease");
+    }
+    finally {
+        await releaseAcquisition();
+    }
+}
+export async function readUpdateExecutionOwner(dataDir) {
+    const path = resolve(dataDir, UPDATE_EXECUTION_LEASE_FILENAME);
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+    if (Buffer.byteLength(source, "utf8") > MAX_LEASE_BYTES)
+        throw new Error("update execution lease is oversized");
+    const value = JSON.parse(source);
+    validateOwner(value);
+    return value;
+}
+async function releaseLease(path, owner) {
+    const current = await readUpdateExecutionOwner(dirname(path));
+    if (current === null || current.ownerId !== owner.ownerId || current.pid !== owner.pid
+        || current.pidStartIdentity !== owner.pidStartIdentity)
+        return;
+    const released = `${path}.released-${owner.ownerId}-${randomUUID()}`;
+    try {
+        await rename(path, released);
+        await rm(released, { force: true });
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT"))
+            throw error;
+    }
+}
+function validateOwner(value) {
+    if (value.schema !== LEASE_SCHEMA || typeof value.ownerId !== "string" || value.ownerId.length === 0
+        || !Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.pidStartIdentity !== "string"
+        || typeof value.packageRoot !== "string" || !["stable", "next"].includes(value.channel)
+        || typeof value.targetVersion !== "string" || !["manual", "automatic"].includes(value.mode)
+        || typeof value.acquiredAt !== "string") {
+        throw new Error("invalid update execution lease");
+    }
+}
+/**
+ * Removes a dead owner's lease once its transaction has been settled. A lease that another owner
+ * holds by now, or whose process turned out to be alive, is left alone.
+ */
+export async function reclaimDeadLease(dataDir, owner) {
+    if (processIsAlive(owner.pid))
+        return;
+    await releaseLease(resolve(dataDir, UPDATE_EXECUTION_LEASE_FILENAME), owner);
+}
+/** The active transaction when it or the request disagrees with the dead owner, else null. */
+async function foreignActiveTransaction(dataDir, owner, requested) {
+    const transaction = await new UpdateTransactionStore(dataDir).read();
+    if (transaction?.status !== "active")
+        return null;
+    const matches = transaction.channel === owner.channel && transaction.targetVersion === owner.targetVersion
+        && samePath(transaction.packageRoot, owner.packageRoot)
+        && requested.channel === owner.channel && requested.targetVersion === owner.targetVersion
+        && 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)}`;
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

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

@@ -1,6 +1,8 @@
 import type { UpdateChannel } from "./types.js";
+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";
 export declare const PRODUCT_PACKAGE: string;
 export type { UpdateChannel } from "./types.js";
@@ -61,10 +63,17 @@ export interface SelfUpdateOptions {
     channel?: UpdateChannel;
     /** A specific preview to install, named by its development number or full version. */
     target?: string;
+    /** Internal exact channel target selected by the automatic update probe. */
+    resolvedTarget?: string;
+    mode?: "manual" | "automatic";
+    onLeaseAcquired?: (owner: UpdateExecutionOwner) => void;
+    onLeaseBusy?: (owner: UpdateExecutionOwner) => void;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
     output?: UpdateOutput;
     runner?: UpdateProcessRunner;
+    /** Reads the registry's package document when a preview is named; defaults to a bounded fetch. */
+    fetcher?: RegistryFetcher;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
     /** Test seam for protected global package replacement. */
@@ -80,6 +89,7 @@ export interface SelfUpdateOptions {
 export type { UpdateActivationPhase, UpdateMaterializationProgress } from "./update-activation.js";
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
+    verifyAutomaticSafety?(): Promise<void>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
         priorActiveVersion: string | null;
     }>;
@@ -123,6 +133,7 @@ export interface UpdatePackageReplacementInput {
  * The update therefore keeps checking for this long before it calls the package locked.
  */
 export declare const PACKAGE_UNLOCK_PATIENCE_MS = 15000;
+export declare const UPDATE_ALREADY_RUNNING_EXIT_CODE = 75;
 /** Whether a rename failure means something holds the tree, as opposed to the tree being wrong. */
 export declare function isPackageLockError(error: unknown): boolean;
 /** What the user reads when the package stayed held for the whole patience window. */
@@ -131,15 +142,9 @@ export declare function lockedPackageDiagnostic(packageRoot: string, waitedMs: n
 export declare const CHILD_DIAGNOSTIC_LIMIT = 8000;
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
-/**
- * What an update does about the owner it found. A cohort running from retained immutable
- * content keeps its work: the installation replaces files it does not read, and it listens on
- * its own endpoint. A cohort running from the mutable installation is the one exception,
- * because that installation is exactly what is about to be replaced under it.
- */
 export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 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. */
-export declare function renderUpdateProgressBar(percent: number): string;
+export declare function renderUpdateProgressBar(percent: number, accent?: string): string;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;