@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

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

@@ -0,0 +1,507 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
+/**
+ * Derive protection exclusively from current selectors and ownership authorities.
+ * The historical retention snapshot is deliberately not an input to this plan.
+ */
+export function planProtectedReleases(state, inputs = {}) {
+    const holds = inputs.externalHolds ?? [];
+    for (const hold of holds) {
+        if (hold.authority !== "agent" && hold.authority !== "migration")
+            throw new Error(`unknown release hold authority: ${String(hold.authority)}`);
+        if (!state.releases[hold.releaseId] && !state.cleanup.pending[hold.releaseId]) {
+            throw new Error(`external ${hold.authority} hold names unknown release ${hold.releaseId}`);
+        }
+    }
+    const protectedIds = new Set();
+    for (const id of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
+        if (id !== null)
+            protectedIds.add(id);
+    }
+    for (const id of inputs.liveReleaseIds ?? [])
+        protectedIds.add(id);
+    for (const hold of holds)
+        protectedIds.add(hold.releaseId);
+    if (inputs.transaction?.status === "active" && inputs.transaction.priorActiveReleaseId !== null) {
+        protectedIds.add(inputs.transaction.priorActiveReleaseId);
+    }
+    const protectedReleaseIds = [...protectedIds].sort();
+    const known = Object.keys(state.releases).sort();
+    return {
+        protectedReleaseIds,
+        retainedReleaseIds: known.filter(id => protectedIds.has(id)),
+        collectibleReleaseIds: known.filter(id => !protectedIds.has(id)),
+    };
+}
+/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
+export class CohortStateStore {
+    path;
+    constructor(dataDir) {
+        this.path = resolve(dataDir, "release-state.json");
+    }
+    async read() {
+        try {
+            const state = normalizeState(JSON.parse(await readFile(this.path, "utf8")));
+            validateState(state);
+            return state;
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return emptyState();
+            throw error;
+        }
+    }
+    async update(operation) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const lockPath = `${this.path}.lock`;
+        const lock = await acquireLock(lockPath);
+        try {
+            const current = await this.read();
+            const next = await operation(current);
+            validateTransition(current, next);
+            const committed = { ...next, revision: current.revision + 1 };
+            const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(committed, null, 2));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, this.path);
+            return committed;
+        }
+        finally {
+            await lock.close();
+            await rm(lockPath, { force: true });
+        }
+    }
+    async recordCandidate(release) {
+        return await this.update(current => {
+            const existing = current.releases[release.releaseId];
+            const record = existing ?? {
+                releaseId: release.releaseId,
+                releaseRoot: release.releaseRoot,
+                packageVersion: release.packageVersion,
+                contentDigest: release.contentDigest,
+                ...(release.launchContract === undefined ? {} : { launchContract: release.launchContract }),
+                approval: "candidate",
+                materializedAt: new Date().toISOString(),
+                certifiedAt: null,
+                diagnosticsPath: null,
+            };
+            return {
+                ...current,
+                releases: { ...current.releases, [release.releaseId]: record },
+                references: {
+                    ...current.references,
+                    pending: current.references.active === release.releaseId ? current.references.pending : release.releaseId,
+                },
+                activation: activation("pending", "candidate awaits certification and safe activation"),
+            };
+        });
+    }
+    async approve(releaseId, diagnosticsPath) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            return {
+                ...current,
+                releases: { ...current.releases, [releaseId]: { ...release, approval: "approved", certifiedAt: new Date().toISOString(), diagnosticsPath } },
+                references: { ...current.references, approved: releaseId, pending: current.references.active === releaseId ? null : releaseId },
+            };
+        });
+    }
+    async activate(releaseId) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            if (release.approval !== "approved")
+                throw new Error(`cannot activate unverified release ${releaseId}`);
+            const prior = current.references.active;
+            return {
+                ...current,
+                references: {
+                    ...current.references,
+                    active: releaseId,
+                    pending: null,
+                    approved: releaseId,
+                    rollback: prior && prior !== releaseId ? prior : current.references.rollback,
+                },
+                activation: activation("idle", null),
+            };
+        });
+    }
+    /** Atomically advances ordinary launch without allowing an older installation to roll active state back. */
+    async activateForLaunch(releaseId, replaceUnlaunchableActiveId) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            if (release.approval !== "approved")
+                throw new Error(`cannot activate unverified release ${releaseId}`);
+            const selectedId = current.references.active === replaceUnlaunchableActiveId
+                ? releaseId
+                : selectOrdinaryLaunchReleaseId(release, current.references.active === null ? undefined : current.releases[current.references.active]);
+            if (selectedId !== releaseId) {
+                return {
+                    ...current,
+                    references: {
+                        ...current.references,
+                        pending: current.references.pending === releaseId ? null : current.references.pending,
+                        approved: selectedId,
+                    },
+                    activation: activation("idle", null),
+                };
+            }
+            const prior = current.references.active;
+            return {
+                ...current,
+                references: {
+                    ...current.references,
+                    active: releaseId,
+                    pending: null,
+                    approved: releaseId,
+                    rollback: prior && prior !== releaseId ? prior : current.references.rollback,
+                },
+                activation: activation("idle", null),
+            };
+        });
+    }
+    async blockPending(reason, blockerGenerationIds) {
+        return await this.update(current => ({ ...current, activation: { ...activation("blocked", reason), blockerGenerationIds: [...blockerGenerationIds] } }));
+    }
+    async rollback(ownershipReleased) {
+        if (!ownershipReleased)
+            throw new Error("cannot roll back before current cohort ownership is released");
+        return await this.update(current => {
+            const rollbackId = current.references.rollback;
+            if (!rollbackId)
+                throw new Error("no rollback release is recorded");
+            const rollback = requiredRelease(current, rollbackId);
+            if (rollback.approval !== "approved")
+                throw new Error(`cannot roll back to unverified release ${rollbackId}`);
+            return {
+                ...current,
+                references: {
+                    ...current.references,
+                    active: rollbackId,
+                    pending: null,
+                    approved: rollbackId,
+                    rollback: current.references.active,
+                },
+                activation: activation("idle", null),
+            };
+        });
+    }
+    async setRetention(releaseIds) {
+        return await this.update(current => {
+            for (const releaseId of releaseIds)
+                requiredRelease(current, releaseId);
+            return { ...current, references: { ...current.references, retention: unique(releaseIds) } };
+        });
+    }
+    /** Atomically replace legacy retention history and detach every currently collectible record. */
+    async reconcileRetention(resolveInputs, orphans = []) {
+        let plan = null;
+        let detachedReleaseIds = [];
+        const state = await this.update(async (current) => {
+            const inputs = await resolveInputs(current);
+            plan = planProtectedReleases(current, inputs);
+            const nextReleases = { ...current.releases };
+            const pending = { ...current.cleanup.pending };
+            for (const releaseId of plan.collectibleReleaseIds) {
+                const release = nextReleases[releaseId];
+                pending[releaseId] ??= cleanupDisposition(release, "detached", null);
+                delete nextReleases[releaseId];
+            }
+            for (const orphan of orphans) {
+                const releaseId = orphan.release.releaseId;
+                if (nextReleases[releaseId] || pending[releaseId] || plan.protectedReleaseIds.includes(releaseId))
+                    continue;
+                pending[releaseId] = cleanupDisposition(orphan.release, orphan.stage, orphan.trashPath ?? null);
+            }
+            detachedReleaseIds = plan.collectibleReleaseIds;
+            return {
+                ...current,
+                releases: nextReleases,
+                references: { ...current.references, retention: plan.retainedReleaseIds },
+                cleanup: { ...current.cleanup, pending },
+            };
+        });
+        if (plan === null)
+            throw new Error("release retention reconciliation did not produce a plan");
+        return { state, plan, detachedReleaseIds };
+    }
+    async markCleanupTrash(releaseId, trashPath) {
+        return await this.update(current => {
+            const disposition = current.cleanup.pending[releaseId];
+            if (!disposition)
+                throw new Error(`release ${releaseId} has no cleanup disposition`);
+            return replaceCleanup(current, releaseId, { ...disposition, stage: "trash", trashPath, lastError: null });
+        });
+    }
+    async recordCleanupFailure(releaseId, stage, error) {
+        return await this.update(current => {
+            const attemptedAt = new Date().toISOString();
+            const message = boundedError(error);
+            const disposition = current.cleanup.pending[releaseId];
+            const pending = disposition ? {
+                ...current.cleanup.pending,
+                [releaseId]: { ...disposition, attempts: disposition.attempts + 1, lastAttemptAt: attemptedAt, lastError: message },
+            } : current.cleanup.pending;
+            return {
+                ...current,
+                cleanup: {
+                    ...current.cleanup,
+                    pending,
+                    diagnostics: [...current.cleanup.diagnostics, { releaseId, stage, attemptedAt, error: message }].slice(-64),
+                },
+            };
+        });
+    }
+    async completeCleanup(releaseId) {
+        return await this.update(current => {
+            const pending = { ...current.cleanup.pending };
+            delete pending[releaseId];
+            return { ...current, cleanup: { ...current.cleanup, pending } };
+        });
+    }
+    async recordCleanupWorkerScheduled(runId) {
+        return await this.update(current => {
+            const scheduledAt = new Date().toISOString();
+            const run = {
+                runId,
+                status: "scheduled",
+                scheduledAt,
+                startedAt: null,
+                completedAt: null,
+                pid: null,
+                batches: 0,
+                attempted: 0,
+                completed: 0,
+                remaining: Object.keys(current.cleanup.pending).length,
+                error: null,
+            };
+            return { ...current, cleanup: { ...current.cleanup, workerRuns: [...current.cleanup.workerRuns, run].slice(-16) } };
+        });
+    }
+    async recordCleanupWorkerStarted(runId, pid) {
+        return await this.update(current => replaceCleanupWorkerRun(current, runId, existing => ({
+            ...(existing ?? cleanupWorkerRun(runId, Object.keys(current.cleanup.pending).length)),
+            status: "running",
+            startedAt: new Date().toISOString(),
+            completedAt: null,
+            pid,
+            error: null,
+        })));
+    }
+    async recordCleanupWorkerProgress(runId, summary) {
+        return await this.update(current => replaceCleanupWorkerRun(current, runId, existing => ({
+            ...(existing ?? cleanupWorkerRun(runId, summary.remaining)),
+            status: "running",
+            startedAt: existing?.startedAt ?? new Date().toISOString(),
+            pid: existing?.pid ?? process.pid,
+            ...summary,
+        })));
+    }
+    async recordCleanupWorkerFinished(runId, status, summary, error = null) {
+        return await this.update(current => replaceCleanupWorkerRun(current, runId, existing => ({
+            ...(existing ?? cleanupWorkerRun(runId, summary.remaining)),
+            status,
+            startedAt: existing?.startedAt ?? new Date().toISOString(),
+            completedAt: new Date().toISOString(),
+            pid: existing?.pid ?? process.pid,
+            ...summary,
+            error: error === null ? null : boundedError(error),
+        })));
+    }
+    async removeUnreferencedRelease(releaseId, externalReferences) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            const protectedIds = new Set([
+                current.references.active,
+                current.references.pending,
+                current.references.approved,
+                current.references.rollback,
+                ...current.references.retention,
+                ...externalReferences,
+            ].filter((value) => value !== null));
+            if (protectedIds.has(releaseId))
+                throw new Error(`release ${releaseId} is still referenced and cannot be collected`);
+            const releases = { ...current.releases };
+            delete releases[releaseId];
+            return {
+                ...current,
+                releases,
+                cleanup: {
+                    ...current.cleanup,
+                    pending: { ...current.cleanup.pending, [releaseId]: cleanupDisposition(release, "detached", null) },
+                },
+            };
+        });
+    }
+}
+export function emptyState() {
+    return {
+        schema: RELEASE_COHORT_SCHEMA,
+        revision: 0,
+        releases: {},
+        references: { active: null, pending: null, approved: null, rollback: null, retention: [] },
+        cleanup: { pending: {}, diagnostics: [], workerRuns: [] },
+        activation: activation("idle", null),
+    };
+}
+function cleanupDisposition(release, stage, trashPath) {
+    return { release, stage, trashPath, attempts: 0, lastAttemptAt: null, lastError: null };
+}
+function replaceCleanup(current, releaseId, disposition) {
+    return { ...current, cleanup: { ...current.cleanup, pending: { ...current.cleanup.pending, [releaseId]: disposition } } };
+}
+function cleanupWorkerRun(runId, remaining) {
+    return {
+        runId,
+        status: "scheduled",
+        scheduledAt: new Date().toISOString(),
+        startedAt: null,
+        completedAt: null,
+        pid: null,
+        batches: 0,
+        attempted: 0,
+        completed: 0,
+        remaining,
+        error: null,
+    };
+}
+function replaceCleanupWorkerRun(current, runId, operation) {
+    const existing = current.cleanup.workerRuns.find(run => run.runId === runId);
+    const workerRuns = existing
+        ? current.cleanup.workerRuns.map(run => run.runId === runId ? operation(run) : run)
+        : [...current.cleanup.workerRuns, operation(undefined)];
+    return { ...current, cleanup: { ...current.cleanup, workerRuns: workerRuns.slice(-16) } };
+}
+function activation(state, reason) {
+    return { state, reason, blockerGenerationIds: [], updatedAt: new Date().toISOString() };
+}
+function requiredRelease(state, releaseId) {
+    const release = state.releases[releaseId];
+    if (!release)
+        throw new Error(`unknown release ${releaseId}`);
+    return release;
+}
+function unique(values) { return [...new Set(values)]; }
+async function acquireLock(path) {
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        try {
+            const lock = await open(path, "wx", 0o600);
+            await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            await lock.sync();
+            return lock;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+            if (await reclaimAbandonedLock(path))
+                continue;
+            if (Date.now() >= deadline)
+                throw error;
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+        }
+    }
+}
+async function reclaimAbandonedLock(path) {
+    let abandoned = false;
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (typeof value.pid === "number") {
+            try {
+                process.kill(value.pid, 0);
+            }
+            catch (error) {
+                abandoned = !(error instanceof Error && "code" in error && error.code === "EPERM");
+            }
+        }
+    }
+    catch {
+        const metadata = await stat(path).catch(() => null);
+        abandoned = metadata !== null && Date.now() - metadata.mtimeMs > 10_000;
+    }
+    if (!abandoned)
+        return false;
+    const quarantine = `${path}.abandoned`;
+    const oldQuarantine = await stat(quarantine).catch(() => null);
+    if (oldQuarantine && Date.now() - oldQuarantine.mtimeMs > 10_000)
+        await rm(quarantine, { force: true });
+    try {
+        // Concurrency: the fixed destination lets exactly one waiter claim the stale lock;
+        // another waiter cannot accidentally rename a newly acquired replacement.
+        await rename(path, quarantine);
+        await rm(quarantine, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeState(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    const state = value;
+    const cleanup = state.cleanup;
+    return {
+        ...state,
+        cleanup: cleanup
+            ? { ...cleanup, workerRuns: cleanup.workerRuns ?? [] }
+            : { pending: {}, diagnostics: [], workerRuns: [] },
+    };
+}
+function validateState(state) {
+    if (!state || state.schema !== RELEASE_COHORT_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0
+        || !state.releases || typeof state.releases !== "object" || !state.references || !Array.isArray(state.references.retention)
+        || !state.cleanup || typeof state.cleanup.pending !== "object" || !Array.isArray(state.cleanup.diagnostics)
+        || !Array.isArray(state.cleanup.workerRuns)) {
+        throw new Error("invalid release cohort state");
+    }
+    for (const run of state.cleanup.workerRuns) {
+        if (!run || typeof run.runId !== "string" || run.runId.length === 0
+            || !["scheduled", "running", "completed", "blocked", "continued", "failed", "skipped"].includes(run.status)
+            || typeof run.scheduledAt !== "string" || (run.startedAt !== null && typeof run.startedAt !== "string")
+            || (run.completedAt !== null && typeof run.completedAt !== "string") || (run.pid !== null && (!Number.isSafeInteger(run.pid) || run.pid < 1))
+            || !Number.isSafeInteger(run.batches) || run.batches < 0 || !Number.isSafeInteger(run.attempted) || run.attempted < 0
+            || !Number.isSafeInteger(run.completed) || run.completed < 0 || run.completed > run.attempted
+            || !Number.isSafeInteger(run.remaining) || run.remaining < 0 || (run.error !== null && typeof run.error !== "string")) {
+            throw new Error("invalid release cleanup worker run");
+        }
+    }
+    for (const [releaseId, release] of Object.entries(state.releases))
+        validateReleaseRecord(releaseId, release);
+    for (const reference of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
+        if (reference !== null && !state.releases[reference])
+            throw new Error(`release reference points to an unknown release: ${reference}`);
+    }
+    for (const [releaseId, disposition] of Object.entries(state.cleanup.pending)) {
+        validateReleaseRecord(releaseId, disposition.release);
+        if (!["detached", "trash"].includes(disposition.stage))
+            throw new Error(`invalid cleanup disposition for ${releaseId}`);
+    }
+}
+function validateReleaseRecord(releaseId, release) {
+    if (release.releaseId !== releaseId || !RELEASE_ID_PATTERN.test(releaseId) || typeof release.releaseRoot !== "string"
+        || typeof release.packageVersion !== "string" || !/^[a-f0-9]{64}$/.test(release.contentDigest)
+        || !["candidate", "approved", "rejected"].includes(release.approval)) {
+        throw new Error(`invalid release record for ${releaseId}`);
+    }
+}
+function validateTransition(current, next) {
+    validateState(next);
+    if (next.schema !== current.schema)
+        throw new Error("release cohort schema cannot change during a state update");
+    if (next.revision !== current.revision)
+        throw new Error("release cohort revision is controlled by the state store");
+}
+function boundedError(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 1_000);
+}

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