@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/dist/round-state.js

@@ -0,0 +1,155 @@
+import { readFileSync, existsSync } from "node:fs";
+const phases = [
+    "RUNNING",
+    "VERIFYING",
+    "SETTLING",
+    "WAITING",
+    "BLOCKED",
+    "COMPLETE",
+];
+export function checkRound(state, { now = Date.now(), evidenceExists = existsSync } = {}) {
+    const errors = [];
+    const require = (ok, message) => {
+        if (!ok)
+            errors.push(message);
+    };
+    require(state && phases.includes(state.status), "运行标记缺失或无效");
+    require(typeof state?.batchId === "string" &&
+        state.batchId.length > 0, "原批次ID缺失");
+    require(Number.isFinite(Date.parse(state?.updatedAt)), "实际更新时间缺失");
+    const items = state?.items ?? [];
+    const scope = state?.scopeKinds ?? ["follow", "original", "reply"];
+    require(Array.isArray(scope) &&
+        scope.length > 0 &&
+        new Set(scope).size === scope.length &&
+        scope.every((k) => ["follow", "original", "reply"].includes(k)), "轮次职责范围无效");
+    if (state?.scopeKinds)
+        require(typeof state.scopeEvidenceRef === "string" &&
+            evidenceExists(state.scopeEvidenceRef), "职责分工缺原合同证据");
+    require(Array.isArray(items) &&
+        items.length === 3, "必须逐项核关注、原创、回复");
+    for (const kind of ["follow", "original", "reply"]) {
+        const matches = items.filter((i) => i.kind === kind);
+        require(matches.length === 1, `${kind}缺失或重复`);
+    }
+    const pending = [];
+    for (const item of items) {
+        require(["planned", "verified", "unknown"].every((k) => Number.isInteger(item[k]) && item[k] >= 0), `${item.kind}数量必须为非负整数`);
+        require(item.verified <= item.planned &&
+            item.unknown <=
+                item.planned - item.verified, `${item.kind}未知不得算成功`);
+        require(typeof item.actionable ===
+            "boolean", `${item.kind}当前可执行性缺失`);
+        require(item.verified === 0 ||
+            (Array.isArray(item.resultEvidence) &&
+                item.resultEvidence.length > 0 &&
+                item.resultEvidence.every(evidenceExists)), `${item.kind}完成量缺真实结果证据`);
+        if (Array.isArray(scope) &&
+            scope.includes(item.kind) &&
+            (item.verified < item.planned || item.unknown > 0))
+            pending.push(item);
+    }
+    const closing = ["WAITING", "BLOCKED", "COMPLETE"].includes(state?.status);
+    if (state?.status === "COMPLETE")
+        require(pending.length === 0, "目标有欠量或未知，禁止标完成");
+    if (state?.status === "WAITING" || state?.status === "BLOCKED") {
+        require(pending.length > 0, "无剩余项不得伪造等待或阻塞");
+        require(pending.every((i) => i.actionable === false), "仍有当前可执行项，禁止结束");
+        for (const item of pending) {
+            require(typeof item.reason === "string" &&
+                item.reason.trim().length > 0, `${item.kind}缺具体等待/阻塞原因`);
+            require(typeof item.resumeWhen === "string" &&
+                item.resumeWhen.trim().length > 0, `${item.kind}缺恢复条件`);
+            require(Array.isArray(item.blockEvidence) &&
+                item.blockEvidence.length > 0 &&
+                item.blockEvidence.every(evidenceExists), `${item.kind}缺存在的阻塞证据`);
+        }
+        require(state.stop?.independentActionsHandled ===
+            true, "未核独立可执行事项，禁止结束");
+        require(Number.isFinite(Date.parse(state.stop?.nextScheduledCheckAt)) &&
+            Date.parse(state.stop.nextScheduledCheckAt) >
+                now, "下一真实调度检查机会缺失或已到，必须接续");
+        if (state.status === "WAITING")
+            require(Number.isFinite(Date.parse(state.stop?.nextEligibleCheckAt)) &&
+                Date.parse(state.stop.nextEligibleCheckAt) >
+                    now, "等待条件已到或缺失，必须接续");
+        if (state.status === "BLOCKED")
+            require(new Set(state.stop?.attemptedPaths ?? []).size >=
+                2, "单一路径失败不足以结束：须核独立替代路径");
+    }
+    // Reply sourcing is work: an empty queue is never an exit permission.
+    if (state?.scopeKinds?.length === 1 &&
+        state.scopeKinds[0] === "reply" &&
+        ["WAITING", "BLOCKED"].includes(state.status)) {
+        const exit = state.stop?.replyExit;
+        const allowed = [
+            "platform-restriction",
+            "authentication-required",
+            "tool-unavailable",
+            "user-stop",
+            "outside-window",
+            "pending-results",
+        ];
+        require(exit &&
+            allowed.includes(exit.reason), "评论专责缺许可停止原因；候选不足、空队列或等待下次唤醒必须继续");
+        if (exit && allowed.includes(exit.reason)) {
+            require(typeof exit.evidenceRef === "string" &&
+                evidenceExists(exit.evidenceRef), "评论停止缺真实限制证据");
+            require(typeof exit.independentEvidenceRef === "string" &&
+                evidenceExists(exit.independentEvidenceRef), "评论停止缺独立可做项审计证据");
+            const age = now - Date.parse(exit.observedAt);
+            require(Number.isFinite(age) &&
+                age >= 0 &&
+                age <= 300000, "评论停止证据必须为最近5分钟实际观察");
+            const reply = items.find((item) => item.kind === "reply");
+            if (exit.reason === "pending-results")
+                require(reply &&
+                    reply.unknown > 0 &&
+                    reply.planned - reply.verified ===
+                        reply.unknown, "未提交欠量仍在；未知提交不能冻结新对象");
+            if (exit.reason === "outside-window") {
+                const shanghaiHour = (new Date(now).getUTCHours() + 8) % 24;
+                require(shanghaiHour <
+                    7, "仍在上海07至24点评论执行窗口，不能以时段截止结束");
+            }
+            if (exit.reason === "user-stop")
+                require(typeof exit.instructionEvidenceRef === "string" &&
+                    evidenceExists(exit.instructionEvidenceRef), "用户停止须有明确原指令证据");
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        mayEnd: closing && errors.length === 0,
+        status: state?.status,
+        scopeKinds: scope,
+        pending: pending.map((i) => ({
+            kind: i.kind,
+            remaining: i.planned - i.verified,
+            unknown: i.unknown,
+        })),
+        errors,
+    };
+}
+export function readRound(markdown) {
+    const match = markdown.match(/```x-round-state\s*\n([\s\S]*?)\n```/);
+    if (!match)
+        throw new Error("当前台账缺运行标记：默认视为未结束，须接续");
+    return JSON.parse(match[1]);
+}
+export function runRoundCLI() {
+    try {
+        const file = process.argv.slice(2).find((a) => !a.startsWith("--"));
+        if (!file)
+            throw new Error("用法：node scripts/x-round-state.mjs <原台账> [--check-end]");
+        const result = checkRound(readRound(readFileSync(file, "utf8")));
+        console.log(JSON.stringify(result));
+        process.exitCode =
+            result.valid && (!process.argv.includes("--check-end") || result.mayEnd)
+                ? 0
+                : 1;
+    }
+    catch (error) {
+        console.log(JSON.stringify({ valid: false, mayEnd: false, errors: [error.message] }));
+        process.exitCode = 1;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,30 @@
+import type { BoundaryRecord } from "./boundary.js";
+export declare class HarnessConflict extends Error {
+    code: string;
+    constructor(message: string);
+}
+export interface RoundSnapshot {
+    state: BoundaryRecord;
+    revision: string;
+    path: string;
+}
+export interface RoundStore {
+    path: string;
+    evidenceExists(path: string): boolean;
+    fingerprint(path: string): string;
+    processId: number | null;
+    ownerAlive(pid: unknown): boolean;
+    transaction(fn: (snapshot: RoundSnapshot) => BoundaryRecord | undefined | Promise<BoundaryRecord | undefined>): Promise<RoundSnapshot>;
+    load(): Promise<RoundSnapshot>;
+    save(snapshot: RoundSnapshot, state: BoundaryRecord): Promise<RoundSnapshot>;
+    withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+    recoverAbandonedLock(): Promise<{
+        recovered: boolean;
+        evidenceRef: string;
+    }>;
+    recordProof(proof: unknown): Promise<string>;
+}
+export declare function createFileRoundStore({ ledgerPath, proofDirectory, }: {
+    ledgerPath: string;
+    proofDirectory: string;
+}): RoundStore;

package/dist/store.js

@@ -0,0 +1,175 @@
+import { readFileSync, writeFileSync, openSync, closeSync, unlinkSync, renameSync, mkdirSync, statSync, existsSync, } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { readRound } from "./round-state.js";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+const block = /```x-round-state\s*\n([\s\S]*?)\n```/;
+export class HarnessConflict extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.code = "CONFLICT";
+    }
+}
+export function createFileRoundStore({ ledgerPath, proofDirectory, }) {
+    const path = resolve(ledgerPath);
+    const lockPath = join(dirname(path), ".x-harness.lock");
+    const proofDir = resolve(proofDirectory);
+    let held = false;
+    return {
+        path,
+        evidenceExists: existsSync,
+        fingerprint: (file) => hash(readFileSync(resolve(file))),
+        processId: typeof process !== "undefined" ? process.pid : null,
+        ownerAlive(ownerPid) {
+            if (typeof ownerPid !== "number" ||
+                !Number.isInteger(ownerPid) ||
+                ownerPid < 1)
+                return true;
+            if (typeof process === "undefined" || typeof process.kill !== "function")
+                return true;
+            try {
+                process.kill(ownerPid, 0);
+                return true;
+            }
+            catch (error) {
+                if (error.code === "ESRCH")
+                    return false;
+                throw error;
+            }
+        },
+        // Only bounded local state work belongs here. Browser I/O never holds this lock.
+        async transaction(fn) {
+            const start = Date.now();
+            while (true) {
+                let entered = false;
+                try {
+                    return await this.withLock(async () => {
+                        entered = true;
+                        const snapshot = await this.load();
+                        const state = await fn(snapshot);
+                        return state ? this.save(snapshot, state) : snapshot;
+                    });
+                }
+                catch (error) {
+                    if (entered ||
+                        error.code !== "CONFLICT" ||
+                        Date.now() - start >= 2000)
+                        throw error;
+                    await new Promise((resolve) => setTimeout(resolve, 10));
+                }
+            }
+        },
+        async load() {
+            const text = readFileSync(path, "utf8");
+            return { state: readRound(text), revision: hash(text), path };
+        },
+        async save(snapshot, state) {
+            if (!held)
+                throw new HarnessConflict("保存原台账必须持有账号锁");
+            const text = readFileSync(path, "utf8");
+            if (snapshot.revision !== hash(text))
+                throw new HarnessConflict("原台账已变化：重新定向读取，禁止覆盖");
+            if (readRound(text).batchId !== state.batchId)
+                throw new HarnessConflict("禁止替换原批次ID");
+            const next = text.replace(block, () => "```x-round-state\n" + JSON.stringify(state, null, 2) + "\n```");
+            const temp = `${path}.harness-${randomUUID()}.tmp`;
+            try {
+                writeFileSync(temp, next, {
+                    flag: "wx",
+                    mode: statSync(path).mode & 0o777,
+                });
+                // Other writers must honor the same lock; CAS additionally detects observed external edits.
+                if (hash(readFileSync(path, "utf8")) !== snapshot.revision)
+                    throw new HarnessConflict("原台账在结算中变化");
+                renameSync(temp, path);
+            }
+            finally {
+                if (existsSync(temp))
+                    unlinkSync(temp);
+            }
+            return { state, revision: hash(next), path };
+        },
+        async withLock(fn) {
+            if (held)
+                throw new HarnessConflict("账号操作禁止重入");
+            if (existsSync(`${lockPath}.recovery`))
+                throw new HarnessConflict("原锁恢复核验进行中");
+            let fd;
+            try {
+                fd = openSync(lockPath, "wx", 0o600);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new HarnessConflict("账号锁占用：不并发写、不自动偷锁");
+                throw error;
+            }
+            try {
+                writeFileSync(fd, JSON.stringify({
+                    pid: typeof process !== "undefined" ? process.pid : null,
+                    acquiredAt: new Date().toISOString(),
+                    ledgerPath: path,
+                }));
+                held = true;
+                return await fn();
+            }
+            finally {
+                held = false;
+                closeSync(fd);
+                unlinkSync(lockPath);
+            }
+        },
+        async recoverAbandonedLock() {
+            if (held)
+                throw new HarnessConflict("不能恢复当前正在持有的锁");
+            const recovery = `${lockPath}.recovery`;
+            let fd;
+            try {
+                fd = openSync(recovery, "wx", 0o600);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new HarnessConflict("另一执行器正在核验原锁");
+                throw error;
+            }
+            try {
+                const original = readFileSync(lockPath, "utf8"), owner = JSON.parse(original);
+                if (!Number.isInteger(owner.pid) || owner.pid < 1)
+                    throw new HarnessConflict("锁owner缺失，不能自动移除");
+                if (typeof process === "undefined" ||
+                    typeof process.kill !== "function")
+                    throw new HarnessConflict("当前宿主无进程核验能力，禁止恢复原锁");
+                try {
+                    process.kill(owner.pid, 0);
+                    throw new HarnessConflict("原进程仍在：禁止抢占账号锁");
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        throw error;
+                }
+                const proof = await this.recordProof({
+                    observedAt: new Date().toISOString(),
+                    recovery: "owner-process-confirmed-exited",
+                    owner,
+                });
+                if (readFileSync(lockPath, "utf8") !== original)
+                    throw new HarnessConflict("原锁已变化，禁止移除");
+                unlinkSync(lockPath);
+                return { recovered: true, evidenceRef: proof };
+            }
+            finally {
+                closeSync(fd);
+                unlinkSync(recovery);
+            }
+        },
+        async recordProof(proof) {
+            mkdirSync(proofDir, { recursive: true });
+            const file = join(proofDir, `${randomUUID()}.json`);
+            writeFileSync(file, JSON.stringify(proof, null, 2), {
+                flag: "wx",
+                mode: 0o600,
+            });
+            return file;
+        },
+    };
+}