@actiondock/core 2.2.2 → 2.4.0

package/dist/ipc/target.js

@@ -2,6 +2,36 @@ import { randomUUID } from "node:crypto";
 import { fork } from "node:child_process";
 import { DiagnosticForwarder } from "./diagnostic.js";
 import { EXECUTION_ABORTED, HOST_PROCESS_EXITED } from "../errors.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ *
+ * @param value 待检查的选项值
+ */
+export function hasIpcSignalMarker(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[IPC_SIGNAL_MARKER] === true);
+}
+/**
+ * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
+ * 未携带 signal 时返回浅拷贝，避免消息通道直接持有调用方原始对象。
+ *
+ * @param options 原始执行选项
+ */
+function markIpcSignal(options) {
+    if (!options)
+        return undefined;
+    const { signal: _signal, ...rest } = options;
+    if (!_signal)
+        return rest;
+    return { ...rest, [IPC_SIGNAL_MARKER]: true };
+}
 /**
  * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
  *
@@ -126,7 +156,7 @@ export class IpcActionDockTarget {
     get process() {
         return this.child;
     }
-    async callRemote(method, args) {
+    async callRemote(method, args, signal) {
         if (this.isClosed || this.exitError) {
             if (method === "runAction") {
                 return {
@@ -147,6 +177,16 @@ export class IpcActionDockTarget {
             method,
             args,
         };
+        // 事件驱动跨进程取消：signal 存在且未中止时注册 abort 监听，
+        // 触发即向宿主子进程发送 abort 消息，由宿主侧中止同调用控制器；
+        // 调用结束（无论成败）后注销监听，避免监听器泄漏
+        let onAbort;
+        if (signal && !signal.aborted) {
+            onAbort = () => {
+                this.sendAbort(id);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
         return new Promise((resolve, reject) => {
             this.pendingCalls.set(id, { resolve, reject, method });
             try {
@@ -162,8 +202,31 @@ export class IpcActionDockTarget {
                 this.pendingCalls.delete(id);
                 reject(err);
             }
+        }).finally(() => {
+            if (onAbort && signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
         });
     }
+    /**
+     * 向宿主子进程发送跨进程取消通知，发送异常不阻断父侧调用链路。
+     *
+     * @param id 目标调用的唯一标识
+     */
+    sendAbort(id) {
+        if (this.isClosed)
+            return;
+        try {
+            const abortMsg = { id, type: "abort" };
+            if (this.child.send) {
+                this.child.send(abortMsg);
+            }
+        }
+        catch (err) {
+            // 通道已断开时发送失败属预期场景：宿主退出路径会另行以结构化错误回包
+            process.stderr.write(`[IPC Target] Failed to send abort for call '${id}': ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
     async info() {
         return this.callRemote("info", []);
     }
@@ -183,8 +246,7 @@ export class IpcActionDockTarget {
         return this.callRemote("describePlaybook", [id]);
     }
     async runAction(ref, input, options) {
-        const { signal, ...serializableOptions } = options || {};
-        if (signal?.aborted) {
+        if (options?.signal?.aborted) {
             return {
                 ok: false,
                 runId: randomUUID(),
@@ -194,11 +256,17 @@ export class IpcActionDockTarget {
                 },
             };
         }
-        return this.callRemote("runAction", [ref, input, serializableOptions]);
+        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
+        const serializableOptions = markIpcSignal(options);
+        return this.callRemote("runAction", [ref, input, serializableOptions], options?.signal);
     }
     async startAction(ref, input, options) {
-        const { signal, ...serializableOptions } = options || {};
-        return this.callRemote("startAction", [ref, input, serializableOptions]);
+        if (options?.signal?.aborted) {
+            throw new Error("Execution was aborted before starting");
+        }
+        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
+        const serializableOptions = markIpcSignal(options);
+        return this.callRemote("startAction", [ref, input, serializableOptions], options?.signal);
     }
     async getRun(runId) {
         const res = await this.callRemote("getRun", [runId]);

package/dist/ipc/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 监督进程向宿主子进程发送的跨进程取消通知。
+ * id 与对应 IpcCallMessage 的调用 id 一致，宿主侧据此中止同调用的 AbortController。
+ */
+export interface IpcAbortMessage {
+    id: string;
+    type: "abort";
+    reason?: string;
+}
 /**
  * 监督进程与宿主子进程间调用的 IPC 请求消息。
  */
@@ -39,4 +48,4 @@ export interface IpcReadyMessage {
 /**
  * 联合 IPC 消息类型。
  */
-export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcEventMessage | IpcReadyMessage;
+export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcAbortMessage | IpcEventMessage | IpcReadyMessage;

package/dist/platform/default.d.ts

@@ -1,6 +1,8 @@
 import type { ProcessAPI } from "@actiondock/sdk";
 import { type Clock } from "../runtime/clock.js";
 import { type ModuleLoader } from "../runtime/module-loader.js";
+import { ProcessManager } from "../process/process-manager.js";
+import type { ProcessDriver } from "../process/driver.js";
 import type { FileSystem, RuntimePlatform, StorageFactory } from "./types.js";
 /**
  * 默认运行时平台构建选项。
@@ -12,8 +14,12 @@ export interface DefaultPlatformOptions {
     files?: FileSystem;
     /** 自定义时间与时钟驱动（默认使用 SystemClock） */
     clock?: Clock;
-    /** 自定义进程执行驱动（默认使用 DefaultProcessExecutor） */
+    /** 自定义进程执行驱动（默认依托 ProcessManager 与对应驱动） */
     process?: ProcessAPI;
+    /** 可选注入的底层进程驱动 */
+    processDriver?: ProcessDriver;
+    /** 可选注入的受管进程管理器 */
+    processManager?: ProcessManager;
     /** 自定义源码加载驱动（默认使用 DefaultModuleLoader） */
     modules?: ModuleLoader;
     /** 自定义存储工厂（默认基于 core/storage 构造） */

package/dist/platform/default.js

@@ -1,8 +1,33 @@
 import { SystemClock } from "../runtime/clock.js";
 import { DefaultModuleLoader } from "../runtime/module-loader.js";
-import { DefaultProcessExecutor } from "../runtime/process.js";
+import { ProcessError, UNSUPPORTED_CAPABILITY } from "../errors.js";
+import { ProcessManager } from "../process/process-manager.js";
 import { createGlobalStorage as coreCreateGlobalStorage, createStorage as coreCreateStorage, } from "../storage/index.js";
 import { NodeFileSystem } from "./node-fs.js";
+/**
+ * 构造不支持进程能力的 ProcessAPI：
+ * 默认平台不含进程驱动，任何进程操作均抛出明确错误，
+ * 指引调用方显式注入 processDriver 或改用 @actiondock/runtime-node 的 createNodePlatform。
+ */
+function createUnsupportedProcessApi() {
+    const unsupported = (operation) => Promise.reject(new ProcessError(UNSUPPORTED_CAPABILITY, `The default platform does not bundle a process driver, so process.${operation} is unavailable. ` +
+        "Explicitly inject a processDriver (for example MemoryProcessDriver from @actiondock/core for testing) " +
+        "or use createNodePlatform from @actiondock/runtime-node, which provides NodeProcessDriver."));
+    return {
+        run: () => unsupported("run"),
+        start: () => unsupported("start"),
+        inspect: () => unsupported("inspect"),
+        list: () => unsupported("list"),
+        acquire: () => unsupported("acquire"),
+        renew: () => unsupported("renew"),
+        release: () => unsupported("release"),
+        write: () => unsupported("write"),
+        operation: () => unsupported("operation"),
+        read: () => unsupported("read"),
+        control: () => unsupported("control"),
+        stop: () => unsupported("stop"),
+    };
+}
 /**
  * 创建默认 RuntimePlatform 平台实例。
  * 直接基于 Node 原生与 Core 内核能力组装平台，禁止任何全局单例状态。
@@ -12,7 +37,20 @@ export function createDefaultPlatform(options = {}) {
     const clock = options.clock ?? new SystemClock();
     const files = options.files ?? new NodeFileSystem({ rootDir: options.rootDir });
     const modules = options.modules ?? new DefaultModuleLoader();
-    const process = options.process ?? new DefaultProcessExecutor();
+    // 未注入底层驱动时不静默回退内存模拟驱动：默认平台不提供可用进程能力，
+    // 避免默认路径下的进程调用无声挂死或必然超时
+    const processDriver = options.processDriver;
+    const processManager = options.processManager ??
+        (processDriver ? new ProcessManager({ driver: processDriver }) : undefined);
+    const process = options.process ??
+        (processManager
+            ? processManager.forOwner({
+                tenantId: "default",
+                principalId: "default",
+                packageInstanceId: "default",
+                generationId: "default",
+            })
+            : createUnsupportedProcessApi());
     const storage = options.storage ?? {
         createStorage(packageId, opts) {
             return coreCreateStorage(packageId, {

package/dist/process/context-process.d.ts

@@ -0,0 +1,83 @@
+import type { CallOptions, ControlGrant, OperationReceipt, ProcessAcquireInput, ProcessAPI, ProcessControlInput, ProcessInfo, ProcessListInput, ProcessListResult, ProcessReadInput, ProcessRunInput, ProcessRunResult, ProcessStartInput, ProcessStartResult, ProcessStopInput, ProcessWriteInput, ReadResult } from "@actiondock/sdk";
+import type { ProcessManager, ProcessOwner } from "./process-manager.js";
+/**
+ * 绑定当前 ActionContext 上下文凭据与运行标识的 ProcessAPI 适配器实现。
+ *
+ * 核心保证：
+ * - 自动注入当前运行上下文的归属所有者与运行标识。
+ * - 跟踪由当前 Run 申请成功持有的控制权令牌。
+ * - 拦截 Run 退出或异常生命周期：若当前 Run 未显式 release 释放控制权，自动撤销 grant 并将目标进程置入隔离状态 quarantined。
+ */
+export declare class ContextProcessAPI implements ProcessAPI {
+    private readonly heldProcesses;
+    private isDisposed;
+    private onAbortHandler?;
+    readonly processManager: ProcessManager;
+    readonly owner: ProcessOwner;
+    readonly runId: string;
+    readonly signal?: AbortSignal;
+    /** 是否为运行级作用域凭据：缺省时依据构造时是否显式传入 runId 判定 */
+    readonly runScoped: boolean;
+    constructor(processManager: ProcessManager, owner: ProcessOwner, runId: string, signal?: AbortSignal, runScoped?: boolean);
+    /**
+     * 底层进程管理器实例（协同入口的公开只读访问）。
+     */
+    get manager(): ProcessManager;
+    /**
+     * 一次性运行外部命令。
+     */
+    run(input: ProcessRunInput, call?: CallOptions): Promise<ProcessRunResult>;
+    /**
+     * 启动新的受管进程资源。
+     */
+    start(input: ProcessStartInput, call?: CallOptions): Promise<ProcessStartResult>;
+    /**
+     * 查看指定受管进程资源的状态快照。
+     */
+    inspect(id: string, call?: CallOptions): Promise<ProcessInfo>;
+    /**
+     * 分页列出当前所有者可见的受管进程列表。
+     */
+    list(input: ProcessListInput, call?: CallOptions): Promise<ProcessListResult>;
+    /**
+     * 申请指定受管进程的独占控制令牌。
+     */
+    acquire(id: string, input: ProcessAcquireInput, call?: CallOptions): Promise<ControlGrant>;
+    /**
+     * 延长当前有效控制令牌的存活时间。
+     */
+    renew(id: string, token: string, ttlMs: number, call?: CallOptions): Promise<ControlGrant>;
+    /**
+     * 显式释放控制令牌。
+     */
+    release(id: string, token: string, call?: CallOptions): Promise<void>;
+    /**
+     * 向受管进程输入流写入原始字节数据。
+     */
+    write(id: string, input: ProcessWriteInput, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 查询指定请求标识的操作执行收据。
+     */
+    operation(id: string, requestId: string, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 按游标读取受管进程输出流。
+     */
+    read(id: string, input: ProcessReadInput, call?: CallOptions): Promise<ReadResult>;
+    /**
+     * 向受管进程发送结构化控制指令。
+     */
+    control(id: string, input: ProcessControlInput, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 终止指定的受管进程资源。
+     */
+    stop(id: string, input: ProcessStopInput, call?: CallOptions): Promise<ProcessInfo>;
+    /**
+     * 拦截 Action Run 生命周期终结：
+     * 若当前 Run 持有进程控制权且未显式 release，自动撤销 grant 并将目标进程置入隔离状态。
+     */
+    dispose(): Promise<void>;
+    /**
+     * 合并上下文取消信号与单次调用选项中的取消信号。
+     */
+    private mergeCallOptions;
+}

package/dist/process/context-process.js

@@ -0,0 +1,168 @@
+/**
+ * 绑定当前 ActionContext 上下文凭据与运行标识的 ProcessAPI 适配器实现。
+ *
+ * 核心保证：
+ * - 自动注入当前运行上下文的归属所有者与运行标识。
+ * - 跟踪由当前 Run 申请成功持有的控制权令牌。
+ * - 拦截 Run 退出或异常生命周期：若当前 Run 未显式 release 释放控制权，自动撤销 grant 并将目标进程置入隔离状态 quarantined。
+ */
+export class ContextProcessAPI {
+    heldProcesses = new Map();
+    isDisposed = false;
+    onAbortHandler;
+    processManager;
+    owner;
+    runId;
+    signal;
+    /** 是否为运行级作用域凭据：缺省时依据构造时是否显式传入 runId 判定 */
+    runScoped;
+    constructor(processManager, owner, runId, signal, runScoped) {
+        this.processManager = processManager;
+        this.owner = owner;
+        this.runId = runId;
+        this.signal = signal;
+        this.runScoped = runScoped ?? Boolean(runId);
+        if (this.signal) {
+            if (this.signal.aborted) {
+                void this.dispose();
+            }
+            else {
+                this.onAbortHandler = () => {
+                    void this.dispose();
+                };
+                this.signal.addEventListener("abort", this.onAbortHandler, { once: true });
+            }
+        }
+    }
+    /**
+     * 底层进程管理器实例（协同入口的公开只读访问）。
+     */
+    get manager() {
+        return this.processManager;
+    }
+    /**
+     * 一次性运行外部命令。
+     */
+    async run(input, call) {
+        return this.processManager.run(this.owner, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 启动新的受管进程资源。
+     */
+    async start(input, call) {
+        return this.processManager.start(this.owner, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 查看指定受管进程资源的状态快照。
+     */
+    async inspect(id, call) {
+        return this.processManager.inspect(this.owner, id, this.mergeCallOptions(call));
+    }
+    /**
+     * 分页列出当前所有者可见的受管进程列表。
+     */
+    async list(input, call) {
+        return this.processManager.list(this.owner, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 申请指定受管进程的独占控制令牌。
+     */
+    async acquire(id, input, call) {
+        const grant = await this.processManager.acquire(this.owner, id, input, this.mergeCallOptions(call), this.runId);
+        this.heldProcesses.set(id, grant.token);
+        return grant;
+    }
+    /**
+     * 延长当前有效控制令牌的存活时间。
+     */
+    async renew(id, token, ttlMs, call) {
+        const renewed = await this.processManager.renew(this.owner, id, token, ttlMs, this.mergeCallOptions(call));
+        this.heldProcesses.set(id, renewed.token);
+        return renewed;
+    }
+    /**
+     * 显式释放控制令牌。
+     */
+    async release(id, token, call) {
+        await this.processManager.release(this.owner, id, token, this.mergeCallOptions(call));
+        this.heldProcesses.delete(id);
+    }
+    /**
+     * 向受管进程输入流写入原始字节数据。
+     */
+    async write(id, input, call) {
+        return this.processManager.write(this.owner, id, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 查询指定请求标识的操作执行收据。
+     */
+    async operation(id, requestId, call) {
+        return this.processManager.operation(this.owner, id, requestId, this.mergeCallOptions(call));
+    }
+    /**
+     * 按游标读取受管进程输出流。
+     */
+    async read(id, input, call) {
+        return this.processManager.read(this.owner, id, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 向受管进程发送结构化控制指令。
+     */
+    async control(id, input, call) {
+        return this.processManager.control(this.owner, id, input, this.mergeCallOptions(call));
+    }
+    /**
+     * 终止指定的受管进程资源。
+     */
+    async stop(id, input, call) {
+        const info = await this.processManager.stop(this.owner, id, input, this.mergeCallOptions(call));
+        this.heldProcesses.delete(id);
+        return info;
+    }
+    /**
+     * 拦截 Action Run 生命周期终结：
+     * 若当前 Run 持有进程控制权且未显式 release，自动撤销 grant 并将目标进程置入隔离状态。
+     */
+    async dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.isDisposed = true;
+        if (this.signal && this.onAbortHandler) {
+            this.signal.removeEventListener("abort", this.onAbortHandler);
+            this.onAbortHandler = undefined;
+        }
+        if (this.heldProcesses.size === 0) {
+            return;
+        }
+        const pendingEntries = Array.from(this.heldProcesses.entries());
+        this.heldProcesses.clear();
+        for (const [processId, token] of pendingEntries) {
+            try {
+                await this.processManager.quarantineProcess(this.owner, processId, token, "Run terminated without explicitly releasing control");
+            }
+            catch {
+                // 忽略终结清理阶段次级异常
+            }
+        }
+    }
+    /**
+     * 合并上下文取消信号与单次调用选项中的取消信号。
+     */
+    mergeCallOptions(call) {
+        if (!this.signal && !call?.signal) {
+            return call;
+        }
+        if (this.signal && !call?.signal) {
+            return { ...call, signal: this.signal };
+        }
+        if (!this.signal && call?.signal) {
+            return call;
+        }
+        // 两个信号同时存在时合成单一信号
+        const combinedSignal = AbortSignal.any
+            ? AbortSignal.any([this.signal, call.signal])
+            : call.signal;
+        return { ...call, signal: combinedSignal };
+    }
+}

package/dist/process/cursor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 已解析的不透明游标完整载荷。
+ */
+export interface ParsedCursor {
+    /** 宿主纪元标识 */
+    hostEpoch: string;
+    /** 受管进程标识 */
+    processId: string;
+    /** 日志记录全局单调自增序号 */
+    sequence: number;
+    /** 记录内字节偏移量 */
+    offset: number;
+}
+/**
+ * 游标逻辑位置坐标。
+ */
+export interface CursorPosition {
+    /** 日志记录全局单调自增序号 */
+    sequence: number;
+    /** 记录内字节偏移量 */
+    offset: number;
+}
+/**
+ * 将内部字段编码为外部不透明游标字符串。
+ *
+ * 规范约束：
+ * - 宿主纪元标识与进程标识必须为非空字符串。
+ * - 序号与偏移量必须为非负整数。
+ * - 游标对外表现为不透明字符串，调用方严禁假定其格式或拆解字段。
+ */
+export declare function encodeCursor(hostEpoch: string, processId: string, sequence: number, offset: number): string;
+/**
+ * 解析不透明游标原始载荷。
+ *
+ * 遇到格式损坏、非法字段或无法解析的游标均抛出 INVALID_CURSOR 异常。
+ */
+export declare function decodeCursor(cursorStr: string): ParsedCursor;
+/**
+ * 校验并解析游标，校验其宿主纪元与受管进程标识与当前目标是否严格匹配。
+ *
+ * 遇到格式错误、跨宿主纪元或跨受管进程的游标，抛出 INVALID_CURSOR 异常。
+ */
+export declare function parseCursor(cursorStr: string, expectedHostEpoch: string, expectedProcessId: string): CursorPosition;
+/**
+ * 比较两个游标坐标的先后次序。
+ *
+ * 返回值：
+ * - 负数：a 位于 b 之前。
+ * - 0：a 与 b 处于同一位置。
+ * - 正数：a 位于 b 之后。
+ */
+export declare function compareCursorPos(a: CursorPosition, b: CursorPosition): number;

package/dist/process/cursor.js

@@ -0,0 +1,144 @@
+import { INVALID_CURSOR, ProcessError } from "../errors.js";
+function toBase64Url(str) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(str, "utf8").toString("base64url");
+    }
+    const bytes = new TextEncoder().encode(str);
+    let binary = "";
+    for (let i = 0; i < bytes.byteLength; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(base64url) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(base64url, "base64url").toString("utf8");
+    }
+    let base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
+    while (base64.length % 4) {
+        base64 += "=";
+    }
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder("utf-8").decode(bytes);
+}
+/**
+ * 将内部字段编码为外部不透明游标字符串。
+ *
+ * 规范约束：
+ * - 宿主纪元标识与进程标识必须为非空字符串。
+ * - 序号与偏移量必须为非负整数。
+ * - 游标对外表现为不透明字符串，调用方严禁假定其格式或拆解字段。
+ */
+export function encodeCursor(hostEpoch, processId, sequence, offset) {
+    if (!hostEpoch || typeof hostEpoch !== "string") {
+        throw new ProcessError(INVALID_CURSOR, "Host epoch must be a non-empty string", { hostEpoch });
+    }
+    if (!processId || typeof processId !== "string") {
+        throw new ProcessError(INVALID_CURSOR, "Process ID must be a non-empty string", { processId });
+    }
+    if (!Number.isInteger(sequence) || sequence < 0) {
+        throw new ProcessError(INVALID_CURSOR, "Sequence must be a non-negative integer", { sequence });
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new ProcessError(INVALID_CURSOR, "Offset must be a non-negative integer", { offset });
+    }
+    const payload = JSON.stringify({
+        v: 1,
+        e: hostEpoch,
+        p: processId,
+        s: sequence,
+        o: offset,
+    });
+    return `cur_${toBase64Url(payload)}`;
+}
+/**
+ * 解析不透明游标原始载荷。
+ *
+ * 遇到格式损坏、非法字段或无法解析的游标均抛出 INVALID_CURSOR 异常。
+ */
+export function decodeCursor(cursorStr) {
+    if (typeof cursorStr !== "string" || cursorStr.trim() === "") {
+        throw new ProcessError(INVALID_CURSOR, "Cursor must be a non-empty string", { cursor: cursorStr });
+    }
+    const raw = cursorStr.startsWith("cur_") ? cursorStr.slice(4) : cursorStr;
+    let decodedStr;
+    try {
+        decodedStr = fromBase64Url(raw);
+    }
+    catch (err) {
+        throw new ProcessError(INVALID_CURSOR, "Failed to decode cursor base64url payload", {
+            cursor: cursorStr,
+            cause: err instanceof Error ? err.message : String(err),
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decodedStr);
+    }
+    catch (err) {
+        throw new ProcessError(INVALID_CURSOR, "Failed to parse cursor JSON payload", {
+            cursor: cursorStr,
+            cause: err instanceof Error ? err.message : String(err),
+        });
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        typeof parsed.e !== "string" ||
+        typeof parsed.p !== "string" ||
+        !Number.isInteger(parsed.s) ||
+        parsed.s < 0 ||
+        !Number.isInteger(parsed.o) ||
+        parsed.o < 0) {
+        throw new ProcessError(INVALID_CURSOR, "Malformed cursor structure", { cursor: cursorStr });
+    }
+    return {
+        hostEpoch: parsed.e,
+        processId: parsed.p,
+        sequence: parsed.s,
+        offset: parsed.o,
+    };
+}
+/**
+ * 校验并解析游标，校验其宿主纪元与受管进程标识与当前目标是否严格匹配。
+ *
+ * 遇到格式错误、跨宿主纪元或跨受管进程的游标，抛出 INVALID_CURSOR 异常。
+ */
+export function parseCursor(cursorStr, expectedHostEpoch, expectedProcessId) {
+    const decoded = decodeCursor(cursorStr);
+    if (decoded.hostEpoch !== expectedHostEpoch) {
+        throw new ProcessError(INVALID_CURSOR, `Cursor host epoch mismatch: expected '${expectedHostEpoch}', got '${decoded.hostEpoch}'`, {
+            cursor: cursorStr,
+            expectedHostEpoch,
+            actualHostEpoch: decoded.hostEpoch,
+        });
+    }
+    if (decoded.processId !== expectedProcessId) {
+        throw new ProcessError(INVALID_CURSOR, `Cursor process ID mismatch: expected '${expectedProcessId}', got '${decoded.processId}'`, {
+            cursor: cursorStr,
+            expectedProcessId,
+            actualProcessId: decoded.processId,
+        });
+    }
+    return {
+        sequence: decoded.sequence,
+        offset: decoded.offset,
+    };
+}
+/**
+ * 比较两个游标坐标的先后次序。
+ *
+ * 返回值：
+ * - 负数：a 位于 b 之前。
+ * - 0：a 与 b 处于同一位置。
+ * - 正数：a 位于 b 之后。
+ */
+export function compareCursorPos(a, b) {
+    if (a.sequence !== b.sequence) {
+        return a.sequence - b.sequence;
+    }
+    return a.offset - b.offset;
+}