@zq-silk/yui 0.15.3 → 0.15.6

package/dist/runtime/exactControlPlane.js

@@ -1,232 +0,0 @@
-import { createHash } from "node:crypto";
-import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
-import { callController as defaultCallController } from "../core/controllerClient.js";
-import { inspectStorageSchema } from "../storage/storageSchema.js";
-import { yuiVersionIdentity } from "../version.js";
-export const EXACT_CONTROL_ARGUMENT = "--yui-control";
-export const YUI_CONTROL_PLANE_DESCRIPTOR = "YUI_CONTROL_PLANE_DESCRIPTOR";
-export function createExactControlPlaneDescriptor(input) {
-    const identity = validateVersionIdentity(input.identity ?? yuiVersionIdentity());
-    return Object.freeze({
-        schemaVersion: 1,
-        kind: "yui-control-plane",
-        executable: canonicalPath(input.executable),
-        cliEntry: canonicalPath(input.cliEntry),
-        yuiHome: canonicalPath(input.yuiHome),
-        identity: Object.freeze({ ...identity }),
-        ...(input.buildId === undefined ? {} : { buildId: input.buildId }),
-        ...(input.activeReleaseDigest === undefined
-            ? {}
-            : { activeReleaseDigest: input.activeReleaseDigest })
-    });
-}
-export function serializeExactDescriptor(descriptor) {
-    return JSON.stringify(descriptor);
-}
-export function parseExactControlPlaneDescriptor(value) {
-    const record = parseDescriptorRecord(value);
-    assertDescriptorKind(record, "yui-control-plane");
-    if (record.schemaVersion !== 1) {
-        throw new Error("Exact control-plane descriptor schema version is invalid.");
-    }
-    return createExactControlPlaneDescriptor({
-        executable: requireText(record.executable, "Control-plane executable"),
-        cliEntry: requireText(record.cliEntry, "Control-plane CLI entry"),
-        yuiHome: requireText(record.yuiHome, "Control-plane YUI_HOME"),
-        identity: validateVersionIdentity(record.identity),
-        ...(typeof record.buildId !== "string" ? {} : { buildId: record.buildId }),
-        ...(typeof record.activeReleaseDigest !== "string"
-            ? {}
-            : { activeReleaseDigest: record.activeReleaseDigest })
-    });
-}
-export function exactControlPlaneDigest(descriptor) {
-    return createHash("sha256").update(serializeExactDescriptor(descriptor)).digest("hex");
-}
-export function extractExactControlArgument(args) {
-    const later = args.indexOf(EXACT_CONTROL_ARGUMENT);
-    if (later < 0)
-        return { args: [...args] };
-    if (later !== 0) {
-        return {
-            args: [...args],
-            error: `${EXACT_CONTROL_ARGUMENT} must be the first CLI argument.`
-        };
-    }
-    const digest = args[1];
-    if (digest === undefined || !/^[a-f0-9]{64}$/u.test(digest)) {
-        return {
-            args: args.slice(2),
-            error: "Exact control-plane digest is invalid."
-        };
-    }
-    return { digest, args: args.slice(2) };
-}
-/**
- * One read-only gate shared by every managed Task control command. It verifies
- * the frozen executable/CLI/Home/digest, protocol and storage identity,
- * on-disk schema, and any live Controller before command routing may construct
- * a writable store. Package version alone may advance at the same managed path
- * so an existing Session can cross an explicitly compatible in-place update.
- */
-export async function assertExactControlPlanePreflight(input, options = {}) {
-    const descriptor = parseExactControlPlaneDescriptor(input.serializedDescriptor);
-    const frozenDigest = exactControlPlaneDigest(descriptor);
-    const requestedDigest = requireDigest(input.digest);
-    if (frozenDigest !== requestedDigest) {
-        throw new Error("Exact control-plane invocation names another runtime than this Session's frozen "
-            + `descriptor (requested ${requestedDigest}, Session ${frozenDigest}). `
-            + "Yui no longer pins package identity into a Session entry point: invoke the "
-            + "ordinary command for this Session, or start a new Session when the Session "
-            + "itself must move to a different runtime.");
-    }
-    assertSamePath(descriptor.executable, input.actualExecutable, "Control-plane executable");
-    assertSamePath(descriptor.cliEntry, input.actualCliEntry, "Control-plane CLI entry");
-    assertSamePath(descriptor.yuiHome, input.actualHome, "Control-plane YUI_HOME");
-    // A frozen descriptor can only assert what cannot legitimately change for a
-    // Session: which Home it belongs to, and which installation launched it. The
-    // protocol and storage numbers it also captured describe the world at launch
-    // time, and Yui upgrades that world on purpose. Asking today's Home to still
-    // match yesterday's snapshot would silence a healthy Session's callbacks the
-    // moment a migration lands, so runtime coherence is proven against the
-    // current CLI, Home, and Controller instead.
-    await assertCompatibleControlPlanePreflight({ actualHome: descriptor.yuiHome }, options);
-    return descriptor;
-}
-/**
- * Compatibility gate for an ordinary `yui` invocation inside a managed
- * Session. The Session Manifest and durable runtime state authenticate the
- * actor separately; this gate proves that the current CLI can safely share the
- * Home with its storage and Controller without pinning package/build identity.
- */
-export async function assertCompatibleControlPlanePreflight(input, options = {}) {
-    const home = canonicalPath(input.actualHome);
-    const identity = validateVersionIdentity(options.identity ?? yuiVersionIdentity());
-    const storage = (options.inspectStorage ?? inspectStorageSchema)(home);
-    if (storage.status !== "current") {
-        throw new Error(`Managed control-plane storage is not current: ${storage.status}.`);
-    }
-    if (storage.currentVersion !== identity.storageVersion) {
-        throw new Error("Managed control-plane storage version is incompatible "
-            + `(expected ${identity.storageVersion}, found `
-            + `${storage.currentVersion ?? "unknown"}).`);
-    }
-    if (options.checkController !== false) {
-        const call = options.callController ?? defaultCallController;
-        try {
-            const status = await call(home, "controller.status", {});
-            assertControllerContinuityIdentity(status, identity);
-        }
-        catch (error) {
-            if (!isDefinitelyNotRunning(error))
-                throw error;
-        }
-    }
-    return identity;
-}
-export function assertControllerStatusIdentity(status, expected = yuiVersionIdentity()) {
-    if (!isRecord(status) || status.running !== true) {
-        throw new Error("Controller status does not describe a running Controller.");
-    }
-    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
-    assertControllerField(status.version, expected.version, "version");
-    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
-    assertControllerField(status.minimumStorageVersion, expected.minimumStorageVersion, "minimum storage migration version");
-}
-function validateVersionIdentity(value) {
-    if (!isRecord(value))
-        throw new Error("Yui version identity is invalid.");
-    const version = requireText(value.version, "Yui version");
-    const controllerProtocolVersion = requireVersion(value.controllerProtocolVersion, "Controller protocol version");
-    const storageVersion = requireVersion(value.storageVersion, "Storage version");
-    const minimumStorageVersion = requireVersion(value.minimumStorageVersion, "Minimum storage migration version");
-    if (minimumStorageVersion > storageVersion) {
-        throw new Error("Minimum storage migration version cannot exceed the current storage version.");
-    }
-    return {
-        version,
-        controllerProtocolVersion,
-        storageVersion,
-        minimumStorageVersion
-    };
-}
-function assertControllerContinuityIdentity(status, expected) {
-    if (!isRecord(status) || status.running !== true) {
-        throw new Error("Controller status does not describe a running Controller.");
-    }
-    if (typeof status.version !== "string" || status.version.trim().length === 0) {
-        throw new Error("Controller version is invalid at the managed continuity gate.");
-    }
-    assertControllerField(status.protocolVersion, expected.controllerProtocolVersion, "protocol");
-    assertControllerField(status.storageVersion, expected.storageVersion, "storage version");
-}
-function assertControllerField(actual, expected, label) {
-    if (actual !== expected) {
-        throw new Error(`Controller ${label} is incompatible with the exact control plane `
-            + `(expected ${expected}, found ${typeof actual === "string" || typeof actual === "number" ? actual : "unknown"}). `
-            + "Run controller restart through the matching exact control-plane invocation "
-            + "before writing new Task records.");
-    }
-}
-function assertSamePath(expected, actual, label) {
-    const normalized = canonicalPath(actual);
-    if (expected !== normalized) {
-        throw new Error(`${label} does not match the frozen control plane (expected ${expected}, found ${normalized}).`);
-    }
-}
-function parseDescriptorRecord(value) {
-    let parsed;
-    try {
-        parsed = JSON.parse(requireText(value, "Exact descriptor"));
-    }
-    catch (error) {
-        throw new Error("Exact descriptor is not valid JSON.", { cause: error });
-    }
-    if (!isRecord(parsed))
-        throw new Error("Exact descriptor must be an object.");
-    return parsed;
-}
-function assertDescriptorKind(value, expected) {
-    if (value.kind !== expected) {
-        throw new Error(`Exact descriptor kind is invalid: expected ${expected}, found `
-            + `${typeof value.kind === "string" ? value.kind : "unknown"}.`);
-    }
-}
-function requireText(value, label) {
-    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
-        throw new Error(`${label} is invalid.`);
-    }
-    return value;
-}
-function requireDigest(value) {
-    const digest = requireText(value, "Control-plane digest");
-    if (!/^[a-f0-9]{64}$/u.test(digest)) {
-        throw new Error("Control-plane digest is invalid.");
-    }
-    return digest;
-}
-function requireVersion(value, label) {
-    if (!Number.isSafeInteger(value) || value < 1) {
-        throw new Error(`${label} is invalid.`);
-    }
-    return value;
-}
-function canonicalPath(value) {
-    const absolute = resolve(requireText(value, "Path"));
-    try {
-        return realpathSync(absolute);
-    }
-    catch {
-        return absolute;
-    }
-}
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\"'\"'")}'`;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isDefinitelyNotRunning(error) {
-    return isRecord(error) && error.code === "CONTROLLER_NOT_RUNNING";
-}