@xioflow/kernel 0.1.5 → 0.2.0

package/README.md

@@ -42,7 +42,7 @@ npm install @xioflow/kernel
 import { ExecutionDomain, NodePlatformDriver, ProcessSupervisor } from '@xioflow/kernel';
 
 // The domain directory will hold domain.db, domain.lock and artifacts/.
-const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow', 'my-domain');
+const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow/kernel', 'my-domain');
 const supervisor = new ProcessSupervisor(domain, new NodePlatformDriver());
 
 // Every operation belongs to a Run, and every Run to a Task. Register them first:
@@ -96,7 +96,7 @@ After a restart, reacquire the domain and run the recovery engine:
 ```js
 import { ExecutionDomain, NodePlatformDriver, RecoveryEngine } from '@xioflow/kernel';
 
-const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow', 'my-domain');
+const domain = ExecutionDomain.acquire('/path/to/workspace/.xioflow/kernel', 'my-domain');
 const report = await new RecoveryEngine(domain, new NodePlatformDriver()).recover();
 ```
 
@@ -150,10 +150,21 @@ Releases are tag-driven. A tag always produces a GitHub Release; the npm upload
 
 1. Bump `version` in `package.json`, commit, and push to `main`.
 2. Push the matching tag, e.g. `git tag v0.1.5 && git push origin v0.1.5`.
-3. `.github/workflows/release.yml` re-runs typecheck, tests and the pack smoke test, refuses a tag that does not match `package.json`, creates the GitHub Release, and — only when the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED` is `true` — publishes with `npm publish --provenance` and verifies the attestation.
+3. `.github/workflows/release.yml` re-runs typecheck, tests and the pack smoke test, refuses a tag that does not match `package.json`, creates the GitHub Release with the packed tarball, `SHA256SUMS` and a build provenance attestation attached, and — only when the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED` is `true` — publishes with `npm publish --provenance` and verifies the attestation.
 
 One-time setup, in this order: (1) npmjs.com → package settings → Trusted Publisher → GitHub Actions: organization `Xio-Shark`, repository `xioflow`, workflow filename `release.yml`, environment left empty; (2) set the repository variable `NPM_TRUSTED_PUBLISHING_ENABLED=true`. Until both exist the publish job is skipped and the reason is printed in the `verify` job's log. npm's registry index can lag several minutes behind an upload, so the verification step polls and may need a job re-run.
 
+To attach assets to an existing tag without publishing to npm, run the workflow manually: `gh workflow run release.yml -f tag=v0.1.5`. An asset that is already attached is kept if identical and fails the run if it differs; published assets are never overwritten.
+
+### Verifying a release
+
+```bash
+gh release download v0.1.5 --repo Xio-Shark/xioflow
+shasum -a 256 -c SHA256SUMS
+gh attestation verify xioflow-kernel-0.1.5.tgz --repo Xio-Shark/xioflow
+npm audit signatures   # inside a project that installed @xioflow/kernel from npm
+```
+
 ## License
 
 MIT

package/dist/domain.d.ts

@@ -1,6 +1,7 @@
 import { SqliteStore } from './store/sqlite.js';
-import { Operation, OwnerRecord, ResourceBudget, DomainBudget, DomainLockedError, ResourceConflictError, EpochFencedError } from './types.js';
-export { DomainLockedError, ResourceConflictError, EpochFencedError };
+import { PlatformDriver } from './driver/types.js';
+import { Operation, OwnerRecord, ResourceBudget, DomainBudget, DomainLockedError, ResourceConflictError, EpochFencedError, TerminationReason, AdjudicationRecord } from './types.js';
+export { DomainLockedError, ResourceConflictError, EpochFencedError, AdjudicationRecord };
 export declare class ExecutionDomain {
     readonly domainPath: string;
     readonly domainId: string;
@@ -9,8 +10,11 @@ export declare class ExecutionDomain {
     private lockFd;
     private ownerRecord;
     private domainBudget?;
+    private driver?;
     private inMemoryLockedResources;
+    private inMemoryAllocatedOps;
     private inMemoryBudgets;
+    private waitQueue;
     private heartbeatInterval;
     private isFenced;
     private constructor();
@@ -34,22 +38,52 @@ export declare class ExecutionDomain {
      * 刷新租约心跳，若失败则触发代际栅栏与写凭证销毁
      */
     renewHeartbeat(): void;
+    private getActiveOperationIds;
+    private diagnoseConflict;
     /**
      * 申请占用资源（支持隔离检查与配额校验）
      */
     allocateResources(operationId: string, resources: string[], waitedDurationMs?: number, budget?: ResourceBudget): void;
     /**
-     * 具备排队等待与诊断的异步资源分配
+     * 具备 FIFO 排队等待与诊断的异步资源分配 (P0-5, P0-13)
      */
-    allocateResourcesWithWait(operationId: string, resources: string[], maxWaitMs?: number, budget?: ResourceBudget): Promise<void>;
+    allocateResourcesWithWait(operationId: string, resources: string[], maxWaitMs?: number, budget?: ResourceBudget, isCancelled?: () => boolean): Promise<void>;
     /**
-     * 释放资源占用
+     * 取消在等待队列中的操作 (立即唤醒以完成取消协议)
      */
-    releaseResources(operationId: string, resources?: string[]): void;
+    cancelWait(operationId: string): boolean;
+    private processWaitQueue;
+    setDriver(driver: PlatformDriver): void;
+    /**
+     * 内部私有资源释放（走代际栅栏并记录 RESOURCES_RELEASED 事件，§0.2 裁决 1 / N6）
+     * @internal 仅供 supervisor、recovery engine 与 adjudicate 等内核内部组件调用
+     */
+    internalReleaseResources(operationId: string, resources?: string[]): void;
+    /**
+     * 人工裁决协议：对 indeterminate 状态进行有审计记录的唯一收口 (ARCHITECTURE §3.6 / P0-7)
+     */
+    adjudicate(opId: string, verdict: 'confirmed_stopped' | 'abandon_with_residuals', actor: string, note?: string): Promise<AdjudicationRecord>;
+    /**
+     * Run 完成与取消协议 (ARCHITECTURE §3.3)
+     */
+    reportRunCancelled(runId: string, reason?: TerminationReason): void;
+    reportRunSucceeded(runId: string): void;
+    reportRunFailed(runId: string, reason?: TerminationReason): void;
     /**
      * 意图登记协议：先持久化意图与占用，再允许驱动调用
      */
     registerOperationIntent(op: Operation): void;
+    /**
+     * 产物回收防线 (ARCHITECTURE §4.3 / N7)
+     * 只回收已终态且未被引用的产物，严格拒绝回收未终结或 indeterminate 状态的产物。
+     */
+    pruneArtifacts(filter?: {
+        olderThanMs?: number;
+        prefix?: string;
+    }): {
+        deleted: string[];
+        retained: string[];
+    };
     isClosed(): boolean;
     close(): void;
 }

package/dist/domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAEL,SAAS,EAET,WAAW,EACX,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AAEtE,qBAAa,eAAe;IAC1B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAC,CAAe;IAEpC,OAAO,CAAC,uBAAuB,CAAkC;IAEjE,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAkB;IAElC,OAAO,eAqCN;IAED,OAAc,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAkB,GAAG,eAAe,CAqDvF;IAED,OAAO,CAAC,MAAM,CAAC,iBAAiB;IASzB,cAAc,IAAI,WAAW,CAEnC;IAEM,QAAQ,IAAI,MAAM,CAExB;IAEM,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAEjD;IAEM,eAAe,IAAI,YAAY,GAAG,SAAS,CAEjD;IAED;;OAEG;IACI,yBAAyB,IAAI,IAAI,CAuBvC;IAEM,QAAQ,IAAI,WAAW,CAE7B;IAEM,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnD;IAEM,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9D;IAEM,qBAAqB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAElD;IAEM,cAAc,IAAI,OAAO,CAE/B;IAED,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACI,cAAc,IAAI,IAAI,CAqB5B;IAED;;OAEG;IACI,iBAAiB,CACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,GAAE,MAAU,EAC5B,MAAM,CAAC,EAAE,cAAc,GACtB,IAAI,CA6BN;IAED;;OAEG;IACU,yBAAyB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,SAAS,GAAE,MAAU,EACrB,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAkBf;IAED;;OAEG;IACI,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAiBvE;IAED;;OAEG;IACI,uBAAuB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAalD;IAEM,QAAQ,IAAI,OAAO,CAEzB;IAEM,KAAK,IAAI,IAAI,CAmCnB;CACF"}
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"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"}

package/dist/domain.js

@@ -12,10 +12,15 @@ export class ExecutionDomain {
     lockFd = null;
     ownerRecord;
     domainBudget;
+    driver;
     // 内存隔离表：resourceId -> operationId
     inMemoryLockedResources = new Map();
+    // 内存活跃操作（独立于资源租约，用于 domain:max_concurrent_ops）
+    inMemoryAllocatedOps = new Set();
     // 内存活跃操作预算
     inMemoryBudgets = new Map();
+    // FIFO 等待队列
+    waitQueue = [];
     heartbeatInterval = null;
     isFenced = false;
     constructor(domainPath, domainId, lockFilePath, lockFd) {
@@ -42,7 +47,7 @@ export class ExecutionDomain {
                     this.heartbeatInterval = null;
                 }
                 try {
-                    this.store.unsafeSetCurrentEpochForTesting(-1);
+                    this.store.fence();
                 }
                 catch { }
             }
@@ -56,6 +61,7 @@ export class ExecutionDomain {
             fs.mkdirSync(domainPath, { recursive: true });
         }
         const lockFilePath = path.join(domainPath, 'domain.lock');
+        const dbPath = path.join(domainPath, 'domain.db');
         let fd = null;
         try {
             // 尝试独占创建锁文件
@@ -74,11 +80,24 @@ export class ExecutionDomain {
                 }
                 if (lockMeta) {
                     const isAlive = ExecutionDomain.checkProcessAlive(lockMeta.ownerPid);
-                    if (isAlive) {
+                    let leaseExpired = false;
+                    // 结合 owners 表判定租约是否过期 (P0-11)
+                    if (fs.existsSync(dbPath)) {
+                        try {
+                            const tempStore = new SqliteStore(dbPath);
+                            const owner = tempStore.getOwner(domainId);
+                            if (owner && new Date(owner.expiresAt).getTime() < Date.now()) {
+                                leaseExpired = true;
+                            }
+                            tempStore.close();
+                        }
+                        catch { }
+                    }
+                    if (isAlive && !leaseExpired) {
                         throw new DomainLockedError(lockMeta.domainId, lockMeta.ownerPid, lockMeta.acquiredAt);
                     }
                 }
-                // 旧进程已死亡，安全覆盖锁
+                // 旧进程已死亡或租约已过期，安全覆盖锁
                 try {
                     fs.unlinkSync(lockFilePath);
                 }
@@ -96,7 +115,22 @@ export class ExecutionDomain {
             hostname: os.hostname(),
         };
         fs.writeSync(fd, JSON.stringify(metadata, null, 2));
-        return new ExecutionDomain(domainPath, domainId, lockFilePath, fd);
+        try {
+            return new ExecutionDomain(domainPath, domainId, lockFilePath, fd);
+        }
+        catch (ctorErr) {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { }
+                try {
+                    fs.unlinkSync(lockFilePath);
+                }
+                catch { }
+            }
+            throw ctorErr;
+        }
     }
     static checkProcessAlive(pid) {
         try {
@@ -125,6 +159,7 @@ export class ExecutionDomain {
     rebuildIsolationFromStore() {
         this.inMemoryLockedResources.clear();
         this.inMemoryBudgets.clear();
+        this.inMemoryAllocatedOps.clear();
         // 1. 读取持久化未释放的 resource_leases
         const leases = this.store.getPersistedResourceLeases(this.domainId);
         for (const lease of leases) {
@@ -133,9 +168,10 @@ export class ExecutionDomain {
                 this.inMemoryBudgets.set(lease.operationId, lease.budget);
             }
         }
-        // 2. 核对未终结操作声明的所有资源
+        // 2. 核对未终结操作声明的所有资源与活跃操作集合 (独立于 resource_leases)
         const unfinishedOps = this.store.getUnfinishedOperations(this.domainId);
         for (const op of unfinishedOps) {
+            this.inMemoryAllocatedOps.add(op.id);
             for (const res of op.requiredResources) {
                 this.inMemoryLockedResources.set(res, op.id);
             }
@@ -181,12 +217,36 @@ export class ExecutionDomain {
                 this.heartbeatInterval = null;
             }
             try {
-                this.store.unsafeSetCurrentEpochForTesting(-1);
+                this.store.fence();
             }
             catch { }
             throw err;
         }
     }
+    getActiveOperationIds() {
+        const set = new Set(this.inMemoryAllocatedOps);
+        const unfinishedOps = this.store.getUnfinishedOperations(this.domainId);
+        for (const op of unfinishedOps) {
+            set.add(op.id);
+        }
+        return set;
+    }
+    diagnoseConflict(operationId, resources, waitedDurationMs = 0, budget) {
+        for (const res of resources) {
+            const existingOwner = this.inMemoryLockedResources.get(res);
+            if (existingOwner && existingOwner !== operationId) {
+                return new ResourceConflictError(res, existingOwner, operationId, waitedDurationMs);
+            }
+        }
+        if (this.domainBudget && this.domainBudget.maxConcurrentOps) {
+            const activeOps = this.getActiveOperationIds();
+            if (activeOps.size >= this.domainBudget.maxConcurrentOps && !activeOps.has(operationId)) {
+                const holder = Array.from(activeOps)[0] || 'domain-concurrency-cap';
+                return new ResourceConflictError('domain:max_concurrent_ops', holder, operationId, waitedDurationMs);
+            }
+        }
+        return new ResourceConflictError(resources[0] || 'domain:resource', 'unknown', operationId, waitedDurationMs);
+    }
     /**
      * 申请占用资源（支持隔离检查与配额校验）
      */
@@ -195,20 +255,22 @@ export class ExecutionDomain {
         // 1. 检查资源冲突
         for (const res of resources) {
             const existingOwner = this.inMemoryLockedResources.get(res);
+            // 注（N8）：现有持有人等于当前 opId 仅当同一调用内部阶段重入（如子操作或多阶段申请）时合法；
+            // 在飞 opId 的重复提交已由 supervisor 入口守卫拦截，绝不可能在此被当作合法持有人放行。
             if (existingOwner && existingOwner !== operationId) {
                 throw new ResourceConflictError(res, existingOwner, operationId, waitedDurationMs);
             }
         }
-        // 2. 检查域级配额（并发数）
-        if (this.domainBudget) {
-            const activeOps = new Set(this.inMemoryLockedResources.values());
-            if (this.domainBudget.maxConcurrentOps &&
-                activeOps.size >= this.domainBudget.maxConcurrentOps &&
+        // 2. 检查域级配额（并发数独立于 resource_leases）
+        if (this.domainBudget && this.domainBudget.maxConcurrentOps) {
+            const activeOps = this.getActiveOperationIds();
+            if (activeOps.size >= this.domainBudget.maxConcurrentOps &&
                 !activeOps.has(operationId)) {
                 const holder = Array.from(activeOps)[0] || 'domain-concurrency-cap';
                 throw new ResourceConflictError('domain:max_concurrent_ops', holder, operationId, waitedDurationMs);
             }
         }
+        this.inMemoryAllocatedOps.add(operationId);
         for (const res of resources) {
             this.inMemoryLockedResources.set(res, operationId);
         }
@@ -217,39 +279,157 @@ export class ExecutionDomain {
         }
     }
     /**
-     * 具备排队等待与诊断的异步资源分配
+     * 具备 FIFO 排队等待与诊断的异步资源分配 (P0-5, P0-13)
      */
-    async allocateResourcesWithWait(operationId, resources, maxWaitMs = 0, budget) {
+    async allocateResourcesWithWait(operationId, resources, maxWaitMs = 0, budget, isCancelled) {
+        this.assertNotFenced();
+        if (isCancelled && isCancelled()) {
+            return;
+        }
         const startTime = Date.now();
-        while (true) {
+        // 如果队列为空，尝试直接分配
+        if (this.waitQueue.length === 0) {
             try {
-                this.allocateResources(operationId, resources, Date.now() - startTime, budget);
+                this.allocateResources(operationId, resources, 0, budget);
                 return;
             }
+            catch (err) {
+                if (!(err instanceof ResourceConflictError)) {
+                    throw err;
+                }
+                if (maxWaitMs <= 0) {
+                    throw err;
+                }
+            }
+        }
+        else {
+            // 队列中已有排队者：若不愿等待则直接抛出诊断
+            if (maxWaitMs <= 0) {
+                throw this.diagnoseConflict(operationId, resources, 0, budget);
+            }
+        }
+        // 必须入队等待 (严格 FIFO)
+        return new Promise((resolve, reject) => {
+            let timer;
+            const item = {
+                operationId,
+                resources,
+                budget,
+                resolve: () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve();
+                },
+                reject: (err) => {
+                    if (timer)
+                        clearTimeout(timer);
+                    reject(err);
+                },
+                isCancelled,
+                startTime,
+                maxWaitMs,
+                timer: undefined,
+            };
+            timer = setTimeout(() => {
+                const idx = this.waitQueue.indexOf(item);
+                if (idx !== -1) {
+                    this.waitQueue.splice(idx, 1);
+                }
+                if (item.isCancelled && item.isCancelled()) {
+                    item.resolve();
+                    return;
+                }
+                const elapsed = Date.now() - item.startTime;
+                const err = this.diagnoseConflict(item.operationId, item.resources, elapsed, item.budget);
+                item.reject(err);
+            }, maxWaitMs);
+            item.timer = timer;
+            this.waitQueue.push(item);
+        });
+    }
+    /**
+     * 取消在等待队列中的操作 (立即唤醒以完成取消协议)
+     */
+    cancelWait(operationId) {
+        const idx = this.waitQueue.findIndex((item) => item.operationId === operationId);
+        if (idx !== -1) {
+            const item = this.waitQueue[idx];
+            this.waitQueue.splice(idx, 1);
+            if (item.timer)
+                clearTimeout(item.timer);
+            item.resolve();
+            return true;
+        }
+        return false;
+    }
+    processWaitQueue() {
+        if (this.waitQueue.length === 0 || this.isFenced) {
+            return;
+        }
+        const reservedResources = new Set();
+        let concurrencyBlocked = false;
+        let i = 0;
+        while (i < this.waitQueue.length) {
+            const item = this.waitQueue[i];
+            // 1. 检查取消
+            if (item.isCancelled && item.isCancelled()) {
+                this.waitQueue.splice(i, 1);
+                item.resolve();
+                continue;
+            }
+            // 2. 检查是否与更早等待者的资源发生争抢
+            const hasConflictWithEarlierWaiters = item.resources.some((r) => reservedResources.has(r));
+            if (hasConflictWithEarlierWaiters || concurrencyBlocked) {
+                for (const res of item.resources) {
+                    reservedResources.add(res);
+                }
+                i++;
+                continue;
+            }
+            // 3. 尝试分配
+            try {
+                const elapsed = Date.now() - item.startTime;
+                this.allocateResources(item.operationId, item.resources, elapsed, item.budget);
+                // 分配成功：移出等待队列并唤醒
+                this.waitQueue.splice(i, 1);
+                item.resolve();
+            }
             catch (err) {
                 if (err instanceof ResourceConflictError) {
-                    const elapsed = Date.now() - startTime;
-                    if (elapsed >= maxWaitMs) {
-                        throw new ResourceConflictError(err.resourceId, err.existingOwnerOpId, operationId, elapsed);
+                    for (const res of item.resources) {
+                        reservedResources.add(res);
+                    }
+                    if (err.resourceId === 'domain:max_concurrent_ops') {
+                        concurrencyBlocked = true;
                     }
-                    await new Promise((r) => setTimeout(r, 50));
+                    i++;
                 }
                 else {
-                    throw err;
+                    this.waitQueue.splice(i, 1);
+                    item.reject(err);
                 }
             }
         }
     }
+    setDriver(driver) {
+        this.driver = driver;
+    }
     /**
-     * 释放资源占用
+     * 内部私有资源释放（走代际栅栏并记录 RESOURCES_RELEASED 事件，§0.2 裁决 1 / N6）
+     * @internal 仅供 supervisor、recovery engine 与 adjudicate 等内核内部组件调用
      */
-    releaseResources(operationId, resources) {
+    internalReleaseResources(operationId, resources) {
+        this.assertNotFenced();
+        this.store.verifyEpochFencing(this.domainId);
+        const releasedList = [];
+        this.inMemoryAllocatedOps.delete(operationId);
         this.inMemoryBudgets.delete(operationId);
-        if (resources) {
+        if (resources && resources.length > 0) {
             for (const res of resources) {
                 if (this.inMemoryLockedResources.get(res) === operationId) {
                     this.inMemoryLockedResources.delete(res);
                     this.store.releaseResourceLease(operationId, res);
+                    releasedList.push(res);
                 }
             }
         }
@@ -257,10 +437,115 @@ export class ExecutionDomain {
             for (const [res, owner] of Array.from(this.inMemoryLockedResources.entries())) {
                 if (owner === operationId) {
                     this.inMemoryLockedResources.delete(res);
+                    releasedList.push(res);
                 }
             }
             this.store.releaseResourceLease(operationId);
         }
+        this.store.recordEventAndTransitionState({
+            domainId: this.domainId,
+            operationId,
+            type: 'RESOURCES_RELEASED',
+            payload: {
+                operationId,
+                resources: releasedList,
+            },
+            timestamp: new Date().toISOString(),
+        });
+        this.processWaitQueue();
+    }
+    /**
+     * 人工裁决协议：对 indeterminate 状态进行有审计记录的唯一收口 (ARCHITECTURE §3.6 / P0-7)
+     */
+    async adjudicate(opId, verdict, actor, note) {
+        this.assertNotFenced();
+        this.store.verifyEpochFencing(this.domainId);
+        const op = this.store.getOperation(opId);
+        if (!op) {
+            throw new Error(`Operation "${opId}" not found`);
+        }
+        if (op.status !== 'done' || op.result?.status !== 'indeterminate') {
+            throw new Error(`Cannot adjudicate operation "${opId}": status must be 'indeterminate' (current status: '${op.status}', result: '${op.result?.status}')`);
+        }
+        // 2. 事实补全：驱动再做一次身份核验与残留扫描
+        const residualPids = [];
+        const pid = op.processIdentity?.pid;
+        const pgid = op.processIdentity?.pgid;
+        if (pid) {
+            try {
+                process.kill(pid, 0);
+                residualPids.push(pid);
+            }
+            catch { }
+        }
+        if (pgid !== undefined) {
+            if (this.driver && this.driver.getGroupEvidence) {
+                try {
+                    const members = await this.driver.getGroupEvidence(pgid);
+                    for (const m of members) {
+                        if (!residualPids.includes(m.pid)) {
+                            residualPids.push(m.pid);
+                        }
+                    }
+                }
+                catch { }
+            }
+            else {
+                try {
+                    process.kill(-pgid, 0);
+                    if (pid && !residualPids.includes(pid)) {
+                        residualPids.push(pid);
+                    }
+                }
+                catch { }
+            }
+        }
+        if (verdict === 'confirmed_stopped' && residualPids.length > 0) {
+            throw new Error(`Cannot adjudicate operation "${opId}" as 'confirmed_stopped': residual processes are still alive: [${residualPids.join(', ')}]. Use 'abandon_with_residuals' or ensure processes are terminated first.`);
+        }
+        const record = {
+            operationId: opId,
+            verdict,
+            actor,
+            note,
+            residualPids: residualPids.length > 0 ? residualPids : undefined,
+            decidedAt: new Date().toISOString(),
+        };
+        // 3. 事务提交：写入 AdjudicationRecord 与 journal 事件 OPERATION_ADJUDICATED
+        this.store.recordEventAndTransitionState({
+            domainId: this.domainId,
+            runId: op.runId,
+            operationId: opId,
+            type: 'OPERATION_ADJUDICATED',
+            payload: {
+                ...record,
+                processIdentity: op.processIdentity,
+            },
+            timestamp: record.decidedAt,
+        });
+        const updatedResult = {
+            ...op.result,
+            adjudication: record,
+        };
+        this.store.updateOperationResult(opId, updatedResult);
+        // 释放租约 (走内部私有释放 API，带 epoch 栅栏与 RESOURCES_RELEASED 事件)
+        this.internalReleaseResources(opId, op.requiredResources);
+        return record;
+    }
+    /**
+     * Run 完成与取消协议 (ARCHITECTURE §3.3)
+     */
+    reportRunCancelled(runId, reason = 'user_cancelled') {
+        this.assertNotFenced();
+        this.store.reportRunCancelled(runId, reason);
+    }
+    reportRunSucceeded(runId) {
+        this.assertNotFenced();
+        this.store.reportRunSucceeded(runId);
+    }
+    reportRunFailed(runId, reason = 'completed') {
+        this.assertNotFenced();
+        this.store.reportRunFailed(runId, reason);
     }
     /**
      * 意图登记协议：先持久化意图与占用，再允许驱动调用
@@ -275,14 +560,93 @@ export class ExecutionDomain {
         }
         catch (err) {
             // 写入失败回滚内存状态
-            this.releaseResources(op.id, op.requiredResources);
+            this.internalReleaseResources(op.id, op.requiredResources);
             throw err;
         }
     }
+    /**
+     * 产物回收防线 (ARCHITECTURE §4.3 / N7)
+     * 只回收已终态且未被引用的产物，严格拒绝回收未终结或 indeterminate 状态的产物。
+     */
+    pruneArtifacts(filter) {
+        this.assertNotFenced();
+        const artifactsDir = path.join(this.domainPath, 'artifacts');
+        if (!fs.existsSync(artifactsDir)) {
+            return { deleted: [], retained: [] };
+        }
+        const protectedFiles = new Set();
+        const allOps = this.store.getAllOperations(this.domainId);
+        for (const op of allOps) {
+            const isIndet = op.result?.status === 'indeterminate' || op.result?.kind === 'indeterminate';
+            const isDone = op.status === 'done';
+            if (!isDone || isIndet) {
+                // 未终结或 indeterminate：保护所有可能关联的产物
+                protectedFiles.add(`${op.id}-stdout.log`);
+                protectedFiles.add(`${op.id}-stderr.log`);
+                if (op.outputRef)
+                    protectedFiles.add(path.basename(op.outputRef));
+                if (op.result?.stdoutRef)
+                    protectedFiles.add(path.basename(op.result.stdoutRef));
+                if (op.result?.stderrRef)
+                    protectedFiles.add(path.basename(op.result.stderrRef));
+            }
+            else {
+                // 已终态：仅保护仍被引用的产物
+                if (op.outputRef)
+                    protectedFiles.add(path.basename(op.outputRef));
+                if (op.result?.stdoutRef)
+                    protectedFiles.add(path.basename(op.result.stdoutRef));
+                if (op.result?.stderrRef)
+                    protectedFiles.add(path.basename(op.result.stderrRef));
+            }
+        }
+        const files = fs.readdirSync(artifactsDir);
+        const deleted = [];
+        const retained = [];
+        const now = Date.now();
+        for (const file of files) {
+            const filePath = path.join(artifactsDir, file);
+            if (protectedFiles.has(file)) {
+                retained.push(filePath);
+                continue;
+            }
+            if (filter?.prefix && !file.startsWith(filter.prefix)) {
+                retained.push(filePath);
+                continue;
+            }
+            if (filter?.olderThanMs !== undefined) {
+                try {
+                    const stat = fs.statSync(filePath);
+                    if (now - stat.mtimeMs < filter.olderThanMs) {
+                        retained.push(filePath);
+                        continue;
+                    }
+                }
+                catch {
+                    retained.push(filePath);
+                    continue;
+                }
+            }
+            try {
+                fs.unlinkSync(filePath);
+                deleted.push(filePath);
+            }
+            catch {
+                retained.push(filePath);
+            }
+        }
+        return { deleted, retained };
+    }
     isClosed() {
         return this.lockFd === null;
     }
     close() {
+        for (const item of this.waitQueue) {
+            if (item.timer)
+                clearTimeout(item.timer);
+            item.reject(new Error(`Domain ${this.domainId} closed while waiting for resources`));
+        }
+        this.waitQueue = [];
         if (this.heartbeatInterval) {
             clearInterval(this.heartbeatInterval);
             this.heartbeatInterval = null;