@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/growth-batch.js

@@ -0,0 +1,190 @@
+import { followWindows, same } from "./growth-constants.js";
+export class FollowBatch {
+    #prepareActionsForCall;
+    #store;
+    #scope;
+    #stamp;
+    #clock;
+    #evidenceExists;
+    #executor;
+    #parallelRound;
+    #round;
+    constructor(dependencies) {
+        this.followBatch = this.followBatch.bind(this);
+        const { prepareActionsForCall, store, scope, stamp, clock, evidenceExists, executor, parallelRound, round, } = dependencies;
+        this.#prepareActionsForCall = prepareActionsForCall;
+        this.#store = store;
+        this.#scope = scope;
+        this.#stamp = stamp;
+        this.#clock = clock;
+        this.#evidenceExists = evidenceExists;
+        this.#executor = executor;
+        this.#parallelRound = parallelRound;
+        this.#round = round;
+    }
+    async followBatch({ taskId, handles, preparedActions } = {}) {
+        const executor = this.#executor;
+        if (!Array.isArray(handles) ||
+            handles.length < 5 ||
+            handles.length > 10 ||
+            handles.some((h) => !/^[A-Za-z0-9_]{1,15}$/.test(h)) ||
+            new Set(handles.map((h) => h.toLowerCase())).size !== handles.length)
+            throw new Error("正常关注子批需5～10位不同的已准备对象");
+        if (preparedActions?.some((a) => a.kind !== "follow" ||
+            !handles.some((h) => same(h, a.handle))))
+            throw new Error("batch-action-target-mismatch");
+        await this.#prepareActionsForCall(taskId, preparedActions);
+        let batchId, resumedBatch = false;
+        const original = await this.#store.transaction(async (snapshot) => {
+            if (!this.#scope(snapshot.state).includes("follow"))
+                throw new Error("kind-outside-round-scope");
+            if (snapshot.state.batchId !== taskId ||
+                handles.some((h) => !snapshot.state.actions?.some((a) => a.kind === "follow" && same(a.handle, h))))
+                throw new Error("子批名单必须归原任务队列");
+            const next = structuredClone(snapshot.state);
+            next.followBatches ??= [];
+            const previous = next.followBatches.findLast((b) => b.status !== "SETTLED" &&
+                b.handles.length === handles.length &&
+                b.handles.every((h, i) => same(h, handles[i])));
+            resumedBatch = Boolean(previous);
+            batchId = previous?.id ?? `${taskId}-FOLLOW-${this.#stamp()}`;
+            if (previous)
+                Object.assign(previous, {
+                    status: "RUNNING",
+                    lastResumedAt: this.#stamp(),
+                });
+            else
+                next.followBatches.push({
+                    id: batchId,
+                    handles,
+                    planned: handles.length,
+                    startedAt: this.#stamp(),
+                    status: "RUNNING",
+                });
+            next.updatedAt = this.#stamp();
+            return next;
+        });
+        const preparedCount = original.state.actions.filter((a) => a.kind === "follow" &&
+            a.status === "prepared" &&
+            handles.some((h) => same(h, a.handle))).length;
+        let eligibleAt = this.#clock();
+        const previousGroup = original.state.execution?.followGroup;
+        const lastAttempt = (original.state.attempts ?? [])
+            .filter((a) => a.kind === "follow")
+            .sort((a, b) => Date.parse(a.at) - Date.parse(b.at))
+            .at(-1);
+        const lastAction = original.state.actions.find((a) => a.id === lastAttempt?.actionId);
+        const sameBatchRecovery = resumedBatch &&
+            lastAction?.status === "verified" &&
+            this.#evidenceExists(lastAction.resultEvidence) &&
+            handles.some((h) => same(h, lastAction.handle));
+        if (preparedCount && previousGroup?.attempts && !sameBatchRecovery)
+            eligibleAt = Math.max(eligibleAt, Date.parse(previousGroup.lastAt) + 180000);
+        for (const [duration, limit] of followWindows) {
+            const recent = (original.state.attempts ?? [])
+                .filter((a) => a.kind === "follow" && Date.parse(a.at) > this.#clock() - duration)
+                .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+            if (preparedCount > limit - recent.length)
+                eligibleAt = Math.max(eligibleAt, Date.parse(recent[recent.length - limit + preparedCount - 1].at) +
+                    duration);
+        }
+        if (eligibleAt > this.#clock()) {
+            const resumeAt = new Date(eligibleAt).toISOString();
+            await this.#store.transaction((snapshot) => {
+                const next = structuredClone(snapshot.state);
+                Object.assign(next.followBatches.find((b) => b.id === batchId), { status: "WAITING", remaining: preparedCount, resumeAt });
+                next.updatedAt = this.#stamp();
+                return next;
+            });
+            return {
+                taskId,
+                batchId,
+                planned: handles.length,
+                attempted: 0,
+                verifiedThisCall: 0,
+                unknownInBatch: original.state.actions.filter((a) => handles.some((h) => same(h, a.handle)) &&
+                    ["unknown", "intent"].includes(a.status)).length,
+                remaining: preparedCount,
+                mayEnd: false,
+                decision: [
+                    {
+                        kind: "follow",
+                        status: "waiting",
+                        reason: "normal-batch-capacity-or-cooldown",
+                        resumeAt,
+                    },
+                ],
+                evidenceRef: this.#store.path,
+            };
+        }
+        let result;
+        const exceptional = [];
+        for (const handle of handles) {
+            // A resumed batch submits only its remaining prepared members. Recovery
+            // stays in the read-only API; a frozen member must not disturb that path.
+            if (!original.state.actions.some((a) => a.kind === "follow" &&
+                same(a.handle, handle) &&
+                a.status === "prepared"))
+                continue;
+            result = await (executor ? this.#parallelRound : this.#round)({
+                taskId,
+                requestedKind: "follow",
+                selector: (a) => a.kind === "follow" && same(a.handle, handle),
+            });
+            const relevant = (result.decision ?? []).filter((d) => d.kind === "follow" ||
+                ["harness-boundary-error", "original-ledger-conflict"].includes(d.reason) ||
+                original.state.actions.some((a) => a.id === d.actionId && a.kind === "follow"));
+            exceptional.push(...relevant);
+            // A new unconfirmed submission is a diagnostic boundary, not permission
+            // to consume the rest of the batch on the same failing write path.
+            if (relevant.length)
+                break;
+        }
+        const after = await this.#store.load();
+        const summary = summarizeFollowBatch(taskId, batchId, handles, after, original, result, exceptional, this.#store.path);
+        await this.#store.transaction((snapshot) => {
+            const next = structuredClone(snapshot.state), batch = next.followBatches.find((b) => b.id === batchId);
+            Object.assign(batch, {
+                attempted: (batch.attempted ?? 0) + summary.attempted,
+                verifiedTotal: (batch.verifiedTotal ?? 0) + summary.verifiedThisCall,
+                verifiedThisCall: summary.verifiedThisCall,
+                unknown: summary.unknownInBatch,
+                remaining: summary.remaining,
+                finishedAt: this.#stamp(),
+                status: summary.remaining || summary.unknownInBatch ? "PARTIAL" : "SETTLED",
+            });
+            next.updatedAt = this.#stamp();
+            return next;
+        });
+        return summary;
+    }
+}
+export function createFollowBatch(...args) {
+    return new FollowBatch(...args);
+}
+function summarizeFollowBatch(taskId, batchId, handles, after, original, result, exceptional, evidenceRef) {
+    return {
+        taskId,
+        batchId,
+        planned: handles.length,
+        attempted: (after.state.attempts ?? [])
+            .slice(original.state.attempts?.length ?? 0)
+            .filter((a) => a.kind === "follow" &&
+            handles.some((h) => same(after.state.actions.find((x) => x.id === a.actionId)?.handle, h))).length,
+        verifiedThisCall: after.state.actions.filter((a) => a.kind === "follow" &&
+            a.status === "verified" &&
+            handles.some((h) => same(h, a.handle)) &&
+            original.state.actions.find((old) => old.id === a.id)?.status !==
+                "verified").length,
+        unknownInBatch: after.state.actions.filter((a) => a.kind === "follow" &&
+            handles.some((h) => same(a.handle, h)) &&
+            ["unknown", "intent"].includes(a.status)).length,
+        remaining: after.state.actions.filter((a) => a.kind === "follow" &&
+            handles.some((h) => same(a.handle, h)) &&
+            a.status === "prepared").length,
+        actual: result?.actual,
+        decision: exceptional,
+        mayEnd: result?.mayEnd ?? false,
+        evidenceRef,
+    };
+}

package/dist/growth-constants.d.ts

@@ -0,0 +1,5 @@
+import type { BoundaryRecord } from "./boundary.js";
+export declare const kinds: string[];
+export declare const followWindows: number[][];
+export declare const operations: BoundaryRecord;
+export declare const same: (a: any, b: any) => boolean;

package/dist/growth-constants.js

@@ -0,0 +1,13 @@
+export const kinds = ["follow", "original", "reply"];
+export const followWindows = [
+    [600000, 20],
+    [3600000, 100],
+];
+export const operations = {
+    follow: "submitFollow",
+    original: "submitPost",
+    reply: "submitReply",
+};
+export const same = (a, b) => typeof a === "string" &&
+    typeof b === "string" &&
+    a.toLowerCase() === b.toLowerCase();

package/dist/growth-dependencies.d.ts

@@ -0,0 +1,33 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { RoundStore } from "./store.js";
+/** Explicit instance dependencies; each owner accepts only its declared subset. */
+export interface GrowthDependencies {
+    platform: BoundaryRecord;
+    store: RoundStore;
+    clock: () => number;
+    executor: BoundaryRecord | undefined;
+    stamp: () => string;
+    evidenceExists: (path: string) => boolean;
+    runtimeId: string;
+    session: {
+        claim: any;
+        running: boolean;
+    };
+    authorizedWindow: (state: any, kind: string) => boolean;
+    scope: (state: any) => any;
+    project: (state: any) => any;
+    load: (taskId: any) => Promise<any>;
+    save: (snapshot: any, state: any) => Promise<any>;
+    result: (snapshot: any, needs?: any) => any;
+    capability: (operation: any, input?: any) => any;
+    waitBudget: (state: any) => any;
+    guardInput: (state: any, action: any, independentExecution?: any) => any;
+    settleProof: (snapshot: any, action: any, observation: any, { preserveStatus }?: any) => Promise<any>;
+    execute: (snapshot: any, action: any) => Promise<any>;
+    parallelRound: ({ taskId, decision, selector, requestedKind, maxActions, }?: any) => Promise<any>;
+    round: ({ taskId, decision, selector, requestedKind }?: any) => Promise<any>;
+    publishIndependent: ({ taskId, draftPath, preparedAction, independentExecution, }: any) => Promise<any>;
+    releaseSession: (taskId?: any) => Promise<any>;
+    readTask: (operation: any, { mode, ...input }?: any) => Promise<any>;
+    prepareActionsForCall: (taskId: string, actions?: any[]) => Promise<void>;
+}

package/dist/growth-dependencies.js

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

package/dist/growth-execution.d.ts

@@ -0,0 +1,17 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { RoundSnapshot } from "./store.js";
+interface ExecutionStep {
+    snapshot: RoundSnapshot;
+    need: BoundaryRecord | null;
+}
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare class GrowthExecution {
+    #private;
+    execute: (snapshot: any, action: any) => Promise<ExecutionStep>;
+    constructor(dependencies: Pick<GrowthDependencies, "capability" | "platform" | "settleProof" | "clock" | "save" | "guardInput" | "waitBudget" | "authorizedWindow" | "stamp" | "store" | "executor" | "session">);
+    private checkExecutionIdentity;
+    private admitAction;
+    private handleExecute;
+}
+export declare function createGrowthExecution(...args: ConstructorParameters<typeof GrowthExecution>): GrowthExecution;
+export {};

package/dist/growth-execution.js

@@ -0,0 +1,346 @@
+import { operations, same } from "./growth-constants.js";
+export class GrowthExecution {
+    #capability;
+    #platform;
+    #settleProof;
+    #clock;
+    #save;
+    #guardInput;
+    #waitBudget;
+    #authorizedWindow;
+    #stamp;
+    #store;
+    #executor;
+    #session;
+    execute;
+    constructor(dependencies) {
+        const { capability, platform, settleProof, clock, save, guardInput, waitBudget, authorizedWindow, stamp, store, executor, session, } = dependencies;
+        this.#capability = capability;
+        this.#platform = platform;
+        this.#settleProof = settleProof;
+        this.#clock = clock;
+        this.#save = save;
+        this.#guardInput = guardInput;
+        this.#waitBudget = waitBudget;
+        this.#authorizedWindow = authorizedWindow;
+        this.#stamp = stamp;
+        this.#store = store;
+        this.#executor = executor;
+        this.#session = session;
+        this.execute = this.handleExecute.bind(this);
+    }
+    async checkExecutionIdentity(snapshot, action) {
+        const state = snapshot.state;
+        let own;
+        try {
+            own = await this.#platform.readAccount();
+        }
+        catch (error) {
+            return {
+                snapshot,
+                need: {
+                    status: "needsDecision",
+                    actionId: action.id,
+                    reason: "account-read-failed",
+                    error: error.message.slice(0, 240),
+                },
+            };
+        }
+        if (own.needsStateCheck ||
+            own.alerts?.length ||
+            !same(own.accountHandle, state.accountHandle))
+            return {
+                snapshot,
+                need: {
+                    status: "needsDecision",
+                    actionId: action.id,
+                    reason: "fresh-account-unconfirmed",
+                },
+            };
+        return null;
+    }
+    async admitAction(snapshot, action) {
+        const state = snapshot.state;
+        const item = state.items.find((i) => i.kind === action.kind);
+        if (!item.actionable)
+            return {
+                snapshot,
+                need: {
+                    status: "needsDecision",
+                    actionId: action.id,
+                    reason: item.reason ?? "original-kind-not-actionable",
+                },
+            };
+        const inputError = this.#guardInput(state, action);
+        if (inputError)
+            return {
+                snapshot,
+                need: {
+                    status: "needsDecision",
+                    actionId: action.id,
+                    reason: inputError,
+                },
+            };
+        const identity = await this.checkExecutionIdentity(snapshot, action);
+        if (identity)
+            return identity;
+        if (action.kind === "follow") {
+            const budget = this.#waitBudget(state);
+            if (budget)
+                return { snapshot, need: { ...budget, actionId: action.id } };
+            let value;
+            try {
+                value = await this.#platform.readPerson(action);
+            }
+            catch (error) {
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "person-read-failed",
+                        error: error.message.slice(0, 240),
+                    },
+                };
+            }
+            if (value.needsStateCheck ||
+                value.alerts?.length ||
+                value.relationship === "unknown" ||
+                !same(value.accountHandle, state.accountHandle))
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "fresh-person-unconfirmed",
+                    },
+                };
+            if (value.blue === false)
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "fresh-blue-qualification-contradicts-review",
+                    },
+                };
+            if (value.relationship === "following") {
+                const next = structuredClone(state);
+                next.actions.find((a) => a.id === action.id).status =
+                    "preexisting";
+                return { snapshot: await this.#save(snapshot, next), need: null };
+            }
+        }
+        else {
+            const hour = Number(new Intl.DateTimeFormat("en-GB", {
+                timeZone: "Asia/Shanghai",
+                hour: "2-digit",
+                hourCycle: "h23",
+            }).format(this.#clock()));
+            if ((hour < 7 || hour >= (action.kind === "reply" ? 24 : 22)) &&
+                !this.#authorizedWindow(state, action.kind))
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "outside-contract-write-window",
+                    },
+                };
+        }
+        let beforeIds = [];
+        if (action.kind !== "follow") {
+            let baseline;
+            try {
+                baseline = await this.#platform.findSubmission({
+                    ...action,
+                    intentAt: this.#stamp(),
+                });
+            }
+            catch (error) {
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "publication-baseline-read-failed",
+                        error: error.message.slice(0, 240),
+                    },
+                };
+            }
+            if (baseline.needsStateCheck || baseline.alerts?.length)
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "publication-baseline-unconfirmed",
+                    },
+                };
+            beforeIds = (baseline.posts ?? []).map((p) => p.id).filter(Boolean);
+        }
+        return { beforeIds };
+    }
+    async handleExecute(snapshot, action) {
+        const executor = this.#executor;
+        const recovering = ["intent", "unknown"].includes(action.status);
+        const caps = this.#capability(recovering ? "read" : operations[action.kind], action);
+        if (!caps.covered)
+            return {
+                snapshot,
+                need: { status: "needsCapability", actionId: action.id, ...caps },
+            };
+        // Recovery is read-only even outside the write window. Never retry an intent.
+        if (recovering) {
+            let observation;
+            try {
+                observation = await this.#platform.findSubmission(action);
+            }
+            catch (error) {
+                observation = {
+                    verified: false,
+                    missing: ["dedup-read-failed"],
+                    error: error.message.slice(0, 240),
+                };
+            }
+            snapshot = await this.#settleProof(snapshot, action, observation);
+            return {
+                snapshot,
+                need: observation.verified
+                    ? null
+                    : {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "submission-unknown-do-not-resubmit",
+                        accountAlert: Boolean(observation.alerts?.length),
+                    },
+            };
+        }
+        if (snapshot.state.items
+            .find((i) => i.kind === action.kind)
+            .reason?.startsWith("harness:") &&
+            Date.parse(snapshot.state.items.find((i) => i.kind === action.kind).resumeAt) <= this.#clock()) {
+            const next = structuredClone(snapshot.state), pending = next.items.find((i) => i.kind === action.kind);
+            pending.actionable = true;
+            delete pending.reason;
+            delete pending.resumeAt;
+            delete pending.resumeWhen;
+            delete pending.blockEvidence;
+            next.status = "RUNNING";
+            snapshot = await this.#save(snapshot, next);
+        }
+        const admission = await this.admitAction(snapshot, action);
+        if ("snapshot" in admission)
+            return admission;
+        const { beforeIds } = admission;
+        const state = snapshot.state;
+        // Persist intent BEFORE any externally visible submission. Even a failed attempt consumes budget.
+        const next = structuredClone(state);
+        const entry = next.actions.find((a) => a.id === action.id);
+        entry.status = "intent";
+        entry.intentAt = this.#stamp();
+        entry.beforeIds = beforeIds;
+        next.items.find((i) => i.kind === action.kind).unknown += 1;
+        next.attempts ??= [];
+        next.attempts.push({
+            actionId: action.id,
+            kind: action.kind,
+            at: entry.intentAt,
+        });
+        if (action.kind === "follow") {
+            next.execution ??= {};
+            const old = next.execution.followGroup;
+            next.execution.followGroup = {
+                attempts: old?.attempts < 10 && this.#clock() < Date.parse(old.lastAt) + 180000
+                    ? old.attempts + 1
+                    : 1,
+                lastAt: entry.intentAt,
+            };
+        }
+        snapshot = await this.#save(snapshot, next);
+        let observation, submissionMayHaveStarted = false;
+        try {
+            await this.#platform[operations[action.kind]]({
+                ...entry,
+                beforeSubmit: async () => {
+                    const latest = await this.#store.load();
+                    if (executor) {
+                        const current = latest.state.actions.find((a) => a.id === entry.id);
+                        if (latest.state.batchId !== snapshot.state.batchId ||
+                            current?.claim?.token !== this.#session.claim.token ||
+                            JSON.stringify(current) !==
+                                JSON.stringify(snapshot.state.actions.find((a) => a.id === entry.id)))
+                            throw new Error("提交前本动作或claim变化");
+                    }
+                    else if (latest.revision !== snapshot.revision)
+                        throw new Error("提交前原台账变化，保留intent并重核执行权");
+                    const inputError = this.#guardInput(latest.state, latest.state.actions.find((a) => a.id === entry.id));
+                    if (inputError)
+                        throw new Error(inputError);
+                    const hour = Number(new Intl.DateTimeFormat("en-GB", {
+                        timeZone: "Asia/Shanghai",
+                        hour: "2-digit",
+                        hourCycle: "h23",
+                    }).format(this.#clock()));
+                    if ((hour < 7 || hour >= (action.kind === "reply" ? 24 : 22)) &&
+                        !this.#authorizedWindow(latest.state, action.kind))
+                        throw new Error("实际提交时已越过运营窗口");
+                    if (action.kind === "follow") {
+                        const check = structuredClone(latest.state);
+                        check.attempts = check.attempts.filter((a) => a.actionId !== entry.id);
+                        if (check.execution.followGroup)
+                            check.execution.followGroup.attempts -= 1;
+                        if (this.#waitBudget(check))
+                            throw new Error("实际提交前关注预算不再可用");
+                    }
+                    submissionMayHaveStarted = true;
+                },
+            });
+            observation = await this.#platform.findSubmission(entry);
+        }
+        catch (error) {
+            if (!submissionMayHaveStarted) {
+                const proof = await this.#store.recordProof({
+                    capturedAt: this.#stamp(),
+                    submissionStarted: false,
+                    error: error.message.slice(0, 240),
+                });
+                const unsubmitted = structuredClone(snapshot.state), target = unsubmitted.actions.find((a) => a.id === entry.id);
+                target.status = "prepared";
+                target.preparationEvidence = proof;
+                unsubmitted.items.find((i) => i.kind === action.kind).unknown -= 1;
+                snapshot = await this.#save(snapshot, unsubmitted);
+                return {
+                    snapshot,
+                    need: {
+                        status: "needsDecision",
+                        actionId: action.id,
+                        reason: "pre-submit-preparation-failed",
+                        evidenceRef: proof,
+                    },
+                };
+            }
+            // A transport error does not distinguish a rejected write from a successful write.
+            observation = {
+                verified: false,
+                missing: ["submission-or-verification-failed"],
+                error: error.message.slice(0, 240),
+            };
+        }
+        snapshot = await this.#settleProof(snapshot, entry, observation);
+        return {
+            snapshot,
+            need: observation.verified
+                ? null
+                : {
+                    status: "needsDecision",
+                    actionId: action.id,
+                    reason: "submission-unknown-do-not-resubmit",
+                    accountAlert: Boolean(observation.alerts?.length),
+                },
+        };
+    }
+}
+export function createGrowthExecution(...args) {
+    return new GrowthExecution(...args);
+}

package/dist/growth-parallel.d.ts

@@ -0,0 +1,8 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare class ParallelRound {
+    #private;
+    parallelRound: ({ taskId, decision, selector, requestedKind, maxActions, }?: any) => Promise<any>;
+    constructor(dependencies: Pick<GrowthDependencies, "load" | "scope" | "result" | "store" | "executor" | "runtimeId" | "stamp" | "evidenceExists" | "execute" | "clock" | "releaseSession" | "session">);
+    private handleParallelRound;
+}
+export declare function createParallelRound(...args: ConstructorParameters<typeof ParallelRound>): ParallelRound;