@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -1,43 +0,0 @@
-import { type ReleaseIdentity } from "./release.js";
-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;
-    readonly releaseRoot: string;
-    readonly packageVersion?: string;
-    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
- * current parent process or an authenticated live supervisor. Callers must
- * establish one of those preconditions; untrusted releases require full
- * verification.
- */
-export declare function readCertifiedReleaseManifest(record: CertifiedReleaseRecord, 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,175 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-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, 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 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 });
-    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(payload.paths.map(path => dirname(resolveWithin(candidate, path))))];
-        await mapWithConcurrency(directories, RELEASE_FILE_IO_CONCURRENCY, async (directory) => {
-            await mkdir(directory, { recursive: true, mode: 0o700 });
-        });
-        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);
-        }
-        catch (error) {
-            if (!await lstat(releaseRoot).catch(() => null))
-                throw error;
-            await rm(candidate, { recursive: true, force: true });
-            return certificationReadyRelease(await verifyMaterializedRelease(releaseRoot, identity));
-        }
-        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"));
-    return await verifyMaterializedRelease(canonical, manifest);
-}
-/**
- * Load metadata for a release whose bytes were already certified by the
- * current parent process or an authenticated live supervisor. Callers must
- * establish one of those preconditions; untrusted releases require full
- * verification.
- */
-export async function readCertifiedReleaseManifest(record, selectedStoreRoot) {
-    const canonical = await realpath(record.releaseRoot);
-    assertContained(await realpath(selectedStoreRoot), canonical, "release root is outside the selected release store");
-    const manifest = JSON.parse(await readFile(resolveWithin(canonical, RELEASE_MANIFEST_FILENAME), "utf8"));
-    validateManifest(manifest);
-    if (manifest.releaseId !== record.releaseId || manifest.contentDigest !== record.contentDigest
-        || (record.packageVersion !== undefined && manifest.packageVersion !== record.packageVersion)) {
-        throw new Error(`certified release record differs from manifest for ${canonical}`);
-    }
-    if (canonical.split(sep).at(-1) !== manifest.releaseId)
-        throw new Error(`release directory does not match identity ${manifest.releaseId}`);
-    return { ...manifest, releaseRoot: canonical };
-}
-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");
-    const manifestPath = resolveWithin(canonical, RELEASE_MANIFEST_FILENAME);
-    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
-    validateManifest(manifest);
-    if (expected && (manifest.releaseId !== expected.releaseId || manifest.contentDigest !== expected.contentDigest)) {
-        throw new Error(`release identity mismatch for ${canonical}`);
-    }
-    if (canonical.split(sep).at(-1) !== manifest.releaseId && !canonical.split(sep).at(-1)?.startsWith(`.candidate-${manifest.releaseId}-`)) {
-        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, options);
-    });
-    const recomputed = digestManifestFiles(manifest.files);
-    if (recomputed !== manifest.contentDigest)
-        throw new Error(`release content digest mismatch for ${manifest.releaseId}`);
-    return { ...manifest, releaseRoot: canonical };
-}
-export async function assertImmutableExecutionRoot(release, dataDir) {
-    const storeRoot = await realpath(resolve(dataDir, "releases"));
-    assertContained(storeRoot, release.releaseRoot, "release root is outside the selected release store");
-    const selectedRoot = process.env[PRODUCT_IDENTITY.environment.releaseRoot];
-    if (!selectedRoot)
-        throw new Error(PRODUCT_TEXT.diagnostic("persistent process has no immutable release root"));
-    const selected = await realpath(selectedRoot);
-    if (selected !== release.releaseRoot)
-        throw new Error(PRODUCT_TEXT.diagnostic("persistent process selected a different immutable release root"));
-}
-export async function resolveReleaseEntryPoint(release, entryPoint) {
-    const normalized = entryPoint.split("\\").join("/").replace(/^\.\//, "");
-    if (!release.files.some(file => file.path === normalized))
-        throw new Error(`entry point is not in the verified release manifest: ${entryPoint}`);
-    const path = resolveWithin(release.releaseRoot, normalized);
-    const canonical = await realpath(path);
-    assertContained(release.releaseRoot, canonical, "entry point resolves outside the selected release root");
-    return canonical;
-}
-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 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"));
-    if (!/^[a-f0-9]{64}$/.test(value.contentDigest) || !/^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/.test(value.releaseId))
-        throw new Error(PRODUCT_TEXT.diagnostic("release identity is invalid"));
-    if (!Array.isArray(value.files) || value.files.length === 0)
-        throw new Error("release manifest contains no files");
-    for (const file of value.files) {
-        if (typeof file.path !== "string" || file.path.length === 0 || file.path.includes("\\") || file.path.startsWith("/") || file.path.split("/").includes("..")) {
-            throw new Error(`invalid release manifest path: ${String(file.path)}`);
-        }
-        if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || !/^[a-f0-9]{64}$/.test(file.sha256))
-            throw new Error(`invalid release manifest file identity: ${file.path}`);
-    }
-}
-function assertContained(parent, child, message) {
-    const fromParent = relative(parent, child);
-    if (fromParent === "" || (!fromParent.startsWith(`..${sep}`) && fromParent !== ".." && !isAbsolute(fromParent)))
-        return;
-    throw new Error(`${message}: ${child}`);
-}

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

@@ -1,38 +0,0 @@
-export declare const PRODUCT_PACKAGE_NAME: string;
-export interface ReleaseFileIdentity {
-    readonly path: string;
-    readonly bytes: number;
-    readonly sha256: string;
-    readonly executable: boolean;
-}
-export interface ReleaseIdentity {
-    readonly packageName: typeof PRODUCT_PACKAGE_NAME;
-    readonly packageVersion: string;
-    readonly contentDigest: string;
-    readonly releaseId: string;
-    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

@@ -1,204 +0,0 @@
-import { createHash } from "node:crypto";
-import { lstat, readFile, readdir, realpath } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
-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;
-/** Discover the complete payload without reading ordinary file contents. */
-export async function discoverReleasePayload(packageRoot, options = {}) {
-    const canonicalRoot = await realpath(packageRoot);
-    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)
-        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() || metadata.isSymbolicLink())
-            throw new Error(`release payload is not a regular file: ${path}`);
-        const bytes = payload.cachedFiles.get(path) ?? await readFile(absolute);
-        return releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0);
-    });
-    return createReleaseIdentity(payload.packageRoot, payload.packageVersion, files);
-}
-export function createReleaseIdentity(packageRoot, packageVersion, files) {
-    const contentDigest = digestManifestFiles(files);
-    return {
-        packageName: PRODUCT_PACKAGE_NAME,
-        packageVersion,
-        contentDigest,
-        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");
-    const absolute = resolve(root, candidate);
-    const fromRoot = relative(root, absolute);
-    if (fromRoot === "" || (!isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`)))
-        return absolute;
-    throw new Error(`release path escapes selected root: ${candidate}`);
-}
-function distributionRoots(manifest) {
-    if (!Array.isArray(manifest.files))
-        throw new Error(PRODUCT_TEXT.diagnostic("package metadata has no distribution files list"));
-    const roots = manifest.files.map(value => {
-        if (typeof value !== "string" || value.length === 0)
-            throw new Error(PRODUCT_TEXT.diagnostic("distribution file entry is invalid"));
-        const normalized = normalizeRelative(value);
-        if (normalized === "package.json")
-            return normalized;
-        if (isAbsolute(value) || normalized === ".." || normalized.startsWith("../"))
-            throw new Error(PRODUCT_TEXT.diagnostic(`distribution path escapes package root: ${value}`));
-        return normalized;
-    });
-    return [...new Set(roots)];
-}
-async function collectFiles(root, path, output, skipNodeModules = false) {
-    const metadata = await lstat(path);
-    const relativePath = normalizeRelative(relative(root, path));
-    if (metadata.isSymbolicLink())
-        throw new Error(`release payload contains a symbolic link: ${relativePath}`);
-    if (metadata.isFile()) {
-        output.add(relativePath);
-        return;
-    }
-    if (!metadata.isDirectory())
-        throw new Error(`release payload contains an unsupported entry: ${relativePath}`);
-    for (const entry of await readdir(path)) {
-        if (entry === ".bin" || (skipNodeModules && entry === "node_modules"))
-            continue;
-        await collectFiles(root, resolve(path, entry), output, skipNodeModules);
-    }
-}
-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()) {
-        const packagePath = await findInstalledDependency(root, requesterRoot, name);
-        if (!packagePath) {
-            if (optional.has(name))
-                continue;
-            throw new Error(`installed ${PRODUCT_TEXT.displayName} dependency is missing: ${name}`);
-        }
-        if (visited.has(packagePath))
-            continue;
-        visited.add(packagePath);
-        await collectFiles(root, packagePath, output, true);
-        await collectDependencyClosure(root, packagePath, await readManifest(packagePath), output, visited, readManifest);
-    }
-}
-async function findInstalledDependency(root, requesterRoot, name) {
-    let directory = requesterRoot;
-    while (true) {
-        const candidate = resolve(directory, "node_modules", name);
-        if (await isContained(root, candidate)) {
-            const metadata = await lstat(candidate).catch(() => null);
-            if (metadata?.isDirectory() && !metadata.isSymbolicLink())
-                return candidate;
-            // A linked dependency directory is how this installation unifies a module
-            // that would otherwise be present twice, and the link is made by A1 itself
-            // at install and at every launch. Follow it to the directory it names and
-            // collect from there, so the payload still reads only real files — but
-            // only when the target is inside this installation, so a link can never
-            // pull bytes in from somewhere else.
-            if (metadata?.isSymbolicLink()) {
-                const target = await realpath(candidate).catch(() => null);
-                if (target !== null && await isContained(root, target)) {
-                    const targetMetadata = await lstat(target).catch(() => null);
-                    if (targetMetadata?.isDirectory())
-                        return target;
-                }
-            }
-        }
-        if (directory === root)
-            return null;
-        const parent = dirname(directory);
-        if (parent === directory || relative(root, parent).startsWith(".."))
-            return null;
-        directory = parent;
-    }
-}
-/** True when `path` sits inside `root`, comparing what each one actually resolves to. */
-async function isContained(root, path) {
-    const within = (from, to) => {
-        const value = relative(from, to);
-        return value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value);
-    };
-    if (within(root, path))
-        return true;
-    const canonicalRoot = await realpath(root).catch(() => null);
-    return canonicalRoot !== null && within(canonicalRoot, path);
-}
-function dependencyNames(value) {
-    if (value === undefined)
-        return [];
-    if (typeof value !== "object" || value === null || Array.isArray(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(/^\.\//, "");
-}
-export function packageRootFromModule(moduleUrl) {
-    const url = new URL(moduleUrl);
-    if (url.protocol !== "file:")
-        throw new Error(PRODUCT_TEXT.diagnostic(`module URL must be a file URL: ${moduleUrl}`));
-    let directory = dirname(url.pathname.replace(/^\/(.:)/, "$1"));
-    while (basename(directory) !== "") {
-        if (basename(directory) === "dist")
-            return dirname(directory);
-        directory = dirname(directory);
-    }
-    throw new Error(PRODUCT_TEXT.diagnostic("package root could not be derived from module URL"));
-}

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

@@ -1,31 +0,0 @@
-export declare const UPDATE_JOURNAL_SCHEMA: string;
-import type { UpdateChannel } from "./update.js";
-export type UpdateTransactionPhase = "shutdown-intent" | "ownership-released" | "package-installed" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified";
-export interface UpdateTransaction {
-    readonly schema: typeof UPDATE_JOURNAL_SCHEMA;
-    readonly transactionId: string;
-    readonly channel: UpdateChannel;
-    readonly targetVersion: string;
-    readonly packageRoot: string;
-    readonly priorActiveReleaseId: string | null;
-    readonly phase: UpdateTransactionPhase;
-    readonly status: "active" | "completed" | "rolled-back" | "failed";
-    readonly error: string | null;
-    readonly startedAt: string;
-    readonly updatedAt: string;
-}
-export declare class UpdateTransactionStore {
-    #private;
-    readonly path: string;
-    constructor(dataDir: string);
-    read(): Promise<UpdateTransaction | null>;
-    begin(input: {
-        channel: UpdateChannel;
-        targetVersion: string;
-        packageRoot: string;
-        priorActiveReleaseId: string | null;
-    }): Promise<UpdateTransaction>;
-    advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
-    finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
-    clearCompleted(): Promise<void>;
-}

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

@@ -1,89 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-export const UPDATE_JOURNAL_SCHEMA = PRODUCT_IDENTITY.protocol.updateJournalSchema;
-export class UpdateTransactionStore {
-    path;
-    constructor(dataDir) { this.path = resolve(dataDir, "update-transaction.json"); }
-    async read() {
-        try {
-            const value = JSON.parse(await readFile(this.path, "utf8"));
-            validate(value);
-            return value;
-        }
-        catch (error) {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT")
-                return null;
-            throw error;
-        }
-    }
-    async begin(input) {
-        const current = await this.read();
-        if (current?.status === "active") {
-            if (current.targetVersion !== input.targetVersion || current.channel !== input.channel) {
-                throw new Error(PRODUCT_TEXT.diagnostic(`has unfinished update ${current.transactionId} targeting ${current.targetVersion}; reconcile it before starting ${input.targetVersion}`));
-            }
-            return current;
-        }
-        const now = new Date().toISOString();
-        return await this.#write({
-            schema: UPDATE_JOURNAL_SCHEMA,
-            transactionId: randomUUID(),
-            ...input,
-            phase: "shutdown-intent",
-            status: "active",
-            error: null,
-            startedAt: now,
-            updatedAt: now,
-        });
-    }
-    async advance(phase) {
-        const current = await this.#requiredActive();
-        if (phaseOrder(phase) < phaseOrder(current.phase))
-            return current;
-        return await this.#write({ ...current, phase, updatedAt: new Date().toISOString() });
-    }
-    async finish(status, error = null) {
-        const current = await this.read();
-        if (!current)
-            throw new Error(`no ${PRODUCT_TEXT.displayName} update transaction is recorded`);
-        return await this.#write({ ...current, status, error, updatedAt: new Date().toISOString() });
-    }
-    async clearCompleted() {
-        const current = await this.read();
-        if (current && current.status !== "active")
-            await rm(this.path, { force: true });
-    }
-    async #requiredActive() {
-        const current = await this.read();
-        if (!current || current.status !== "active")
-            throw new Error(`no active ${PRODUCT_TEXT.displayName} update transaction is recorded`);
-        return current;
-    }
-    async #write(value) {
-        validate(value);
-        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
-        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
-        const file = await open(temporary, "wx", 0o600);
-        try {
-            await file.writeFile(JSON.stringify(value, null, 2));
-            await file.sync();
-        }
-        finally {
-            await file.close();
-        }
-        await rename(temporary, this.path);
-        return value;
-    }
-}
-function phaseOrder(phase) {
-    return ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed", "supervisor-verified"].indexOf(phase);
-}
-function validate(value) {
-    if (value.schema !== UPDATE_JOURNAL_SCHEMA || typeof value.transactionId !== "string" || !["stable", "next"].includes(value.channel)
-        || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.startedAt !== "string"
-        || typeof value.updatedAt !== "string" || phaseOrder(value.phase) < 0 || !["active", "completed", "rolled-back", "failed"].includes(value.status)) {
-        throw new Error(`invalid ${PRODUCT_TEXT.displayName} update transaction journal`);
-    }
-}

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

@@ -1,82 +0,0 @@
-import { type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
-export declare const PRODUCT_PACKAGE: string;
-export type UpdateChannel = "stable" | "next";
-export interface ProcessRequest {
-    captureStdout: boolean;
-}
-export interface ProcessResult {
-    code: number | null;
-    stdout: string;
-}
-export type UpdateProcessRunner = (command: string, arguments_: readonly string[], request: ProcessRequest) => Promise<ProcessResult>;
-export interface UpdateFileSystem {
-    readFile(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
-    access?(path: string): Promise<void>;
-}
-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;
-    /** A specific preview to install, named by its commit or its full version. */
-    target?: string;
-    environment?: NodeJS.ProcessEnv;
-    fileSystem?: UpdateFileSystem;
-    output?: UpdateOutput;
-    runner?: UpdateProcessRunner;
-    lifecycle?: UpdateLifecycleCoordinator;
-    transactionStore?: UpdateTransactionJournal;
-    progress?: boolean;
-    onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
-    now?: () => number;
-}
-export type UpdateActivationPhase = Extract<UpdateTransactionPhase, "materialized" | "certified" | "active-reference-committed">;
-/**
- * Copying the release is the longest step with nothing to say for itself, so it
- * reports the files it has written against the files it must write. A caller that
- * shows progress can then move with the work instead of guessing at it.
- */
-export interface UpdateMaterializationProgress {
-    readonly completed: number;
-    readonly total: number;
-}
-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: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void): Promise<void>;
-}
-export interface UpdateTransactionJournal {
-    readonly path: string;
-    read(): Promise<UpdateTransaction | null>;
-    begin(input: {
-        channel: UpdateChannel;
-        targetVersion: string;
-        packageRoot: string;
-        priorActiveReleaseId: string | null;
-    }): Promise<UpdateTransaction>;
-    advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
-    finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
-    clearCompleted(): Promise<void>;
-}
-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;