@nextclaw/x-harness 0.1.0 → 0.1.1

package/dist/growth-recovery.js

@@ -0,0 +1,158 @@
+import { xURL } from "./platform-rules.js";
+import { same } from "./growth-constants.js";
+export function createGrowthRecovery(dependencies) {
+    const { capability, platform, load, evidenceExists, clock, store, settleProof, executor, parallelRound, round, readTask, } = dependencies;
+    return {
+        async verifyPublishedPost({ taskId, draftPath, publicURL, evidenceRef, sourceLink, }) {
+            // Read-only recovery of a single submitted original; never opens a composer.
+            const caps = capability("read");
+            if (!caps.covered || typeof platform.readPost !== "function")
+                return {
+                    status: "needsCapability",
+                    missing: ["platform.readPost", ...caps.missing],
+                };
+            const initial = await load(taskId);
+            const action = initial.state.actions.find((a) => a.kind === "original" && a.draftPath === draftPath);
+            if (!action ||
+                !["intent", "unknown"].includes(action.status) ||
+                !evidenceExists(evidenceRef))
+                throw new Error("submitted-original-and-public-proof-required");
+            const url = xURL(publicURL), postId = url.pathname.match(/\/status\/(\d+)$/)?.[1];
+            if (!postId ||
+                url.pathname.toLowerCase() !==
+                    `/${action.accountHandle}/status/${postId}`.toLowerCase())
+                throw new Error("public-account-mismatch");
+            const observation = await platform.readPost({
+                postId,
+                url: publicURL,
+                evidenceRef,
+            });
+            const trailing = action.text.match(/\n\n(https:\/\/\S+)$/);
+            const matches = (observation.posts ?? []).filter((p) => {
+                const exact = p.body === action.text;
+                const card = trailing &&
+                    sourceLink &&
+                    evidenceExists(sourceLink.evidenceRef) &&
+                    sourceLink.resolvedURL === trailing[1] &&
+                    p.links?.includes(sourceLink.href) &&
+                    p.body === action.text.slice(0, -trailing[0].length);
+                let renderedSource = false;
+                if (trailing &&
+                    sourceLink?.renderedText &&
+                    evidenceExists(sourceLink.evidenceRef) &&
+                    sourceLink.resolvedURL === trailing[1] &&
+                    p.links?.includes(sourceLink.href)) {
+                    try {
+                        renderedSource =
+                            new URL(sourceLink.renderedText.replace(/\s/g, "")).href ===
+                                sourceLink.resolvedURL &&
+                                p.body?.endsWith(sourceLink.renderedText) &&
+                                p.body.slice(0, -sourceLink.renderedText.length).trimEnd() ===
+                                    action.text.slice(0, -trailing[0].length);
+                    }
+                    catch {
+                        /* Invalid rendered URL cannot verify publication. */
+                    }
+                }
+                return (p.id === postId &&
+                    same(p.author, action.accountHandle) &&
+                    (exact || card || renderedSource) &&
+                    !p.needsExpansion &&
+                    !(action.beforeIds ?? []).includes(p.id) &&
+                    Date.parse(p.datetime) >= Date.parse(action.intentAt) &&
+                    Date.parse(p.datetime) <= clock() + 5000 &&
+                    (!action.assets?.length ||
+                        action.assets.every((a) => p.images?.some((i) => i.alt === a.alt))));
+            });
+            Object.assign(observation, {
+                verified: !observation.needsStateCheck &&
+                    !observation.alerts?.length &&
+                    matches.length === 1,
+                publicId: matches.length === 1 ? postId : null,
+                sourceLink,
+            });
+            return store.withLock(async () => {
+                const latest = await load(taskId), target = latest.state.actions.find((a) => a.id === action.id);
+                if (!["intent", "unknown"].includes(target?.status) ||
+                    target.intentAt !== action.intentAt ||
+                    target.text !== action.text)
+                    throw new Error("recovery-action-changed");
+                await settleProof(latest, target, observation, {
+                    preserveStatus: true,
+                });
+                return {
+                    status: observation.verified ? "verified" : "unknown",
+                    publicId: observation.publicId,
+                    taskId,
+                    actionId: action.id,
+                    mayEnd: false,
+                };
+            });
+        },
+        verifySubmission: async ({ taskId, actionId }) => {
+            const snapshot = await load(taskId), action = snapshot.state.actions?.find((a) => a.id === actionId);
+            if (!action || !["intent", "unknown"].includes(action.status))
+                return {
+                    status: "needsDecision",
+                    reason: "verification-requires-original-unknown-or-intent",
+                    mayEnd: false,
+                };
+            return (executor ? parallelRound : round)({
+                taskId,
+                requestedKind: action.kind,
+                selector: (a) => a.id === actionId,
+            });
+        },
+        verifyFollow: async (target) => {
+            const mode = target.mode ?? "receipt";
+            if (!["receipt", "decision"].includes(mode))
+                throw new Error("关注核验模式须为receipt/decision");
+            const caps = platform.preflight({ operation: "read" });
+            if (!caps.covered)
+                return {
+                    handle: target.handle,
+                    verified: false,
+                    status: "needsCapability",
+                    ...caps,
+                };
+            if (!target.url || !target.evidenceRef) {
+                const original = (await store.load()).state.actions?.find((a) => a.kind === "follow" && same(a.handle, target.handle));
+                if (!original)
+                    return {
+                        handle: target.handle,
+                        verified: false,
+                        status: "needsDecision",
+                        reason: "original-person-observation-required",
+                    };
+                target = original;
+            }
+            const value = await readTask("readPerson", {
+                ...target,
+                mode: "decision",
+            });
+            return {
+                handle: target.handle,
+                status: value.status,
+                fresh: value.fresh,
+                verified: value.status === "observed" &&
+                    !value.needsStateCheck &&
+                    !value.alerts?.length &&
+                    value.relationship === "following" &&
+                    (!target.accountHandle ||
+                        same(value.accountHandle, target.accountHandle)),
+                ...(value.evidenceRef ? { evidenceRef: value.evidenceRef } : {}),
+                ...(value.missing?.length ? { missing: value.missing } : {}),
+                ...(value.diagnostic
+                    ? {
+                        diagnostic: {
+                            operation: value.diagnostic.operation,
+                            category: value.diagnostic.category,
+                            code: value.diagnostic.code,
+                        },
+                    }
+                    : {}),
+                ...(mode === "decision" ? { observation: value } : {}),
+            };
+        },
+    };
+}

package/dist/growth-state.d.ts

@@ -0,0 +1,8 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createGrowthState(dependencies: Pick<GrowthDependencies, "store" | "project" | "clock" | "evidenceExists" | "stamp" | "executor" | "waitBudget" | "platform" | "runtimeId" | "session">): {
+    load: (taskId: any) => Promise<any>;
+    save: (snapshot: any, state: any) => Promise<any>;
+    result: (snapshot: any, needs?: any) => any;
+    settleProof: (snapshot: any, action: any, observation: any, { preserveStatus }?: any) => Promise<any>;
+    releaseSession: (taskId?: any) => Promise<any>;
+};

package/dist/growth-state.js

@@ -0,0 +1,183 @@
+import { checkRound } from "./round-state.js";
+import { kinds } from "./growth-constants.js";
+export function createGrowthState(dependencies) {
+    const { store, project, clock, evidenceExists, stamp, executor, waitBudget, platform, runtimeId, session, } = dependencies;
+    async function load(taskId) {
+        const snapshot = await store.load();
+        if (snapshot.state.batchId !== taskId)
+            throw new Error("任务ID不是原台账当前批次");
+        // Expired WAITING is actionable, not a malformed ledger. Validate structure separately from stopping.
+        const gate = checkRound({ ...project(snapshot.state), status: "RUNNING" }, { now: clock(), evidenceExists });
+        if (!gate.valid)
+            throw new Error(`原轮次标记无效：${gate.errors.join("；")}`);
+        const actions = snapshot.state.actions ?? [];
+        if (new Set(actions.map((a) => a.id)).size !== actions.length)
+            throw new Error("原队列动作ID重复");
+        for (const a of actions) {
+            if (!a.id ||
+                !kinds.includes(a.kind) ||
+                ![
+                    "prepared",
+                    "intent",
+                    "unknown",
+                    "verified",
+                    "preexisting",
+                    "skipped",
+                ].includes(a.status))
+                throw new Error("原队列动作结构无效");
+        }
+        return snapshot;
+    }
+    async function save(snapshot, state) {
+        state.updatedAt = stamp();
+        if (!executor)
+            return store.save(snapshot, state);
+        // Batch metadata still uses a short withLock transaction; it never contains browser I/O.
+        if (!session.claim)
+            return store.save(snapshot, state);
+        return store.transaction((latest) => {
+            const next = structuredClone(latest.state), before = snapshot.state.actions.find((a) => a.id === session.claim.actionId);
+            const entry = next.actions.find((a) => a.id === session.claim.actionId), after = state.actions.find((a) => a.id === session.claim.actionId);
+            if (next.batchId !== snapshot.state.batchId ||
+                entry?.claim?.token !== session.claim.token ||
+                JSON.stringify({ ...entry, claim: undefined }) !==
+                    JSON.stringify({ ...before, claim: undefined }))
+                throw new Error("action-claim-or-version-conflict");
+            const oldItem = snapshot.state.items.find((i) => i.kind === entry.kind), newItem = state.items.find((i) => i.kind === entry.kind);
+            const item = next.items.find((i) => i.kind === entry.kind);
+            const reservation = before.status === "prepared" && after.status === "intent";
+            if (reservation) {
+                if (!item.actionable || item.verified + item.unknown >= item.planned)
+                    throw new Error("shared-target-capacity-exhausted");
+                if (entry.kind === "follow" && waitBudget(next))
+                    throw new Error("shared-follow-budget-exhausted");
+            }
+            if (after.status === "verified" &&
+                entry.kind !== "follow" &&
+                next.actions.some((a) => a.id !== entry.id &&
+                    a.status === "verified" &&
+                    a.publicId === after.publicId))
+                throw new Error("同一公开结果不能重复结算");
+            Object.assign(entry, after, { claim: entry.claim });
+            item.verified += newItem.verified - oldItem.verified;
+            item.unknown += newItem.unknown - oldItem.unknown;
+            if (item.unknown < 0 || item.verified + item.unknown > item.planned)
+                throw new Error("并行结算越界");
+            item.resultEvidence = [
+                ...new Set([
+                    ...(item.resultEvidence ?? []),
+                    ...(newItem.resultEvidence ?? []),
+                ]),
+            ];
+            for (const key of [
+                "actionable",
+                "reason",
+                "resumeAt",
+                "resumeWhen",
+                "blockEvidence",
+            ]) {
+                if (JSON.stringify(oldItem[key]) !== JSON.stringify(newItem[key])) {
+                    if (key in newItem)
+                        item[key] = newItem[key];
+                    else
+                        delete item[key];
+                }
+            }
+            if (reservation) {
+                const attempt = state.attempts.at(-1);
+                next.attempts ??= [];
+                next.attempts.push(attempt);
+                if (entry.kind === "follow") {
+                    next.execution ??= {};
+                    const old = next.execution.followGroup;
+                    next.execution.followGroup = {
+                        attempts: old?.attempts < 10 && clock() < Date.parse(old.lastAt) + 180000
+                            ? old.attempts + 1
+                            : 1,
+                        lastAt: attempt.at,
+                    };
+                }
+            }
+            next.status = "RUNNING";
+            next.updatedAt = stamp();
+            return next;
+        });
+    }
+    function result(snapshot, needs = []) {
+        const gate = checkRound(project(snapshot.state), {
+            now: clock(),
+            evidenceExists,
+        });
+        return {
+            status: gate.mayEnd
+                ? gate.status === "COMPLETE"
+                    ? "complete"
+                    : "waiting"
+                : needs.some((n) => n.status === "needsCapability")
+                    ? "needsCapability"
+                    : "needsDecision",
+            taskId: snapshot.state.batchId,
+            mayEnd: gate.mayEnd,
+            scopeKinds: gate.scopeKinds,
+            actual: Object.fromEntries(snapshot.state.items.map((i) => [
+                i.kind,
+                { verified: i.verified, unknown: i.unknown },
+            ])),
+            gaps: gate.pending,
+            ...(needs.length ? { decision: needs } : {}),
+            evidenceRef: snapshot.path ?? store.path,
+            ...(gate.errors.length ? { settlementErrors: gate.errors } : {}),
+        };
+    }
+    async function settleProof(snapshot, action, observation, { preserveStatus = false } = {}) {
+        const proof = await store.recordProof(await platform.captureProof({ observation }));
+        const state = structuredClone(snapshot.state);
+        const entry = state.actions.find((a) => a.id === action.id);
+        const item = state.items.find((i) => i.kind === action.kind);
+        if (observation.verified) {
+            if (action.kind !== "follow" &&
+                (!/^\d+$/.test(observation.publicId ?? "") ||
+                    state.actions.some((a) => a.id !== action.id &&
+                        a.status === "verified" &&
+                        a.publicId === observation.publicId)))
+                throw new Error("同一公开结果不能重复结算");
+            if (["intent", "unknown"].includes(entry.status))
+                item.unknown -= 1;
+            if (entry.status !== "verified")
+                item.verified += 1;
+            entry.status = "verified";
+            entry.publicId = observation.publicId;
+            entry.resultEvidence = proof;
+            item.resultEvidence = [
+                ...new Set([...(item.resultEvidence ?? []), proof]),
+            ];
+        }
+        else {
+            if (!["intent", "unknown"].includes(entry.status))
+                item.unknown += 1;
+            entry.status = "unknown";
+            entry.resultEvidence = proof;
+        }
+        if (item.verified > item.planned || item.unknown < 0)
+            throw new Error("结算越界：不覆盖原目标或重复计数");
+        if (!preserveStatus)
+            state.status = "RUNNING";
+        return save(snapshot, state);
+    }
+    async function releaseSession(taskId = undefined) {
+        if (!executor)
+            return;
+        await store.transaction((latest) => {
+            const own = latest.state.executions?.[executor.id];
+            if ((taskId && latest.state.batchId !== taskId) ||
+                own?.runtimeId !== runtimeId ||
+                !own.activity)
+                return null;
+            const next = structuredClone(latest.state);
+            delete next.executions[executor.id].activity;
+            next.updatedAt = stamp();
+            return next;
+        });
+    }
+    return { load, save, result, settleProof, releaseSession };
+}

package/dist/growth-tasks.d.ts

@@ -0,0 +1,17 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createGrowthTasks(dependencies: Pick<GrowthDependencies, "platform" | "capability" | "executor" | "readTask" | "parallelRound" | "round" | "load" | "result" | "publishIndependent" | "prepareActionsForCall">): {
+    preflight: ({ operation, input }: any) => any;
+    readCreator: (args: any) => Promise<any>;
+    inspectAccount: (args: any) => Promise<any>;
+    readPost: (args: any) => Promise<any>;
+    readPerson: (args: any) => Promise<any>;
+    readBookmarks: (args: any) => Promise<any>;
+    searchSources: (args: any) => Promise<any>;
+    readFeedback: (args: any) => Promise<any>;
+    runGrowthRound: (args: any) => Promise<any>;
+    resumeGrowthRound: (args: any) => Promise<any>;
+    inspectRound: ({ taskId }: any) => Promise<any>;
+    followOne: ({ taskId, handle }: any) => Promise<any>;
+    publishPost: (input: any) => Promise<any>;
+    replyToPost: ({ taskId, postId, text, preparedAction }: any) => Promise<any>;
+};

package/dist/growth-tasks.js

@@ -0,0 +1,101 @@
+import { kinds, operations, same } from "./growth-constants.js";
+export function createGrowthTasks(dependencies) {
+    const { platform, capability, executor, readTask, parallelRound, round, load, result, publishIndependent, prepareActionsForCall, } = dependencies;
+    return {
+        preflight: ({ operation, input = {} }) => {
+            if (["readBookmarks", "searchSources", "readFeedback"].includes(operation))
+                return platform.preflight({ operation, input });
+            if (["inspectRound", "verifySubmission"].includes(operation))
+                return capability("read", input);
+            if (["inspectAccount", "verifyFollow"].includes(operation)) {
+                const name = operation === "verifyFollow" ? "readPerson" : "readAccount";
+                if (typeof platform?.preflight !== "function" ||
+                    typeof platform?.[name] !== "function")
+                    return {
+                        covered: false,
+                        missing: [name],
+                        owner: "scripts/x-harness-platform.mjs",
+                    };
+                return platform.preflight({ operation: "read", input });
+            }
+            if (["runGrowthRound", "resumeGrowthRound"].includes(operation)) {
+                const scoped = executor?.scopeKinds ?? input.scopeKinds ?? kinds;
+                if (!Array.isArray(scoped) ||
+                    !scoped.length ||
+                    scoped.some((k) => !kinds.includes(k)))
+                    return {
+                        covered: false,
+                        missing: ["scopeKinds"],
+                        owner: "scripts/x-growth-harness.mjs",
+                    };
+                const all = scoped.map((kind) => capability(operations[kind], { ...input, kind }));
+                return {
+                    covered: all.every((c) => c.covered),
+                    missing: [...new Set(all.flatMap((c) => c.missing))],
+                    owners: [
+                        ...new Set(all.filter((c) => !c.covered).map((c) => c.owner)),
+                    ],
+                };
+            }
+            if (![
+                "read",
+                "followOne",
+                "followBatch",
+                "publishPost",
+                "replyToPost",
+                ...Object.values(operations),
+            ].includes(operation))
+                return {
+                    covered: false,
+                    missing: [`operation.${operation}`],
+                    owner: "scripts/x-growth-harness.mjs",
+                };
+            return capability(operation, input);
+        },
+        readCreator: (args) => readTask("readCreator", args),
+        inspectAccount: (args) => readTask("readAccount", args),
+        readPost: (args) => readTask("readPost", { ...args, expand: true }),
+        readPerson: (args) => readTask("readPerson", args),
+        readBookmarks: (args) => readTask("readBookmarks", args),
+        searchSources: (args) => readTask("searchSources", args),
+        readFeedback: (args) => readTask("readFeedback", args),
+        runGrowthRound: (args) => executor ? parallelRound(args) : round(args),
+        resumeGrowthRound: (args) => executor ? parallelRound(args) : round(args),
+        inspectRound: async ({ taskId }) => {
+            const snapshot = await load(taskId);
+            return result(snapshot);
+        },
+        followOne: ({ taskId, handle }) => (executor ? parallelRound : round)({
+            taskId,
+            requestedKind: "follow",
+            selector: (a) => a.kind === "follow" && same(a.handle, handle),
+        }),
+        publishPost: async (input) => {
+            if (!executor && input.independentExecution)
+                return publishIndependent(input);
+            if (input.preparedAction &&
+                (input.preparedAction.kind !== "original" ||
+                    input.preparedAction.draftPath !== input.draftPath))
+                throw new Error("prepared-original-target-mismatch");
+            await prepareActionsForCall(input.taskId, input.preparedAction ? [input.preparedAction] : []);
+            return (executor ? parallelRound : round)({
+                taskId: input.taskId,
+                requestedKind: "original",
+                selector: (a) => a.kind === "original" && a.draftPath === input.draftPath,
+            });
+        },
+        replyToPost: async ({ taskId, postId, text, preparedAction }) => {
+            if (preparedAction &&
+                (preparedAction.kind !== "reply" ||
+                    preparedAction.postId !== postId ||
+                    preparedAction.text !== text))
+                throw new Error("prepared-reply-target-mismatch");
+            await prepareActionsForCall(taskId, preparedAction ? [preparedAction] : []);
+            return (executor ? parallelRound : round)({
+                taskId,
+                requestedKind: "reply",
+                selector: (a) => a.kind === "reply" && a.postId === postId && a.text === text,
+            });
+        },
+    };
+}

package/dist/growth.d.ts

@@ -1 +1,2 @@
+/** Synchronous composition only; owners retain one original ledger and settlement path. */
 export declare function createGrowthHarness({ platform, store, clock, executor, }?: any): any;