newmark-agent 0.6.2 → 0.6.4

package/dist/core/continuation/contracts.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * continuation-v1 contracts.
+ *
+ * These are the runtime-checked boundaries shared by the PC GUI, the hosted
+ * mobile API and the isolated runtimes. A view may read a snapshot, but it can
+ * never supply the execution identity that a write is allowed to use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContinuationError = exports.CONTINUATION_SCHEMA_VERSION = void 0;
+exports.stableJson = stableJson;
+exports.emptyLedger = emptyLedger;
+exports.defaultGuard = defaultGuard;
+exports.commandKey = commandKey;
+exports.buildInputHash = buildInputHash;
+exports.requestHash = requestHash;
+exports.CONTINUATION_SCHEMA_VERSION = 1;
+class ContinuationError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'ContinuationError';
+    }
+}
+exports.ContinuationError = ContinuationError;
+function stableJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(item => stableJson(item)).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+}
+function emptyLedger(workspaceId) {
+    return {
+        version: exports.CONTINUATION_SCHEMA_VERSION,
+        workspaceId,
+        roots: {},
+        branches: {},
+        builds: {},
+        attempts: {},
+        guards: {},
+        commands: {},
+        finals: {},
+        events: [],
+        nextEventCursor: 1,
+        nextQueueSequence: 1,
+    };
+}
+function defaultGuard(branchId) {
+    return { branchId, activeBuildId: null, activeAttemptId: null, fence: 0, leaseUntil: 0, workerCapability: '' };
+}
+function commandKey(actorId, commandId) {
+    return `${actorId}\u0000${commandId}`;
+}
+function buildInputHash(input) {
+    return require('crypto').createHash('sha256').update(stableJson(input)).digest('hex').slice(0, 24);
+}
+function requestHash(command) {
+    return require('crypto').createHash('sha256').update(stableJson({
+        type: command.type,
+        target: command.target,
+        expectedTailBuildId: command.expectedTailBuildId,
+        expectedQueueRevision: command.expectedQueueRevision,
+        input: command.input,
+        recipeSnapshotId: command.recipeSnapshotId,
+    })).digest('hex');
+}
+//# sourceMappingURL=contracts.js.map

package/dist/core/continuation/store.d.ts

@@ -0,0 +1,206 @@
+import { BranchId, BranchRecord, BuildId, BuildInput, BuildRecord, CommandReceipt, ContinuationEvent, EnqueueBuildCommand, ExecutionScope, FinalRecord, QueueSnapshot, RootId, SnapshotId } from './contracts';
+export interface GuardedContinuationStoreOptions {
+    /** Lease duration for one attempt. */
+    leaseMs?: number;
+    /** Maximum retained append-only events per workspace ledger. */
+    eventRetention?: number;
+}
+/**
+ * Single-writer continuation ledger for one workspace.
+ *
+ * The spec's reference uses SQLite. This implementation keeps the same
+ * boundaries with a lock-file + atomic-replace JSON ledger because the project
+ * does not ship a native SQLite module and an Electron native dependency would
+ * change the packaging/signing contract. All continuation writes must go
+ * through this class; callers never mutate the ledger directly.
+ */
+export declare class GuardedContinuationStore {
+    private readonly workspacePath;
+    private readonly workspaceId;
+    private readonly ledgerPath;
+    private readonly lockPath;
+    private readonly leaseMs;
+    private readonly eventRetention;
+    private fingerprint;
+    private cached;
+    constructor(workspacePath: string, workspaceId: string, options?: GuardedContinuationStoreOptions);
+    get filePath(): string;
+    ensureRoot(rootId: RootId, defaultBranchId: BranchId): void;
+    ensureBranch(input: {
+        rootId: RootId;
+        branchId: BranchId;
+        parentAnchorBuildId: BuildId | null;
+    }): BranchRecord;
+    getReceipt(actorId: string, commandId: string): CommandReceipt | undefined;
+    enqueueBuild(command: EnqueueBuildCommand): CommandReceipt;
+    claimBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        workerCapability: string;
+        now?: number;
+    }): ExecutionScope | null;
+    updateQueuedBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        input: BuildInput;
+    }): BuildRecord;
+    /**
+     * dev-0.6.4 hotfix: 当某个被受理的 Build 失败/取消后，它的后继会永远无法被
+     * claim（`claimBuild` 只认「父 = 已提交 frontier」），整条队列就此卡死，新提交
+     * 也只是接在失败链后面。
+     *
+     * 这里提供一条**显式**修复通道：把被阻断的排队 Build 重新挂到当前已提交的
+     * frontier 上，保持原有队列顺序，并为每一次改挂写入 `BuildQueueRepaired`
+     * 审计事件（记录旧 parent / 新 parent / 原因）。它不是静默 rebase：调用方是
+     * 用户的显式动作（恢复队列）或一次新的入队命令。
+     */
+    repairBlockedQueue(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        reason?: string;
+    }): {
+        repaired: BuildId[];
+        frontier: BuildId | null;
+    };
+    /**
+     * dev-0.6.4 hotfix: 读取视角的受阻推导。
+     *
+     * 一个 QUEUED Build 只有在它的父正好是「已提交 frontier」或队列里位于它之前
+     * 的可执行 Build 时才可能被 claim（见 `claimBuild`）。这里按队列顺序推导哪些行
+     * 目前不可执行：父不是链上前驱、或父已 FAILED/CANCELLED 的行即为受阻，且受阻点
+     * 之后的所有行同样受阻。
+     */
+    private blockedQueuedBuildIds;
+    deleteQueuedBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): void;
+    reorderQueuedBuilds(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        orderedBuildIds: BuildId[];
+    }): QueueSnapshot;
+    heartbeat(scope: Pick<ExecutionScope, 'branchId' | 'buildId' | 'attemptId' | 'fence'>, now?: number): boolean;
+    commitFinal(input: {
+        scope: ExecutionScope;
+        text: string;
+        finalHash?: string;
+        stateSnapshotId?: SnapshotId;
+        now?: number;
+    }): FinalRecord;
+    /**
+     * Trusted external-owner completion.
+     *
+     * A Flow is a kernel-owned external run, not a leased model worker. It still
+     * has to be a durable build so queued Goal/Next successors have a committed
+     * parent. This path validates the parent/head relation transactionally but
+     * does not require a BranchGuard attempt; the kernel owns the Flow lifetime.
+     * If the build is not the next ready build, it stays QUEUED and the caller
+     * must retry after the predecessor commits.
+     */
+    commitExternalBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        text?: string;
+        now?: number;
+    }): boolean;
+    /**
+     * Claim a new attempt for an existing external Flow build (suspend/resume).
+     * The build identity and fixed parent are preserved; only the attempt/fence
+     * advance. This is the external-owner equivalent of retryBuild.
+     */
+    claimExternalBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        workerCapability?: string;
+        now?: number;
+    }): ExecutionScope;
+    failBuild(input: {
+        scope: ExecutionScope;
+        reason: string;
+        now?: number;
+    }): void;
+    cancelBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+        now?: number;
+    }): void;
+    retryBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): BuildRecord;
+    /**
+     * Idempotent failure recovery for an input that was never accepted.
+     *
+     * Stop/archive may release the branch guard before the runtime reports the
+     * failure. In that case the build is still the same durable row and must be
+     * returned to QUEUED for an explicit resume instead of being stranded in
+     * RUNNING (or permanently FAILED). A committed build is never requeued.
+     */
+    requeueBuild(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        buildId: BuildId;
+    }): BuildRecord;
+    forkBranch(input: {
+        commandId: string;
+        actorId: string;
+        workspaceId: string;
+        sourceBranchId: BranchId;
+        anchorBuildId: BuildId;
+        newBranchId: BranchId;
+    }): BranchRecord;
+    setPaused(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+        paused: boolean;
+    }): boolean;
+    snapshot(input: {
+        workspaceId: string;
+        rootId: RootId;
+        branchId: BranchId;
+    }): QueueSnapshot;
+    private snapshotUnlocked;
+    events(afterCursor?: number, limit?: number): ContinuationEvent[];
+    recoverExpiredLeases(now?: number): number;
+    private terminateAttempt;
+    private releaseExpiredGuard;
+    private markDependentsBlocked;
+    private hasCommittedDescendant;
+    private isAncestorOfHead;
+    private ensureBranchRecord;
+    private requireBranch;
+    private ensureGuard;
+    /**
+     * Release the active attempt without ever moving the branch fence backward.
+     * A recovered/completed attempt's fence stays as the monotonic high-water
+     * mark; the next claim increments it again.
+     */
+    private releaseGuard;
+    private appendEvent;
+    private mutate;
+    private acquireLock;
+    private readLedger;
+    private readLedgerUnlocked;
+    private writeLedgerUnlocked;
+    private ensureLedgerExists;
+    private invalidateCache;
+}
+//# sourceMappingURL=store.d.ts.map