@zq-silk/yui 0.6.0 → 0.6.2

package/dist/release/runtimeRelease.js

@@ -0,0 +1,495 @@
+/**
+ * Immutable local runtime releases and Controller handover provenance
+ * (Issue 02).
+ *
+ * A release is a self-contained, content-addressed runtime package unpacked
+ * below `runtime/releases/<version>-<package-sha256>/`. The Home's active
+ * release pointer (`runtime/active-release.json`) names exactly one release;
+ * the stable launcher shim resolves the CLI through that pointer instead of
+ * symlinking a development checkout.
+ *
+ * The Controller writes its provenance to `runtime/runtime-identity.json` on
+ * every start, and a versioned handover fence (`runtime/handover-fence.json`)
+ * plus receipt (`runtime/handover.json`) make a Controller replacement
+ * deterministic and recoverable.
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+export const RELEASES_DIRECTORY = "runtime/releases";
+export const ACTIVE_RELEASE_POINTER_PATH = "runtime/active-release.json";
+export const RUNTIME_IDENTITY_PATH = "runtime/runtime-identity.json";
+export const HANDOVER_FENCE_PATH = "runtime/handover-fence.json";
+export const HANDOVER_RECEIPT_PATH = "runtime/handover.json";
+export const CANDIDATE_DISCOVERY_PATH = "runtime/controller-candidate.json";
+export const RELEASE_MANIFEST_FILE = "release-manifest.json";
+export const SMOKE_RECEIPT_FILE = "smoke-receipt.json";
+/** `<version>-<package-sha256>` — the immutable release directory name. */
+export function releaseDirectoryName(manifest) {
+    return `${manifest.version}-${manifest.packageDigest}`;
+}
+export function releasesDirectory(home) {
+    return join(resolve(home), RELEASES_DIRECTORY);
+}
+export function releaseDirectoryFor(home, manifest) {
+    return join(releasesDirectory(home), releaseDirectoryName(manifest));
+}
+/** Reads and validates a release manifest. Fails closed on any drift. */
+export function readReleaseManifest(releaseDir) {
+    const manifestPath = join(releaseDir, RELEASE_MANIFEST_FILE);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Runtime release manifest is unreadable: ${manifestPath}.`, { cause: error });
+    }
+    return validateManifest(parsed);
+}
+/**
+ * Verifies an installed release against its manifest: every listed file must
+ * exist with the exact SHA-256 and byte length, the tree must contain no
+ * unlisted files, and the package digest must match. Any drift fails closed.
+ */
+export function verifyReleaseIntegrity(releaseDir) {
+    const manifest = readReleaseManifest(releaseDir);
+    const actual = listReleaseFiles(releaseDir)
+        .map((name) => inventoryFile(releaseDir, name));
+    const expected = [...manifest.files].sort(compareFiles);
+    if (actual.length !== expected.length) {
+        throw new Error(`Runtime release file count drifted from its manifest `
+            + `(expected ${expected.length}, found ${actual.length}).`);
+    }
+    for (let index = 0; index < expected.length; index += 1) {
+        const expectedFile = expected[index];
+        const actualFile = actual[index];
+        if (expectedFile.path !== actualFile.path
+            || expectedFile.sha256 !== actualFile.sha256
+            || expectedFile.bytes !== actualFile.bytes) {
+            throw new Error(`Runtime release content drifted from its manifest: ${expectedFile.path}.`);
+        }
+    }
+    if (computePackageDigest(actual) !== manifest.packageDigest) {
+        throw new Error("Runtime release package digest does not match its manifest.");
+    }
+    return manifest;
+}
+/**
+ * A release directory must be immutable and self-contained: no Git worktree
+ * metadata at its root and no symbolic links anywhere below it.
+ */
+export function assertReleaseIsNotWorktreeOrLinked(releaseDir) {
+    const root = resolve(releaseDir);
+    for (const marker of [".git", ".gitfile"]) {
+        if (existsSync(join(root, marker))) {
+            throw new Error(`Runtime release directory must not be a Git worktree: ${root} `
+                + `(found ${marker}).`);
+        }
+    }
+    assertNoSymlinks(root, root);
+}
+export function readSmokeReceipt(releaseDir) {
+    const receiptPath = join(releaseDir, SMOKE_RECEIPT_FILE);
+    if (!existsSync(receiptPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(receiptPath, "utf8"));
+        if (parsed === null
+            || typeof parsed !== "object"
+            || parsed.schemaVersion !== 1
+            || typeof parsed.buildId !== "string"
+            || typeof parsed.packageDigest !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSmokeReceipt(releaseDir, receipt) {
+    writeTextFileAtomically(join(releaseDir, SMOKE_RECEIPT_FILE), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+export function readActiveReleasePointer(home) {
+    const pointerPath = join(resolve(home), ACTIVE_RELEASE_POINTER_PATH);
+    if (!existsSync(pointerPath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(pointerPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Active release pointer is unreadable: ${pointerPath}.`, { cause: error });
+    }
+    return validatePointer(parsed);
+}
+export function writeActiveReleasePointer(home, pointer) {
+    validatePointer(pointer);
+    writeTextFileAtomically(join(resolve(home), ACTIVE_RELEASE_POINTER_PATH), `${JSON.stringify(pointer, null, 2)}\n`);
+}
+/**
+ * Resolves the Home's active release. Returns null when no pointer exists
+ * (legacy/dev Home). Fails closed when the pointer names a release that is
+ * missing or drifted.
+ */
+export function resolveActiveRelease(home) {
+    const pointer = readActiveReleasePointer(home);
+    if (pointer === null)
+        return null;
+    const releaseDir = join(releasesDirectory(home), pointer.releaseId);
+    if (!existsSync(releaseDir)) {
+        throw new Error(`Active release ${pointer.releaseId} is not installed; reinstall it or `
+            + "point the active release pointer at an installed release.");
+    }
+    const manifest = verifyReleaseIntegrity(releaseDir);
+    if (manifest.packageDigest !== pointer.packageDigest || manifest.buildId !== pointer.buildId) {
+        throw new Error(`Active release ${pointer.releaseId} does not match its pointer; reinstall the release.`);
+    }
+    return { releaseDir, manifest, pointer };
+}
+/**
+ * Detects the release a running script belongs to by walking up from the
+ * script's directory until a release manifest sits next to a `dist/cli.js`.
+ * Returns null for a development checkout.
+ */
+export function detectRunningRelease(scriptPath) {
+    let directory = dirname(resolve(scriptPath));
+    for (;;) {
+        const manifestPath = join(directory, RELEASE_MANIFEST_FILE);
+        const cliEntry = join(directory, "dist", "cli.js");
+        if (existsSync(manifestPath) && existsSync(cliEntry)) {
+            return { releaseDir: directory, manifest: readReleaseManifest(directory) };
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+export function readRuntimeIdentity(home) {
+    const identityPath = join(resolve(home), RUNTIME_IDENTITY_PATH);
+    if (!existsSync(identityPath))
+        return null;
+    try {
+        return validateRuntimeIdentity(JSON.parse(readFileSync(identityPath, "utf8")));
+    }
+    catch (error) {
+        throw new Error(`Runtime identity receipt is unreadable: ${identityPath}.`, { cause: error });
+    }
+}
+export function writeRuntimeIdentity(home, receipt) {
+    validateRuntimeIdentity(receipt);
+    writeTextFileAtomically(join(resolve(home), RUNTIME_IDENTITY_PATH), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+export function readHandoverFence(home) {
+    const fencePath = join(resolve(home), HANDOVER_FENCE_PATH);
+    if (!existsSync(fencePath))
+        return null;
+    try {
+        return validateHandoverFence(JSON.parse(readFileSync(fencePath, "utf8")));
+    }
+    catch (error) {
+        throw new Error(`Handover fence is unreadable: ${fencePath}.`, { cause: error });
+    }
+}
+export function writeHandoverFence(home, fence) {
+    validateHandoverFence(fence);
+    writeTextFileAtomically(join(resolve(home), HANDOVER_FENCE_PATH), `${JSON.stringify(fence, null, 2)}\n`);
+}
+export function removeHandoverFence(home) {
+    rmSync(join(resolve(home), HANDOVER_FENCE_PATH), { force: true });
+}
+export function readHandoverReceipt(home) {
+    const receiptPath = join(resolve(home), HANDOVER_RECEIPT_PATH);
+    if (!existsSync(receiptPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(receiptPath, "utf8"));
+        if (parsed === null
+            || typeof parsed !== "object"
+            || parsed.schemaVersion !== 1
+            || typeof parsed.handoverId !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeHandoverReceipt(home, receipt) {
+    writeTextFileAtomically(join(resolve(home), HANDOVER_RECEIPT_PATH), `${JSON.stringify(receipt, null, 2)}\n`);
+}
+/** True when the exact process (PID + start identity) is still alive. */
+export function isOwnerLive(owner) {
+    return readLinuxProcessStartIdentity(owner.pid) === owner.processStartIdentity;
+}
+export function readCandidateDiscovery(home) {
+    const candidatePath = join(resolve(home), CANDIDATE_DISCOVERY_PATH);
+    if (!existsSync(candidatePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(candidatePath, "utf8"));
+        if (typeof parsed.pid !== "number"
+            || !Number.isSafeInteger(parsed.pid)
+            || parsed.pid <= 0
+            || typeof parsed.processStartIdentity !== "string"
+            || !/^[0-9]{1,32}$/u.test(parsed.processStartIdentity)) {
+            return null;
+        }
+        return { pid: parsed.pid, processStartIdentity: parsed.processStartIdentity };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCandidateDiscovery(home, candidate) {
+    writeTextFileAtomically(join(resolve(home), CANDIDATE_DISCOVERY_PATH), `${JSON.stringify(candidate, null, 2)}\n`);
+}
+export function removeCandidateDiscovery(home) {
+    rmSync(join(resolve(home), CANDIDATE_DISCOVERY_PATH), { force: true });
+}
+export function acquireHandoverLock(home) {
+    const lockPath = join(resolve(home), "runtime", "handover.lock");
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const startIdentity = readLinuxProcessStartIdentity(process.pid);
+    if (startIdentity === undefined) {
+        throw new Error(`Cannot read Linux process start identity for activator PID ${process.pid}.`);
+    }
+    const owner = Object.freeze({
+        pid: process.pid,
+        processStartIdentity: startIdentity,
+        token: randomBytes(16).toString("hex"),
+        createdAt: new Date().toISOString()
+    });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            writeFileSync(lockPath, `${JSON.stringify(owner)}\n`, { flag: "wx", mode: 0o600 });
+            let released = false;
+            return {
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        const current = JSON.parse(readFileSync(lockPath, "utf8"));
+                        if (current.token === owner.token)
+                            rmSync(lockPath, { force: true });
+                    }
+                    catch {
+                        // A damaged lock must not block a future activate; leave it for
+                        // the stale-lock diagnosis below.
+                    }
+                }
+            };
+        }
+        catch (error) {
+            if (!isEexist(error))
+                throw error;
+        }
+        let existing;
+        try {
+            existing = JSON.parse(readFileSync(lockPath, "utf8"));
+        }
+        catch (error) {
+            if (isEnoent(error))
+                continue;
+            throw error;
+        }
+        if (typeof existing.pid === "number"
+            && Number.isSafeInteger(existing.pid)
+            && existing.pid > 0
+            && isHandoverLockLive(existing)) {
+            throw new Error(`Another Controller handover is already running (owner PID ${existing.pid}, `
+                + `createdAt ${String(existing.createdAt)}): ${lockPath}`);
+        }
+        rmSync(lockPath, { force: true });
+    }
+    throw new Error(`Cannot safely acquire the Controller handover lock because its owner changed repeatedly: `
+        + lockPath);
+}
+/**
+ * A handover lock is live only when its owner process is still the same
+ * generation that wrote it. A PID that exists but with a different start
+ * identity was reused by an unrelated process, so the lock is stale.
+ * Locks written before the start-identity field existed fall back to the
+ * PID-exists check for backward compatibility.
+ */
+function isHandoverLockLive(existing) {
+    if (typeof existing.pid !== "number"
+        || !Number.isSafeInteger(existing.pid)
+        || existing.pid <= 0) {
+        return false;
+    }
+    const currentIdentity = readLinuxProcessStartIdentity(existing.pid);
+    if (currentIdentity === undefined)
+        return false;
+    if (typeof existing.processStartIdentity === "string") {
+        return currentIdentity === existing.processStartIdentity;
+    }
+    return true;
+}
+export function newHandoverId() {
+    return `handover-${randomUUID()}`;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+function listReleaseFiles(directory, prefix = "") {
+    const files = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const relativeName = prefix.length === 0 ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...listReleaseFiles(join(directory, entry.name), relativeName));
+            continue;
+        }
+        if (!entry.isFile() || entry.isSymbolicLink()) {
+            throw new Error(`Runtime release tree contains an unsupported entry: ${relativeName}.`);
+        }
+        if (relativeName === RELEASE_MANIFEST_FILE || relativeName === SMOKE_RECEIPT_FILE)
+            continue;
+        files.push(relativeName);
+    }
+    return files.sort();
+}
+function inventoryFile(releaseDir, relativePath) {
+    const absolute = join(releaseDir, relativePath);
+    const metadata = lstatSync(absolute);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new Error(`Runtime release entry must be one regular file: ${relativePath}.`);
+    }
+    return {
+        path: relativePath,
+        sha256: createHash("sha256").update(readFileSync(absolute)).digest("hex"),
+        bytes: metadata.size
+    };
+}
+export function computePackageDigest(files) {
+    const hash = createHash("sha256");
+    for (const file of [...files].sort(compareFiles)) {
+        hash.update(`${file.path}\0${file.sha256}\0${file.bytes}\n`);
+    }
+    return hash.digest("hex");
+}
+function assertNoSymlinks(directory, root) {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const child = join(directory, entry.name);
+        if (entry.isSymbolicLink()) {
+            const target = (() => {
+                try {
+                    return readlinkSync(child);
+                }
+                catch {
+                    return "?";
+                }
+            })();
+            throw new Error(`Runtime release directory must not contain symbolic links: ${child} -> ${target}.`);
+        }
+        if (entry.isDirectory())
+            assertNoSymlinks(child, root);
+    }
+}
+function compareFiles(left, right) {
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+function validateManifest(value) {
+    if (value === null
+        || typeof value !== "object"
+        || value.schemaVersion !== 1
+        || typeof value.version !== "string"
+        || value.version.length === 0
+        || typeof value.buildId !== "string"
+        || value.buildId.length === 0
+        || typeof value.packageDigest !== "string"
+        || !/^[a-f0-9]{64}$/u.test(value.packageDigest)
+        || !Array.isArray(value.files)) {
+        throw new Error("Runtime release manifest is invalid.");
+    }
+    const manifest = value;
+    for (const file of manifest.files) {
+        if (file === null
+            || typeof file !== "object"
+            || typeof file.path !== "string"
+            || file.path.length === 0
+            || typeof file.sha256 !== "string"
+            || !/^[a-f0-9]{64}$/u.test(file.sha256)
+            || !Number.isSafeInteger(file.bytes)
+            || file.bytes < 0) {
+            throw new Error(`Runtime release manifest file entry is invalid: ${JSON.stringify(file)}.`);
+        }
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        version: manifest.version,
+        buildId: manifest.buildId,
+        packageDigest: manifest.packageDigest,
+        ...(manifest.sourceCommit === undefined ? {} : { sourceCommit: manifest.sourceCommit }),
+        files: Object.freeze(manifest.files.map((file) => Object.freeze({ ...file }))),
+        assembledAt: manifest.assembledAt
+    });
+}
+function validatePointer(value) {
+    if (value === null
+        || typeof value !== "object"
+        || value.schemaVersion !== 1
+        || typeof value.releaseId !== "string"
+        || value.releaseId.length === 0
+        || typeof value.version !== "string"
+        || typeof value.buildId !== "string"
+        || typeof value.packageDigest !== "string"
+        || !/^[a-f0-9]{64}$/u.test(value.packageDigest)
+        || typeof value.activatedAt !== "string") {
+        throw new Error("Active release pointer is invalid.");
+    }
+    const pointer = value;
+    return Object.freeze({ ...pointer, schemaVersion: 1 });
+}
+function validateRuntimeIdentity(value) {
+    if (value === null
+        || typeof value !== "object"
+        || value.schemaVersion !== 1
+        || typeof value.version !== "string"
+        || typeof value.executablePath !== "string"
+        || value.executablePath === ""
+        || !isStringArray(value.args)
+        || typeof value.buildId !== "string"
+        || typeof value.cliRealpath !== "string"
+        || typeof value.controllerRealpath !== "string"
+        || typeof value.pid !== "number"
+        || typeof value.processStartIdentity !== "string"
+        || (value.mode !== "primary"
+            && value.mode !== "candidate")
+        || typeof value.dualOwner !== "boolean") {
+        throw new Error("Runtime identity receipt is invalid.");
+    }
+    return value;
+}
+function validateHandoverFence(value) {
+    if (value === null
+        || typeof value !== "object"
+        || value.schemaVersion !== 1
+        || typeof value.handoverId !== "string"
+        || !isHandoverPhase(value.phase)) {
+        throw new Error("Handover fence is invalid.");
+    }
+    return value;
+}
+function isHandoverPhase(value) {
+    return value === "fenced"
+        || value === "candidate-ready"
+        || value === "committed"
+        || value === "rolled-back";
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isEexist(error) {
+    return isNodeError(error) && error.code === "EEXIST";
+}
+function isEnoent(error) {
+    return isNodeError(error) && error.code === "ENOENT";
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}