@mininglamp-oss/octo-runtime-client 0.0.0-stage → 1.1.11

package/dist/invocation-lifecycle.js

@@ -0,0 +1,287 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { admissionClosedError } from "./submission-error.js";
+import { isHostTerminal } from "@mininglamp-oss/octo-runtime-protocol";
+import { KernelError } from "./types.js";
+/**
+ * 每个 client 独立保存 invoke 的身份、取消和观察状态；执行与断线恢复由 client.ts 负责。
+ * 最多登记 128 项，不缓存正文；未知结果继续占用额度，不能通过删除记录伪造排空成功。
+ */
+export class InvocationRegistry {
+    transport;
+    #records = new Map();
+    #stopped = false;
+    #draining;
+    #drainDeadline;
+    #closed = false;
+    #cancelling = 0;
+    #cancelQueue = [];
+    #cancelControllers = new Set();
+    constructor(transport) {
+        this.transport = transport;
+    }
+    begin(key) {
+        this.assertSubmission();
+        if (this.#records.has(key.invocation_id))
+            throw new KernelError("EXECUTION_IDENTITY_CONFLICT");
+        if (this.#records.size >= 128)
+            throw new KernelError("CLIENT_INVOCATION_CAPACITY_EXHAUSTED");
+        let settleAdmission;
+        const admitted = new Promise((resolve) => {
+            settleAdmission = resolve;
+        });
+        const record = {
+            key,
+            submitted: false,
+            phase: "admitting",
+            cancellation: "none",
+            lastSeq: 0,
+            admitted,
+            settleAdmission
+        };
+        this.#records.set(key.invocation_id, record);
+        return record;
+    }
+    assertSubmission() {
+        if (this.#stopped)
+            throw admissionClosedError();
+    }
+    accepted(record, ref, terminal) {
+        record.ref = ref;
+        record.instance = ref.kernel_instance_id;
+        record.phase = "accepted";
+        record.settleAdmission();
+        if (terminal)
+            this.observe(ref, terminal);
+        if (record.reason !== undefined && !terminal && this.#records.get(ref.invocation_id) === record)
+            void this.cancel(record, record.reason).catch(() => undefined);
+    }
+    reconcile(ref, terminal) {
+        const record = this.#records.get(ref.invocation_id);
+        if (!record ||
+            (record.instance && record.instance !== ref.kernel_instance_id) ||
+            Object.entries(record.key).some(([field, value]) => Reflect.get(ref, field) !== value))
+            return;
+        if (record.ref &&
+            (record.ref.stream_id !== ref.stream_id || record.ref.protocol !== ref.protocol))
+            throw new KernelError("RUN_IDENTITY_MISMATCH");
+        if (!record.ref)
+            this.accepted(record, ref, terminal);
+        else if (terminal)
+            this.observe(ref, terminal);
+    }
+    rejected(record, error) {
+        if (record.ref) {
+            record.settleAdmission();
+            this.interrupted(record, error);
+            return;
+        }
+        record.admissionError = error instanceof Error ? error : new KernelError("ACCEPTANCE_UNKNOWN");
+        record.observationError = errorCode(error);
+        record.phase = "acceptance_unknown";
+        record.settleAdmission();
+        const rejectedByServer = error instanceof KernelError &&
+            error.data !== undefined &&
+            !["KERNEL_INSTANCE_CHANGED", "RUN_IDENTITY_MISMATCH"].includes(error.code);
+        // 仅未发送或明确拒绝可安全移除；已发送但 ACK 未知时保留身份，后续 drain 只能查询确认。
+        if (!record.submitted || rejectedByServer)
+            this.#records.delete(record.key.invocation_id);
+    }
+    observe(ref, frame) {
+        const record = this.#records.get(ref.invocation_id);
+        if (!record ||
+            !record.ref ||
+            record.ref.stream_id !== ref.stream_id ||
+            record.ref.kernel_instance_id !== ref.kernel_instance_id)
+            return;
+        record.lastSeq = Math.max(record.lastSeq, frame.seq);
+        if (!isHostTerminal(frame))
+            return;
+        if (frame.kind === "control" &&
+            frame.control.type === "state" &&
+            frame.control.state === "lost") {
+            record.phase = "unobserved";
+            record.observationError = "RUN_OUTCOME_UNKNOWN";
+        }
+        else
+            this.#records.delete(ref.invocation_id);
+    }
+    interrupted(record, error) {
+        if (this.#records.get(record.key.invocation_id) !== record || !record.ref)
+            return;
+        record.phase = "unobserved";
+        if (error !== undefined)
+            record.observationError = errorCode(error);
+    }
+    active(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new KernelError("INVOCATION_NOT_TRACKED");
+        return record;
+    }
+    ref(id) {
+        const record = this.active(id);
+        if (!record.ref)
+            throw new KernelError("INVOCATION_NOT_ACCEPTED");
+        return record.ref;
+    }
+    cancel(record, reason = "caller_cancelled", { explicit = false } = {}) {
+        if (record.ref && this.#records.get(record.key.invocation_id) !== record)
+            return Promise.resolve({ accepted: false });
+        if (record.observationError === "RUN_OUTCOME_UNKNOWN")
+            return Promise.reject(new KernelError("RUN_OUTCOME_UNKNOWN"));
+        record.reason ??= reason;
+        if (record.cancellation === "none")
+            record.cancellation = "requested";
+        // 取消可能早于接纳 ACK：记住首次原因，等同一执行获得 RunRef 后发出一次控制请求。
+        if (!record.ref)
+            return record.admitted.then(() => {
+                if (!record.ref)
+                    throw record.admissionError ?? new KernelError("ACCEPTANCE_UNKNOWN");
+                // ACK 接续仍属于原意图；不能因其首次控制已失败而暗中再发送一次。
+                return this.cancel(record, reason);
+            });
+        // 仅新的公开 Stop 可重试未知控制；drain/signal 保留原 Promise，并发 Stop 共享在途尝试。
+        const retry = explicit && record.cancellation === "unknown";
+        if (!record.cancelTask || retry) {
+            if (retry)
+                record.reason = reason;
+            record.cancellation = "requested";
+            const controller = new AbortController();
+            this.#cancelControllers.add(controller);
+            record.cancelTask = new Promise((resolve, reject) => {
+                this.#cancelQueue.push(async () => {
+                    try {
+                        if (this.#closed)
+                            throw new KernelError("CLIENT_CLOSED");
+                        if (this.#records.get(record.key.invocation_id) !== record) {
+                            resolve({ accepted: false });
+                            return;
+                        }
+                        if (record.observationError === "RUN_OUTCOME_UNKNOWN")
+                            throw new KernelError("RUN_OUTCOME_UNKNOWN");
+                        const deadline = Math.min(Date.now() + 5000, this.#drainDeadline ?? Infinity);
+                        if (deadline <= Date.now())
+                            throw new KernelError("OPERATION_OUTCOME_UNKNOWN");
+                        resolve(await this.transport.cancel(record.ref, record.reason, deadline, controller.signal));
+                    }
+                    catch (error) {
+                        reject(error instanceof Error ? error : new KernelError("OPERATION_OUTCOME_UNKNOWN"));
+                    }
+                });
+                this.#pumpCancellations();
+            })
+                .then((result) => {
+                record.cancellation = "acknowledged";
+                return result;
+            })
+                .catch((error) => {
+                record.cancellation = "unknown";
+                record.observationError = errorCode(error);
+                throw error;
+            })
+                .finally(() => this.#cancelControllers.delete(controller));
+            record.firstCancelTask ??= record.cancelTask;
+            // Automatic signal cancellation may outlive its consumer; always consume rejection.
+            void record.cancelTask.catch(() => undefined);
+        }
+        return record.cancelTask;
+    }
+    #pumpCancellations() {
+        while (this.#cancelling < 4 && this.#cancelQueue.length) {
+            this.#cancelling++;
+            void this.#cancelQueue.shift()().finally(() => {
+                this.#cancelling--;
+                this.#pumpCancellations();
+            });
+        }
+    }
+    snapshot() {
+        return [...this.#records.values()].map((record) => ({
+            key: { ...record.key },
+            ...(record.ref ? { ref: { ...record.ref } } : {}),
+            phase: record.phase,
+            cancellation: record.cancellation,
+            lastSeq: record.lastSeq,
+            ...(record.observationError ? { observationError: record.observationError } : {})
+        }));
+    }
+    stopAdmission() {
+        this.#stopped = true;
+    }
+    close() {
+        this.#closed = true;
+        this.stopAdmission();
+        for (const controller of this.#cancelControllers)
+            controller.abort();
+    }
+    drain(options) {
+        if (!Number.isSafeInteger(options.deadline) || options.deadline - Date.now() > 2_147_483_647)
+            throw new KernelError("INVOCATION_DEADLINE_INVALID");
+        // 首次关闭锁定绝对期限；重复调用不能延长预算，也不能启动第二轮取消副作用。
+        if (this.#draining)
+            return this.#draining;
+        this.stopAdmission();
+        this.#drainDeadline = options.deadline;
+        return (this.#draining = this.#drain(options));
+    }
+    async #drain({ deadline, reason }) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+            for (const cancelController of this.#cancelControllers)
+                cancelController.abort();
+        }, Math.max(0, deadline - Date.now()));
+        try {
+            while (this.#records.size && !controller.signal.aborted && Date.now() < deadline) {
+                const records = [...this.#records.values()];
+                // 最多四路查询/控制 IO；只查终态元数据，不新增正文订阅，避免与业务消费者争夺尾流。
+                let index = 0;
+                await Promise.all(Array.from({ length: Math.min(4, records.length) }, async () => {
+                    while (index < records.length && !controller.signal.aborted && Date.now() < deadline) {
+                        const record = records[index++];
+                        record.reason ??= reason;
+                        if (record.cancellation === "none")
+                            record.cancellation = "requested";
+                        if (!record.instance)
+                            continue;
+                        try {
+                            const info = await this.transport.get(record.key, record.instance, deadline, controller.signal);
+                            if (!record.ref)
+                                this.accepted(record, info.ref);
+                            if (info.terminal)
+                                this.observe(info.ref, info.terminal);
+                            if (!this.#records.has(record.key.invocation_id))
+                                continue;
+                            // lost 表示执行结果未知，必须留在 unresolved，不能据此重放可能已有副作用的执行。
+                            if (record.observationError !== "RUN_OUTCOME_UNKNOWN")
+                                await this.cancel(record, reason);
+                        }
+                        catch (error) {
+                            if (record.observationError !== "RUN_OUTCOME_UNKNOWN")
+                                record.observationError = errorCode(error);
+                        }
+                    }
+                }));
+                if (this.#records.size && Date.now() < deadline) {
+                    await delay(Math.min(100, deadline - Date.now()), undefined, {
+                        signal: controller.signal
+                    }).catch(() => undefined);
+                }
+            }
+            return { complete: this.#records.size === 0, unresolved: this.snapshot() };
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+            for (const cancelController of this.#cancelControllers)
+                cancelController.abort();
+        }
+    }
+}
+export function errorCode(error) {
+    return error instanceof KernelError
+        ? error.code
+        : error instanceof Error && /^[A-Z][A-Z0-9_]+$/.test(error.message)
+            ? error.message
+            : "INVOCATION_OBSERVATION_FAILED";
+}

package/dist/notification.d.ts

@@ -0,0 +1 @@
+export * from "@mininglamp-oss/octo-runtime-protocol/notification";

package/dist/notification.js

@@ -0,0 +1 @@
+export * from "@mininglamp-oss/octo-runtime-protocol/notification";

package/dist/protocol.d.ts

@@ -0,0 +1 @@
+export * from "@mininglamp-oss/octo-runtime-protocol";

package/dist/protocol.js

@@ -0,0 +1 @@
+export * from "@mininglamp-oss/octo-runtime-protocol";

package/dist/runtime-path.d.ts

@@ -0,0 +1,21 @@
+import { type StartupDiagnostic, type StartupPathDiagnostic } from "./startup-diagnostics.js";
+export type { StartupPathDiagnostic } from "./startup-diagnostics.js";
+/** 启动域的受控路径失败；保留公共码、cause 和 #306 的平铺属性读取。 */
+export declare class RuntimeHomeError extends Error {
+    readonly code: string;
+    readonly diagnostic: Readonly<StartupDiagnostic & StartupPathDiagnostic>;
+    constructor(diagnostic: Omit<StartupPathDiagnostic, "domain" | "action"> & {
+        action?: string;
+    }, cause?: unknown);
+}
+/** 先检查原始输入，再规范化；这是纯路径计算，不代表目录已存在或启动已验证。 */
+export declare function normalizeRuntimeHome(input: string, platform?: NodeJS.Platform, resource?: string): string;
+export interface PathLimits {
+    path: number;
+    name: number;
+}
+export declare function platformLimits(platform: NodeJS.Platform): PathLimits;
+/** 检查实际附加文件名的预算；Windows 按 UTF-16 code unit，POSIX 按 UTF-8 字节。 */
+export declare function assertRuntimePath(path: string, resource: string, platform?: NodeJS.Platform, limits?: PathLimits): void;
+/** endpoint-only API 只拥有传输，不推断或创建 Home；同样在连接/监听前拒绝无效或超长地址。 */
+export declare function assertIpcEndpoint(endpoint: string, platform?: NodeJS.Platform): void;

package/dist/runtime-path.js

@@ -0,0 +1,138 @@
+import { posix, win32 } from "node:path";
+import { describeStartupError, startupPathDiagnostic } from "./startup-diagnostics.js";
+/** 启动域的受控路径失败；保留公共码、cause 和 #306 的平铺属性读取。 */
+export class RuntimeHomeError extends Error {
+    code;
+    diagnostic;
+    constructor(diagnostic, cause) {
+        super(diagnostic.code, { cause });
+        this.name = "RuntimeHomeError";
+        this.code = diagnostic.code;
+        Object.defineProperty(this, "startupContext", { value: diagnostic });
+        const shared = describeStartupError(this);
+        const legacy = startupPathDiagnostic(shared);
+        // 兼容读取的别名不进入 JSON；序列化只有一个标准诊断结构，文案不能由输入 action 覆盖。
+        for (const [key, value] of Object.entries(legacy ?? {})) {
+            if (!(key in shared))
+                Object.defineProperty(shared, key, { value });
+        }
+        this.diagnostic = Object.freeze(shared);
+    }
+}
+/** 先检查原始输入，再规范化；这是纯路径计算，不代表目录已存在或启动已验证。 */
+export function normalizeRuntimeHome(input, platform = process.platform, resource = "home") {
+    const fail = (code) => {
+        throw new RuntimeHomeError({
+            code,
+            ...(typeof input === "string" ? { path: input } : {}),
+            resource,
+            operation: "validate-input"
+        });
+    };
+    if (typeof input !== "string" ||
+        !input.trim() ||
+        input.includes("\0") ||
+        /[\uD800-\uDFFF]/u.test(input))
+        fail("HOME_INVALID");
+    if (!["win32", "darwin", "linux"].includes(platform))
+        fail("HOME_UNSUPPORTED");
+    const api = platform === "win32" ? win32 : posix;
+    if (!api.isAbsolute(input))
+        fail("HOME_INVALID");
+    if (platform === "win32") {
+        // 仅支持本地盘绝对路径。拒绝 UNC/device/root-relative/ADS 和 Win32 别名，避免 hash 与 IO 指向不同资源。
+        const local = input.replaceAll("/", "\\");
+        if (!/^[a-z]:\\/i.test(local) ||
+            /[<>"|?*]/.test(local) ||
+            [...local].some((character) => character.codePointAt(0) < 32) ||
+            local.slice(2).includes(":"))
+            fail("HOME_UNSUPPORTED");
+        for (const part of local.slice(3).split("\\")) {
+            if (part === "." || part === "..")
+                continue;
+            if (/[ .]$/.test(part) || /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part))
+                fail("HOME_UNSUPPORTED");
+        }
+    }
+    const home = api.resolve(input);
+    if (home === api.parse(home).root)
+        fail("HOME_UNSUPPORTED");
+    return home;
+}
+// Unix 的纯计算上限来自对应 OS 的 PATH_MAX/NAME_MAX；真实启动再查询所选文件系统。
+// Windows Node/libuv 使用扩展 UTF-16 路径：32767 包括 NUL 和自动追加的 \\?\ 前缀，不使用 MAX_PATH=260。
+export function platformLimits(platform) {
+    if (platform === "win32")
+        return { path: 32767 - 1 - 4, name: 255 };
+    if (platform === "linux")
+        return { path: 4096 - 1, name: 255 };
+    if (platform === "darwin")
+        return { path: 1024 - 1, name: 255 };
+    throw new RuntimeHomeError({
+        code: "HOME_UNSUPPORTED",
+        resource: "home",
+        operation: "path-budget"
+    });
+}
+/** 检查实际附加文件名的预算；Windows 按 UTF-16 code unit，POSIX 按 UTF-8 字节。 */
+export function assertRuntimePath(path, resource, platform = process.platform, limits = platformLimits(platform)) {
+    const unit = platform === "win32" ? "utf16-units" : "utf8-bytes";
+    const measure = (value) => Buffer.byteLength(value, platform === "win32" ? "utf16le" : "utf8") /
+        (platform === "win32" ? 2 : 1);
+    const fail = (measured, limit, operation) => {
+        throw new RuntimeHomeError({
+            code: "HOME_PATH_TOO_LONG",
+            path,
+            resource,
+            operation,
+            measured,
+            limit,
+            unit
+        });
+    };
+    if (measure(path) > limits.path)
+        fail(measure(path), limits.path, "path-budget");
+    const api = platform === "win32" ? win32 : posix;
+    for (const part of path.slice(api.parse(path).root.length).split(api.sep)) {
+        if (measure(part) > limits.name)
+            fail(measure(part), limits.name, "filename-budget");
+    }
+}
+/** endpoint-only API 只拥有传输，不推断或创建 Home；同样在连接/监听前拒绝无效或超长地址。 */
+export function assertIpcEndpoint(endpoint, platform = process.platform) {
+    const fail = (code, extra = {}) => {
+        throw new RuntimeHomeError({
+            code,
+            ...(typeof endpoint === "string" ? { path: endpoint, endpoint } : {}),
+            resource: "ipc-endpoint",
+            operation: "ipc-address",
+            ...extra
+        });
+    };
+    if (typeof endpoint !== "string" ||
+        !endpoint ||
+        endpoint.includes("\0") ||
+        /[\uD800-\uDFFF]/u.test(endpoint))
+        fail("IPC_ENDPOINT_INVALID");
+    if (platform === "win32") {
+        if (!/^\\\\[.?]\\pipe\\[^\\]+$/i.test(endpoint))
+            fail("IPC_ENDPOINT_INVALID");
+        const measured = Buffer.byteLength(endpoint, "utf16le") / 2;
+        // CreateNamedPipeW: 完整 pipe 名最多 256 WCHAR；namespace 不是文件路径，不套用 Unix sun_path。
+        if (measured > 256)
+            fail("IPC_ENDPOINT_TOO_LONG", { measured, limit: 256, unit: "utf16-units" });
+    }
+    else {
+        if (!posix.isAbsolute(endpoint))
+            fail("IPC_ENDPOINT_INVALID");
+        // Node net + libuv 的 pathname socket 必须留出结尾 NUL：Linux 108、Darwin 104 字节 sun_path。
+        const limit = platform === "linux" ? 107 : platform === "darwin" ? 103 : undefined;
+        if (limit === undefined)
+            fail("IPC_ENDPOINT_UNSUPPORTED");
+        const measured = Buffer.byteLength(endpoint, "utf8");
+        if (measured > limit)
+            fail("IPC_ENDPOINT_TOO_LONG", { measured, limit, unit: "utf8-bytes" });
+        assertRuntimePath(endpoint, "ipc-endpoint", platform);
+        assertRuntimePath(`${endpoint}.owner.recovery`, "endpoint-ownership", platform);
+    }
+}

package/dist/startup-catalog.d.ts

@@ -0,0 +1,8 @@
+/** client 与服务端共用的唯一启动文案目录；不含 Run 控制码，不触发修复或网络请求。 */
+export interface StartupCatalogEntry {
+    readonly summary: string;
+    readonly action: string;
+    readonly retryable: boolean;
+    readonly configKey?: string;
+}
+export declare const STARTUP_CATALOG: Readonly<Record<string, StartupCatalogEntry>>;

package/dist/startup-catalog.js

@@ -0,0 +1,65 @@
+const entry = (summary, action, retryable = false, configKey) => Object.freeze({ summary, action, retryable, ...(configKey ? { configKey } : {}) });
+const homeAction = "The SDK host must select and prepare an existing accessible absolute Runtime Home, then retry. CLI users can select their intended Home with --home. Existing data is not moved automatically.";
+const endpointAction = "Inspect the endpoint owner and component status. Stop the owning service through its host before retrying; do not remove an active endpoint or ownership record.";
+const inspectAction = "Inspect the component configuration and controlled lifecycle logs in the host. Capture the diagnostic codes and safe resource context before retrying; the cause is not yet known.";
+export const STARTUP_CATALOG = Object.freeze({
+    STARTUP_UNKNOWN: entry("The startup cause is unknown.", inspectAction),
+    LOG_DIRECTORY_MUST_BE_ABSOLUTE: entry("The logging directory must be absolute.", "Pass an absolute directory in logging.directory, then retry startup through the host.", false, "logging.directory"),
+    LOG_STATUS_OUTPUT_INVALID: entry("The logging status output callback is invalid.", "Provide a function in logging.statusOutput or omit that optional callback, then retry construction.", false, "logging.statusOutput"),
+    SERVICE_INITIALIZATION_FAILED: entry("Component initialization failed.", inspectAction),
+    KERNEL_START_CLEANUP_INCOMPLETE: entry("Kernel startup rollback is incomplete.", endpointAction),
+    KERNEL_CLEANUP_INCOMPLETE: entry("Kernel resources have not all been released.", endpointAction),
+    HOME_UNAVAILABLE: entry("Runtime Home is unavailable.", homeAction),
+    HOME_INVALID: entry("Runtime Home must be a valid absolute directory path.", homeAction),
+    HOME_UNSUPPORTED: entry("This Runtime Home path or platform is unsupported.", homeAction),
+    HOME_NOT_FOUND: entry("The required Runtime Home resource does not exist.", homeAction),
+    HOME_NOT_DIRECTORY: entry("The required directory has the wrong resource type.", homeAction),
+    HOME_PERMISSION_DENIED: entry("Access to the Runtime Home resource was denied.", "Check permissions for the reported resource and operation under the host account, then retry. Do not reset identities or replace Home to bypass the error."),
+    HOME_PATH_TOO_LONG: entry("The Runtime resource exceeds a path limit.", "The host must select and prepare a shorter supported path within the reported limit, then retry. Existing data is not moved automatically."),
+    HOME_LIMIT_UNAVAILABLE: entry("Filesystem path limits could not be determined.", "Make the operating system getconf utility available to query PATH_MAX/NAME_MAX, then retry with the same prepared Home."),
+    HOME_UNUSABLE: entry("The Runtime Home resource could not be used.", inspectAction),
+    IPC_ENDPOINT_INVALID: entry("The IPC endpoint is invalid.", "Pass a valid local IPC endpoint through the host's endpoint option, then retry."),
+    IPC_ENDPOINT_UNSUPPORTED: entry("The IPC transport platform is unsupported.", "Use a supported platform and local IPC transport."),
+    IPC_ENDPOINT_TOO_LONG: entry("The IPC endpoint exceeds the transport limit.", "Select a shorter Home or endpoint within the reported transport limit, then retry. Existing data is not moved automatically."),
+    ENDPOINT_IN_USE: entry("The IPC endpoint already has an owner.", endpointAction),
+    EADDRINUSE: entry("The IPC endpoint is already in use.", endpointAction),
+    ENDPOINT_PATH_INVALID: entry("The endpoint path contains a different resource type.", "Inspect the reported endpoint and correct the host's endpoint selection. Do not delete an unrelated file."),
+    ENDPOINT_OWNER_INVALID: entry("The endpoint ownership record is invalid.", endpointAction),
+    ENDPOINT_UNVERIFIABLE: entry("Endpoint ownership could not be verified.", endpointAction),
+    ENDPOINT_RECOVERY_IN_PROGRESS: entry("Endpoint recovery is in progress.", "Wait for the owning recovery operation to finish, inspect status, then retry.", true),
+    ENOENT: entry("A required startup resource was not found.", "Correct the reported resource selection or prepare the required dependency, then retry."),
+    ENOTDIR: entry("A required directory has the wrong resource type.", "Correct the reported directory path to an existing directory, then retry."),
+    EISDIR: entry("A required file is a directory.", "Correct the selected file path to the intended regular file, then retry."),
+    IM_CONTEXT_LOADING_CONFIG_INVALID: entry("The Extra context-loading configuration is invalid.", "Set context_loading.timeout_ms to an integer from 1 to 30000 and max_in_flight to an integer from 1 to 32; remove unsupported keys, then retry Extra initialization.", false, "context_loading"),
+    EACCES: entry("The startup operation was denied access.", "Check the host account's permissions for the reported resource and operation, then retry."),
+    EPERM: entry("The operating system denied the startup operation.", "Check the host account's permissions and the reported resource, then retry."),
+    EROFS: entry("The startup operation requires a writable filesystem.", "Use an accessible writable resource for the reported operation, then retry."),
+    ENAMETOOLONG: entry("The startup resource name exceeds a system limit.", "Select a shorter supported path or endpoint, then retry."),
+    ECONNREFUSED: entry("The component is not accepting IPC connections.", "Inspect the target component's lifecycle and logs, start it through its host, then retry.", true),
+    SETUP_IN_PROGRESS: entry("A component lifecycle operation is in progress.", "Wait for that operation to finish, then retry.", true),
+    SERVICE_INITIALIZATION_CANCELLED: entry("Component initialization was cancelled.", "Check the host cancellation request and cleanup outcome before starting again.", true),
+    KERNEL_CONFIGURATION_INVALID: entry("Kernel construction inputs are invalid.", "Pass endpoint and an adapters array to createKernelService. Compose Adapter objects in the host; retired worker/manifest/env options are unsupported."),
+    ERR_MODULE_NOT_FOUND: entry("A selected module or one of its dependencies was not found.", "Check the selected module and its installed dependency graph in the host; correct the declaration or install the required package, then retry."),
+    MODULE_NOT_FOUND: entry("A selected module or one of its dependencies was not found.", "Check the selected module and its installed dependency graph in the host; correct the declaration or install the required package, then retry."),
+    EXTRA_MODULE_REQUIRED: entry("The Extra module selection is missing.", "Supply the module field in the host's Extra declaration before loading it.", false, "module"),
+    EXTRA_CONFIG_OBJECT_REQUIRED: entry("The Extra configuration must be an object.", "Provide a JSON object in the Extra config field, then retry initialization.", false, "config"),
+    EXTRA_CONFIG_JSON_REQUIRED: entry("The Extra configuration contains a non-JSON value.", "Pass only finite JSON values in config; supply functions separately through dependencies.", false, "config"),
+    EXTRA_CONFIG_PERMISSIONS_INVALID: entry("The Extra configuration file failed its file or access checks.", "Inspect the reported configuration file's type, identity and permissions under the host account; use a protected regular file, then retry."),
+    MANIFEST_INVALID: entry("The CLI module manifest is invalid.", "Check the selected manifest.json: version must be 1 and adapters/extras must be valid arrays without duplicate keys."),
+    EXTRA_NOT_REGISTERED: entry("The Extra has no saved CLI declaration.", "Save this component's declaration with its configure or extraset command, then start it."),
+    EXTRA_MODULE_LOAD_FAILED: entry("The selected Extra module could not be loaded.", "Check the selected module, package installation and ESM exports; correct the declaration or reinstall the dependency, then retry."),
+    EXTRA_INITIALIZER_REQUIRED: entry("The Extra did not return an initializer.", "Provide an Extra factory that synchronously returns its initialization function."),
+    EXTRA_NAME_MISMATCH: entry("The Extra module name differs from its declaration.", "Make the selected module's exported name match its catalog entry."),
+    EXTRA_ALREADY_LOADED: entry("This Extra already has an active owner.", "Close the existing Extra through its host before constructing another instance."),
+    EXTRA_DISPOSE_FAILED: entry("The previous Extra still has unconfirmed resources.", "Inspect the previous cleanup result and pending resources. Complete the owning host's cleanup before retrying."),
+    LOCAL_STATE_INVALID: entry("The local state could not be read.", "Inspect the reported file and system cause. Preserve existing identities and configuration; correct the file or access through the host."),
+    WRITE_FAILED: entry("A local state update failed.", "Inspect the reported path, operation and system cause; correct access before retrying the host operation."),
+    COMPONENT_UNAVAILABLE: entry("The component did not become ready.", "Inspect component status and controlled lifecycle logs. Process liveness alone does not establish Kernel execution readiness or Extra business connectivity.", true),
+    SERVICE_PROCESS_EXITED: entry("The service process exited unexpectedly.", "Inspect this startup attempt's controlled diagnostic and lifecycle logs before restarting."),
+    SERVICE_NOT_INSTALLED: entry("The component service is not installed.", "Run this component's install command, then start it."),
+    NOT_INSTALLED: entry("The component service is not installed.", "Run this component's install command, then start it."),
+    SERVICE_DISABLED: entry("The component service is disabled.", "Run this component's install --autostart=true command, then start it."),
+    MANAGER_UNAVAILABLE: entry("The native service manager is unavailable.", "Run doctor and inspect the current user's native service manager."),
+    ORPHAN_CLEANUP_INCOMPLETE: entry("Previous Kernel resource cleanup is incomplete.", "CLI users: run doctor with the same --home. After confirming all owned orphan tools have stopped, run executor-kernel recover --acknowledge-orphan-cleanup with that Home, then start again. SDK hosts must use the corresponding inspect/acknowledge API; do not remove ownership records."),
+    ORPHAN_RECORD_UNSUPPORTED: entry("The stored Kernel ownership format is unsupported.", "Preserve the ownership evidence. Stop and clean up using the version and host that created it before upgrading; do not acknowledge or delete an unknown record.")
+});

package/dist/startup-diagnostics.d.ts

@@ -0,0 +1,82 @@
+export { STARTUP_CATALOG, type StartupCatalogEntry } from "./startup-catalog.js";
+/** 诊断仅保存生命周期事实；服务实现复用这些数据类型，不在客户端启动或清理服务。 */
+export type ServicePhase = "created" | "initializing" | "ready" | "closing" | "closed" | "failed";
+export interface ServiceCleanupResult {
+    readonly complete: boolean;
+    readonly errors: readonly {
+        resource: string;
+        code: string;
+    }[];
+    readonly pendingResources: readonly string[];
+}
+/** 只接受启动调用方已确认的资源事实；不接受原始配置、环境、stderr 或异常正文。 */
+export interface StartupContext {
+    path?: string;
+    resource?: string;
+    operation?: string;
+    configKey?: string;
+    endpoint?: string;
+    executable?: string;
+    module?: string;
+    systemCode?: string;
+    measured?: number;
+    limit?: number;
+    unit?: "utf8-bytes" | "utf16-units";
+}
+/** #306 路径诊断兼容投影；所有字段均从共享诊断白名单生成。 */
+export interface StartupPathDiagnostic extends Pick<StartupContext, "path" | "systemCode" | "endpoint" | "measured" | "limit" | "unit"> {
+    domain: "startup";
+    code: string;
+    resource: string;
+    operation: string;
+    action: string;
+}
+/** CLI 继续提供 #306 的 startup 字段；恢复建议始终来自同一 catalog。 */
+export declare function startupPathDiagnostic(diagnostic: StartupDiagnostic): StartupPathDiagnostic | undefined;
+export interface StartupCause {
+    code: string;
+    context: Readonly<StartupContext>;
+    component?: string;
+    phase?: ServicePhase;
+    cleanup?: ServiceCleanupResult;
+}
+export interface StartupDiagnostic {
+    domain: "startup";
+    code: string;
+    rootCode: string;
+    component: string;
+    phase: ServicePhase;
+    summary: string;
+    explanation: string;
+    actions: readonly string[];
+    retryable: boolean;
+    userActionRequired: boolean;
+    context: Readonly<StartupContext>;
+    causes: readonly StartupCause[];
+    cleanup?: ServiceCleanupResult;
+    truncated: boolean;
+}
+export interface StartupLocation {
+    component: string;
+    phase: ServicePhase;
+    context?: StartupContext;
+}
+/** 保持原类型/message/code/cause，仅在可扩展错误上增加安全诊断；冻结错误可由调用边界直接投影。 */
+export declare function withStartupContext<T>(error: T, location: StartupLocation, classification?: string): T;
+/** 文本与 JSON 同用确定性规范化：去控制字符，去 URL 认证/query/hash 和显式敏感赋值。 */
+export declare function safeStartupValue(value: string, maximum?: number): string;
+/**
+ * 在失败调用边界投影启动事实；不依赖 IPC/Run，不改变原错误、退出码或清理行为。
+ * cause/aggregate 按主失败优先有界遍历（16 节点/6 层）；循环和原始异常正文均不输出。
+ */
+export declare function describeStartupError(error: unknown, location?: StartupLocation): StartupDiagnostic;
+/** 可读投影只消费已净化的共享结构；SDK 可直接按 rootCode/context 分支。 */
+export declare function formatStartupDiagnostic(diagnostic: StartupDiagnostic): string;
+/** 持久化/JSON 是不可信边界：仅重建码、位置、资源和清理，文案始终重新来自当前 catalog。 */
+export declare function restoreStartupDiagnostic(value: unknown): StartupDiagnostic | undefined;
+/** 仅供启动边界补充已确认的位置事实；cause 保留给本地深度排障，公开输出用 diagnostic。 */
+export declare class StartupError extends Error {
+    readonly code: string;
+    readonly diagnostic: StartupDiagnostic;
+    constructor(code: string, location: StartupLocation, cause?: unknown);
+}