@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } 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";
+import { managedDependencyCertificationPath } from "./dependency-certification.js";
+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";
+const RESTART_SEAL_VERSION = 1;
+const REQUIRED_LAUNCH_ENTRIES = ["bin/supervisor.js", "bin/guardian.js"];
+/** Build compact restart authority after complete content verification established read-only payload files. */
+export async function createRestartSeal(release, dataDir) {
+    const policy = immutablePlatformPolicy();
+    if (policy === null)
+        return null;
+    const canonicalData = await realpath(dataDir);
+    const releasesRoot = await realpath(resolve(canonicalData, "releases"));
+    const releaseRoot = await realpath(release.releaseRoot);
+    assertDirectChild(releasesRoot, releaseRoot, release.releaseId, "release");
+    const manifestPath = resolve(releaseRoot, RELEASE_MANIFEST_FILENAME);
+    const launchEntries = REQUIRED_LAUNCH_ENTRIES.map(path => release.files.find(candidate => candidate.path === path));
+    if (launchEntries.some(file => file === undefined))
+        return null;
+    const certifiedLaunchEntries = launchEntries;
+    const layersRoot = release.dependencyLayers?.length ? await realpath(resolve(canonicalData, "dependency-layers")) : null;
+    const dependencyLayers = await Promise.all((release.dependencyLayers ?? []).map(async (reference) => {
+        if (layersRoot === null)
+            throw new Error("restart certification has no dependency-layer root");
+        await readCertifiedDependencyLayer(canonicalData, reference.layerId, reference);
+        const layerRoot = await realpath(resolve(layersRoot, reference.layerId));
+        assertDirectChild(layersRoot, layerRoot, reference.layerId, "dependency layer");
+        const bindingPath = resolve(releaseRoot, reference.binding);
+        const bindingTarget = await realpath(bindingPath);
+        const expectedTarget = await realpath(resolve(layerRoot, "node_modules"));
+        if (bindingTarget !== expectedTarget)
+            throw new Error(`restart certification dependency binding targets unexpected content: ${bindingPath}`);
+        return {
+            ...reference,
+            layerRoot: await pathEvidence(layerRoot, "directory"),
+            manifest: await pathEvidence(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "file"),
+            certification: await pathEvidence(dependencyLayerCertificationPath(canonicalData, reference.layerId), "file"),
+            bindingEvidence: await pathEvidence(bindingPath, "binding", true),
+            bindingTarget,
+        };
+    }));
+    const core = {
+        version: RESTART_SEAL_VERSION,
+        launchContract: launchContractTarget(release),
+        platform: process.platform,
+        platformPolicy: policy,
+        releaseId: release.releaseId,
+        packageVersion: release.packageVersion,
+        contentDigest: release.contentDigest,
+        packageRoot: release.packageRoot,
+        releaseRoot: await pathEvidence(releaseRoot, "directory"),
+        manifest: await pathEvidence(manifestPath, "file"),
+        launchEntries: certifiedLaunchEntries,
+        launchEntryEvidence: await Promise.all(certifiedLaunchEntries.map(file => pathEvidence(resolve(releaseRoot, file.path), "file"))),
+        dependencyLayers,
+        certifiedAt: new Date().toISOString(),
+    };
+    return { ...core, sealDigest: restartSealDigest(core) };
+}
+/** Recover an approved release from durable bounded evidence without traversing its payload. */
+export async function readRestartCertifiedRelease(record, dataDir, onEvent) {
+    const transaction = await new UpdateTransactionStore(dataDir).read();
+    if (transaction?.status === "active")
+        throw new Error("restart certification is unavailable during an active update transaction");
+    const certificationPath = resolve(dataDir, `certification-${record.releaseId}.json`);
+    if (record.diagnosticsPath !== undefined && record.diagnosticsPath !== certificationPath) {
+        throw new Error("restart certification path differs from the approved release record");
+    }
+    const certificationMetadata = await lstat(certificationPath);
+    onEvent?.({ operation: "restart-evidence-read", path: certificationPath });
+    if (!certificationMetadata.isFile() || certificationMetadata.isSymbolicLink() || (certificationMetadata.mode & 0o222) !== 0) {
+        throw new Error("restart certification is not an immutable regular file");
+    }
+    const certification = await readJson(certificationPath, onEvent);
+    if (certification.schema !== PRODUCT_IDENTITY.evidence.releaseCertificationSchema
+        || certification.releaseId !== record.releaseId || certification.contentDigest !== record.contentDigest
+        || !certification.checks.some(check => check.id === "immutable-content" && check.passed)) {
+        throw new Error("restart certification differs from the approved release record");
+    }
+    const seal = normalizeRestartSeal(certification.restartSeal);
+    // Invariant: a seal is restart authority only for a handoff this build can still
+    // perform, which is the contract it emits or the pre-cutover one it retains.
+    if (seal.launchContract !== PRIVATE_LAUNCH_CONTRACT && seal.launchContract !== "superseded") {
+        throw new Error(`restart seal declares an unsupported launch contract: ${String(seal.launchContract)}`);
+    }
+    if (seal.platform !== process.platform || seal.platformPolicy !== immutablePlatformPolicy()) {
+        throw new Error("restart certification platform immutability evidence is unsupported");
+    }
+    if (seal.releaseId !== record.releaseId || seal.contentDigest !== record.contentDigest
+        || resolve(seal.releaseRoot.path) !== resolve(record.releaseRoot)
+        || (record.packageVersion !== undefined && seal.packageVersion !== record.packageVersion)) {
+        throw new Error("restart seal differs from the approved release identity");
+    }
+    const { sealDigest, ...core } = seal;
+    if (restartSealDigest(core) !== sealDigest)
+        throw new Error("restart seal digest is invalid");
+    const canonicalData = await observedRealpath(dataDir, onEvent);
+    const releasesRoot = await observedRealpath(resolve(canonicalData, "releases"), onEvent);
+    const releaseRoot = await observedRealpath(seal.releaseRoot.path, onEvent);
+    assertDirectChild(releasesRoot, releaseRoot, seal.releaseId, "release");
+    await assertPathEvidence(seal.releaseRoot, onEvent);
+    await assertPathEvidence(seal.manifest, onEvent);
+    for (let index = 0; index < seal.launchEntries.length; index += 1) {
+        const file = seal.launchEntries[index];
+        if (!REQUIRED_LAUNCH_ENTRIES.includes(file.path)) {
+            throw new Error(`restart seal contains an unexpected launch entry: ${file.path}`);
+        }
+        const evidence = seal.launchEntryEvidence[index];
+        if (!evidence || evidence.path !== resolve(releaseRoot, file.path) || file.bytes !== Number(evidence.size)) {
+            throw new Error(`restart launch entry evidence differs: ${file.path}`);
+        }
+        await assertPathEvidence(evidence, onEvent);
+    }
+    if (seal.launchEntries.length !== REQUIRED_LAUNCH_ENTRIES.length)
+        throw new Error("restart seal launch entries are incomplete");
+    const layersRoot = seal.dependencyLayers.length ? await observedRealpath(resolve(canonicalData, "dependency-layers"), onEvent) : null;
+    for (const layer of seal.dependencyLayers) {
+        if (layersRoot === null)
+            throw new Error("restart seal has no dependency-layer root");
+        const layerRoot = await observedRealpath(layer.layerRoot.path, onEvent);
+        assertDirectChild(layersRoot, layerRoot, layer.layerId, "dependency layer");
+        await assertPathEvidence(layer.layerRoot, onEvent);
+        await assertPathEvidence(layer.manifest, onEvent);
+        const legacyPath = legacyDependencyLayerCertificationPath(canonicalData, layer.layerId);
+        const canonicalPath = dependencyLayerCertificationPath(canonicalData, layer.layerId);
+        if (layer.certification.path !== legacyPath && layer.certification.path !== canonicalPath) {
+            throw new Error("restart dependency certification path is outside managed storage");
+        }
+        await managedDependencyCertificationPath(canonicalData, layer.layerId, layer.certification.path === legacyPath);
+        await assertPathEvidence(layer.certification, onEvent);
+        await assertPathEvidence(layer.bindingEvidence, onEvent, true);
+        const bindingTarget = await observedRealpath(layer.bindingEvidence.path, onEvent);
+        const expectedTarget = await observedRealpath(resolve(layerRoot, "node_modules"), onEvent);
+        if (bindingTarget !== layer.bindingTarget || bindingTarget !== expectedTarget) {
+            throw new Error(`restart dependency binding targets unexpected content: ${layer.bindingEvidence.path}`);
+        }
+    }
+    return {
+        packageName: PRODUCT_PACKAGE_NAME,
+        launchContract: seal.launchContract,
+        packageVersion: seal.packageVersion,
+        contentDigest: seal.contentDigest,
+        releaseId: seal.releaseId,
+        packageRoot: seal.packageRoot,
+        files: seal.launchEntries,
+        ...(seal.dependencyLayers.length === 0 ? {} : {
+            dependencyLayers: seal.dependencyLayers.map(({ layerId, contentDigest, binding }) => ({ layerId, contentDigest, binding })),
+        }),
+        releaseRoot,
+    };
+}
+export function releaseCertificationDocument(release, restartSeal, verifiedAt = new Date().toISOString()) {
+    return {
+        schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,
+        releaseId: release.releaseId,
+        contentDigest: release.contentDigest,
+        verifiedAt,
+        checks: [{ id: "immutable-content", passed: true }],
+        restartSeal,
+    };
+}
+export function restartSealDigest(core) {
+    return createHash("sha256").update(JSON.stringify(core)).digest("hex");
+}
+async function assertPathEvidence(evidence, onEvent, symbolic = false) {
+    const actual = await pathEvidence(evidence.path, evidence.kind, symbolic, onEvent);
+    if (JSON.stringify(actual) !== JSON.stringify(evidence))
+        throw new Error(`restart path evidence changed: ${evidence.path}`);
+}
+async function pathEvidence(path, kind, symbolic = false, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    const metadata = symbolic ? await lstat(path, { bigint: true }) : await stat(path, { bigint: true });
+    if ((kind === "directory") !== metadata.isDirectory())
+        throw new Error(`restart evidence kind changed: ${path}`);
+    if (kind === "file" && !metadata.isFile())
+        throw new Error(`restart evidence file changed: ${path}`);
+    if (kind === "binding" && !metadata.isSymbolicLink())
+        throw new Error(`restart evidence binding changed: ${path}`);
+    if (kind === "file" && (metadata.mode & 146n) !== 0n)
+        throw new Error(`restart evidence file is writable: ${path}`);
+    return {
+        path: resolve(path),
+        kind,
+        device: metadata.dev.toString(),
+        inode: metadata.ino.toString(),
+        mode: Number(metadata.mode),
+        size: metadata.size.toString(),
+        modifiedNs: metadata.mtimeNs.toString(),
+        changedNs: metadata.ctimeNs.toString(),
+        bornNs: metadata.birthtimeNs.toString(),
+    };
+}
+function normalizeRestartSeal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("release certification has no durable restart seal");
+    const seal = value;
+    if (seal.version !== RESTART_SEAL_VERSION || typeof seal.platform !== "string" || typeof seal.platformPolicy !== "string"
+        || typeof seal.releaseId !== "string" || typeof seal.packageVersion !== "string" || typeof seal.contentDigest !== "string"
+        || typeof seal.packageRoot !== "string" || typeof seal.certifiedAt !== "string" || typeof seal.sealDigest !== "string"
+        || !seal.releaseRoot || !seal.manifest || !Array.isArray(seal.launchEntries) || !Array.isArray(seal.launchEntryEvidence)
+        || !Array.isArray(seal.dependencyLayers)) {
+        throw new Error("durable restart seal is invalid");
+    }
+    return seal;
+}
+async function readJson(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function observedRealpath(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    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) {
+        throw new Error(`restart ${kind} is outside its managed store: ${child}`);
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Leaf types shared across the release subsystem. They live here so that the transaction store,
+ * launch selection, and dependency layers can name them without importing the update command or
+ * the release reader, which is what closed the subsystem's import cycles.
+ */
+export type UpdateChannel = "stable" | "next";
+export interface DependencyLayerReference {
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly binding: "node_modules";
+}

package/dist/foundation/release/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+import type { CohortState, ReleaseRecord } from "./cohort-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;
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export declare function selectSupervisorLaunchReleaseId(state: CohortState, transaction: UpdateTransaction | null): string | null;

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

@@ -0,0 +1,17 @@
+/** Keep interactive launches on the last successful release until the update commits success. */
+export function selectUpdateLaunchRelease(state, transaction) {
+    if (transaction === null || transaction.status === "completed")
+        return null;
+    const prior = transaction.priorActiveReleaseId === null ? undefined : state.releases[transaction.priorActiveReleaseId];
+    if (!prior || prior.approval !== "approved") {
+        throw new Error("unfinished update has no verified previous release available for launch; resume the update");
+    }
+    return prior;
+}
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export function selectSupervisorLaunchReleaseId(state, transaction) {
+    // Concurrency: both the previous cohort and the warming candidate must remain available until cutover.
+    if (transaction?.status === "active")
+        return null;
+    return selectUpdateLaunchRelease(state, transaction)?.releaseId ?? state.references.active;
+}

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

@@ -0,0 +1,76 @@
+import { PRIVATE_LAUNCH_CONTRACT } from "../launch-context/index.js";
+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 launchContract: typeof PRIVATE_LAUNCH_CONTRACT;
+    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>;