@timurproko/a1 0.1.8-dev.259 → 0.1.8-dev.269

package/bin/update-recovery.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+// Security: this file intentionally depends only on Node built-ins: the updater copies it into a
+// transaction capsule before npm is allowed to rename or remove the installed package.
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCHEMA = "a1-update-recovery-v1";
+const [, , mode, manifestPath, separator, ...forwarded] = process.argv;
+
+if ((mode !== "--worker" && mode !== "--launch") || !manifestPath || (mode === "--launch" && separator !== "--")) {
+  throw new Error("invalid A1 update recovery invocation");
+}
+
+const capsule = await readCapsule(manifestPath);
+if (mode === "--worker") {
+  await runWorker(capsule);
+} else {
+  process.exitCode = await runRecoveredCommand(capsule, forwarded);
+}
+
+async function runWorker(value) {
+  await rm(value.resultPath, { force: true });
+  await writeJson(value.ownerPath, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    pid: process.pid,
+    startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+    startedAt: new Date().toISOString(),
+  });
+  const heartbeat = setInterval(() => {
+    void writeJson(value.ownerPath, {
+      schema: SCHEMA,
+      transactionId: value.transactionId,
+      pid: process.pid,
+      startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+      heartbeatAt: new Date().toISOString(),
+    });
+  }, 500);
+  heartbeat.unref?.();
+  const child = spawn(process.execPath, [value.npmCli, ...value.npmArguments], {
+    detached: false,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+  child.stderr?.on("data", chunk => stderr.push(Buffer.from(chunk)));
+  let cancelled = false;
+  let forced = false;
+  let forceTimer = null;
+  const cancellationPoll = setInterval(async () => {
+    if (cancelled || !await exists(value.cancellationPath)) return;
+    cancelled = true;
+    child.kill("SIGTERM");
+    forceTimer = setTimeout(() => { forced = true; child.kill("SIGKILL"); }, 2_000);
+    forceTimer.unref?.();
+  }, 50);
+  cancellationPoll.unref?.();
+
+  let npmExitCode = null;
+  let spawnError = null;
+  try {
+    npmExitCode = await new Promise((resolvePromise, rejectPromise) => {
+      child.once("error", rejectPromise);
+      child.once("close", code => resolvePromise(code));
+    });
+  } catch (error) {
+    spawnError = error;
+  } finally {
+    clearInterval(cancellationPoll);
+    clearInterval(heartbeat);
+    if (forceTimer) clearTimeout(forceTimer);
+  }
+
+  const targetReady = await installedTargetIsCallable(value);
+  let launcherDisposition = "unavailable";
+  let outcome = "failed";
+  if (targetReady) {
+    launcherDisposition = "target";
+    outcome = "installed";
+  } else {
+    await writeRecoveryLaunchers(value);
+    if (await recoveryLaunchersAreCallable(value)) {
+      launcherDisposition = "recovery";
+      outcome = "recovery-launcher";
+    }
+  }
+  await writeJson(value.resultPath, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    outcome,
+    npmExitCode,
+    cancelled,
+    launcherDisposition,
+    stdout: bounded(Buffer.concat(stdout).toString("utf8")),
+    stderr: bounded(`${Buffer.concat(stderr).toString("utf8")}${spawnError ? `\n${String(spawnError)}` : ""}${forced ? "\nforced npm termination after cancellation" : ""}`.trim()),
+    completedAt: new Date().toISOString(),
+  });
+  if (launcherDisposition === "unavailable") process.exitCode = 1;
+}
+
+async function runRecoveredCommand(value, arguments_) {
+  let entry = await installedTargetEntry(value);
+  if (entry === null && arguments_[0] === "update") {
+    await rm(value.cancellationPath, { force: true });
+    await rm(value.resultPath, { force: true });
+    await rm(value.ownerPath, { force: true });
+    const worker = spawn(process.execPath, [fileURLToPath(import.meta.url), "--worker", manifestPath], {
+      detached: true,
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    worker.unref();
+    const deadline = Date.now() + 15 * 60 * 1000;
+    const requestCancellation = signal => { void writeJson(value.cancellationPath, { schema: SCHEMA, transactionId: value.transactionId, signal, requestedAt: new Date().toISOString() }); };
+    const onSigint = () => requestCancellation("SIGINT");
+    const onSigterm = () => requestCancellation("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    try {
+      while (Date.now() < deadline && !await exists(value.resultPath)) await sleep(50);
+    } finally {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    }
+    entry = await installedTargetEntry(value);
+  }
+  entry ??= resolve(value.priorReleaseRoot, "bin", "cli.js");
+  const child = spawn(process.execPath, [entry, ...arguments_], { stdio: "inherit", windowsHide: false });
+  return await new Promise(resolvePromise => {
+    child.once("error", error => { console.error(error instanceof Error ? error.message : String(error)); resolvePromise(1); });
+    child.once("close", code => resolvePromise(code ?? 1));
+  });
+}
+
+async function readCapsule(path) {
+  const value = JSON.parse(await readFile(path, "utf8"));
+  if (value.schema !== SCHEMA || typeof value.transactionId !== "string" || typeof value.packageName !== "string"
+    || typeof value.packageName !== "string" || !value.packageName.includes("/") || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.globalRoot !== "string"
+    || typeof value.launcherRoot !== "string" || !Array.isArray(value.launchers) || typeof value.priorReleaseId !== "string" || typeof value.priorReleaseRoot !== "string"
+    || !/^[a-f0-9]{64}$/.test(value.priorContentDigest) || typeof value.releaseManifestName !== "string"
+    || typeof value.recoveryEntry !== "string" || typeof value.recoveryEntryDigest !== "string" || value.nodeExecutable !== process.execPath || typeof value.npmCli !== "string"
+    || !Array.isArray(value.npmArguments) || typeof value.resultPath !== "string" || typeof value.cancellationPath !== "string") {
+    throw new Error("invalid A1 update recovery capsule");
+  }
+  const lexicalCapsuleRoot = dirname(resolve(path));
+  if (lexicalCapsuleRoot.split(sep).at(-1) !== value.transactionId) throw new Error("A1 update recovery transaction path is invalid");
+  const capsuleRoot = await realpath(lexicalCapsuleRoot);
+  const entry = await realpath(value.recoveryEntry);
+  assertDirectChild(capsuleRoot, entry);
+  if (!samePath(entry, resolve(capsuleRoot, "recovery.js"))) throw new Error("A1 update recovery entry path is invalid");
+  const digest = createHash("sha256").update(await readFile(entry)).digest("hex");
+  if (digest !== value.recoveryEntryDigest) throw new Error("A1 update recovery payload digest mismatch");
+  const globalRoot = await realpath(value.globalRoot);
+  const packageRoot = await realpath(value.packageRoot).catch(() => resolve(value.packageRoot));
+  const expectedPackage = resolve(globalRoot, ...value.packageName.split("/"));
+  if (!samePath(packageRoot, expectedPackage) || !containedBy(globalRoot, packageRoot)) throw new Error("A1 update recovery package root escapes npm global root");
+  const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  if (JSON.stringify(value.npmArguments) !== JSON.stringify(expectedNpmArguments)) throw new Error("A1 update recovery npm arguments are invalid");
+  const launcherRoot = resolve(value.launcherRoot);
+  const expectedLaunchers = process.platform === "win32"
+    ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
+    : [resolve(launcherRoot, "a1")];
+  if (JSON.stringify(value.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers)) throw new Error("A1 update recovery launcher set is invalid");
+  for (const launcher of value.launchers) assertDirectChild(launcherRoot, resolve(launcher));
+  const expectedSidecars = [resolve(lexicalCapsuleRoot, "cancel.json"), resolve(lexicalCapsuleRoot, "result.json"), resolve(lexicalCapsuleRoot, "owner.json")];
+  if (![value.cancellationPath, value.resultPath, value.ownerPath].every((candidate, index) => samePath(candidate, expectedSidecars[index]))) {
+    throw new Error("A1 update recovery sidecar paths are invalid");
+  }
+  const dataDir = dirname(dirname(capsuleRoot));
+  const releasesRoot = await realpath(resolve(dataDir, "releases"));
+  const priorReleaseRoot = await realpath(value.priorReleaseRoot);
+  assertDirectChild(releasesRoot, priorReleaseRoot);
+  if (priorReleaseRoot.split(sep).at(-1) !== value.priorReleaseId) throw new Error("A1 update recovery prior release identity is invalid");
+  const priorManifest = JSON.parse(await readFile(resolve(priorReleaseRoot, value.releaseManifestName), "utf8"));
+  if (priorManifest.releaseId !== value.priorReleaseId || priorManifest.contentDigest !== value.priorContentDigest) {
+    throw new Error("A1 update recovery prior release manifest is invalid");
+  }
+  const npmMetadata = await lstat(value.npmCli);
+  if (!npmMetadata.isFile() || npmMetadata.isSymbolicLink()) throw new Error("A1 update recovery npm entry is invalid");
+  return value;
+}
+
+async function installedTargetEntry(value) {
+  try {
+    const manifest = JSON.parse(await readFile(resolve(value.packageRoot, "package.json"), "utf8"));
+    const entry = resolve(value.packageRoot, "bin", "cli.js");
+    if (manifest.name !== value.packageName || manifest.version !== value.targetVersion || !(await lstat(entry)).isFile()) return null;
+    return entry;
+  } catch { return null; }
+}
+
+async function installedTargetIsCallable(value) {
+  if (await installedTargetEntry(value) === null) return false;
+  const token = `node_modules/${value.packageName}/bin/cli.js`;
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      const normalized = (await readFile(path, "utf8")).replaceAll("\\", "/");
+      if (!normalized.includes(token)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+async function writeRecoveryLaunchers(value) {
+  const node = value.nodeExecutable ?? process.execPath;
+  const entry = value.recoveryEntry;
+  const manifest = manifestPath;
+  const shell = `#!/bin/sh\nexec ${shellQuote(node)} ${shellQuote(entry)} --launch ${shellQuote(manifest)} -- "$@"\n`;
+  const command = `@ECHO off\r\n"${node}" "${entry}" --launch "${manifest}" -- %*\r\n`;
+  const powershell = `& '${psQuote(node)}' '${psQuote(entry)}' --launch '${psQuote(manifest)}' -- $args\nexit $LASTEXITCODE\n`;
+  const content = process.platform === "win32" ? [shell, command, powershell] : [shell];
+  await mkdir(value.launcherRoot, { recursive: true });
+  for (let index = 0; index < value.launchers.length; index += 1) await atomicWrite(value.launchers[index], content[index], 0o755);
+}
+
+async function recoveryLaunchersAreCallable(value) {
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      if (!(await readFile(path, "utf8")).includes(value.recoveryEntry)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+async function atomicWrite(path, content, mode) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode });
+  await chmod(temporary, mode);
+  await rm(path, { force: true });
+  await rename(temporary, path);
+}
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const file = await open(temporary, "wx", 0o600);
+  try { await file.writeFile(JSON.stringify(value, null, 2)); await file.sync(); }
+  finally { await file.close(); }
+  await rm(path, { force: true });
+  await rename(temporary, path);
+}
+
+function samePath(left, right) {
+  return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
+function containedBy(parent, child) {
+  const fromParent = relative(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) throw new Error(`A1 update recovery path escapes its managed root: ${child}`);
+}
+function shellQuote(value) { return `'${String(value).replaceAll("'", `'"'"'`)}'`; }
+function psQuote(value) { return String(value).replaceAll("'", "''"); }
+function bounded(value) { return value.length <= 64 * 1024 ? value : value.slice(-64 * 1024); }
+async function exists(path) { return await lstat(path).then(() => true).catch(() => false); }
+async function sleep(ms) { await new Promise(resolvePromise => setTimeout(resolvePromise, ms)); }

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

@@ -27,6 +27,8 @@ export interface BootstrapOptions {
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
 export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
+/** Persist current-format evidence after an authenticated parent has certified the exact release. */
+export declare function recordParentCertifiedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
 export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdentity {
     readonly childOutcome: Promise<{
         readonly exitCode: number | null;

package/dist/foundation/release/bootstrap.js

@@ -193,6 +193,10 @@ export async function certifyMaterializedRelease(release, dataDir, verification
     if (!consumeMaterializationProof(release)) {
         await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"), verification);
     }
+    return await recordParentCertifiedRelease(release, dataDir);
+}
+/** Persist current-format evidence after an authenticated parent has certified the exact release. */
+export async function recordParentCertifiedRelease(release, dataDir) {
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);
     const restartSeal = await createRestartSeal(release, dataDir);
     await chmod(path, 0o600).catch(() => { });

package/dist/foundation/release/dependency-layer.d.ts

@@ -37,6 +37,10 @@ export interface DependencyLayerOperationEvent {
     readonly path: string;
     readonly bytes: number;
 }
+export interface ReadCertifiedDependencyLayerOptions {
+    /** Accept and replace certification written by the immediately preceding updater format. */
+    readonly allowLegacyParentCertification?: boolean;
+}
 export interface SelectedRuntimePayload {
     readonly paths: readonly string[];
     readonly inventory: RuntimePayloadInventory;
@@ -71,7 +75,7 @@ export interface MaterializeDependencyLayerOptions {
 /** Materialize or reuse an exact immutable dependency layer after one source-content pass. */
 export declare function materializeDependencyLayer(packageRoot: string, dataDir: string, paths: readonly string[], options: MaterializeDependencyLayerOptions): Promise<MaterializedDependencyLayer | null>;
 /** Read trusted layer certification and canonical metadata without rereading every payload byte. */
-export declare function readCertifiedDependencyLayer(dataDir: string, layerId: string, expected?: Pick<DependencyLayerIdentity, "layerId" | "contentDigest">): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+export declare function readCertifiedDependencyLayer(dataDir: string, layerId: string, expected?: Pick<DependencyLayerIdentity, "layerId" | "contentDigest">, options?: ReadCertifiedDependencyLayerOptions): Promise<Omit<MaterializedDependencyLayer, "reused">>;
 /** Fully verify a layer when certification is absent or explicit tamper evidence is required. */
 export declare function verifyDependencyLayer(dataDir: string, reference: DependencyLayerReference, onOperation?: (event: DependencyLayerOperationEvent) => void): Promise<Omit<MaterializedDependencyLayer, "reused">>;
 export declare function dependencyReference(layer: MaterializedDependencyLayer): DependencyLayerReference;

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

@@ -269,7 +269,7 @@ export async function materializeDependencyLayer(packageRoot, dataDir, paths, op
     }
 }
 /** Read trusted layer certification and canonical metadata without rereading every payload byte. */
-export async function readCertifiedDependencyLayer(dataDir, layerId, expected) {
+export async function readCertifiedDependencyLayer(dataDir, layerId, expected, options = {}) {
     const layersRoot = await realpath(resolve(dataDir, "dependency-layers"));
     const layerRoot = await realpath(resolveWithin(layersRoot, layerId));
     assertDirectChild(layersRoot, layerRoot);
@@ -278,14 +278,23 @@ export async function readCertifiedDependencyLayer(dataDir, layerId, expected) {
         throw new Error(`dependency layer is not a managed non-link directory: ${layerId}`);
     const manifest = JSON.parse(await readFile(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "utf8"));
     validateLayerManifest(manifest);
-    const certification = JSON.parse(await readFile(certificationPath(dataDir, layerId), "utf8"));
-    if (certification.schema !== PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema || certification.layerId !== manifest.layerId || certification.contentDigest !== manifest.contentDigest
-        || certification.platform !== process.platform || certification.platformPolicy !== immutablePlatformPolicy()) {
-        throw new Error(`dependency layer certification differs from manifest: ${layerId}`);
-    }
     if (expected && (expected.layerId !== manifest.layerId || expected.contentDigest !== manifest.contentDigest)) {
         throw new Error(`dependency layer identity mismatch: ${layerId}`);
     }
+    const certification = JSON.parse(await readFile(certificationPath(dataDir, layerId), "utf8"));
+    const identityMatches = certification.schema === PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema
+        && certification.layerId === manifest.layerId && certification.contentDigest === manifest.contentDigest;
+    const currentPlatformEvidence = certification.platform === process.platform && certification.platformPolicy === immutablePlatformPolicy();
+    // Compatibility: the updater that introduced layers certified these exact identities but did
+    // not record platform fields. Only an authenticated parent-started supervisor opts into this
+    // transition; durable/reuse readers remain strict and cannot treat the legacy marker as authority.
+    const legacyParentCertification = options.allowLegacyParentCertification === true
+        && certification.platform === undefined && certification.platformPolicy === undefined;
+    if (!identityMatches || (!currentPlatformEvidence && !legacyParentCertification)) {
+        throw new Error(`dependency layer certification differs from manifest: ${layerId}`);
+    }
+    if (legacyParentCertification)
+        await writeLayerCertification(dataDir, manifest);
     return { ...manifest, layerRoot };
 }
 /** Fully verify a layer when certification is absent or explicit tamper evidence is required. */

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

@@ -10,5 +10,6 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

package/dist/foundation/release/index.js

@@ -10,5 +10,6 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

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

@@ -9,6 +9,7 @@ import { resolveProductPaths } from "../lifecycle/index.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
 import { DEPENDENCY_LAYER_MANIFEST, dependencyLayerCertificationPath } from "./dependency-layer.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
+import { cleanupUpdateRecoveryCapsules } from "./update-recovery.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { collectCompileCaches, startupCompileCachePath } from "../startup/index.js";
 const DEFAULT_CANDIDATE_AGE_MS = 60 * 60 * 1_000;
@@ -115,6 +116,7 @@ export async function runBoundedReleaseCleanup(dataDir, paths, options = {}) {
     }
     if (!activeTransaction && hasTime()) {
         await collectCompileCaches(dataDir, await protectedCompileCachePaths(dataDir, await store.read())).catch(() => { });
+        await cleanupUpdateRecoveryCapsules(dataDir).catch(() => { });
     }
     const remaining = Object.keys((await store.read()).cleanup.pending).length;
     return { planned: pending.length + artifacts.length, attempted, completed, remaining, durationMs: Math.max(0, now() - startedAt) };

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

@@ -1,5 +1,5 @@
 import { type ReleaseIdentity } from "./release.js";
-import { type RuntimePayloadInventory } from "./dependency-layer.js";
+import { type ReadCertifiedDependencyLayerOptions, type RuntimePayloadInventory } from "./dependency-layer.js";
 export declare const RELEASE_MANIFEST_FILENAME: string;
 export interface MaterializedRelease extends ReleaseIdentity {
     readonly releaseRoot: string;
@@ -29,6 +29,8 @@ export interface CertifiedReleaseRecord {
     readonly packageVersion?: string;
     readonly contentDigest: string;
 }
+/** 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;
@@ -39,7 +41,7 @@ export declare function readMaterializedRelease(releaseRoot: string, selectedSto
  * establish one of those preconditions; untrusted releases require full
  * verification.
  */
-export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string): Promise<MaterializedRelease>;
+export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string, options?: ReadCertifiedReleaseManifestOptions): Promise<MaterializedRelease>;
 export declare function verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, selectedStoreRoot?: string, options?: VerifyMaterializedReleaseOptions): Promise<MaterializedRelease>;
 export declare function assertImmutableExecutionRoot(release: MaterializedRelease, dataDir: string): Promise<void>;
 export declare function resolveReleaseEntryPoint(release: MaterializedRelease, entryPoint: string): Promise<string>;

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

@@ -106,7 +106,7 @@ export async function readMaterializedRelease(releaseRoot, selectedStoreRoot) {
  * establish one of those preconditions; untrusted releases require full
  * verification.
  */
-export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
+export async function readCertifiedReleaseManifest(record, selectedStoreRoot, options = {}) {
     const canonical = await realpath(record.releaseRoot);
     const canonicalStoreRoot = await realpath(selectedStoreRoot);
     assertContained(canonicalStoreRoot, canonical, "release root is outside the selected release store");
@@ -118,7 +118,7 @@ export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
     }
     if (canonical.split(sep).at(-1) !== manifest.releaseId)
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
-    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], false);
+    await verifyReleaseDependencies(canonical, canonicalStoreRoot, manifest.dependencyLayers ?? [], false, {}, options);
     return { ...manifest, releaseRoot: canonical };
 }
 export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot, options = {}) {
@@ -162,7 +162,7 @@ export async function resolveReleaseEntryPoint(release, entryPoint) {
     assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
     return canonical;
 }
-async function verifyReleaseDependencies(releaseRoot, storeRoot, references, fullVerification, options = {}) {
+async function verifyReleaseDependencies(releaseRoot, storeRoot, references, fullVerification, options = {}, certificationOptions = {}) {
     if (references.length === 0)
         return;
     if (references.length !== 1)
@@ -171,7 +171,7 @@ async function verifyReleaseDependencies(releaseRoot, storeRoot, references, ful
     const reference = references[0];
     const layer = fullVerification
         ? await verifyDependencyLayer(dataDir, reference, event => options.onOperation?.({ operation: event.operation, path: event.path, bytes: event.bytes }))
-        : await readCertifiedDependencyLayer(dataDir, reference.layerId, reference);
+        : await readCertifiedDependencyLayer(dataDir, reference.layerId, reference, certificationOptions);
     const binding = resolveWithin(releaseRoot, reference.binding);
     const metadata = await lstat(binding);
     if (!metadata.isSymbolicLink())

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

@@ -0,0 +1,74 @@
+import type { UpdateTransaction, UpdateRecoveryState } from "./update-transaction.js";
+export declare const UPDATE_RECOVERY_SCHEMA: "a1-update-recovery-v1";
+export interface UpdateRecoveryCapsule {
+    readonly schema: typeof UPDATE_RECOVERY_SCHEMA;
+    readonly transactionId: string;
+    readonly packageName: string;
+    readonly targetVersion: string;
+    readonly packageRoot: string;
+    readonly globalRoot: string;
+    readonly launcherRoot: string;
+    readonly launchers: readonly string[];
+    readonly priorReleaseId: string;
+    readonly priorReleaseRoot: string;
+    readonly priorContentDigest: string;
+    readonly releaseManifestName: string;
+    readonly recoveryEntry: string;
+    readonly recoveryEntryDigest: string;
+    readonly nodeExecutable: string;
+    readonly npmCli: string;
+    readonly npmArguments: readonly string[];
+    readonly cancellationPath: string;
+    readonly resultPath: string;
+    readonly ownerPath: string;
+    readonly createdAt: string;
+}
+export interface UpdateRecoveryResult {
+    readonly schema: typeof UPDATE_RECOVERY_SCHEMA;
+    readonly transactionId: string;
+    readonly outcome: "installed" | "recovery-launcher" | "failed";
+    readonly npmExitCode: number | null;
+    readonly cancelled: boolean;
+    readonly launcherDisposition: "target" | "recovery" | "unavailable";
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly completedAt: string;
+}
+export interface ProtectedPackageReplacementOptions {
+    readonly dataDir: string;
+    readonly globalRoot: string;
+    readonly packageRoot: string;
+    readonly transaction: UpdateTransaction;
+    readonly priorRelease: {
+        readonly releaseId: string;
+        readonly releaseRoot: string;
+        readonly contentDigest: string;
+    };
+    readonly output: {
+        stderr(message: string): void;
+    };
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly timeoutMs?: number;
+    readonly workerSpawner?: (entry: string, manifestPath: string, environment: NodeJS.ProcessEnv) => Promise<void>;
+    readonly onRecoveryState?: (state: UpdateRecoveryState) => Promise<void>;
+}
+export interface ProtectedPackageReplacementResult extends UpdateRecoveryResult {
+    readonly recovery: UpdateRecoveryState;
+}
+/** Resolve the complete public launcher set npm owns for the active platform. */
+export declare function updateLauncherPaths(globalRoot: string, platform?: NodeJS.Platform): readonly string[];
+/** Validate transaction-scoped recovery authority without trusting npm temporary names. */
+export declare function readUpdateRecoveryCapsule(manifestPath: string, platform?: NodeJS.Platform): Promise<UpdateRecoveryCapsule>;
+/** Prepare durable recovery authority before npm can mutate the live launcher set. */
+export declare function prepareUpdateRecoveryCapsule(options: ProtectedPackageReplacementOptions): Promise<{
+    capsule: UpdateRecoveryCapsule;
+    manifestPath: string;
+}>;
+/** Execute global replacement behind a detached owner and coordinate terminal cancellation. */
+export declare function runProtectedPackageReplacement(options: ProtectedPackageReplacementOptions): Promise<ProtectedPackageReplacementResult>;
+export declare function removeUpdateRecoveryCapsule(dataDir: string, transactionId: string): Promise<void>;
+/** Classify a complete launcher set without following linked or mixed launcher files. */
+export declare function inspectUpdateLauncherSet(capsule: UpdateRecoveryCapsule, platform?: NodeJS.Platform): Promise<"target" | "recovery" | "unavailable">;
+/** Remove terminal recovery capsules only after no canonical launcher references them. */
+export declare function cleanupUpdateRecoveryCapsules(dataDir: string): Promise<void>;