@actiondock/core 2.5.1 → 2.6.0

package/dist/process/managed-record.d.ts

@@ -0,0 +1,78 @@
+import type { ControlGrant, Limits, OperationReceipt, ProcessControlAction, ProcessInfo } from "@actiondock/sdk";
+import type { ProcessDriverHandle } from "./driver.js";
+import type { ProcessRequestKey } from "./metadata-store.js";
+import type { ProcessOutputLog } from "./output-log.js";
+import type { EvictedOutputTombstone } from "./terminal-output-cache.js";
+/**
+ * 受管进程归属所有者身份。
+ */
+export interface ProcessOwner {
+    tenantId: string;
+    principalId: string;
+    packageInstanceId: string;
+    generationId: string;
+}
+/**
+ * 待调度的异步操作队列条目。
+ */
+export interface QueuedOperation {
+    type: "write" | "control";
+    requestId: string;
+    token: string;
+    bytes?: Uint8Array;
+    action?: ProcessControlAction;
+    /** 入队时进程的取消纪元，用于 stop 与 dispatch 竞态判定 */
+    cancelEpoch: number;
+    receipt: OperationReceipt;
+    key: ProcessRequestKey;
+    payloadHash: string;
+}
+/**
+ * 排队等待获取控制权的调用者条目。
+ */
+export interface AcquireWaiter {
+    requestId: string;
+    waitMs: number;
+    ttlMs: number;
+    runId?: string;
+    timer?: ReturnType<typeof setTimeout>;
+    onAbort?: () => void;
+    resolve: (grant: ControlGrant) => void;
+    reject: (err: unknown) => void;
+}
+/**
+ * 进程管理器内部维护的活跃受管进程记录。
+ *
+ * 该结构为进程管理器、控制权仲裁器与输入调度器的共享事实源：
+ * 控制权与输入队列相关字段经仲裁器与调度器协作推进，禁止绕过二者直接改写。
+ */
+export interface ManagedProcessRecord {
+    info: ProcessInfo;
+    owner: ProcessOwner;
+    scope: string;
+    handle?: ProcessDriverHandle;
+    outputLog: ProcessOutputLog;
+    outputUnavailable?: boolean;
+    outputTombstone?: EvictedOutputTombstone;
+    controlEpoch: number;
+    /** 取消纪元：stop 接管输入队列时递增，用于让挂起中的 dispatch 放弃过期结算 */
+    cancelEpoch: number;
+    currentGrant?: {
+        token: string;
+        epoch: number;
+        ttlMs: number;
+        expiresAt: string;
+        runId?: string;
+        requestId: string;
+    };
+    ttlTimer?: ReturnType<typeof setTimeout>;
+    idleTimer?: ReturnType<typeof setTimeout>;
+    lifetimeTimer?: ReturnType<typeof setTimeout>;
+    drainTimer?: ReturnType<typeof setTimeout>;
+    inputQueue: QueuedOperation[];
+    pendingInputBytes: number;
+    acquireWaiters: AcquireWaiter[];
+    inputClosed: boolean;
+    isDispatching: boolean;
+    effectiveLimits: Required<Limits>;
+}

package/dist/process/managed-record.js

@@ -0,0 +1 @@
+export {};

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

@@ -2,15 +2,8 @@ import { type CallOptions, type ControlGrant, type Limits, type Logger, type Ope
 import { ContextProcessAPI } from "./context-process.js";
 import type { ProcessDriver } from "./driver.js";
 import { type ProcessMetadataStore } from "./metadata-store.js";
-/**
- * 受管进程归属所有者身份。
- */
-export interface ProcessOwner {
-    tenantId: string;
-    principalId: string;
-    packageInstanceId: string;
-    generationId: string;
-}
+import type { ProcessOwner } from "./managed-record.js";
+export type { ManagedProcessRecord, QueuedOperation, AcquireWaiter, ProcessOwner, } from "./managed-record.js";
 /**
  * 宿主与作用域资源配额配置。
  */
@@ -75,18 +68,21 @@ export declare class ProcessManager {
     readonly defaultLimits: Required<Limits>;
     readonly drainDeadlineMs: number;
     readonly terminalLogRetentionMs: number;
-    private readonly logger?;
     private processes;
-    /** 已驱逐进程的输出日志缓存：附带时间戳支撑 TTL 过期回收与 LRU 淘汰 */
-    private evictedOutputLogs;
-    /** 已淘汰输出日志的墓碑缓存：防止因日志淘汰静默丢失输出数据，支撑缺口明确告知与不可用异常 */
-    private evictedOutputTombstones;
+    /** 内部诊断日志汇聚器：未注入 logger 时保留最近的持久化与驱动错误，避免静默吞没异常 */
+    private readonly diagnosticsSink;
     /** 同步幂等预占表：以复合键在异步落盘窗口内锁定并发重复请求 */
-    private requestReservations;
+    private readonly reservationTable;
+    /** 终态输出日志保留缓存：附带 TTL 过期回收与 LRU 淘汰，及墓碑登记 */
+    private readonly terminalOutputCache;
+    /** 一次性 run 执行器：仅依赖驱动、错误映射与输入校验，不触碰进程注册表 */
+    private readonly runExecutor;
+    /** 控制权仲裁器：独占控制权状态机全部推进路径的唯一持有者 */
+    private readonly controlArbiter;
+    /** 输入调度器：输入队列入队、串行调度与接管原语的唯一持有者 */
+    private readonly inputDispatcher;
     private initPromise;
     private isShutdown;
-    /** 内部诊断日志：未注入 logger 时保留最近的持久化与驱动错误，避免静默吞没异常 */
-    private diagnostics;
     constructor(options: ProcessManagerOptions);
     /**
      * 初始化宿主环境，原子性收敛旧宿主遗留的非终态进程。
@@ -115,9 +111,7 @@ export declare class ProcessManager {
     private persistReceipt;
     /**
      * 同步预占幂等请求：跨 await 的检查与落盘窗口内锁定同复合键并发调用。
-     * 返回 undefined 表示预占成功，调用方继续异步路径并在完成时调用 commit/cancel。
-     * 返回 RequestReservation 表示已有同请求进行中，调用方可等待其结果。
-     * 若已有请求负载或操作类型不同，立即抛出 REQUEST_CONFLICT 杜绝混用结果。
+     * 实现委托给独立持有的预占表，语义详见 ReservationTable.reserve。
      */
     private reserveRequest;
     private commitReservation;
@@ -181,28 +175,9 @@ export declare class ProcessManager {
     quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): Promise<void>;
     /**
      * 一次性运行外部命令，收集有限输出并支持协作式取消与超时回收。
+     * 实现委托给独立持有的一次性 run 执行器，不触碰受管进程注册表。
      */
     run(owner: ProcessOwner, input: ProcessRunInput, call?: CallOptions): Promise<ProcessRunResult>;
-    /**
-     * 授予指定受管进程控制令牌。
-     */
-    private grantControl;
-    /**
-     * 控制权到期未释放时自动转为隔离状态。
-     */
-    private handleGrantTtlExpired;
-    /**
-     * 唤醒排队等待控制权的下一个调用者。
-     */
-    private wakeNextAcquireWaiter;
-    /**
-     * 串行调度执行输入队列操作。
-     */
-    private dispatchNext;
-    /**
-     * 操作提交前校验持有者令牌与授权。
-     */
-    private checkOperationAuth;
     /**
      * 启动空闲超时定时器。
      */
@@ -239,26 +214,10 @@ export declare class ProcessManager {
      * 加载或读取受管进程记录并校验所有者鉴权。
      */
     private getOrLoadProcess;
-    /**
-     * 记录已淘汰输出日志的墓碑信息（保留最近 2048 条，防止内存无限积压）。
-     */
-    private recordTombstone;
-    /**
-     * 清理已过期的终态输出日志条目。
-     */
-    private cleanExpiredTerminalLogs;
     /**
      * 统计终态保留日志当前在内存中实际占用的输出缓冲字节总数。
      */
     private countRetainedOutputBufferBytes;
-    /**
-     * 将终态输出日志存入保留缓存，并根据宿主配额执行 LRU 与 TTL 淘汰。
-     */
-    private retainTerminalOutputLog;
-    /**
-     * 获取终态保留日志（附带过期清理与 LRU 触达更新）。
-     */
-    private getRetainedOutputLog;
     /**
      * 终态驱逐与驱动释放：进程到达终态且输出已关闭后移除内存记录，
      * 并防御性释放底层驱动句柄（失败仅记录诊断不中断）。