@timurproko/a1 0.1.1-dev.4 → 0.1.1-dev.5

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

@@ -2,7 +2,7 @@ import { type OwnershipProbe } from "./cohort-selection.js";
 import { type SupervisorEndpointMetadata } from "./cohort-state.js";
 import { type LaunchProfileId } from "../lifecycle/index.js";
 import { cleanupProvenIdleOwner } from "./process-cleanup.js";
-import { type MaterializedRelease } from "./release-store.js";
+import { type MaterializedRelease, type VerifyMaterializedReleaseOptions } from "./release-store.js";
 export interface BootstrapOptions {
     readonly packageRoot: string;
     readonly launchIntent?: {
@@ -15,7 +15,7 @@ export interface BootstrapOptions {
     readonly output?: Pick<NodeJS.WriteStream, "write">;
 }
 export declare function runBootstrap(options: BootstrapOptions): Promise<number>;
-export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string): Promise<string>;
+export declare function certifyMaterializedRelease(release: MaterializedRelease, dataDir: string, verification?: VerifyMaterializedReleaseOptions): Promise<string>;
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
 export declare function releaseEnvironment(environment: NodeJS.ProcessEnv, release: MaterializedRelease): NodeJS.ProcessEnv;
 export declare function waitForVerifiedEndpoint(path: string, release: MaterializedRelease, timeoutMs: number): Promise<void>;

package/dist/src/foundation/release/bootstrap.js

@@ -8,7 +8,7 @@ import { CohortStateStore } from "./cohort-state.js";
 import { assertLaunchProfileId, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
-import { materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
+import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export async function runBootstrap(options) {
     const environment = { ...(options.environment ?? process.env) };
@@ -123,8 +123,10 @@ async function readInstalledVersion(packageRoot) {
     }
     return manifest.version;
 }
-export async function certifyMaterializedRelease(release, dataDir) {
-    await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"));
+export async function certifyMaterializedRelease(release, dataDir, verification = {}) {
+    if (!consumeMaterializationProof(release)) {
+        await verifyMaterializedRelease(release.releaseRoot, release, resolve(dataDir, "releases"), verification);
+    }
     const path = resolve(dataDir, `certification-${release.releaseId}.json`);
     await writeFile(path, JSON.stringify({
         schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,

package/dist/src/foundation/release/release-store.d.ts

@@ -3,11 +3,23 @@ export declare const RELEASE_MANIFEST_FILENAME: string;
 export interface MaterializedRelease extends ReleaseIdentity {
     readonly releaseRoot: string;
 }
+export type ReleaseContentOperation = "source-read" | "candidate-write" | "verification-read";
+export interface ReleaseContentOperationEvent {
+    readonly operation: ReleaseContentOperation;
+    readonly path: string;
+    readonly bytes: number;
+}
 export interface MaterializeReleaseOptions {
     readonly onProgress?: (progress: {
         readonly phase: "copying";
         readonly fileCount: number;
     }) => void;
+    readonly onOperation?: (event: ReleaseContentOperationEvent) => void;
+    /** Test seam for deterministic write-failure coverage. */
+    readonly writeCandidateFile?: (path: string, bytes: Uint8Array, mode: number) => Promise<void>;
+}
+export interface VerifyMaterializedReleaseOptions {
+    readonly onOperation?: (event: ReleaseContentOperationEvent) => void;
 }
 export interface CertifiedReleaseRecord {
     readonly releaseId: string;
@@ -16,6 +28,8 @@ export interface CertifiedReleaseRecord {
     readonly contentDigest: string;
 }
 export declare function materializeRelease(packageRoot: string, dataDir: string, options?: MaterializeReleaseOptions): Promise<MaterializedRelease>;
+/** Consume proof that this exact object was freshly materialized or fully verified in this process. */
+export declare function consumeMaterializationProof(release: MaterializedRelease): boolean;
 export declare function readMaterializedRelease(releaseRoot: string): Promise<MaterializedRelease>;
 /**
  * Load metadata for a release whose bytes were already certified by the
@@ -24,6 +38,6 @@ export declare function readMaterializedRelease(releaseRoot: string): Promise<Ma
  * verification.
  */
 export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, selectedStoreRoot: string): Promise<MaterializedRelease>;
-export declare function verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, selectedStoreRoot?: string): Promise<MaterializedRelease>;
+export declare function verifyMaterializedRelease(releaseRoot: string, expected?: ReleaseIdentity, selectedStoreRoot?: string, options?: VerifyMaterializedReleaseOptions): Promise<MaterializedRelease>;
 export declare function assertImmutableExecutionRoot(release: MaterializedRelease, dataDir: string): Promise<void>;
 export declare function resolveReleaseEntryPoint(release: MaterializedRelease, entryPoint: string): Promise<string>;

package/dist/src/foundation/release/release-store.js

@@ -1,33 +1,52 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, copyFile, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { PRODUCT_PACKAGE_NAME, deriveReleaseIdentity, resolveWithin } from "./release.js";
+import { PRODUCT_PACKAGE_NAME, createReleaseIdentity, digestManifestFiles, discoverReleasePayload, releaseFileIdentity, resolveWithin, } from "./release.js";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { mapWithConcurrency } from "./concurrency.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
+const certificationReady = new WeakSet();
 export const RELEASE_MANIFEST_FILENAME = PRODUCT_IDENTITY.manifest.releaseFilename;
 export async function materializeRelease(packageRoot, dataDir, options = {}) {
-    const identity = await deriveReleaseIdentity(packageRoot);
+    const payload = await discoverReleasePayload(packageRoot, {
+        onSourceRead: (path, bytes) => options.onOperation?.({ operation: "source-read", path, bytes }),
+    });
     const storeRoot = resolve(dataDir, "releases");
     await mkdir(storeRoot, { recursive: true, mode: 0o700 });
-    const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
-    const existing = await lstat(releaseRoot).catch(() => null);
-    if (existing)
-        return await verifyMaterializedRelease(releaseRoot, identity);
-    options.onProgress?.({ phase: "copying", fileCount: identity.files.length });
-    const candidate = resolveWithin(storeRoot, `.candidate-${identity.releaseId}-${randomUUID()}`);
+    options.onProgress?.({ phase: "copying", fileCount: payload.paths.length });
+    const candidate = resolveWithin(storeRoot, `.candidate-${randomUUID()}`);
     await mkdir(candidate, { recursive: false, mode: 0o700 });
     try {
-        const directories = [...new Set(identity.files.map(file => dirname(resolveWithin(candidate, file.path))))];
+        const directories = [...new Set(payload.paths.map(path => dirname(resolveWithin(candidate, path))))];
         await mapWithConcurrency(directories, RELEASE_FILE_IO_CONCURRENCY, async (directory) => {
             await mkdir(directory, { recursive: true, mode: 0o700 });
         });
-        await mapWithConcurrency(identity.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
-            const source = resolveWithin(identity.packageRoot, file.path);
-            const destination = resolveWithin(candidate, file.path);
-            await copyFile(source, destination);
-            await chmod(destination, file.executable ? 0o500 : 0o400);
+        const files = await mapWithConcurrency(payload.paths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+            const source = resolveWithin(payload.packageRoot, path);
+            const destination = resolveWithin(candidate, path);
+            const metadata = await lstat(source);
+            if (!metadata.isFile() || metadata.isSymbolicLink())
+                throw new Error(`release payload is not a regular file: ${path}`);
+            const cached = payload.cachedFiles.get(path);
+            const bytes = cached ?? await readFile(source);
+            if (!cached)
+                options.onOperation?.({ operation: "source-read", path, bytes: bytes.length });
+            const mode = (metadata.mode & 0o111) !== 0 ? 0o500 : 0o400;
+            if (options.writeCandidateFile)
+                await options.writeCandidateFile(destination, bytes, mode);
+            else {
+                await writeFile(destination, bytes, { flag: "wx", mode });
+                await chmod(destination, mode);
+            }
+            options.onOperation?.({ operation: "candidate-write", path, bytes: bytes.length });
+            return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
         });
+        const identity = createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
+        const releaseRoot = resolveWithin(storeRoot, identity.releaseId);
+        if (await lstat(releaseRoot).catch(() => null)) {
+            await rm(candidate, { recursive: true, force: true });
+            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
+        }
         await writeFile(resolve(candidate, RELEASE_MANIFEST_FILENAME), JSON.stringify(identity, null, 2), { mode: 0o400, flag: "wx" });
         try {
             await rename(candidate, releaseRoot);
@@ -36,15 +55,22 @@ export async function materializeRelease(packageRoot, dataDir, options = {}) {
             if (!await lstat(releaseRoot).catch(() => null))
                 throw error;
             await rm(candidate, { recursive: true, force: true });
-            return await verifyMaterializedRelease(releaseRoot, identity);
+            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
         }
-        return { ...identity, releaseRoot: await realpath(releaseRoot) };
+        return certificationReadyRelease({ ...identity, releaseRoot: await realpath(releaseRoot) });
     }
     catch (error) {
         await rm(candidate, { recursive: true, force: true });
         throw error;
     }
 }
+/** Consume proof that this exact object was freshly materialized or fully verified in this process. */
+export function consumeMaterializationProof(release) {
+    if (!certificationReady.has(release))
+        return false;
+    certificationReady.delete(release);
+    return true;
+}
 export async function readMaterializedRelease(releaseRoot) {
     const canonical = await realpath(releaseRoot);
     const manifest = JSON.parse(await readFile(resolve(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
@@ -69,7 +95,7 @@ export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
     return { ...manifest, releaseRoot: canonical };
 }
-export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot) {
+export async function verifyMaterializedRelease(releaseRoot, expected, selectedStoreRoot, options = {}) {
     const canonical = await realpath(releaseRoot);
     if (selectedStoreRoot)
         assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
@@ -83,7 +109,7 @@ export async function verifyMaterializedRelease(releaseRoot, expected, selectedS
         throw new Error(`release directory does not match identity ${manifest.releaseId}`);
     }
     await mapWithConcurrency(manifest.files, RELEASE_FILE_IO_CONCURRENCY, async (file) => {
-        await verifyFile(canonical, file);
+        await verifyFile(canonical, file, options);
     });
     const recomputed = digestManifestFiles(manifest.files);
     if (recomputed !== manifest.contentDigest)
@@ -109,17 +135,23 @@ export async function resolveReleaseEntryPoint(release, entryPoint) {
     assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
     return canonical;
 }
-async function verifyFile(root, file) {
+async function verifyFile(root, file, options) {
     const path = resolveWithin(root, file.path);
     const metadata = await lstat(path).catch(() => null);
     if (!metadata?.isFile() || metadata.isSymbolicLink())
         throw new Error(`release candidate is incomplete: ${file.path}`);
     if (metadata.size !== file.bytes)
         throw new Error(`release file size mismatch: ${file.path}`);
-    const digest = createHash("sha256").update(await readFile(path)).digest("hex");
+    const bytes = await readFile(path);
+    options.onOperation?.({ operation: "verification-read", path: file.path, bytes: bytes.length });
+    const digest = createHash("sha256").update(bytes).digest("hex");
     if (digest !== file.sha256)
         throw new Error(`release file digest mismatch: ${file.path}`);
 }
+function certificationReadyRelease(release) {
+    certificationReady.add(release);
+    return release;
+}
 function validateManifest(value) {
     if (value.packageName !== PRODUCT_PACKAGE_NAME || typeof value.packageVersion !== "string")
         throw new Error(PRODUCT_TEXT.diagnostic("release manifest metadata is invalid"));
@@ -135,13 +167,6 @@ function validateManifest(value) {
             throw new Error(`invalid release manifest file identity: ${file.path}`);
     }
 }
-function digestManifestFiles(files) {
-    const digest = createHash("sha256");
-    for (const file of [...files].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)) {
-        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
-    }
-    return digest.digest("hex");
-}
 function assertContained(parent, child, message) {
     const fromParent = relative(parent, child);
     if (fromParent === "" || (!fromParent.startsWith(`..${sep}`) && fromParent !== ".." && !isAbsolute(fromParent)))

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

@@ -13,11 +13,26 @@ export interface ReleaseIdentity {
     readonly packageRoot: string;
     readonly files: readonly ReleaseFileIdentity[];
 }
+export interface DiscoveredReleasePayload {
+    readonly packageRoot: string;
+    readonly packageVersion: string;
+    readonly paths: readonly string[];
+    /** Package manifests already read to discover the dependency closure. */
+    readonly cachedFiles: ReadonlyMap<string, Buffer>;
+}
+export interface DiscoverReleasePayloadOptions {
+    readonly onSourceRead?: (path: string, bytes: number) => void;
+}
+/** Discover the complete payload without reading ordinary file contents. */
+export declare function discoverReleasePayload(packageRoot: string, options?: DiscoverReleasePayloadOptions): Promise<DiscoveredReleasePayload>;
 /**
  * Derive release execution identity only from installed distribution metadata and
  * bytes. The version remains display metadata; the digest selects executable
  * content.
  */
 export declare function deriveReleaseIdentity(packageRoot: string): Promise<ReleaseIdentity>;
+export declare function createReleaseIdentity(packageRoot: string, packageVersion: string, files: readonly ReleaseFileIdentity[]): ReleaseIdentity;
+export declare function releaseFileIdentity(path: string, bytes: Uint8Array, executable: boolean): ReleaseFileIdentity;
+export declare function digestManifestFiles(files: readonly ReleaseFileIdentity[]): string;
 export declare function resolveWithin(root: string, candidate: string): string;
 export declare function packageRootFromModule(moduleUrl: string): string;

package/dist/src/foundation/release/release.js

@@ -5,53 +5,78 @@ import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 import { mapWithConcurrency } from "./concurrency.js";
 const RELEASE_FILE_IO_CONCURRENCY = 32;
 export const PRODUCT_PACKAGE_NAME = PRODUCT_IDENTITY.packageName;
-/**
- * Derive release execution identity only from installed distribution metadata and
- * bytes. The version remains display metadata; the digest selects executable
- * content.
- */
-export async function deriveReleaseIdentity(packageRoot) {
+/** Discover the complete payload without reading ordinary file contents. */
+export async function discoverReleasePayload(packageRoot, options = {}) {
     const canonicalRoot = await realpath(packageRoot);
-    const manifestPath = resolve(canonicalRoot, "package.json");
-    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    const cachedFiles = new Map();
+    const readManifest = async (manifestRoot) => {
+        const manifestPath = resolve(manifestRoot, "package.json");
+        const bytes = await readFile(manifestPath);
+        const path = normalizeRelative(relative(canonicalRoot, manifestPath));
+        cachedFiles.set(path, bytes);
+        options.onSourceRead?.(path, bytes.length);
+        return JSON.parse(bytes.toString("utf8"));
+    };
+    const manifest = await readManifest(canonicalRoot);
     if (manifest.name !== PRODUCT_PACKAGE_NAME)
         throw new Error(`unexpected ${PRODUCT_TEXT.displayName} package name: ${String(manifest.name)}`);
     if (typeof manifest.version !== "string" || manifest.version.length === 0)
         throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no version"));
     const roots = distributionRoots(manifest);
     const paths = new Set(["package.json"]);
-    for (const root of roots) {
-        const absolute = resolveWithin(canonicalRoot, root);
-        await collectFiles(canonicalRoot, absolute, paths);
-    }
-    await collectDependencyClosure(canonicalRoot, canonicalRoot, manifest, paths, new Set());
-    const sortedPaths = [...paths].sort();
-    const files = await mapWithConcurrency(sortedPaths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
-        const absolute = resolveWithin(canonicalRoot, path);
+    for (const root of roots)
+        await collectFiles(canonicalRoot, resolveWithin(canonicalRoot, root), paths);
+    await collectDependencyClosure(canonicalRoot, canonicalRoot, manifest, paths, new Set(), readManifest);
+    return {
+        packageRoot: canonicalRoot,
+        packageVersion: manifest.version,
+        paths: [...paths].sort(),
+        cachedFiles,
+    };
+}
+/**
+ * Derive release execution identity only from installed distribution metadata and
+ * bytes. The version remains display metadata; the digest selects executable
+ * content.
+ */
+export async function deriveReleaseIdentity(packageRoot) {
+    const payload = await discoverReleasePayload(packageRoot);
+    const files = await mapWithConcurrency(payload.paths, RELEASE_FILE_IO_CONCURRENCY, async (path) => {
+        const absolute = resolveWithin(payload.packageRoot, path);
         const metadata = await lstat(absolute);
-        if (!metadata.isFile())
+        if (!metadata.isFile() || metadata.isSymbolicLink())
             throw new Error(`release payload is not a regular file: ${path}`);
-        const bytes = await readFile(absolute);
-        return {
-            path: normalizeRelative(path),
-            bytes: bytes.length,
-            sha256: createHash("sha256").update(bytes).digest("hex"),
-            executable: (metadata.mode & 0o111) !== 0,
-        };
+        const bytes = payload.cachedFiles.get(path) ?? await readFile(absolute);
+        return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
     });
-    const digest = createHash("sha256");
-    for (const file of files)
-        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
-    const contentDigest = digest.digest("hex");
+    return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
+}
+export function createReleaseIdentity(packageRoot, packageVersion, files) {
+    const contentDigest = digestManifestFiles(files);
     return {
         packageName: PRODUCT_PACKAGE_NAME,
-        packageVersion: manifest.version,
+        packageVersion,
         contentDigest,
-        releaseId: `${manifest.version}-${contentDigest.slice(0, 20)}`,
-        packageRoot: canonicalRoot,
-        files,
+        releaseId: `${packageVersion}-${contentDigest.slice(0, 20)}`,
+        packageRoot,
+        files: [...files].sort(compareReleaseFiles),
     };
 }
+export function releaseFileIdentity(path, bytes, executable) {
+    return {
+        path: normalizeRelative(path),
+        bytes: bytes.length,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        executable,
+    };
+}
+export function digestManifestFiles(files) {
+    const digest = createHash("sha256");
+    for (const file of [...files].sort(compareReleaseFiles)) {
+        digest.update(`${file.path}\0${file.bytes}\0${file.sha256}\0${file.executable ? 1 : 0}\n`);
+    }
+    return digest.digest("hex");
+}
 export function resolveWithin(root, candidate) {
     if (candidate.includes("\0"))
         throw new Error("release path contains a null byte");
@@ -93,7 +118,7 @@ async function collectFiles(root, path, output, skipNodeModules = false) {
         await collectFiles(root, resolve(path, entry), output, skipNodeModules);
     }
 }
-async function collectDependencyClosure(root, requesterRoot, manifest, output, visited) {
+async function collectDependencyClosure(root, requesterRoot, manifest, output, visited, readManifest) {
     const required = dependencyNames(manifest.dependencies);
     const optional = new Set(dependencyNames(manifest.optionalDependencies));
     for (const name of [...new Set([...required, ...optional])].sort()) {
@@ -107,8 +132,7 @@ async function collectDependencyClosure(root, requesterRoot, manifest, output, v
             continue;
         visited.add(packagePath);
         await collectFiles(root, packagePath, output, true);
-        const dependencyManifest = JSON.parse(await readFile(resolve(packagePath, "package.json"), "utf8"));
-        await collectDependencyClosure(root, packagePath, dependencyManifest, output, visited);
+        await collectDependencyClosure(root, packagePath, await readManifest(packagePath), output, visited, readManifest);
     }
 }
 async function findInstalledDependency(root, requesterRoot, name) {
@@ -136,6 +160,9 @@ function dependencyNames(value) {
         throw new Error(PRODUCT_TEXT.diagnostic("dependency metadata is invalid"));
     return Object.keys(value);
 }
+function compareReleaseFiles(left, right) {
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
 function normalizeRelative(path) {
     return path.split(sep).join("/").replace(/^\.\//, "");
 }

package/dist/src/foundation/release/update.d.ts

@@ -18,6 +18,18 @@ export interface UpdateOutput {
     stdout(message: string): void;
     stderr(message: string): void;
 }
+export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified" | "transaction-complete";
+export interface UpdatePhaseTimingEvent {
+    readonly phase: UpdateMeasuredPhase;
+    readonly durationMs: number;
+}
+export interface UpdatePerformanceEvidence {
+    readonly fileCount: number;
+    readonly sourceReads: number;
+    readonly candidateWrites: number;
+    readonly verificationReads: number;
+    readonly postNpmDurationMs: number;
+}
 export interface SelfUpdateOptions {
     packageRoot: string;
     channel?: UpdateChannel;
@@ -27,14 +39,17 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
+    now?: () => number;
 }
+export type UpdateActivationPhase = Extract<UpdateTransactionPhase, "materialized" | "certified" | "active-reference-committed">;
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
         priorActiveVersion: string | null;
     }>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateTransactionPhase) => Promise<void>): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>): Promise<void>;
 }
 export interface UpdateTransactionJournal {
     readonly path: string;
@@ -52,3 +67,4 @@ export interface UpdateTransactionJournal {
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
+export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

package/dist/src/foundation/release/update.js

@@ -127,9 +127,19 @@ export async function runSelfUpdate(options) {
     const runner = options.runner ?? createNpmProcessRunner();
     const channel = options.channel ?? "stable";
     const distTag = UPDATE_DIST_TAGS[channel];
+    const now = options.now ?? (() => performance.now());
+    const measure = async (phase, operation) => {
+        const startedAt = now();
+        try {
+            return await operation();
+        }
+        finally {
+            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - startedAt) });
+        }
+    };
     let runningVersion;
     try {
-        const packageJson = JSON.parse(await fileSystem.readFile(resolve(options.packageRoot, "package.json")));
+        const packageJson = JSON.parse(await measure("package-version", async () => await fileSystem.readFile(resolve(options.packageRoot, "package.json"))));
         const parsedVersion = typeof packageJson.version === "string" ? validSemver(packageJson.version) : null;
         if (parsedVersion === null)
             throw new Error("package.json does not contain a valid semantic version");
@@ -139,7 +149,7 @@ export async function runSelfUpdate(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its running package version: ${errorMessage(error)}`)}\n`);
         return 1;
     }
-    const targetLookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`);
+    const targetLookup = await measure("target-resolution", async () => await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`));
     if (targetLookup.result === null)
         return targetLookup.exitCode;
     const targetVersion = validSemver(targetLookup.result.stdout.trim());
@@ -148,7 +158,7 @@ export async function runSelfUpdate(options) {
         return 1;
     }
     output.stdout(`${PRODUCT_TEXT.diagnostic(`update (${channel}): ${runningVersion} → ${targetVersion}.`)}\n`);
-    const rootLookup = await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root");
+    const rootLookup = await measure("global-root", async () => await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root"));
     if (rootLookup.result === null)
         return rootLookup.exitCode;
     if (rootLookup.result.stdout.trim().length === 0) {
@@ -191,12 +201,14 @@ export async function runSelfUpdate(options) {
             priorActiveReleaseId: cohortState.references.active,
         });
         if (phaseBefore(transaction.phase, "ownership-released")) {
-            await lifecycle.shutdownVerifiedOwners(targetVersion);
-            await lifecycle.verifyPackageUnlocked(packageRoot);
+            await measure("ownership-release", async () => {
+                await lifecycle.shutdownVerifiedOwners(targetVersion);
+                await lifecycle.verifyPackageUnlocked(packageRoot);
+            });
             transaction = await transactionStore.advance("ownership-released");
         }
         if (phaseBefore(transaction.phase, "package-installed")) {
-            const installation = await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false);
+            const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
             if (installation.result === null)
                 throw new UpdateFailure(installation.exitCode, "npm process failed");
             if (installation.result.code !== 0) {
@@ -209,11 +221,19 @@ export async function runSelfUpdate(options) {
         // Ownership can be reacquired after an interrupted installation (for
         // example, if bare A1 is launched before the update is resumed). Recheck
         // immediately before activation so recovery cannot start a second cohort.
-        await lifecycle.shutdownVerifiedOwners(targetVersion);
-        await lifecycle.activateInstalled(packageRoot, targetVersion, async (phase) => { transaction = await transactionStore.advance(phase); });
+        await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
+        let activationPhaseStartedAt = now();
+        await lifecycle.activateInstalled(packageRoot, targetVersion, async (phase) => {
+            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+            transaction = await transactionStore.advance(phase);
+            activationPhaseStartedAt = now();
+        });
+        options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
+        const transactionStartedAt = now();
         await transactionStore.advance("supervisor-verified");
         await transactionStore.finish("completed");
         await transactionStore.clearCompleted();
+        options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         output.stdout(`${PRODUCT_TEXT.diagnostic(`updated successfully: ${targetVersion} (${channel}).`)}\n`);
         return 0;
     }
@@ -228,6 +248,21 @@ export async function runSelfUpdate(options) {
         return error instanceof UpdateFailure ? error.exitCode : 1;
     }
 }
+export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs = 30_000) {
+    const failures = [];
+    if (evidence.fileCount < 1)
+        failures.push("fixture contains no payload files");
+    if (evidence.sourceReads !== evidence.fileCount)
+        failures.push(`source payload read count is ${evidence.sourceReads} for ${evidence.fileCount} files`);
+    if (evidence.candidateWrites !== evidence.fileCount)
+        failures.push(`candidate payload write count is ${evidence.candidateWrites} for ${evidence.fileCount} files`);
+    if (evidence.verificationReads > 0)
+        failures.push(`fresh certification reread ${evidence.verificationReads} candidate files`);
+    if (evidence.postNpmDurationMs > maximumPostNpmDurationMs)
+        failures.push(`post-npm activation took ${Math.round(evidence.postNpmDurationMs)}ms; budget is ${maximumPostNpmDurationMs}ms`);
+    if (failures.length > 0)
+        throw new Error(`update performance budget failed: ${failures.join("; ")}`);
+}
 async function requestUpdateShutdown(metadata, targetVersion, timeoutMs) {
     if (!processIsAlive(metadata.pid))
         return { accepted: false, reason: "recorded owner is dead" };

package/docs/ci-release-runbook.md

@@ -0,0 +1,63 @@
+# CI and release operations
+
+This runbook is the operational source for scoped development validation, immutable npm candidates, stable certification, and branch enforcement. GitHub Actions is the only automation platform.
+
+## Stable status names
+
+Repository rules use job display names, not internal job keys. Keep these names stable:
+
+| Protected flow | Required check | Producer |
+| --- | --- | --- |
+| Pull request into `develop` | `Development validation required` | `.github/workflows/ci.yml` |
+| Accepted `develop` commit | `Development validation required` | `.github/workflows/ci.yml` push run |
+| Promotion into `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
+
+Matrix and tier job names are implementation details. Change a required name only by updating the reviewable ruleset definition, its governance tests, this runbook, and the live ruleset together.
+
+## Advisory rollout and widening validation
+
+New or materially changed selection rules run in advisory mode before their check becomes required. Compare at least one feature-only change and one cross-cutting change with a complete run. A selection miss is a policy defect: widen `config/validation-impact.json`, add a regression test, and rerun complete validation before enabling enforcement.
+
+The selector can only widen validation. To override an affected plan, dispatch **Development validation** at the exact `develop` ref with `full: true`. This selects `full-release`; it cannot suppress mandatory tiers. Dispatch **Full regression** for the complete non-physical package and clean-install path. Scheduled Full regression is also the backstop for impact-map mistakes.
+
+When selection is uncertain, deleted, renamed, unmapped, or based on an unavailable Git range, it must fail closed to full validation. Do not bypass this fallback with labels or edited workflow inputs.
+
+## Preview candidate and `next` publication
+
+1. Confirm `Development validation required` is green for the exact `develop` tip.
+2. Dispatch **Build npm next candidate** on `develop` with the exact source commit, a trusted ancestor base commit, and `confirm_candidate=build-uncertified-next-candidate`. Use `full: true` whenever ordinary affected coverage is not sufficient for the release decision.
+3. Review `candidate-evidence.json`, selected scopes, gate outcomes, package integrity, and source tree. The candidate remains explicitly stable-ineligible.
+4. Approve the protected `npm-next` environment and dispatch **Publish npm next** with the successful candidate run id and `confirm_next=publish-certified-next`.
+5. The publisher downloads and verifies the certified tarball, then publishes those bytes without checkout, installation, build, or tests. Verify its registry digest and `next` tag result.
+
+Preview candidates expire after 14 days. An expired, missing, failed, or mismatched artifact is never reconstructed in the publisher. Build and certify a new candidate.
+
+## Stable candidate, physical evidence, and `latest` publication
+
+1. Commit the final non-prerelease version to `develop`. Confirm it is clean, registry-unpublished, and `v<package-version>` is the intended tag.
+2. Dispatch **Build stable candidate** on that exact `develop` commit with `confirm_candidate=build-stable-candidate`. It packs once on Windows and fans the same verified digest to Windows, Linux, and macOS complete automated validation and clean installation.
+3. Review the `Stable automated candidate` artifact. It is not stable-eligible; physical evidence is still required.
+4. On dedicated isolated workers only, dispatch **Certify stable physical platforms** for the same source and automated-candidate run with `confirm_isolated=run-isolated-physical-certification`. Workers must carry `self-hosted`, `a1-physical`, and platform-specific labels, set `PHYSICAL_WORKER_ISOLATED=true`, and be protected by the `stable-physical` environment. Never run physical host probes on a developer workstation or ordinary hosted runner.
+5. Dispatch **Certify stable candidate** with the successful automated and physical run ids and `confirm_certification=certify-stable-candidate`. `Stable candidate required` passes only when all three automated and all three isolated physical verdicts bind the same commit, tree, version, integrity, and shasum.
+6. Promote that exact commit to `master` without source or package changes and create `v<version>` at the same commit. The protected `master` rule requires the existing `Stable candidate required` check on that commit.
+7. Dispatch **Publish npm stable** on the tag with the certification run id and `confirm_stable=publish-certified-stable-latest`, then approve `npm-stable`. It requires the current `master` and tag to equal the certified source, confirms the version is unpublished, publishes the exact tarball to `latest` with provenance, and verifies registry bytes.
+
+Stable automated and physical candidate artifacts expire after 30 days. Publication evidence is retained for 90 days. Artifact expiry requires a new pack and complete recertification; it does not permit repacking during publication.
+
+## Failure recovery
+
+- **Development failure:** inspect impact and outcome artifacts. Fix the source or mapping and rerun. Do not mark a failed tier optional.
+- **Candidate validation failure:** discard the candidate. Any source change, package change, or uncertain evidence requires a new candidate run.
+- **Physical failure:** quarantine the worker result, fix or replace the isolated worker, and rerun all evidence needed for one exact package. A hosted matrix cannot substitute for physical evidence.
+- **Approval or artifact expiry:** create and certify a new candidate. Never upload locally rebuilt bytes.
+- **Publisher failure before npm accepts bytes:** retain the candidate and diagnose identity, permissions, registry, or provenance. Retry only with the same candidate run if the registry still proves the version unpublished and the artifact has not expired.
+- **Publisher uncertainty after npm accepts bytes:** do not republish or rebuild. Query the registry for version, dist-tag, integrity, and shasum; repair a dist-tag only through a separately reviewed registry operation.
+- **Partial stable certification:** stable eligibility remains false. Missing, duplicated, failed, non-isolated, or mismatched platform evidence fails closed.
+
+## Enforcement rollout and rollback
+
+Ruleset mutation is a separate administrative operation. First run `node scripts/check-github-rulesets.mjs` in report mode and review the proposed diff. Apply only after workflows exist on the default branch, representative advisory runs pass, and a maintainer explicitly confirms the exact ruleset change. Capture the post-apply repository API response as evidence.
+
+If a required check is operationally broken, prefer correcting the workflow. Emergency rollback may disable only the affected required context after restoring the previous blocking validation path and recording maintainer approval. Never weaken force-push/deletion protection to release. Never route around certification by rebuilding inside a publisher.
+
+After rollback, publication still requires exact certified bytes. A failed or unavailable candidate workflow means release waits for a new candidate; it does not authorize an ad hoc npm upload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.1-dev.4",
+  "version": "0.1.1-dev.5",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -21,16 +21,20 @@
     "clean": "node scripts/clean.mjs",
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
+    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs && node scripts/check-validation-governance.mjs",
     "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
-    "check": "npm run typecheck && npm run check:architecture && npm run check:customization-ready && npm run check:deprecated && npm test && npm run test:release",
+    "report:validation-inventory": "node scripts/report-validation-inventory.mjs",
+    "check": "npm run test:release",
     "validate:agent": "npm run check",
     "publish:next": "tsx scripts/publish-next.ts",
-    "test": "vitest run",
-    "test:unit": "vitest run test/cli test/features test/foundation test/repository-governance --exclude '**/*.integration.test.ts'",
-    "test:integration": "vitest run test/foundation/release/update-transition.integration.test.ts test/features/launch/profile-isolation.integration.test.ts",
+    "test": "npm run test:fast",
+    "test:fast": "node scripts/run-validation-tier.mjs invariants fast",
+    "test:unit": "node scripts/run-validation-tier.mjs fast",
+    "test:integration": "node scripts/run-validation-tier.mjs launch-integration pi-engine-conformance release-update structured-runtime-integration",
+    "test:scope": "node scripts/run-validation-tier.mjs",
+    "test:full": "node scripts/run-validation-tier.mjs full-release",
     "test:release": "node scripts/run-release-gates.mjs",
     "test:terminal-host": "node scripts/run-terminal-host-probe.mjs",
     "test:pi-terminal-parity": "npm run build --silent && node scripts/run-pi-terminal-parity.mjs",