@timurproko/a1 0.2.7-dev.1252 → 0.2.7-dev.1264

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

@@ -6,21 +6,22 @@ import { basename, dirname, resolve } from "node:path";
 import { valid as validSemver } from "semver";
 import { readLaunchContext } from "../launch-context/index.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
-import { CohortStateStore } from "./cohort-state.js";
+import { ReleaseStateStore } from "./release-state.js";
 import { processIsAlive } from "./process-liveness.js";
 import { isNewerRelease, releaseChannelOf } from "./latest-release.js";
 import { readCertifiedReleaseManifest, resolveReleaseEntryPoint } from "./release-store.js";
 import { acquireUpdateExecutionLease, readUpdateExecutionOwner } from "./update-execution-lease.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { runSelfUpdate, UPDATE_ALREADY_RUNNING_EXIT_CODE } from "./update.js";
-export const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
-export const AUTOMATIC_UPDATE_RETRY_MS = 24 * 60 * 60_000;
+import { errorMessage, samePath } from "./managed-path.js";
+const AUTOMATIC_UPDATE_STATE_SCHEMA = 1;
+const AUTOMATIC_UPDATE_RETRY_MS = 24 * 60 * 60_000;
 const AUTOMATIC_UPDATE_STATE_FILENAME = "automatic-update.json";
 const MAX_STATE_BYTES = 16_384;
 const OBSERVER_POLL_MS = 250;
 const WORKER_START_GRACE_MS = 5_000;
-export const ACTIVE_RELEASE_FALLBACK_MS = 5_000;
-export class AutomaticUpdateStateStore {
+const ACTIVE_RELEASE_FALLBACK_MS = 5_000;
+class AutomaticUpdateStateStore {
     path;
     constructor(dataDir) { this.path = resolve(dataDir, AUTOMATIC_UPDATE_STATE_FILENAME); }
     async read() {
@@ -65,7 +66,7 @@ export class AutomaticUpdateStateStore {
     }
 }
 /** Read the approved active release only when this process executes an older release on that channel. */
-export async function readNewerActiveRelease(runningVersion, environment = process.env) {
+async function readNewerActiveRelease(runningVersion, environment = process.env) {
     const channel = releaseChannelOf(runningVersion);
     if (channel === null)
         return null;
@@ -83,7 +84,7 @@ export function observeNewerActiveRelease(options) {
     if (releaseChannelOf(options.runningVersion) === null || options.signal?.aborted)
         return () => { };
     const paths = resolveProductPaths(options.environment ?? process.env);
-    const store = new CohortStateStore(paths.dataDir);
+    const store = new ReleaseStateStore(paths.dataDir);
     let closed = false;
     let checking = false;
     let requested = false;
@@ -193,8 +194,8 @@ export async function requestAutomaticUpdate(options) {
     let worker = options.worker;
     if (worker === undefined) {
         const launch = readLaunchContext(environment, "release");
-        const cohort = await new CohortStateStore(paths.dataDir).read();
-        const record = launch.releaseId === undefined ? undefined : cohort.releases[launch.releaseId];
+        const releaseState = await new ReleaseStateStore(paths.dataDir).read();
+        const record = launch.releaseId === undefined ? undefined : releaseState.releases[launch.releaseId];
         if (!record || record.approval !== "approved" || record.releaseRoot !== launch.releaseRoot
             || record.contentDigest !== launch.releaseDigest)
             return null;
@@ -248,8 +249,8 @@ export async function runAutomaticUpdateWorker(argv, environment = process.env)
     let verified = false;
     try {
         const launch = readLaunchContext(environment, "release");
-        const cohort = await new CohortStateStore(paths.dataDir).read();
-        const record = launch.releaseId === undefined ? undefined : cohort.releases[launch.releaseId];
+        const releaseState = await new ReleaseStateStore(paths.dataDir).read();
+        const record = launch.releaseId === undefined ? undefined : releaseState.releases[launch.releaseId];
         if (record?.approval === "approved" && samePath(record.releaseRoot, launch.releaseRoot ?? "")
             && record.contentDigest === launch.releaseDigest) {
             const selected = await readCertifiedReleaseManifest(record, resolve(paths.dataDir, "releases"));
@@ -360,11 +361,11 @@ function activeNewerPackageVersion(active, runningVersion, channel, minimum) {
         ? active.packageVersion : null;
 }
 async function activeRelease(dataDir) {
-    const cohort = await new CohortStateStore(dataDir).read();
-    const activeId = cohort.references.active;
+    const releaseState = await new ReleaseStateStore(dataDir).read();
+    const activeId = releaseState.references.active;
     if (activeId === null)
         return null;
-    const active = cohort.releases[activeId];
+    const active = releaseState.releases[activeId];
     return active?.approval === "approved" ? active : null;
 }
 function state(parsed, status, attemptedAt, installedVersion, failure) {
@@ -406,14 +407,6 @@ function validateState(value) {
         throw new Error("invalid automatic update state");
     }
 }
-function samePath(left, right) {
-    const canonicalLeft = resolve(left);
-    const canonicalRight = resolve(right);
-    return process.platform === "win32"
-        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
-        : canonicalLeft === canonicalRight;
-}
 function hasCode(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/bootstrap.js

@@ -4,7 +4,7 @@ import { deliverExitNotice, restoreAfterOwnedExit } from "../terminal-cleanup/in
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-import { CohortStateStore } from "./cohort-state.js";
+import { ReleaseStateStore } from "./release-state.js";
 import { assertLaunchProfileId, resolveProductPaths, sessionSelectionArguments } from "../lifecycle/index.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { selectUpdateLaunchRelease } from "./update-launch.js";
@@ -39,7 +39,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
         output.write(`${PRODUCT_TEXT.diagnostic("active release changed repeatedly during startup; launch could not converge")}\n`);
         return 1;
     };
-    const stateStore = new CohortStateStore(paths.dataDir);
+    const stateStore = new ReleaseStateStore(paths.dataDir);
     let state = await stateStore.read();
     const launchDuringUpdate = async () => {
         // Concurrency: read the journal before touching npm's mutable tree, including package.json.
@@ -55,7 +55,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     const duringUpdate = await launchDuringUpdate();
     if (duringUpdate !== null)
         return duringUpdate;
-    // Performance: reconciliation is serialized by cohort state, but launch never awaits a physical
+    // Performance: reconciliation is serialized by the release state lock, but launch never awaits a physical
     // backlog. The scheduler commits a plan and starts a detached bounded worker.
     const scheduleMaintenance = options.scheduleMaintenance ?? scheduleReleaseCleanup;
     void scheduleMaintenance(paths.dataDir, paths).catch(() => { });
@@ -149,7 +149,7 @@ async function runBootstrapAttempt(options, retriesRemaining) {
     return await launchSelected(candidate);
 }
 /**
- * Start the retained active cohort when the installed payload cannot be taken. The
+ * Start the retained active release 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.

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

@@ -1,4 +1,3 @@
-export declare const DEPENDENCY_CERTIFICATIONS_DIRECTORY = "dependency-certifications";
 type LayerIdentity = {
     readonly layerId: string;
     readonly contentDigest: string;

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

@@ -3,7 +3,7 @@ import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile
 import { basename, 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";
+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);

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

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, posix, relative, resolve, sep } from "node:path";
+import { dirname, posix, resolve, sep } from "node:path";
 import { mapWithConcurrency } from "./concurrency.js";
 import { assertImmutableFileMode } from "./immutable-platform.js";
 import { readDependencyCertification, writeDependencyCertification as writeLayerCertification } from "./dependency-certification.js";
 export { dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath } from "./dependency-certification.js";
 import { digestManifestFiles, releaseFileIdentity, resolveWithin } from "./release.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { isDirectChild } from "./managed-path.js";
 const LAYER_IO_CONCURRENCY = 32;
 export const DEPENDENCY_LAYER_SCHEMA = PRODUCT_IDENTITY.evidence.dependencyLayerSchema;
 export const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
@@ -460,7 +461,6 @@ function isKnownRuntimePath(path) {
 }
 function isJavaScriptModule(path) { return /\.(?:js|mjs|cjs)$/.test(path); }
 function assertDirectChild(parent, child) {
-    const path = relative(parent, child);
-    if (path.length === 0 || path === ".." || path.startsWith(`..${sep}`) || path.includes(sep))
+    if (!isDirectChild(parent, child))
         throw new Error(`dependency layer escapes managed storage: ${child}`);
 }

package/dist/foundation/release/early-accent.d.ts

@@ -1,6 +1,6 @@
 type UiAccentColor = "blue" | "purple" | "cyan" | "green" | "orange" | "pink";
-export type EarlyAccentAppearance = "dark" | "light";
-export type EarlyAccentMode = "truecolor" | "256color";
+type EarlyAccentAppearance = "dark" | "light";
+type EarlyAccentMode = "truecolor" | "256color";
 /** Read only global profile data, never project settings or the interactive resource pipeline. */
 export declare function resolveEarlyAccentColor(environment?: NodeJS.ProcessEnv, home?: () => string): UiAccentColor;
 export declare function earlyAccentPalette(color: UiAccentColor, appearance?: EarlyAccentAppearance, mode?: EarlyAccentMode): {

package/dist/foundation/release/early-accent.js

@@ -2,7 +2,7 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { SHARED_PROGRESS_PALETTE } from "./progress-palette.generated.js";
+import { SHARED_PROGRESS_PALETTE } from "../../contracts/presentation/index.js";
 const MAX_SETTINGS_BYTES = 256 * 1024;
 /** Read only global profile data, never project settings or the interactive resource pipeline. */
 export function resolveEarlyAccentColor(environment = process.env, home = homedir) {

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

@@ -1,8 +1,8 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export type { BootstrapOptions } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { CohortStateStore, RELEASE_COHORT_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./cohort-state.js";
-export type { ActiveReleaseTransactionReference, CohortState, OrphanReleaseDisposition, ProtectedReleaseInputs, ProtectedReleasePlan, ReleaseApproval, ReleaseCleanupDiagnostic, ReleaseCleanupDisposition, ReleaseCleanupStage, ReleaseCleanupState, ReleaseCleanupWorkerRun, ReleaseCleanupWorkerStatus, ReleaseCleanupWorkerSummary, ReleaseRecord, ReleaseReferences, ReleaseRetentionReconciliation, } from "./cohort-state.js";
+export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
+export type { ActiveReleaseTransactionReference, ReleaseState, OrphanReleaseDisposition, ProtectedReleaseInputs, ProtectedReleasePlan, ReleaseApproval, ReleaseCleanupDiagnostic, ReleaseCleanupDisposition, ReleaseCleanupStage, ReleaseCleanupState, ReleaseCleanupWorkerRun, ReleaseCleanupWorkerStatus, ReleaseCleanupWorkerSummary, ReleaseRecord, ReleaseReferences, ReleaseRetentionReconciliation, } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export type { DependencyLayerIdentity, DependencyLayerOperationEvent, DependencyLayerReference, GeneratedRuntimePayload, MaterializeDependencyLayerOptions, MaterializedDependencyLayer, PublishedRuntimeFileClassification, PublishedRuntimePayload, ReadCertifiedDependencyLayerOptions, RuntimePayloadExclusion, RuntimePayloadInventory, SelectedRuntimePayload, } from "./dependency-layer.js";
 export { processIsAlive } from "./process-liveness.js";

package/dist/foundation/release/index.js

@@ -1,6 +1,6 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { CohortStateStore, RELEASE_COHORT_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./cohort-state.js";
+export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export { processIsAlive } from "./process-liveness.js";
 export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, digestManifestFiles, discoverReleasePayload, packageRootFromModule, releaseFileIdentity, resolveWithin, } from "./release.js";

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

@@ -1,11 +1,6 @@
 /** Published release channels: stable `X.Y.Z` on dist-tag `latest`, development `X.Y.Z-dev.N` on `next`. */
 export type ReleaseChannel = "stable" | "development";
-export type StartupUpdateMode = "auto" | "no";
-export interface DistTagVersions {
-    readonly release: string | null;
-    readonly develop: string | null;
-    readonly error: string | null;
-}
+export type StartupUpdateMode = "auto" | "manual";
 export type RegistryFetcher = (url: string) => Promise<{
     readonly ok: boolean;
     readonly status: number;
@@ -19,14 +14,13 @@ export interface AvailableRelease {
     /** The GitHub Release page; development releases have none. */
     readonly changelogUrl: string | null;
 }
-export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 export declare const UPDATE_CHECK_INTERVAL_MS: number;
 /** One published version with the pull request its manifest records, when it records one. */
 export interface PublishedVersion {
     readonly version: string;
     readonly pullRequest: number | null;
 }
-export interface PublishedVersions {
+interface PublishedVersions {
     readonly versions: readonly PublishedVersion[];
     readonly error: string | null;
 }
@@ -37,23 +31,14 @@ export interface PublishedVersions {
 export declare function releaseChannelOf(version: string): ReleaseChannel | null;
 /** True only when both versions are valid semver and the candidate sorts strictly above the current one. */
 export declare function isNewerRelease(candidate: string, current: string): boolean;
-export declare function distTagsUrl(registry?: string): string;
-/** Read `latest` (required) and `next` (optional) from a dist-tags object. */
-export declare function parseDistTags(metadata: unknown, source: string): DistTagVersions;
-export declare function queryRegistryDistTags(fetcher: RegistryFetcher, registry?: string): Promise<DistTagVersions>;
-export declare function packageDocumentUrl(registry?: string): string;
-/** The pull request a published or installed manifest records under `publication.pullRequest`, when valid. */
-export declare function recordedPullRequest(manifest: unknown): number | null;
 /**
  * Every published version with its recorded pull request, read from the registry's full package
  * document: its per-version manifests keep the publication metadata that version lists and the
  * abbreviated install document leave out.
  */
 export declare function queryPublishedVersions(fetcher: RegistryFetcher, registry?: string): Promise<PublishedVersions>;
-export declare function parsePublishedVersions(document: unknown): PublishedVersions;
 /** Forget the startup release check so the next interactive launch asks the registry again. */
 export declare function invalidateReleaseCheckCache(configDir: string): Promise<void>;
-export declare function unavailableDistTags(error: string): DistTagVersions;
 export declare function createRegistryFetcher(timeoutMs: number, signal?: AbortSignal): RegistryFetcher;
 export interface StartupReleaseCheckOptions {
     readonly runningVersion: string;
@@ -77,4 +62,4 @@ export declare function startupReleaseCheckSkipReason(options: StartupReleaseChe
  * answer replaces the cache. Every failure resolves to null: the notice is best-effort.
  */
 export declare function checkForNewerRelease(options: StartupReleaseCheckOptions): Promise<AvailableRelease | null>;
-export declare function availableRelease(channel: ReleaseChannel, version: string): AvailableRelease;
+export {};

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

@@ -4,7 +4,8 @@ import { join } from "node:path";
 import { gt, prerelease, valid as validSemver } from "semver";
 import lockfile from "proper-lockfile";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+import { errorMessage } from "./managed-path.js";
+const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 export const UPDATE_CHECK_INTERVAL_MS = 15 * 60_000;
 const STARTUP_FETCH_TIMEOUT_MS = 3_000;
 const CACHE_FILENAME = "update-check.json";
@@ -30,11 +31,11 @@ export function isNewerRelease(candidate, current) {
     const right = validSemver(current);
     return left !== null && right !== null && gt(left, right);
 }
-export function distTagsUrl(registry = DEFAULT_NPM_REGISTRY) {
+function distTagsUrl(registry = DEFAULT_NPM_REGISTRY) {
     return `${registry.replace(/\/+$/u, "")}/-/package/${encodeURIComponent(PRODUCT_TEXT.packageName)}/dist-tags`;
 }
 /** Read `latest` (required) and `next` (optional) from a dist-tags object. */
-export function parseDistTags(metadata, source) {
+function parseDistTags(metadata, source) {
     if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
         return unavailableDistTags(`${source} returned a non-object dist-tags value`);
     }
@@ -48,7 +49,7 @@ export function parseDistTags(metadata, source) {
         return unavailableDistTags(errorMessage(error));
     }
 }
-export async function queryRegistryDistTags(fetcher, registry) {
+async function queryRegistryDistTags(fetcher, registry) {
     try {
         const response = await fetcher(distTagsUrl(registry));
         if (!response.ok)
@@ -59,11 +60,11 @@ export async function queryRegistryDistTags(fetcher, registry) {
         return unavailableDistTags(errorMessage(error));
     }
 }
-export function packageDocumentUrl(registry = DEFAULT_NPM_REGISTRY) {
+function packageDocumentUrl(registry = DEFAULT_NPM_REGISTRY) {
     return `${registry.replace(/\/+$/u, "")}/${encodeURIComponent(PRODUCT_TEXT.packageName)}`;
 }
 /** The pull request a published or installed manifest records under `publication.pullRequest`, when valid. */
-export function recordedPullRequest(manifest) {
+function recordedPullRequest(manifest) {
     if (typeof manifest !== "object" || manifest === null)
         return null;
     const publication = manifest.publication;
@@ -91,7 +92,7 @@ export async function queryPublishedVersions(fetcher, registry) {
         return { versions: [], error: errorMessage(error) };
     }
 }
-export function parsePublishedVersions(document) {
+function parsePublishedVersions(document) {
     if (typeof document !== "object" || document === null || Array.isArray(document)) {
         return { versions: [], error: "registry returned a non-object package document" };
     }
@@ -108,7 +109,7 @@ export function parsePublishedVersions(document) {
 export async function invalidateReleaseCheckCache(configDir) {
     await withCacheLock(configDir, async () => { await rm(join(configDir, CACHE_FILENAME), { force: true }); });
 }
-export function unavailableDistTags(error) {
+function unavailableDistTags(error) {
     return { release: null, develop: null, error };
 }
 export function createRegistryFetcher(timeoutMs, signal) {
@@ -126,7 +127,7 @@ export function startupReleaseCheckSkipReason(options) {
         return "ci";
     if (!options.interactive)
         return "not-interactive";
-    if (options.settingMode === "no")
+    if (options.settingMode === "manual")
         return "disabled-by-setting";
     if (releaseChannelOf(options.runningVersion) === null)
         return "unpublished-version";
@@ -170,7 +171,7 @@ export async function checkForNewerRelease(options) {
         return null;
     }
 }
-export function availableRelease(channel, version) {
+function availableRelease(channel, version) {
     return {
         channel,
         version,
@@ -255,4 +256,3 @@ function parseVersion(value, source) {
         throw new Error(`${source} did not provide a valid semantic version`);
     return parsed;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/managed-path.d.ts

@@ -0,0 +1,10 @@
+/** Whether two paths name the same location; Windows paths compare without case. */
+export declare function samePath(left: string, right: string): boolean;
+/**
+ * Whether `child` is exactly one non-empty segment below `parent`.
+ * Invariant: release storage operations act only on such paths, never on the root itself, another drive, a nested descendant,
+ * or anything reached through `..`. `path.relative` already ignores case on Windows.
+ */
+export declare function isDirectChild(parent: string, child: string): boolean;
+/** The message of a thrown value, whatever was thrown. */
+export declare function errorMessage(error: unknown): string;

package/dist/foundation/release/managed-path.js

@@ -0,0 +1,26 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/** Whether two paths name the same location; Windows paths compare without case. */
+export function samePath(left, right) {
+    const canonicalLeft = resolve(left);
+    const canonicalRight = resolve(right);
+    return process.platform === "win32"
+        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
+        : canonicalLeft === canonicalRight;
+}
+/**
+ * Whether `child` is exactly one non-empty segment below `parent`.
+ * Invariant: release storage operations act only on such paths, never on the root itself, another drive, a nested descendant,
+ * or anything reached through `..`. `path.relative` already ignores case on Windows.
+ */
+export function isDirectChild(parent, child) {
+    const fromParent = relative(resolve(parent), resolve(child));
+    return fromParent.length > 0
+        && fromParent !== ".."
+        && !fromParent.startsWith(`..${sep}`)
+        && !isAbsolute(fromParent)
+        && !fromParent.includes(sep);
+}
+/** The message of a thrown value, whatever was thrown. */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/foundation/release/ordinary-launch-selection.d.ts

@@ -8,7 +8,7 @@ interface ApprovedOrdinaryLaunchRelease extends OrdinaryLaunchRelease {
 /**
  * Ordinary launch has no rollback authority: it may advance to its installed package, but an
  * older package installation must follow a newer approved active release instead of moving the
- * shared selector backward. Explicit update/rollback uses CohortStateStore.activate directly.
+ * shared selector backward. Explicit update/rollback uses ReleaseStateStore.activate directly.
  */
 export declare function selectOrdinaryLaunchReleaseId(candidate: OrdinaryLaunchRelease, active?: ApprovedOrdinaryLaunchRelease): string;
 export {};

package/dist/foundation/release/ordinary-launch-selection.js

@@ -2,7 +2,7 @@ import { compare, valid as validSemver } from "semver";
 /**
  * Ordinary launch has no rollback authority: it may advance to its installed package, but an
  * older package installation must follow a newer approved active release instead of moving the
- * shared selector backward. Explicit update/rollback uses CohortStateStore.activate directly.
+ * shared selector backward. Explicit update/rollback uses ReleaseStateStore.activate directly.
  */
 export function selectOrdinaryLaunchReleaseId(candidate, active) {
     if (!active || active.approval !== "approved")

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

@@ -1,5 +1,5 @@
 import { rename, rm } from "node:fs/promises";
-import { CohortStateStore, type OrphanReleaseDisposition } from "./cohort-state.js";
+import { ReleaseStateStore, type OrphanReleaseDisposition } from "./release-state.js";
 import type { ProductPaths } from "../lifecycle/index.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 export interface ReleaseCleanupLimits {
@@ -58,11 +58,11 @@ interface DiscoveredCleanupInputs {
     }[];
 }
 /**
- * Reconcile age-based retention under the cohort-state lock and durably detach obsolete releases.
+ * Reconcile age-based retention under the release-state lock and durably detach obsolete releases.
  * This operation intentionally reads only manifests and directory metadata, never payload bytes.
  */
 export declare function prepareReleaseCleanup(dataDir: string, _paths?: ProductPaths, options?: ReleaseCleanupOptions): Promise<{
-    readonly store: CohortStateStore;
+    readonly store: ReleaseStateStore;
     readonly discovered: DiscoveredCleanupInputs;
 }>;
 /** Run a bounded, restart-safe physical cleanup pass over detached releases and abandoned artifacts. */

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

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CohortStateStore, } from "./cohort-state.js";
+import { ReleaseStateStore, } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
 import { DEPENDENCY_LAYER_MANIFEST, readCertifiedDependencyLayer } from "./dependency-layer.js";
@@ -15,6 +15,7 @@ import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { collectCompileCaches, startupCompileCachePath } from "../startup/index.js";
 import { readLaunchContext } from "../launch-context/index.js";
 import { processIsAlive } from "./process-liveness.js";
+import { errorMessage, isDirectChild } from "./managed-path.js";
 const DEFAULT_CANDIDATE_AGE_MS = 60 * 60 * 1_000;
 const DEFAULT_LIMITS = { maxItems: 8, maxDurationMs: 2_000, concurrency: 1 };
 const DEFAULT_WORKER_DURATION_MS = 10 * 60 * 1_000;
@@ -24,11 +25,11 @@ const WORKER_KEEP_ENV = "RELEASE_CLEANUP_KEEP";
 const WORKER_RUN_ID_ENV = "RELEASE_CLEANUP_RUN_ID";
 const WORKER_LEASE_FILENAME = "release-cleanup-worker.lock";
 /**
- * Reconcile age-based retention under the cohort-state lock and durably detach obsolete releases.
+ * Reconcile age-based retention under the release-state lock and durably detach obsolete releases.
  * This operation intentionally reads only manifests and directory metadata, never payload bytes.
  */
 export async function prepareReleaseCleanup(dataDir, _paths, options = {}) {
-    const store = new CohortStateStore(dataDir);
+    const store = new ReleaseStateStore(dataDir);
     const discovered = await discoverCleanupInputs(dataDir, store, options);
     const transactionStore = options.transactionStore ?? new UpdateTransactionStore(dataDir);
     await store.reconcileRetention(async () => await protectionInputs(transactionStore, options), discovered.orphans);
@@ -152,7 +153,7 @@ export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
 /** Entry used by the private cleanup executable shipped in every immutable release. */
 export async function runReleaseCleanupWorker(environment = process.env, workerOptions = {}) {
     const paths = resolveProductPaths(environment);
-    const store = new CohortStateStore(paths.dataDir);
+    const store = new ReleaseStateStore(paths.dataDir);
     const runId = environment[WORKER_RUN_ID_ENV] ?? randomUUID();
     const now = workerOptions.now ?? Date.now;
     const sleep = workerOptions.sleep ?? (async (durationMs) => await new Promise(resolvePromise => setTimeout(resolvePromise, durationMs)));
@@ -638,12 +639,6 @@ async function protectedCompileCachePaths(dataDir, state) {
     }
     return paths;
 }
-function assertDirectChild(parent, child) {
-    const fromParent = relative(parent, child);
-    if (fromParent.length === 0 || fromParent === ".." || fromParent.startsWith(`..${sep}`) || isAbsolute(fromParent) || fromParent.includes(sep)) {
-        throw new Error(`cleanup path is not a direct child of its managed root: ${child}`);
-    }
-}
 function normalizeLimits(input) {
     const limits = { ...DEFAULT_LIMITS, ...input };
     for (const [name, value] of Object.entries(limits)) {
@@ -748,4 +743,7 @@ function artifactName(path) { return path.split(sep).at(-1) ?? "artifact"; }
 function certificationReleaseId(path) {
     return /^certification-(.+)\.json$/.exec(artifactName(path))?.[1] ?? null;
 }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function assertDirectChild(parent, child) {
+    if (!isDirectChild(parent, child))
+        throw new Error(`cleanup path is not a direct child of its managed root: ${child}`);
+}

package/dist/foundation/release/{cohort-state.d.ts → release-state.d.ts}

@@ -1,5 +1,5 @@
 import type { MaterializedRelease } from "./release-store.js";
-export declare const RELEASE_COHORT_SCHEMA: string;
+export declare const RELEASE_STATE_SCHEMA: string;
 /** How long a release stays on disk after its approval, so processes started from it keep their files. */
 export declare const RELEASE_RETENTION_MS: number;
 export type ReleaseApproval = "candidate" | "approved" | "rejected";
@@ -66,8 +66,8 @@ export interface ReleaseCleanupState {
     readonly diagnostics: readonly ReleaseCleanupDiagnostic[];
     readonly workerRuns: readonly ReleaseCleanupWorkerRun[];
 }
-export interface CohortState {
-    readonly schema: typeof RELEASE_COHORT_SCHEMA;
+export interface ReleaseState {
+    readonly schema: typeof RELEASE_STATE_SCHEMA;
     readonly revision: number;
     readonly releases: Readonly<Record<string, ReleaseRecord>>;
     readonly references: ReleaseReferences;
@@ -93,7 +93,7 @@ export interface OrphanReleaseDisposition {
     readonly trashPath?: string | null;
 }
 export interface ReleaseRetentionReconciliation {
-    readonly state: CohortState;
+    readonly state: ReleaseState;
     readonly plan: ProtectedReleasePlan;
     readonly detachedReleaseIds: readonly string[];
 }
@@ -104,33 +104,33 @@ export interface ReleaseRetentionReconciliation {
  * Nothing asks which processes are running: a session that outlives the window and two updates
  * can lose its release files, which is the documented trade-off.
  */
-export declare function planProtectedReleases(state: CohortState, inputs?: ProtectedReleaseInputs): ProtectedReleasePlan;
+export declare function planProtectedReleases(state: ReleaseState, inputs?: ProtectedReleaseInputs): ProtectedReleasePlan;
 /**
  * Whether a release is young enough to keep. An approved release counts from its approval; a
  * candidate still awaiting certification counts from its materialization so concurrent work is
  * not collected under it. A record without a readable timestamp is treated as old.
  */
 export declare function withinRetention(release: ReleaseRecord, now: number, retentionMs?: number): boolean;
-/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
-export declare class CohortStateStore {
+/** Serializes validated release-state revisions under a lock and commits each update atomically. */
+export declare class ReleaseStateStore {
     readonly path: string;
     constructor(dataDir: string);
-    read(): Promise<CohortState>;
-    update(operation: (current: CohortState) => CohortState | Promise<CohortState>): Promise<CohortState>;
-    recordCandidate(release: MaterializedRelease): Promise<CohortState>;
-    approve(releaseId: string, diagnosticsPath: string): Promise<CohortState>;
-    activate(releaseId: string): Promise<CohortState>;
+    read(): Promise<ReleaseState>;
+    update(operation: (current: ReleaseState) => ReleaseState | Promise<ReleaseState>): Promise<ReleaseState>;
+    recordCandidate(release: MaterializedRelease): Promise<ReleaseState>;
+    approve(releaseId: string, diagnosticsPath: string): Promise<ReleaseState>;
+    activate(releaseId: string): Promise<ReleaseState>;
     /** Atomically advances ordinary launch without allowing an older installation to roll active state back. */
-    activateForLaunch(releaseId: string, replaceUnlaunchableActiveId?: string): Promise<CohortState>;
-    rollback(): Promise<CohortState>;
+    activateForLaunch(releaseId: string, replaceUnlaunchableActiveId?: string): Promise<ReleaseState>;
+    rollback(): Promise<ReleaseState>;
     /** Atomically replace legacy retention history and detach every currently collectible record. */
-    reconcileRetention(resolveInputs: (current: CohortState) => ProtectedReleaseInputs | Promise<ProtectedReleaseInputs>, orphans?: readonly OrphanReleaseDisposition[]): Promise<ReleaseRetentionReconciliation>;
-    markCleanupTrash(releaseId: string, trashPath: string): Promise<CohortState>;
-    recordCleanupFailure(releaseId: string, stage: string, error: unknown): Promise<CohortState>;
-    completeCleanup(releaseId: string): Promise<CohortState>;
-    recordCleanupWorkerScheduled(runId: string): Promise<CohortState>;
-    recordCleanupWorkerStarted(runId: string, pid: number): Promise<CohortState>;
-    recordCleanupWorkerProgress(runId: string, summary: ReleaseCleanupWorkerSummary): Promise<CohortState>;
-    recordCleanupWorkerFinished(runId: string, status: Exclude<ReleaseCleanupWorkerStatus, "scheduled" | "running">, summary: ReleaseCleanupWorkerSummary, error?: unknown): Promise<CohortState>;
+    reconcileRetention(resolveInputs: (current: ReleaseState) => ProtectedReleaseInputs | Promise<ProtectedReleaseInputs>, orphans?: readonly OrphanReleaseDisposition[]): Promise<ReleaseRetentionReconciliation>;
+    markCleanupTrash(releaseId: string, trashPath: string): Promise<ReleaseState>;
+    recordCleanupFailure(releaseId: string, stage: string, error: unknown): Promise<ReleaseState>;
+    completeCleanup(releaseId: string): Promise<ReleaseState>;
+    recordCleanupWorkerScheduled(runId: string): Promise<ReleaseState>;
+    recordCleanupWorkerStarted(runId: string, pid: number): Promise<ReleaseState>;
+    recordCleanupWorkerProgress(runId: string, summary: ReleaseCleanupWorkerSummary): Promise<ReleaseState>;
+    recordCleanupWorkerFinished(runId: string, status: Exclude<ReleaseCleanupWorkerStatus, "scheduled" | "running">, summary: ReleaseCleanupWorkerSummary, error?: unknown): Promise<ReleaseState>;
 }
-export declare function emptyState(): CohortState;
+export declare function emptyState(): ReleaseState;