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

package/dist/features/prompt-history/worker.js

@@ -1,6 +1,6 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { setTimeout as delay } from "node:timers/promises";
-import { PromptHistoryStore, classifyHistoryError } from "./store.js";
+import { HistoryStorageError, PromptHistoryStore, classifyHistoryError } from "./store.js";
 const port = parentPort;
 if (port !== null) {
     let store;
@@ -22,7 +22,8 @@ if (port !== null) {
                 port.postMessage({ id: request.id, ok: true, value });
             }
             catch (error) {
-                port.postMessage({ id: request.id, ok: false, code: classifyHistoryError(error) });
+                port.postMessage({ id: request.id, ok: false, code: classifyHistoryError(error),
+                    certainty: error instanceof HistoryStorageError ? error.certainty : "unknown" });
             }
         });
     });
@@ -34,7 +35,9 @@ async function retry(operation) {
             return operation();
         }
         catch (error) {
-            if (classifyHistoryError(error) !== "busy" || performance.now() >= deadline)
+            if (classifyHistoryError(error) !== "busy"
+                || error instanceof HistoryStorageError && error.certainty === "unknown"
+                || performance.now() >= deadline)
                 throw error;
             await delay(25);
         }

package/dist/foundation/launch-context/index.d.ts

@@ -1,4 +1,4 @@
-/** The one supported private process contract; public settings remain product identity data. */
+/** The contract this build emits; supersedes the pre-cutover key set it still accepts. */
 export declare const PRIVATE_LAUNCH_CONTRACT = "neutral-launch-v1";
 export declare const PRIVATE_ENVIRONMENT: Readonly<{
     releaseRoot: "LAUNCH_CONTEXT_RELEASE_ROOT";
@@ -8,6 +8,22 @@ export declare const PRIVATE_ENVIRONMENT: Readonly<{
     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 declare const SUPERSEDED_ENVIRONMENT: Readonly<{
+    releaseRoot: "A1_RELEASE_ROOT";
+    releaseId: "A1_RELEASE_ID";
+    releaseDigest: "A1_RELEASE_DIGEST";
+    releaseLayers: "A1_RELEASE_LAYERS";
+    launchProfile: "A1_LAUNCH_PROFILE";
+    immutableWarmup: "A1_IMMUTABLE_WARMUP";
+}>;
+/** A release either declares the current contract or predates contract declaration. */
+export type LaunchContractTarget = typeof PRIVATE_LAUNCH_CONTRACT | "superseded";
 export interface LaunchContext {
     readonly releaseRoot?: string;
     readonly releaseId?: string;
@@ -17,13 +33,27 @@ export interface LaunchContext {
     readonly immutableWarmup?: "1";
 }
 export type LaunchContextRequirement = "optional" | "profile" | "release" | "warmup";
-/** Read current private keys only, with entry-specific required fields and bounded diagnostics. */
+/** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
 export declare function readLaunchContext(environment: NodeJS.ProcessEnv, requirement?: LaunchContextRequirement, platform?: NodeJS.Platform): LaunchContext;
-/** Rebuild owned context without inheriting a prior session's private selection. */
-export declare function withLaunchContext(environment: NodeJS.ProcessEnv, context: LaunchContext, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
-/** Remove only this implementation's private keys, leaving user and integration settings intact. */
+/** The key set a process started for this release must receive. */
+export declare function launchEnvironmentKeys(contract: LaunchContractTarget): Readonly<Record<string, string>>;
+/** Classify metadata by the contract it declares rather than rejecting what it omits. */
+export declare function launchContractTarget(value: {
+    readonly launchContract?: unknown;
+}): LaunchContractTarget;
+/** Whether metadata was produced by a build that declares this contract. */
+export declare function isCurrentLaunchContract(value: {
+    readonly launchContract?: unknown;
+}): boolean;
+/**
+ * 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 declare function withLaunchContext(environment: NodeJS.ProcessEnv, context: LaunchContext, platform?: NodeJS.Platform, contract?: LaunchContractTarget): NodeJS.ProcessEnv;
+/** Remove both key sets, leaving user and integration settings intact. */
 export declare function withoutLaunchContext(environment: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
-/** Reject unsupported target metadata instead of negotiating or rewriting an older contract. */
+/** Require this build's own contract where nothing older can be accepted, such as recovery capsules. */
 export declare function assertCurrentLaunchContract(value: {
     readonly launchContract?: unknown;
 }): void;

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

@@ -1,4 +1,4 @@
-/** The one supported private process contract; public settings remain product identity data. */
+/** 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",
@@ -8,18 +8,39 @@ export const PRIVATE_ENVIRONMENT = Object.freeze({
     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 PRIVATE_KEYS = new Set(Object.values(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]));
-/** Read current private keys only, with entry-specific required fields and bounded diagnostics. */
+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 logical = LOGICAL_KEYS.get(name.toUpperCase());
+            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 {
@@ -27,7 +48,16 @@ export function readLaunchContext(environment, requirement = "optional", platfor
             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");
     }
@@ -37,16 +67,39 @@ export function readLaunchContext(environment, requirement = "optional", platfor
         throw invalidContext("releaseDigest", "invalid digest");
     if (requirement === "profile")
         requireFields(values, ["launchProfile"]);
-    if (requirement === "release" || requirement === "warmup")
-        requireFields(values, ["releaseRoot", "releaseId", "releaseDigest", "releaseLayers"]);
+    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);
 }
-/** Rebuild owned context without inheriting a prior session's private selection. */
-export function withLaunchContext(environment, context, platform = process.platform) {
+/** 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 PRIVATE_ENTRIES) {
+    for (const [logical, key] of Object.entries(launchEnvironmentKeys(contract))) {
         const value = context[logical];
         if (value !== undefined)
             result[key] = value;
@@ -54,11 +107,11 @@ export function withLaunchContext(environment, context, platform = process.platf
     readLaunchContext(result, "optional", platform);
     return result;
 }
-/** Remove only this implementation's private keys, leaving user and integration settings intact. */
+/** 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)));
 }
-/** Reject unsupported target metadata instead of negotiating or rewriting an older contract. */
+/** 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.");

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+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";
@@ -175,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,6 +36,11 @@ export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdenti
     }>;
 }
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
+/**
+ * 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>;

package/dist/foundation/release/bootstrap.js

@@ -15,7 +15,7 @@ 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 { assertCurrentLaunchContract, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
+import { launchContractTarget, readLaunchContext, withLaunchContext } from "../launch-context/index.js";
 export async function runBootstrap(options) {
     const environment = withLaunchContext(options.environment ?? process.env, { launchProfile: options.launchIntent?.profileId ?? "a1" });
     await markStartupPhase(environment, "bootstrap-start");
@@ -29,9 +29,6 @@ export async function runBootstrap(options) {
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const stateStore = new CohortStateStore(paths.dataDir);
     let state = await stateStore.read();
-    const activeRecord = state.references.active === null ? undefined : state.releases[state.references.active];
-    if (activeRecord)
-        assertCurrentLaunchContract(activeRecord);
     // Invariant: records left by cohorts whose processes are gone say nothing about ownership, and there
     // can now be several of them. Clearing them first keeps the decision below about what is
     // actually running.
@@ -91,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) {
@@ -186,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) {
@@ -194,7 +232,6 @@ async function readInstalledVersion(packageRoot) {
     return manifest.version;
 }
 export async function certifyMaterializedRelease(release, dataDir, verification = {}) {
-    assertCurrentLaunchContract(release);
     if (!consumeMaterializationProof(release)) {
         await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"), verification);
     }
@@ -202,7 +239,6 @@ export async function certifyMaterializedRelease(release, dataDir, verification
 }
 /** Persist current-format evidence after an authenticated parent has certified the exact release. */
 export async function recordParentCertifiedRelease(release, dataDir) {
-    assertCurrentLaunchContract(release);
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);
     const restartSeal = await createRestartSeal(release, dataDir);
     await chmod(path, 0o600).catch(() => { });
@@ -243,15 +279,19 @@ async function launchUi(release, environment, sessionArgs) {
         child.once("close", (code, signal) => resolvePromise(restoreAfterOwnedExit(readLaunchContext(environment).launchProfile === "a1", code, signal)));
     });
 }
+/**
+ * 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) {
-    assertCurrentLaunchContract(release);
     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.js

@@ -2,7 +2,6 @@ import { randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { assertCurrentLaunchContract } from "../launch-context/index.js";
 export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
 const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
 /**
@@ -122,7 +121,6 @@ export class CohortStateStore {
             const release = requiredRelease(current, releaseId);
             if (release.approval !== "approved")
                 throw new Error(`cannot activate unverified release ${releaseId}`);
-            assertCurrentLaunchContract(release);
             const prior = current.references.active;
             return {
                 ...current,
@@ -150,7 +148,6 @@ export class CohortStateStore {
             const rollback = requiredRelease(current, rollbackId);
             if (rollback.approval !== "approved")
                 throw new Error(`cannot roll back to unverified release ${rollbackId}`);
-            assertCurrentLaunchContract(rollback);
             return {
                 ...current,
                 references: {

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 {};