@timurproko/a1 0.1.8-dev.299 → 0.1.8-dev.332

package/dist/foundation/launch-context/index.js

@@ -0,0 +1,136 @@
+/** The contract this build emits; supersedes the pre-cutover key set it still accepts. */
+export const PRIVATE_LAUNCH_CONTRACT = "neutral-launch-v1";
+export const PRIVATE_ENVIRONMENT = Object.freeze({
+    releaseRoot: "LAUNCH_CONTEXT_RELEASE_ROOT",
+    releaseId: "LAUNCH_CONTEXT_RELEASE_ID",
+    releaseDigest: "LAUNCH_CONTEXT_RELEASE_DIGEST",
+    releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS",
+    launchProfile: "LAUNCH_CONTEXT_PROFILE",
+    immutableWarmup: "LAUNCH_CONTEXT_WARMUP",
+});
+/**
+ * Keys published by releases that predate the neutral cutover. They are read when
+ * an older launcher hands this build a process, and written when this build
+ * starts a release that declares no contract of its own, so an upgrade never
+ * depends on both sides having been rebuilt at the same moment.
+ */
+export const SUPERSEDED_ENVIRONMENT = Object.freeze({
+    releaseRoot: "A1_RELEASE_ROOT",
+    releaseId: "A1_RELEASE_ID",
+    releaseDigest: "A1_RELEASE_DIGEST",
+    releaseLayers: "A1_RELEASE_LAYERS",
+    launchProfile: "A1_LAUNCH_PROFILE",
+    immutableWarmup: "A1_IMMUTABLE_WARMUP",
+});
+const PRIVATE_ENTRIES = Object.entries(PRIVATE_ENVIRONMENT);
+const SUPERSEDED_ENTRIES = Object.entries(SUPERSEDED_ENVIRONMENT);
+const PRIVATE_KEYS = new Set([...Object.values(PRIVATE_ENVIRONMENT), ...Object.values(SUPERSEDED_ENVIRONMENT)]);
+const LOGICAL_KEYS = new Map(PRIVATE_ENTRIES.map(([logical, key]) => [key, logical]));
+const SUPERSEDED_LOGICAL_KEYS = new Map(SUPERSEDED_ENTRIES.map(([logical, key]) => [key, logical]));
+/** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
+export function readLaunchContext(environment, requirement = "optional", platform = process.platform) {
+    const values = {};
+    const superseded = {};
+    // Performance: enumerate names only for Windows casing; never fetch unrelated environment values.
+    if (platform === "win32") {
+        for (const name of Object.keys(environment)) {
+            const upper = name.toUpperCase();
+            const logical = LOGICAL_KEYS.get(upper);
+            if (logical !== undefined)
+                acceptValue(values, logical, environment[name]);
+            const supersededLogical = SUPERSEDED_LOGICAL_KEYS.get(upper);
+            if (supersededLogical !== undefined)
+                acceptValue(superseded, supersededLogical, environment[name]);
+        }
+    }
+    else {
+        for (const [logical, key] of PRIVATE_ENTRIES) {
+            if (Object.prototype.propertyIsEnumerable.call(environment, key))
+                acceptValue(values, logical, environment[key]);
+        }
+        for (const [logical, key] of SUPERSEDED_ENTRIES) {
+            if (Object.prototype.propertyIsEnumerable.call(environment, key))
+                acceptValue(superseded, logical, environment[key]);
+        }
+    }
+    // Compatibility: the current key wins wherever both are present, so a launcher that
+    // emits this contract is never overruled by an inherited pre-cutover value.
+    for (const [logical, value] of Object.entries(superseded))
+        if (values[logical] === undefined)
+            values[logical] = value;
+    if (values.launchProfile !== undefined && values.launchProfile !== "a1" && values.launchProfile !== "pi") {
+        throw invalidContext("launchProfile", "unsupported profile");
+    }
+    if (values.immutableWarmup !== undefined && values.immutableWarmup !== "1")
+        throw invalidContext("immutableWarmup", "invalid permission flag");
+    if (values.releaseDigest !== undefined && !/^[a-f0-9]{64}$/.test(values.releaseDigest))
+        throw invalidContext("releaseDigest", "invalid digest");
+    if (requirement === "profile")
+        requireFields(values, ["launchProfile"]);
+    if (requirement === "release" || requirement === "warmup") {
+        requireFields(values, ["releaseRoot", "releaseId", "releaseDigest"]);
+        // Compatibility: Windows drops an empty value from a child environment block, so a
+        // release with no dependency layer arrives without the key it was given. The
+        // layer list is metadata of the release being started, never authority, and an
+        // absent list means the same thing the empty string does.
+        if (values.releaseLayers === undefined)
+            values.releaseLayers = "";
+    }
+    if (requirement === "warmup")
+        requireFields(values, ["immutableWarmup"]);
+    return Object.freeze(values);
+}
+/** The key set a process started for this release must receive. */
+export function launchEnvironmentKeys(contract) {
+    return contract === PRIVATE_LAUNCH_CONTRACT ? PRIVATE_ENVIRONMENT : SUPERSEDED_ENVIRONMENT;
+}
+/** Classify metadata by the contract it declares rather than rejecting what it omits. */
+export function launchContractTarget(value) {
+    return value.launchContract === PRIVATE_LAUNCH_CONTRACT ? PRIVATE_LAUNCH_CONTRACT : "superseded";
+}
+/** Whether metadata was produced by a build that declares this contract. */
+export function isCurrentLaunchContract(value) {
+    return value.launchContract === PRIVATE_LAUNCH_CONTRACT;
+}
+/**
+ * Rebuild owned context without inheriting a prior session's private selection. The
+ * contract selects which key set is written, so this build can start either its
+ * own releases or a retained pre-cutover release it must keep serving.
+ */
+export function withLaunchContext(environment, context, platform = process.platform, contract = PRIVATE_LAUNCH_CONTRACT) {
+    const result = withoutLaunchContext(environment, platform);
+    for (const [logical, key] of Object.entries(launchEnvironmentKeys(contract))) {
+        const value = context[logical];
+        if (value !== undefined)
+            result[key] = value;
+    }
+    readLaunchContext(result, "optional", platform);
+    return result;
+}
+/** Remove both key sets, leaving user and integration settings intact. */
+export function withoutLaunchContext(environment, platform = process.platform) {
+    return Object.fromEntries(Object.entries(environment).filter(([key]) => !PRIVATE_KEYS.has(platform === "win32" ? key.toUpperCase() : key)));
+}
+/** Require this build's own contract where nothing older can be accepted, such as recovery capsules. */
+export function assertCurrentLaunchContract(value) {
+    if (value.launchContract !== PRIVATE_LAUNCH_CONTRACT) {
+        throw new Error("Unsupported private launch contract. Stop existing processes and install the current package directly with npm; review disposable runtime/release state before any manual reset. User settings, sessions, and history must be preserved.");
+    }
+}
+function acceptValue(values, logical, value) {
+    if (value === undefined)
+        return;
+    if (values[logical] !== undefined && values[logical] !== value)
+        throw invalidContext(logical, "conflicting environment key casing");
+    if (typeof value !== "string" || value.includes("\0") || (value.length === 0 && logical !== "releaseLayers"))
+        throw invalidContext(logical, "invalid value");
+    values[logical] = value;
+}
+function requireFields(values, fields) {
+    for (const field of fields)
+        if (values[field] === undefined)
+            throw invalidContext(field, "required current-contract field is missing");
+}
+function invalidContext(logical, reason) {
+    return new Error(`Invalid private launch context (${logical}): ${reason}`);
+}

package/dist/foundation/launch-guardian/main.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { readLaunchContext } from "../launch-context/index.js";
 import { resolve } from "node:path";
 import { assertLaunchProfileId, sessionSelectionArguments } from "../lifecycle/index.js";
 import { closeVerifiedContainment, DarwinNativeProcessInspector, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
@@ -20,10 +21,11 @@ export async function runLaunchGuardian(options) {
     const guardianIdentity = await inspector.observe(process.pid);
     if (!guardianIdentity)
         throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
-    const client = options.control ?? new SupervisorClient(environment[PRODUCT_IDENTITY.environment.releaseId]);
+    const context = readLaunchContext(environment);
+    const client = options.control ?? new SupervisorClient(context.releaseId);
     // Invariant: an instance belongs to the cohort that launched it and talks to that cohort's endpoint
     // for its whole life, whatever release becomes the active one meanwhile.
-    const releaseId = environment[PRODUCT_IDENTITY.environment.releaseId];
+    const releaseId = context.releaseId;
     const endpoint = releaseId
         ? resolveCohortEndpoint(paths, releaseId, environment).endpoint
         : paths.endpoint;
@@ -174,5 +176,5 @@ function exitCode(outcome) {
     return 1;
 }
 function diagnosticError(message, code) {
-    return Object.assign(new Error(`A1: ${message}`), { code });
+    return Object.assign(new Error(`${PRODUCT_TEXT.displayName}: ${message}`), { code });
 }

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

@@ -36,7 +36,12 @@ export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdenti
     }>;
 }
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
-export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease): NodeJS.ProcessEnv;
+/**
+ * Hand a release the key set its own build reads. A retained pre-cutover release is
+ * still startable this way, which is what lets a launch fall back to the previous
+ * version instead of failing while an installation is being replaced.
+ */
+export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease, profile?: LaunchProfileId): NodeJS.ProcessEnv;
 export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number, startup?: SupervisorStartupAttempt): Promise<void>;
 export declare function readEndpointMetadata(path: string): Promise<SupervisorEndpointMetadata | null>;
 export declare function probeOwnership(metadata: SupervisorEndpointMetadata): Promise<OwnershipProbe>;

package/dist/foundation/release/bootstrap.js

@@ -15,15 +15,15 @@ import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { markStartupPhase } from "../startup/index.js";
+import { launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
 export async function runBootstrap(options) {
-    const environment = { ...(options.environment ?? process.env) };
+    const environment = withLaunchContext(options.environment ?? process.env, { launchProfile: options.launchIntent?.profileId ?? "a1" });
     await markStartupPhase(environment, "bootstrap-start");
     const launchProfileId = options.launchIntent?.profileId ?? "a1";
     assertLaunchProfileId(launchProfileId);
     const sessionArgs = sessionSelectionArguments(options.launchIntent?.sessionSelection);
     if (sessionArgs.length > 0 && launchProfileId !== "a1")
         throw new Error("session selection requires the normal A1 profile");
-    environment[PRODUCT_IDENTITY.environment.launchProfile] = launchProfileId;
     const output = options.output ?? process.stderr;
     const paths = resolveProductPaths(environment);
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
@@ -88,7 +88,20 @@ export async function runBootstrap(options) {
             return await launchUi(retained, environment, sessionArgs);
         }
     }
-    const candidate = await materializeRelease(options.packageRoot, paths.dataDir);
+    // Concurrency: an installation being replaced is not a reason to refuse a launch. While
+    // npm is rewriting the package tree the candidate cannot be read consistently, so a
+    // launch that cannot take the installed payload starts the retained active release
+    // instead and leaves activation to the launch that follows the replacement.
+    let candidate;
+    try {
+        candidate = await materializeRelease(options.packageRoot, paths.dataDir);
+    }
+    catch (error) {
+        const fallback = await launchRetainedActive(state, paths, environment, sessionArgs, output);
+        if (fallback === null)
+            throw error;
+        return fallback;
+    }
     await stateStore.recordCandidate(candidate);
     state = await stateStore.read();
     if (!state.references.active) {
@@ -183,6 +196,34 @@ export async function runBootstrap(options) {
     await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, selected.releaseId, environment).endpointMetadataPath, selected, 8_000, startup);
     return await launchUi(selected, environment, sessionArgs);
 }
+/**
+ * Start the retained active cohort when the installed payload cannot be taken. The
+ * release already carries certified evidence, so this reuses it rather than
+ * certifying anything new, and reports no selection when there is nothing safe
+ * to fall back to.
+ */
+async function launchRetainedActive(state, paths, environment, sessionArgs, output) {
+    const activeId = state.references.active;
+    const active = activeId === null ? undefined : state.releases[activeId];
+    if (!active || active.approval !== "approved")
+        return null;
+    try {
+        const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
+        const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
+        const endpoint = await readEndpointMetadata(retainedPaths.endpointMetadataPath);
+        if (!endpoint || await probeOwnership(endpoint) !== "live-verified") {
+            if (endpoint)
+                await removeEndpointArtifacts(retainedPaths.endpointMetadataPath, retainedPaths.endpoint);
+            const startup = await startSupervisor(retained, environment);
+            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000, startup);
+        }
+        output.write(`${PRODUCT_TEXT.diagnostic(`installation is being replaced; starting the retained release ${retained.packageVersion}`)}\n`);
+        return await launchUi(retained, environment, sessionArgs);
+    }
+    catch {
+        return null;
+    }
+}
 async function readInstalledVersion(packageRoot) {
     const manifest = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
     if (typeof manifest.version !== "string" || manifest.version.length === 0) {
@@ -230,22 +271,27 @@ async function launchUi(release, environment, sessionArgs) {
     const entry = await resolveReleaseEntryPoint(release, "bin/guardian.js");
     return await new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(process.execPath, [entry, ...sessionArgs], {
-            env: releaseEnvironment(environment, release),
+            env: releaseEnvironment(environment, release, readLaunchContext(environment, "profile").launchProfile),
             stdio: "inherit",
             windowsHide: false,
         });
         child.once("error", rejectPromise);
-        child.once("close", (code, signal) => resolvePromise(restoreAfterOwnedExit(environment[PRODUCT_IDENTITY.environment.launchProfile] === "a1", code, signal)));
+        child.once("close", (code, signal) => resolvePromise(restoreAfterOwnedExit(readLaunchContext(environment).launchProfile === "a1", code, signal)));
     });
 }
-export function releaseEnvironment(environment, release) {
-    return {
-        ...environment,
-        [PRODUCT_IDENTITY.environment.releaseId]: release.releaseId,
-        [PRODUCT_IDENTITY.environment.releaseLayers]: (release.dependencyLayers ?? []).map(layer => layer.layerId).join(","),
-        [PRODUCT_IDENTITY.environment.releaseRoot]: release.releaseRoot,
-        [PRODUCT_IDENTITY.environment.releaseDigest]: release.contentDigest,
-    };
+/**
+ * Hand a release the key set its own build reads. A retained pre-cutover release is
+ * still startable this way, which is what lets a launch fall back to the previous
+ * version instead of failing while an installation is being replaced.
+ */
+export function releaseEnvironment(environment, release, profile) {
+    return withLaunchContext(environment, {
+        releaseId: release.releaseId,
+        releaseLayers: (release.dependencyLayers ?? []).map(layer => layer.layerId).join(","),
+        releaseRoot: release.releaseRoot,
+        releaseDigest: release.contentDigest,
+        ...(profile === undefined ? {} : { launchProfile: profile }),
+    }, process.platform, launchContractTarget(release));
 }
 export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup) {
     const deadline = Date.now() + timeoutMs;

package/dist/foundation/release/cohort-state.d.ts

@@ -6,6 +6,7 @@ export interface ReleaseRecord {
     readonly releaseRoot: string;
     readonly packageVersion: string;
     readonly contentDigest: string;
+    readonly launchContract?: string;
     readonly approval: ReleaseApproval;
     readonly materializedAt: string;
     readonly certifiedAt: string | null;

package/dist/foundation/release/cohort-state.js

@@ -89,6 +89,7 @@ export class CohortStateStore {
                 releaseRoot: release.releaseRoot,
                 packageVersion: release.packageVersion,
                 contentDigest: release.contentDigest,
+                ...(release.launchContract === undefined ? {} : { launchContract: release.launchContract }),
                 approval: "candidate",
                 materializedAt: new Date().toISOString(),
                 certifiedAt: null,

package/dist/foundation/release/dependency-certification-retention.d.ts

@@ -0,0 +1,7 @@
+export interface DependencyCertificationProtection {
+    readonly referenced: Set<string>;
+    readonly legacyRequired: Set<string>;
+    readonly uncertain: boolean;
+}
+/** Inspect retained and not-yet-collected release metadata, never dependency payload bytes. */
+export declare function dependencyCertificationProtection(dataDir: string, retainedReleaseIds?: readonly string[]): Promise<DependencyCertificationProtection>;

package/dist/foundation/release/dependency-certification-retention.js

@@ -0,0 +1,88 @@
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { dependencyLayerCertificationPath } from "./dependency-certification.js";
+import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
+import { readRestartCertifiedRelease } from "./restart-certification.js";
+/** Inspect retained and not-yet-collected release metadata, never dependency payload bytes. */
+export async function dependencyCertificationProtection(dataDir, retainedReleaseIds = []) {
+    const referenced = new Set();
+    const legacyRequired = new Set();
+    const canonicalData = await realpath(dataDir);
+    const releasesRoot = resolve(canonicalData, "releases");
+    const roots = [];
+    let uncertain = false;
+    const rootMetadata = await lstat(releasesRoot);
+    if (!rootMetadata.isDirectory() || rootMetadata.isSymbolicLink())
+        return { referenced, legacyRequired, uncertain: true };
+    const entries = await readdir(releasesRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink()) {
+            uncertain = true;
+            continue;
+        }
+        if (!entry.isDirectory() || entry.name.startsWith(".candidate-"))
+            continue;
+        if (entry.name === ".trash") {
+            for (const trash of await readdir(resolve(releasesRoot, entry.name), { withFileTypes: true })) {
+                if (trash.isSymbolicLink())
+                    uncertain = true;
+                else if (trash.isDirectory() && !trash.name.startsWith(".candidate"))
+                    roots.push(resolve(releasesRoot, entry.name, trash.name));
+            }
+        }
+        else
+            roots.push(resolve(releasesRoot, entry.name));
+    }
+    const discoveredIds = new Set(roots.map(root => basename(root).split("--", 1)[0]));
+    if (retainedReleaseIds.some(id => !discoveredIds.has(id)))
+        uncertain = true;
+    for (const root of roots) {
+        try {
+            const manifestPath = resolve(root, RELEASE_MANIFEST_FILENAME);
+            const metadata = await lstat(manifestPath);
+            if (!metadata.isFile() || metadata.isSymbolicLink())
+                throw new Error("release manifest is not a regular file");
+            const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+            if (!manifest || !/^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/.test(manifest.releaseId)
+                || (manifest.dependencyLayers !== undefined && !Array.isArray(manifest.dependencyLayers)))
+                throw new Error("invalid retained release manifest");
+            const seal = await canonicalConsumerSeal(canonicalData, manifest.releaseId, manifest.contentDigest);
+            for (const layer of manifest.dependencyLayers ?? []) {
+                if (!layer || !/^dependencies-[a-f0-9]{32}$/.test(layer.layerId))
+                    throw new Error("invalid retained dependency reference");
+                referenced.add(layer.layerId);
+                const evidence = seal?.dependencyLayers.filter(item => item.layerId === layer.layerId);
+                if (evidence?.length !== 1 || evidence[0].contentDigest !== layer.contentDigest
+                    || evidence[0].certification?.path !== dependencyLayerCertificationPath(canonicalData, layer.layerId)) {
+                    // Compatibility: an absent, legacy, or uncertain seal cannot prove canonical-only use.
+                    legacyRequired.add(layer.layerId);
+                }
+            }
+        }
+        catch {
+            // Security: an unreadable retained manifest might reference any layer; do not guess ownership.
+            uncertain = true;
+        }
+    }
+    return { referenced, legacyRequired, uncertain };
+}
+async function canonicalConsumerSeal(dataDir, releaseId, contentDigest) {
+    try {
+        const path = resolve(dataDir, `certification-${releaseId}.json`);
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o222) !== 0)
+            return null;
+        const document = JSON.parse(await readFile(path, "utf8"));
+        if (document.schema !== PRODUCT_IDENTITY.evidence.releaseCertificationSchema || document.releaseId !== releaseId
+            || document.contentDigest !== contentDigest || !document.restartSeal)
+            return null;
+        // Security: path claims alone do not prove a canonical-only consumer. Reuse the bounded
+        // restart validator so stale, unsupported, or tampered seals conservatively retain legacy files.
+        await readRestartCertifiedRelease({ releaseId, contentDigest, releaseRoot: resolve(dataDir, "releases", releaseId) }, dataDir);
+        return document.restartSeal;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,24 @@
+export declare const DEPENDENCY_CERTIFICATIONS_DIRECTORY = "dependency-certifications";
+type LayerIdentity = {
+    readonly layerId: string;
+    readonly contentDigest: string;
+};
+export interface ReadDependencyCertificationOptions {
+    /** Only authenticated parent-started supervisors may upgrade missing platform evidence. */
+    readonly allowLegacyParentCertification?: boolean;
+    /** Cleanup must validate canonical evidence without migrating or falling back. */
+    readonly canonicalOnly?: boolean;
+}
+/** Derive the canonical record path without accepting path components as layer identities. */
+export declare function dependencyLayerCertificationPath(dataDir: string, layerId: string): string;
+/** Keep the historical filename solely for compatibility reads and managed cleanup. */
+export declare function legacyDependencyLayerCertificationPath(dataDir: string, layerId: string): string;
+/** Validate the dedicated directory before reading, creating, or deleting any contained record. */
+export declare function dependencyCertificationDirectory(dataDir: string, create?: boolean): Promise<string | null>;
+/** Resolve only direct regular managed records; callers never follow directory or record links. */
+export declare function managedDependencyCertificationPath(dataDir: string, layerId: string, legacy?: boolean): Promise<string | null>;
+/** Prefer canonical evidence; copy validated legacy evidence without changing its sealed source. */
+export declare function readDependencyCertification(dataDir: string, identity: LayerIdentity, options?: ReadDependencyCertificationOptions): Promise<void>;
+/** Publish certification after materialization/full verification, preserving an already-valid winner. */
+export declare function writeDependencyCertification(dataDir: string, identity: LayerIdentity): Promise<void>;
+export {};

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

@@ -0,0 +1,208 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { immutablePlatformPolicy } from "./immutable-platform.js";
+export const DEPENDENCY_CERTIFICATIONS_DIRECTORY = "dependency-certifications";
+/** Derive the canonical record path without accepting path components as layer identities. */
+export function dependencyLayerCertificationPath(dataDir, layerId) {
+    assertLayerId(layerId);
+    return resolve(dataDir, DEPENDENCY_CERTIFICATIONS_DIRECTORY, `${layerId}.json`);
+}
+/** Keep the historical filename solely for compatibility reads and managed cleanup. */
+export function legacyDependencyLayerCertificationPath(dataDir, layerId) {
+    assertLayerId(layerId);
+    return resolve(dataDir, `dependency-layer-certification-${layerId}.json`);
+}
+/** Validate the dedicated directory before reading, creating, or deleting any contained record. */
+export async function dependencyCertificationDirectory(dataDir, create = false) {
+    const canonicalData = await realpath(dataDir);
+    const directory = resolve(canonicalData, DEPENDENCY_CERTIFICATIONS_DIRECTORY);
+    if (create)
+        await mkdir(directory, { mode: 0o700 }).catch(error => {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        });
+    const metadata = await lstat(directory).catch(missingOrThrow);
+    if (metadata === null)
+        return null;
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpath(directory) !== directory) {
+        throw new Error("dependency certification directory is not a managed non-link directory");
+    }
+    return directory;
+}
+/** Resolve only direct regular managed records; callers never follow directory or record links. */
+export async function managedDependencyCertificationPath(dataDir, layerId, legacy = false) {
+    const canonicalData = await realpath(dataDir);
+    const path = legacy ? legacyDependencyLayerCertificationPath(canonicalData, layerId) : dependencyLayerCertificationPath(canonicalData, layerId);
+    if (!legacy && await dependencyCertificationDirectory(canonicalData) === null)
+        return null;
+    const metadata = await lstat(path).catch(missingOrThrow);
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || await realpath(path) !== path) {
+        throw new Error(`dependency certification is not a managed regular file: ${path}`);
+    }
+    return path;
+}
+/** Prefer canonical evidence; copy validated legacy evidence without changing its sealed source. */
+export async function readDependencyCertification(dataDir, identity, options = {}) {
+    const canonical = await managedDependencyCertificationPath(dataDir, identity.layerId);
+    const source = canonical ?? (options.canonicalOnly ? null : await managedDependencyCertificationPath(dataDir, identity.layerId, true));
+    if (source === null)
+        throw new Error(`dependency layer certification is absent: ${identity.layerId}`);
+    const document = JSON.parse(await readFile(source, "utf8"));
+    const legacyPlatform = validateCertification(document, identity, options.allowLegacyParentCertification === true);
+    if (!legacyPlatform && ((await lstat(source)).mode & 0o222) !== 0)
+        throw new Error("dependency certification is writable");
+    if (legacyPlatform) {
+        // Compatibility: only the authenticated parent path may replace older platform-less evidence.
+        await writeDependencyCertification(dataDir, identity);
+    }
+    else if (canonical === null) {
+        await publishCertification(dataDir, identity, document, false);
+    }
+}
+/** Publish certification after materialization/full verification, preserving an already-valid winner. */
+export async function writeDependencyCertification(dataDir, identity) {
+    await publishCertification(dataDir, identity, {
+        schema: PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema,
+        layerId: identity.layerId,
+        contentDigest: identity.contentDigest,
+        platform: process.platform,
+        platformPolicy: immutablePlatformPolicy(),
+        certifiedAt: new Date().toISOString(),
+    }, true);
+}
+async function publishCertification(dataDir, identity, document, replaceInvalid) {
+    const directory = (await dependencyCertificationDirectory(dataDir, true));
+    const path = dependencyLayerCertificationPath(dirname(directory), identity.layerId);
+    const lockPath = `${path}.lock`;
+    const releaseLock = await acquirePublicationLock(lockPath);
+    try {
+        await publishLockedCertification(dataDir, identity, document, replaceInvalid, path);
+    }
+    finally {
+        await releaseLock();
+    }
+}
+async function publishLockedCertification(dataDir, identity, document, replaceInvalid, path) {
+    const existing = await managedDependencyCertificationPath(dataDir, identity.layerId);
+    if (existing !== null) {
+        const source = await readFile(existing, "utf8");
+        const metadata = await lstat(existing);
+        try {
+            validateCertification(JSON.parse(source), identity);
+            // Invariant: full verification restores writable evidence; ordinary valid reuse is read-only.
+            if ((metadata.mode & 0o222) === 0)
+                return;
+            if (!replaceInvalid)
+                throw new Error("dependency certification is writable");
+        }
+        catch (error) {
+            if (!replaceInvalid)
+                throw error;
+        }
+        await rm(existing, { force: true });
+    }
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(document, null, 2), { flag: "wx", mode: 0o400 });
+        await chmod(temporary, 0o400);
+        await dependencyCertificationDirectory(dataDir);
+        // Concurrency: the per-layer lease protects the winner check and atomic publication together.
+        // Rename publishes final read-only metadata; no later temporary unlink changes sealed evidence.
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function acquirePublicationLock(path) {
+    const token = randomUUID();
+    const candidate = `${path}.candidate-${token}`;
+    await mkdir(candidate, { mode: 0o700 });
+    try {
+        await writeFile(resolve(candidate, "owner.json"), JSON.stringify({ pid: process.pid, token }), { flag: "wx", mode: 0o600 });
+        const deadline = Date.now() + 5_000;
+        while (true) {
+            try {
+                // Concurrency: a nonempty directory cannot replace another nonempty directory on either
+                // platform. Publishing the complete owner atomically also avoids partially written leases.
+                await rename(candidate, path);
+                return async () => {
+                    const released = `${path}.released-${token}`;
+                    await rename(path, released);
+                    await rm(released, { recursive: true, force: true });
+                };
+            }
+            catch (error) {
+                if (!["EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].some(code => hasCode(error, code)))
+                    throw error;
+                const metadata = await lstat(path).catch(missingOrThrow);
+                if (metadata !== null) {
+                    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                        throw new Error("dependency certification publication lock is not a managed directory");
+                    const ownerPath = resolve(path, "owner.json");
+                    const ownerMetadata = await lstat(ownerPath).catch(missingOrThrow);
+                    if (ownerMetadata !== null) {
+                        if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink())
+                            throw new Error("dependency certification publication owner is not a regular file");
+                        const owner = await readFile(ownerPath, "utf8").then(source => JSON.parse(source)).catch(error => {
+                            if (hasCode(error, "ENOENT"))
+                                return null;
+                            throw error;
+                        });
+                        if (owner !== null && Number.isSafeInteger(owner.pid) && owner.pid > 0 && /^[a-f0-9-]{36}$/.test(owner.token)) {
+                            let abandoned = false;
+                            try {
+                                process.kill(owner.pid, 0);
+                            }
+                            catch (probeError) {
+                                abandoned = hasCode(probeError, "ESRCH");
+                            }
+                            if (abandoned) {
+                                // Concurrency: retain this generation's nonempty tombstone. A delayed second reclaimer
+                                // cannot overwrite it and accidentally steal a newly acquired replacement lease.
+                                await rename(path, `${path}.abandoned-${owner.token}`).catch(error => {
+                                    if (!["ENOENT", "EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].some(code => hasCode(error, code)))
+                                        throw error;
+                                });
+                            }
+                        }
+                    }
+                }
+                if (Date.now() >= deadline)
+                    throw new Error("dependency certification publication is busy");
+                await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+            }
+        }
+    }
+    finally {
+        await rm(candidate, { recursive: true, force: true });
+    }
+}
+function validateCertification(value, identity, allowLegacyPlatform = false) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`dependency layer certification differs from manifest: ${identity.layerId}`);
+    const certification = value;
+    const identityMatches = certification.schema === PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema
+        && certification.layerId === identity.layerId && certification.contentDigest === identity.contentDigest;
+    const currentPlatform = certification.platform === process.platform && certification.platformPolicy === immutablePlatformPolicy();
+    const legacyPlatform = allowLegacyPlatform && certification.platform === undefined && certification.platformPolicy === undefined;
+    if (!identityMatches || (!currentPlatform && !legacyPlatform))
+        throw new Error(`dependency layer certification differs from manifest: ${identity.layerId}`);
+    return legacyPlatform;
+}
+function assertLayerId(layerId) {
+    if (!/^dependencies-[a-f0-9]{32}$/.test(layerId))
+        throw new Error(`invalid dependency layer identity: ${layerId}`);
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function missingOrThrow(error) {
+    if (hasCode(error, "ENOENT"))
+        return null;
+    throw error;
+}