@nextclaw/x-harness 0.1.0 → 0.1.1

package/dist/growth-policy.js

@@ -0,0 +1,181 @@
+import { xURL } from "./platform-rules.js";
+import { kinds, followWindows, operations, same } from "./growth-constants.js";
+export function createGrowthPolicy(dependencies) {
+    const { executor, clock, evidenceExists, platform, store } = dependencies;
+    // Manual user authorization applies only to the named executor and action kind.
+    const authorizedWindow = (state, kind) => {
+        const permit = state.executions?.[executor?.id]?.windowAuthorization;
+        const now = clock();
+        return Boolean(permit &&
+            permit.kind === kind &&
+            permit.executorId === executor?.id &&
+            permit.userAuthorized === true &&
+            evidenceExists(permit.evidenceRef) &&
+            Date.parse(permit.startsAt) <= now &&
+            now < Date.parse(permit.expiresAt));
+    };
+    const scope = (state) => executor?.scopeKinds ?? state.scopeKinds ?? kinds;
+    const project = (state) => executor
+        ? {
+            ...state,
+            scopeKinds: executor.scopeKinds,
+            scopeEvidenceRef: executor.evidenceRef,
+            status: state.executions?.[executor.id]?.status ?? "RUNNING",
+            stop: state.executions?.[executor.id]?.stop,
+        }
+        : state;
+    function capability(operation, input = {}) {
+        const kind = input.kind ??
+            {
+                followOne: "follow",
+                followBatch: "follow",
+                submitFollow: "follow",
+                publishPost: "original",
+                submitPost: "original",
+                replyToPost: "reply",
+                submitReply: "reply",
+            }[operation];
+        const required = [
+            "preflight",
+            "readAccount",
+            "findSubmission",
+            "captureProof",
+            ...(operation === "read" ? [] : [operations[kind]]),
+        ];
+        if (kind === "follow")
+            required.push("readPerson");
+        const missing = required.filter((name) => typeof platform?.[name] !== "function");
+        const storage = ["load", "save", "withLock", "recordProof"].filter((name) => typeof store?.[name] !==
+            "function");
+        if (operation === "followBatch" && typeof store?.transaction !== "function")
+            storage.push("transaction");
+        if (kind === "original" &&
+            operation !== "read" &&
+            typeof store?.fingerprint !== "function")
+            storage.push("fingerprint");
+        const lower = typeof platform?.preflight === "function"
+            ? platform.preflight({
+                operation: operation === "read" ? "read" : operations[kind],
+                input,
+            })
+            : { covered: false, missing: [] };
+        return {
+            covered: !missing.length && !storage.length && lower.covered,
+            missing: [
+                ...missing.map((n) => `platform.${n}`),
+                ...storage.map((n) => `store.${n}`),
+                ...(lower.missing ?? []),
+            ],
+            owner: missing.length
+                ? "scripts/x-harness-platform.mjs"
+                : storage.length
+                    ? "scripts/x-harness-store.mjs"
+                    : lower.owner,
+        };
+    }
+    function waitBudget(state) {
+        const now = clock();
+        const hour = Number(new Intl.DateTimeFormat("en-GB", {
+            timeZone: "Asia/Shanghai",
+            hour: "2-digit",
+            hourCycle: "h23",
+        }).format(now));
+        if (hour < 7 || hour >= 22)
+            return {
+                status: "needsDecision",
+                reason: "outside-contract-write-window",
+            };
+        const coverage = state.attemptsCoverage;
+        if (!coverage?.complete ||
+            !Number.isFinite(Date.parse(coverage.since)) ||
+            Date.parse(coverage.since) > now - 3600000 ||
+            !evidenceExists(coverage.evidenceRef))
+            return {
+                status: "needsDecision",
+                reason: "shared-attempt-history-incomplete",
+            };
+        const attempts = state.attempts ?? [];
+        if (attempts.some((a) => !kinds.includes(a.kind) || !Number.isFinite(Date.parse(a.at))))
+            return { status: "needsDecision", reason: "attempt-history-invalid" };
+        const follows = attempts.filter((a) => a.kind === "follow");
+        for (const [duration, limit] of followWindows) {
+            const recent = follows
+                .filter((a) => Date.parse(a.at) > now - duration)
+                .sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+            if (recent.length >= limit)
+                return {
+                    status: "waiting",
+                    reason: "follow-rolling-budget",
+                    resumeAt: new Date(Date.parse(recent[recent.length - limit].at) + duration).toISOString(),
+                };
+        }
+        const group = state.execution?.followGroup;
+        if (group?.attempts >= 10 && now < Date.parse(group.lastAt) + 180000)
+            return {
+                status: "waiting",
+                reason: "follow-group-cooldown",
+                resumeAt: new Date(Date.parse(group.lastAt) + 180000).toISOString(),
+            };
+        return null;
+    }
+    function guardInput(state, action, independentExecution = undefined) {
+        if (!independentExecution && !scope(state).includes(action.kind))
+            return "kind-outside-round-scope";
+        if (independentExecution) {
+            if (action.kind !== "original" ||
+                !independentExecution.tabId ||
+                !evidenceExists(independentExecution.evidenceRef) ||
+                !evidenceExists(independentExecution.scopeEvidenceRef))
+                return "independent-execution-proof-missing";
+        }
+        else if (!executor &&
+            (!state.execution?.exclusive || state.execution.owner !== "harness"))
+            return "exclusive-account-execution-unconfirmed";
+        if (!same(state.accountHandle, action.accountHandle))
+            return "account-identity-mismatch";
+        if (!evidenceExists(action.accountEvidenceRef) ||
+            xURL(action.accountURL).pathname.toLowerCase() !==
+                `/${state.accountHandle}`.toLowerCase())
+            return "own-profile-proof-missing";
+        if (!action.quality?.approved ||
+            !evidenceExists(action.quality.evidenceRef))
+            return "quality-review-required";
+        if (action.kind === "follow") {
+            if (!same(action.quality.handle, action.handle) ||
+                action.quality.blue !== true ||
+                action.quality.chinese !== true)
+                return "follow-qualification-required";
+            if (!evidenceExists(action.evidenceRef))
+                return "person-observation-proof-missing";
+        }
+        else {
+            if (!action.text || action.quality.approvedText !== action.text)
+                return "exact-text-quality-review-required";
+            if (action.kind === "original" &&
+                (!action.draftPath || !evidenceExists(action.draftPath)))
+                return "draft-source-missing";
+            if (action.kind === "original" &&
+                (!action.draftPath.endsWith(".post.md") ||
+                    action.quality.draftFingerprint !==
+                        store.fingerprint(action.draftPath)))
+                return "draft-changed-since-quality-review";
+            if (action.kind === "original" &&
+                (!evidenceExists(action.composeEvidenceRef) ||
+                    xURL(action.composeURL).pathname !== "/compose/post"))
+                return "observed-composer-proof-missing";
+            if (action.kind === "reply" &&
+                (!/^\d+$/.test(action.postId ?? "") ||
+                    !evidenceExists(action.evidenceRef)))
+                return "reply-target-proof-missing";
+        }
+        return null;
+    }
+    return {
+        authorizedWindow,
+        scope,
+        project,
+        capability,
+        waitBudget,
+        guardInput,
+    };
+}

package/dist/growth-publishing.d.ts

@@ -0,0 +1,5 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createIndependentPublishing(dependencies: Pick<GrowthDependencies, "clock" | "evidenceExists" | "capability" | "store" | "load" | "guardInput" | "save" | "platform" | "stamp" | "settleProof">): {
+    publishIndependent: ({ taskId, draftPath, preparedAction, independentExecution, }: any) => Promise<any>;
+    prepareActionsForCall: (taskId: string, actions?: any[]) => Promise<void>;
+};

package/dist/growth-publishing.js

@@ -0,0 +1,240 @@
+import { kinds, same } from "./growth-constants.js";
+export function createIndependentPublishing(dependencies) {
+    const { clock, evidenceExists, capability, store, load, guardInput, save, platform, stamp, settleProof, } = dependencies;
+    // Independent tabs share only short ledger transactions, never a browser-operation lock.
+    async function publishIndependent({ taskId, draftPath, preparedAction, independentExecution, }) {
+        let action, token, submissionStarted = false;
+        const inWindow = () => {
+            const hour = Number(new Intl.DateTimeFormat("en-GB", {
+                timeZone: "Asia/Shanghai",
+                hour: "2-digit",
+                hourCycle: "h23",
+            }).format(clock()));
+            const permit = independentExecution?.windowAuthorization;
+            return ((hour >= 7 && hour < 22) ||
+                Boolean(permit?.userAuthorized === true &&
+                    permit.actionId === (action?.id ?? preparedAction?.id) &&
+                    evidenceExists(permit.evidenceRef) &&
+                    clock() < Date.parse(permit.expiresAt)));
+        };
+        try {
+            const caps = capability("submitPost", preparedAction ?? {});
+            if (!caps.covered)
+                return { status: "needsCapability", ...caps };
+            if (!inWindow())
+                throw new Error("outside-contract-write-window");
+            await store.withLock(async () => {
+                const snapshot = await load(taskId), state = structuredClone(snapshot.state);
+                state.actions ??= [];
+                action = state.actions.find((a) => a.kind === "original" && a.draftPath === draftPath);
+                if (!action) {
+                    if (!preparedAction?.id ||
+                        preparedAction.kind !== "original" ||
+                        preparedAction.status !== "prepared" ||
+                        preparedAction.draftPath !== draftPath ||
+                        state.actions.some((a) => a.id === preparedAction.id))
+                        throw new Error("unique-prepared-original-required");
+                    const error = guardInput(state, preparedAction, independentExecution);
+                    if (error)
+                        throw new Error(error);
+                    action = structuredClone(preparedAction);
+                    state.actions.push(action);
+                    await save(snapshot, state);
+                }
+                if (action.status !== "prepared")
+                    throw new Error("existing-submission-do-not-resubmit");
+                if (action.claim && store.ownerAlive(action.claim.pid))
+                    throw new Error("same-action-claimed");
+                const error = guardInput(state, action, independentExecution);
+                if (error)
+                    throw new Error(error);
+            });
+            const own = await platform.readAccount();
+            if (own.needsStateCheck ||
+                own.alerts?.length ||
+                !same(own.accountHandle, action.accountHandle))
+                throw new Error("fresh-account-unconfirmed");
+            const baseline = await platform.findSubmission({
+                ...action,
+                intentAt: stamp(),
+            });
+            if (baseline.needsStateCheck || baseline.alerts?.length)
+                throw new Error("publication-baseline-unconfirmed");
+            token = `${action.id}:${stamp()}:${Math.random()}`;
+            await store.withLock(async () => {
+                const snapshot = await load(taskId), state = structuredClone(snapshot.state);
+                const target = state.actions.find((a) => a.id === action.id), item = state.items.find((i) => i.kind === "original");
+                if (target?.status !== "prepared" ||
+                    (target.claim && store.ownerAlive(target.claim.pid)))
+                    throw new Error("action-already-claimed-do-not-resubmit");
+                const error = guardInput(state, target, independentExecution);
+                if (error)
+                    throw new Error(error);
+                if (!inWindow() || item.verified + item.unknown >= item.planned)
+                    throw new Error("window-or-original-capacity-unavailable");
+                Object.assign(target, {
+                    status: "intent",
+                    intentAt: stamp(),
+                    beforeIds: (baseline.posts ?? [])
+                        .map((p) => p.id)
+                        .filter(Boolean),
+                    claimToken: token,
+                    independentExecution,
+                    claim: {
+                        actionId: target.id,
+                        token,
+                        pid: store.processId,
+                        tabId: independentExecution.tabId,
+                        acquiredAt: stamp(),
+                    },
+                });
+                item.unknown += 1;
+                state.attempts ??= [];
+                state.attempts.push({
+                    actionId: target.id,
+                    kind: "original",
+                    at: target.intentAt,
+                });
+                await save(snapshot, state);
+                action = structuredClone(target);
+            });
+            let observation;
+            try {
+                await platform.submitPost({
+                    ...action,
+                    beforeSubmit: async () => {
+                        const latest = await load(taskId), target = latest.state.actions.find((a) => a.id === action.id);
+                        if (target?.status !== "intent" ||
+                            target.claimToken !== token ||
+                            !inWindow())
+                            throw new Error("action-claim-or-window-changed");
+                        const error = guardInput(latest.state, target, independentExecution);
+                        if (error)
+                            throw new Error(error);
+                        submissionStarted = true;
+                    },
+                });
+                observation = await platform.findSubmission(action);
+            }
+            catch (error) {
+                if (!submissionStarted)
+                    throw error;
+                observation = {
+                    verified: false,
+                    missing: ["submission-or-verification-failed"],
+                    error: error.message.slice(0, 240),
+                };
+            }
+            return await store.withLock(async () => {
+                const snapshot = await load(taskId), target = snapshot.state.actions.find((a) => a.id === action.id);
+                if (target?.claimToken !== token || target.status !== "intent")
+                    throw new Error("action-settlement-conflict");
+                await settleProof(snapshot, target, observation, {
+                    preserveStatus: true,
+                });
+                return {
+                    status: observation.verified ? "verified" : "unknown",
+                    taskId,
+                    actionId: action.id,
+                    publicId: observation.publicId,
+                    evidenceRef: store.path,
+                    mayEnd: false,
+                };
+            });
+        }
+        catch (error) {
+            if (token && !submissionStarted)
+                await store.withLock(async () => {
+                    const snapshot = await load(taskId), state = structuredClone(snapshot.state), target = state.actions.find((a) => a.id === action.id);
+                    if (target?.claimToken !== token || target.status !== "intent")
+                        return;
+                    target.status = "prepared";
+                    target.preparationEvidence = await store.recordProof({
+                        observedAt: stamp(),
+                        submissionStarted: false,
+                        error: error.message.slice(0, 240),
+                    });
+                    state.items.find((i) => i.kind === "original").unknown -= 1;
+                    await save(snapshot, state);
+                });
+            return {
+                status: "needsDecision",
+                taskId,
+                mayEnd: false,
+                decision: [
+                    {
+                        reason: error.code === "CONFLICT"
+                            ? "original-ledger-conflict"
+                            : error.message.slice(0, 240),
+                    },
+                ],
+            };
+        }
+        finally {
+            if (token)
+                await store.transaction((snapshot) => {
+                    if (snapshot.state.batchId !== taskId)
+                        return null;
+                    const next = structuredClone(snapshot.state), target = next.actions.find((a) => a.id === action.id);
+                    if (target?.claim?.token !== token)
+                        return null;
+                    delete target.claim;
+                    return next;
+                });
+        }
+    }
+    // Stable prepared actions are adopted in the original ledger, never in a second queue.
+    async function prepareActionsForCall(taskId, actions = []) {
+        if (!actions.length)
+            return;
+        await store.transaction(async (snapshot) => {
+            if (snapshot.state.batchId !== taskId)
+                throw new Error("original-task-id-required");
+            const next = structuredClone(snapshot.state);
+            next.actions ??= [];
+            const ids = new Set();
+            for (const action of actions) {
+                if (!action?.id ||
+                    ids.has(action.id) ||
+                    action.status !== "prepared" ||
+                    !kinds.includes(action.kind))
+                    throw new Error("unique-prepared-action-required");
+                ids.add(action.id);
+                const inputError = guardInput(next, action);
+                if (inputError)
+                    throw new Error(inputError);
+                const existing = next.actions.find((a) => a.id === action.id);
+                if (existing) {
+                    const fields = [
+                        "kind",
+                        "accountHandle",
+                        "handle",
+                        "postId",
+                        "text",
+                        "draftPath",
+                    ];
+                    if (fields.some((field) => existing[field] !== action[field]))
+                        throw new Error("original-action-input-changed");
+                    continue; // intent/unknown/verified stay untouched and follow their original recovery.
+                }
+                const duplicate = next.actions.some((a) => a.kind === action.kind &&
+                    (action.kind === "follow"
+                        ? same(a.handle, action.handle)
+                        : action.kind === "original"
+                            ? a.draftPath === action.draftPath
+                            : a.postId === action.postId && a.text === action.text));
+                if (duplicate)
+                    throw new Error("business-object-already-prepared");
+                const item = next.items.find((i) => i.kind === action.kind);
+                const queued = next.actions.filter((a) => a.kind === action.kind &&
+                    !["skipped", "preexisting"].includes(a.status)).length;
+                if (!item || queued >= item.planned)
+                    throw new Error("prepared-actions-exceed-original-target");
+                next.actions.push(structuredClone(action));
+            }
+            next.updatedAt = stamp();
+            return next;
+        });
+    }
+    return { publishIndependent, prepareActionsForCall };
+}

package/dist/growth-reading.d.ts

@@ -0,0 +1,4 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createGrowthReading(dependencies: Pick<GrowthDependencies, "platform" | "executor" | "store" | "runtimeId" | "stamp" | "releaseSession" | "session">): {
+    readTask: (operation: any, { mode, ...input }?: any) => Promise<any>;
+};

package/dist/growth-reading.js

@@ -0,0 +1,135 @@
+export function createGrowthReading(dependencies) {
+    const { platform, executor, store, runtimeId, stamp, releaseSession, session, } = dependencies;
+    const readCache = new Map();
+    async function readTask(operation, { mode = "receipt", ...input } = {}) {
+        if (!["decision", "receipt", "delta"].includes(mode))
+            throw new Error("读取模式须为decision/receipt/delta");
+        if (session.running)
+            return {
+                status: "needsDecision",
+                complete: false,
+                reason: "same-tab-operation-running",
+            };
+        const caps = platform.preflight({
+            operation: ["readAccount", "readPerson", "readPost"].includes(operation)
+                ? "read"
+                : operation,
+            input,
+        });
+        if (!caps.covered || typeof platform[operation] !== "function")
+            return {
+                status: "needsCapability",
+                ...caps,
+                missing: [
+                    ...(caps.missing ?? []),
+                    ...(typeof platform[operation] === "function"
+                        ? []
+                        : [`platform.${operation}`]),
+                ],
+            };
+        session.running = true;
+        try {
+            if (executor)
+                await store.transaction((latest) => {
+                    const next = structuredClone(latest.state);
+                    next.executions ??= {};
+                    if (Object.values(next.executions).some((e) => (e.tabId === executor.tabId || e.id === executor.id) &&
+                        e.runtimeId !== runtimeId &&
+                        (e.activity || e.actionId) &&
+                        store.ownerAlive(e.pid)))
+                        throw new Error("same-tab-or-executor-claimed");
+                    next.executions[executor.id] = {
+                        ...next.executions[executor.id],
+                        ...executor,
+                        runtimeId,
+                        pid: store.processId,
+                        activity: operation,
+                        status: next.executions[executor.id]?.status ?? "RUNNING",
+                        updatedAt: stamp(),
+                    };
+                    next.updatedAt = stamp();
+                    return next;
+                });
+            const value = await platform[operation](input);
+            const evidenceRef = await store.recordProof(await platform.captureProof({ observation: value }));
+            const status = value.status ??
+                (value.complete === false ||
+                    value.needsStateCheck ||
+                    value.alerts?.length
+                    ? "needsDecision"
+                    : "observed");
+            const receipt = {
+                status,
+                fresh: true,
+                evidenceRef,
+                complete: status === "observed" && (value.complete ?? !value.needsStateCheck),
+                ...((value.sources ?? value.feedback)
+                    ? { ids: (value.sources ?? value.feedback).map((p) => p.id) }
+                    : {}),
+                ...(operation === "readAccount"
+                    ? {
+                        accountHandle: value.accountHandle ?? null,
+                        accountURL: value.accountURL ?? null,
+                    }
+                    : {}),
+                ...(value.missing?.length ? { missing: value.missing } : {}),
+            };
+            if (mode === "receipt")
+                return receipt;
+            const collection = value.sources
+                ? "sources"
+                : value.feedback
+                    ? "feedback"
+                    : null;
+            if (mode === "delta" && collection) {
+                const unchangedIds = [], changed = [];
+                for (const entry of value[collection]) {
+                    const key = JSON.stringify([operation, input, entry.id]);
+                    const normalized = JSON.stringify(entry, (name, val) => name === "observedAt" ? undefined : val);
+                    if (readCache.get(key) === normalized)
+                        unchangedIds.push(entry.id);
+                    else
+                        changed.push(entry);
+                    readCache.set(key, normalized);
+                }
+                return { ...receipt, [collection]: changed, unchangedIds };
+            }
+            return mode === "delta" ? receipt : { ...value, ...receipt };
+        }
+        catch (error) {
+            const category = /connection|transport|interrupted|extension/i.test(error.message)
+                ? "browser-connection"
+                : "ui-not-confirmed";
+            const code = error.code === "CONFLICT"
+                ? "ledger-conflict"
+                : /same-tab-or-executor-claimed/.test(error.message)
+                    ? "tab-busy"
+                    : category === "browser-connection"
+                        ? "connection-failed"
+                        : "observation-unconfirmed";
+            const diagnostic = { operation, category, code };
+            const evidenceRef = await store.recordProof({
+                capturedAt: stamp(),
+                diagnostic: { ...diagnostic, error: error.message },
+            });
+            return {
+                status: "needsDecision",
+                fresh: false,
+                complete: false,
+                evidenceRef,
+                diagnostic: mode === "decision"
+                    ? { ...diagnostic, error: error.message.slice(0, 240) }
+                    : diagnostic,
+            };
+        }
+        finally {
+            try {
+                await releaseSession();
+            }
+            finally {
+                session.running = false;
+            }
+        }
+    }
+    return { readTask };
+}

package/dist/growth-recovery.d.ts

@@ -0,0 +1,6 @@
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare function createGrowthRecovery(dependencies: Pick<GrowthDependencies, "capability" | "platform" | "load" | "evidenceExists" | "clock" | "store" | "settleProof" | "executor" | "parallelRound" | "round" | "readTask">): {
+    verifyPublishedPost({ taskId, draftPath, publicURL, evidenceRef, sourceLink, }: any): Promise<any>;
+    verifySubmission: ({ taskId, actionId }: any) => Promise<any>;
+    verifyFollow: (target: any) => Promise<any>;
+};