@pellux/goodvibes-sdk 0.37.1 → 0.38.0

package/dist/platform/orchestration/engine.js

@@ -0,0 +1,418 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * OrchestrationEngine (Wave 4, wo701) — owns Workstream state and drives the
+ * pipeline. WRAPS a canned/authored workstream; does not rewrite or touch
+ * WrfcController (stage 1 of the 3-stage migration — see controller-compat.ts
+ * and the work-order report).
+ *
+ * The tick loop is reactive, not timer-driven: `start()` runs one tick;
+ * every phase-run completion re-runs tick() for its workstream. Because JS
+ * is single-threaded, computeClaims()'s synchronous read of in-flight counts
+ * is never racing a concurrent claim — items are marked 'in-phase'
+ * synchronously before any `await` inside the claim loop, so a re-entrant
+ * tick() (triggered by an earlier completion resolving on a later turn of
+ * the microtask queue) always sees up-to-date state.
+ */
+import { checkBudget } from './budget.js';
+import { createCancellationRegistry } from './cancellation.js';
+import { runPhase } from './phase-runner.js';
+import { snapshotDirtyTree } from './dirty-guard.js';
+import { deserializeWorkstream as deserializeWorkstreamModel, deserializeWorkstreamSnapshot, attachDebouncedWriter, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstreamSnapshot, } from './persistence.js';
+import { computeClaims, firstPhase, nextPhaseAfter, reviewPhaseBefore, sortedPhases } from './scheduler.js';
+import { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage, } from './types.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+function generateId(prefix) {
+    return `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+}
+export function createOrchestrationEngine(deps) {
+    const now = deps.now ?? (() => Date.now());
+    const sessionId = deps.sessionId ?? crypto.randomUUID().slice(0, 8);
+    const maxPhaseVisits = deps.maxPhaseVisits ?? 5;
+    const workstreams = new Map();
+    const completedResults = new Map();
+    const cancellation = createCancellationRegistry();
+    const listeners = new Set();
+    let disposed = false;
+    function emit(event) {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                logger.warn('orchestration engine: listener threw', { error: summarizeError(error) });
+            }
+        }
+    }
+    function on(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    // Dirty-residue guard (Wave 6, wo-F item 4): snapshot the working tree's
+    // dirty paths + content hashes ONCE, right at engine launch (synchronous —
+    // see dirty-guard.ts's doc comment for why this must not be a promise
+    // backed by real subprocess I/O), before any phase of this run has had a
+    // chance to touch anything. A previously killed run sharing this same
+    // projectRoot can leave uncommitted residue behind; this snapshot is what
+    // lets a later scoped commit tell "residue from before this run" apart
+    // from "this run's own changes" (see dirty-guard.ts and phase-runner.ts's
+    // commitPhaseWork).
+    const launchDirtySnapshot = snapshotDirtyTree(deps.projectRoot);
+    if (launchDirtySnapshot.size > 0) {
+        emit({ type: 'dirty-tree-at-launch', paths: [...launchDirtySnapshot.keys()] });
+    }
+    function getWorkstream(id) {
+        return workstreams.get(id) ?? null;
+    }
+    function listWorkstreams() {
+        return Array.from(workstreams.values());
+    }
+    function getPhaseResults(workstreamId) {
+        return completedResults.get(workstreamId) ?? [];
+    }
+    const unsubscribeWriter = deps.persist === false
+        ? () => undefined
+        : attachDebouncedWriter(deps.projectRoot, getWorkstream, getPhaseResults, on);
+    function buildPhase(spec, ordinal, insertedAt) {
+        return {
+            id: spec.id ?? generateId('phase'),
+            ordinal,
+            role: spec.role,
+            capacity: spec.capacity,
+            gate: spec.gate,
+            kind: spec.kind,
+            ...(insertedAt !== undefined ? { insertedAt } : {}),
+        };
+    }
+    function buildItem(spec, startPhaseId) {
+        return {
+            id: spec.id ?? generateId('item'),
+            title: spec.title,
+            task: spec.task,
+            currentPhaseId: startPhaseId,
+            state: startPhaseId ? 'pending' : 'passed',
+            allAgentIds: [],
+            visits: new Map(),
+            touchedPaths: [],
+            usage: emptyWorkItemUsage(),
+            transportRetryCount: 0,
+            createdAt: now(),
+            ...(startPhaseId ? {} : { completedAt: now() }),
+        };
+    }
+    function createWorkstream(input) {
+        const phases = input.phases.map((spec, index) => buildPhase(spec, index + 1));
+        const workstream = {
+            id: input.id ?? generateId('ws'),
+            title: input.title,
+            schemaVersion: CURRENT_WORKSTREAM_SCHEMA_VERSION,
+            phases,
+            items: [],
+            budget: input.budget,
+            createdAt: now(),
+        };
+        const first = firstPhase(workstream)?.id ?? null;
+        workstream.items = input.items.map((spec) => buildItem(spec, first));
+        workstreams.set(workstream.id, workstream);
+        completedResults.set(workstream.id, []);
+        return workstream;
+    }
+    function insertPhase(workstreamId, afterOrdinal, spec) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return null;
+        const following = sortedPhases(workstream).filter((p) => p.ordinal > afterOrdinal);
+        const nextOrdinal = following[0]?.ordinal ?? afterOrdinal + 1;
+        const ordinal = (afterOrdinal + nextOrdinal) / 2;
+        const phase = buildPhase(spec, ordinal, now());
+        workstream.phases.push(phase);
+        emit({ type: 'phase-inserted', workstreamId, phase });
+        return phase;
+    }
+    function findOrInsertFixPhase(workstream, reviewPhase) {
+        const existing = workstream.phases.find((p) => p.kind === 'fix' && reviewPhaseBefore(workstream, p)?.id === reviewPhase.id);
+        if (existing)
+            return existing;
+        return insertPhase(workstream.id, reviewPhase.ordinal, {
+            role: 'fixer',
+            capacity: reviewPhase.capacity,
+            gate: reviewPhase.gate,
+            kind: 'fix',
+        });
+    }
+    function visitsFor(item, phaseId) {
+        return item.visits.get(phaseId) ?? 0;
+    }
+    function recordVisit(item, phaseId) {
+        item.visits.set(phaseId, visitsFor(item, phaseId) + 1);
+    }
+    function routeItem(workstream, item, toPhase, fromPhaseId) {
+        if (toPhase) {
+            item.currentPhaseId = toPhase.id;
+            item.state = 'awaiting-capacity';
+            emit({ type: 'item-advanced', workstreamId: workstream.id, itemId: item.id, fromPhaseId, toPhaseId: toPhase.id });
+        }
+        else {
+            item.currentPhaseId = null;
+            item.state = 'passed';
+            item.completedAt = now();
+            emit({ type: 'item-passed', workstreamId: workstream.id, itemId: item.id });
+        }
+    }
+    function failItem(workstream, item, reason) {
+        item.state = 'failed';
+        item.completedAt = now();
+        item.failureReason = reason;
+        emit({ type: 'item-failed', workstreamId: workstream.id, itemId: item.id, reason });
+    }
+    /** Indirection to defeat TS's cross-await narrowing of item.state — see the call site below. */
+    function currentState(item) {
+        return item.state;
+    }
+    async function runItemPhase(workstream, item, phase) {
+        recordVisit(item, phase.id);
+        item.state = 'in-phase';
+        item.currentPhaseId = phase.id;
+        item.blockedReason = undefined;
+        const priorReports = getPhaseResults(workstream.id).filter((r) => r.itemId === item.id);
+        const outcome = await runPhase(workstream, item, phase, priorReports, {
+            agentManager: deps.agentManager,
+            configManager: deps.configManager,
+            runtimeBus: deps.runtimeBus,
+            projectRoot: deps.projectRoot,
+            sessionId,
+            createWorktree: deps.createWorktree,
+            cancellation,
+            priceUsage: deps.priceUsage,
+            skipClaimVerification: deps.skipClaimVerification,
+            launchDirtySnapshot,
+        });
+        item.usage = mergeUsageFromResult(item.usage, outcome.result.usage);
+        const results = completedResults.get(workstream.id) ?? [];
+        results.push(outcome.result);
+        completedResults.set(workstream.id, results);
+        emit({ type: 'workstream-persisted', workstreamId: workstream.id });
+        // kill() already transitioned the item to 'failed' synchronously before
+        // this promise settled — don't clobber that terminal state. Read through
+        // currentState() (not a direct `item.state` narrowing site) since TS's
+        // control-flow analysis otherwise "remembers" the 'in-phase' assignment
+        // above as if it still held after the `await`, even though kill() can
+        // mutate the same object concurrently while this call was in flight.
+        if (currentState(item) === 'failed')
+            return;
+        if (outcome.agentStatus === 'cancelled') {
+            failItem(workstream, item, 'cancelled by operator');
+            return;
+        }
+        if (outcome.agentStatus === 'failed') {
+            failItem(workstream, item, outcome.result.report.summary);
+            return;
+        }
+        if (outcome.result.gate.passed) {
+            // A fix phase's PASSING gate routes BACK to the review phase it was
+            // inserted after (dynamic insertion places 'fix' at an ordinal AFTER
+            // its review, per design (b) — "inserts a fix phase after review and
+            // re-routes that item back"), not forward past it. Every other kind
+            // advances to the next phase by ordinal as usual.
+            const forwardTarget = phase.kind === 'fix'
+                ? (reviewPhaseBefore(workstream, phase) ?? nextPhaseAfter(workstream, phase.ordinal) ?? null)
+                : (nextPhaseAfter(workstream, phase.ordinal) ?? null);
+            routeItem(workstream, item, forwardTarget, phase.id);
+            return;
+        }
+        // A review's FAILING gate with unsatisfied constraints gets one more
+        // cycle through a (found-or-inserted) fix phase, bounded by visits. A
+        // fix phase's own FAILING gate (the fixer didn't actually fix anything —
+        // phantom guard or quality gates caught it) is a genuine terminal
+        // failure, not something to retry-loop.
+        const unsatisfied = outcome.result.gate.unsatisfiedConstraintIds ?? [];
+        if (phase.kind === 'review' && unsatisfied.length > 0 && visitsFor(item, phase.id) < maxPhaseVisits) {
+            const fixPhase = findOrInsertFixPhase(workstream, phase);
+            routeItem(workstream, item, fixPhase, phase.id);
+            return;
+        }
+        failItem(workstream, item, outcome.result.gate.results.filter((r) => !r.passed).map((r) => `${r.gate}: ${r.output}`).join('; ') || 'gate failed');
+    }
+    function mergeUsageFromResult(current, added) {
+        const sawReasoning = current.reasoningTokens !== undefined || added.reasoningTokens !== undefined;
+        const bothPriced = current.costState === 'priced' && added.costState === 'priced';
+        const neitherPriced = current.costUsd === null && added.costUsd === null;
+        return {
+            inputTokens: current.inputTokens + added.inputTokens,
+            outputTokens: current.outputTokens + added.outputTokens,
+            cacheReadTokens: current.cacheReadTokens + added.cacheReadTokens,
+            cacheWriteTokens: current.cacheWriteTokens + added.cacheWriteTokens,
+            reasoningTokens: sawReasoning ? (current.reasoningTokens ?? 0) + (added.reasoningTokens ?? 0) : undefined,
+            llmCallCount: current.llmCallCount + added.llmCallCount,
+            turnCount: current.turnCount + added.turnCount,
+            toolCallCount: current.toolCallCount + added.toolCallCount,
+            costUsd: current.costUsd !== null && added.costUsd !== null ? current.costUsd + added.costUsd : (current.costUsd ?? added.costUsd),
+            costState: bothPriced ? 'priced' : neitherPriced ? 'unpriced' : 'estimated',
+        };
+    }
+    function tick(workstreamId) {
+        if (disposed)
+            return;
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return;
+        const claims = computeClaims(workstream);
+        for (const { item, phase } of claims) {
+            const budgetCheck = checkBudget(workstream);
+            if (!budgetCheck.allowed) {
+                // Re-checked on every tick (computeClaims keeps 'blocked-budget'
+                // items in the waiting set — see scheduler.ts) rather than a
+                // one-time transition: the reason can change between checks (e.g.
+                // token ceiling was the blocker, then a cost ceiling is reached
+                // too), so keep it current even though the event only fires once
+                // per NEW block to avoid spamming listeners on every idle tick.
+                const wasAlreadyBlocked = item.state === 'blocked-budget';
+                item.state = 'blocked-budget';
+                item.blockedReason = budgetCheck.reason;
+                if (!wasAlreadyBlocked) {
+                    emit({ type: 'item-blocked-budget', workstreamId, itemId: item.id, phaseId: phase.id, reason: budgetCheck.reason ?? 'budget ceiling reached' });
+                }
+                continue;
+            }
+            void runItemPhase(workstream, item, phase)
+                .catch((error) => {
+                logger.error('orchestration engine: phase run threw', {
+                    workstreamId, itemId: item.id, phaseId: phase.id, error: summarizeError(error),
+                });
+                failItem(workstream, item, summarizeError(error));
+            })
+                .finally(() => {
+                if (!disposed)
+                    tick(workstreamId);
+            });
+        }
+    }
+    function start(workstreamId) {
+        tick(workstreamId);
+    }
+    function findItemAndWorkstream(itemId) {
+        for (const workstream of workstreams.values()) {
+            const item = workstream.items.find((i) => i.id === itemId);
+            if (item)
+                return { workstream, item };
+        }
+        return null;
+    }
+    function kill(itemId) {
+        const found = findItemAndWorkstream(itemId);
+        if (!found)
+            return false;
+        const { workstream, item } = found;
+        if (item.state === 'passed' || item.state === 'failed')
+            return false;
+        cancellation.abort(itemId);
+        if (item.agentId)
+            deps.agentManager.cancel(item.agentId, 'kill');
+        failItem(workstream, item, 'cancelled by operator');
+        emit({ type: 'item-cancelled', workstreamId: workstream.id, itemId, reason: 'cancelled by operator' });
+        return true;
+    }
+    function updateBudget(workstreamId, ceiling) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return false;
+        workstream.budget = ceiling;
+        tick(workstreamId);
+        return true;
+    }
+    function serializeWorkstream(workstreamId) {
+        const workstream = workstreams.get(workstreamId);
+        if (!workstream)
+            return null;
+        return serializeWorkstreamSnapshot(workstream, getPhaseResults(workstreamId));
+    }
+    function isTerminalWorkstream(workstream) {
+        return workstream.items.every((item) => item.state === 'passed' || item.state === 'failed');
+    }
+    /**
+     * An item persisted as 'in-phase' was mid-run when the snapshot was
+     * written (the debounced writer, persistence.ts, captures state
+     * synchronously — see runItemPhase — so this is always a crash artifact,
+     * never a live agent this process could still be waiting on). Left
+     * verbatim, it would count as an OCCUPIED capacity slot forever
+     * (computeClaims, scheduler.ts) while never being in the re-claimable
+     * waiting set, permanently starving every sibling in the same phase.
+     * Requeue it as 'pending' and drop the stale agentId so the next tick()
+     * reclaims it like any other waiting item — its prior PhaseResult (if any)
+     * was only ever pushed AFTER phase completion (see runItemPhase), so
+     * re-running the phase from here cannot produce a duplicate result.
+     */
+    function reconcileImportedItems(workstream) {
+        for (const item of workstream.items) {
+            if (item.state !== 'in-phase')
+                continue;
+            item.state = 'pending';
+            item.agentId = undefined;
+            emit({
+                type: 'item-requeued',
+                workstreamId: workstream.id,
+                itemId: item.id,
+                reason: 're-queued after restart — was in-phase when the snapshot was written',
+            });
+        }
+    }
+    function importWorkstream(snapshotJson, force = false) {
+        const snapshot = deserializeWorkstreamSnapshot(snapshotJson);
+        if (!snapshot)
+            return false;
+        const workstream = deserializeWorkstreamModel(snapshot.workstream);
+        const existing = workstreams.get(workstream.id);
+        if (existing && !isTerminalWorkstream(existing) && !force) {
+            logger.warn('orchestration engine: importWorkstream refused — existing workstream is non-terminal; use force=true to overwrite', {
+                workstreamId: workstream.id,
+            });
+            return false;
+        }
+        reconcileImportedItems(workstream);
+        workstreams.set(workstream.id, workstream);
+        completedResults.set(workstream.id, [...snapshot.completedResults]);
+        return true;
+    }
+    function resumeWorkstream(workstreamId) {
+        if (!workstreams.has(workstreamId)) {
+            const snapshot = loadWorkstreamSnapshot(deps.projectRoot, workstreamId);
+            if (!snapshot)
+                return false;
+            if (!importWorkstream(JSON.stringify(snapshot)))
+                return false;
+        }
+        tick(workstreamId);
+        return true;
+    }
+    function resumeAllFromDisk() {
+        let count = 0;
+        for (const workstreamId of listSnapshotWorkstreamIds(deps.projectRoot)) {
+            if (resumeWorkstream(workstreamId))
+                count += 1;
+        }
+        return count;
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubscribeWriter();
+        listeners.clear();
+    }
+    return {
+        createWorkstream,
+        getWorkstream,
+        listWorkstreams,
+        insertPhase,
+        start,
+        kill,
+        updateBudget,
+        getPhaseResults,
+        serializeWorkstream,
+        importWorkstream,
+        resumeWorkstream,
+        resumeAllFromDisk,
+        on,
+        dispose,
+    };
+}

package/dist/platform/orchestration/index.d.ts

@@ -0,0 +1,18 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export type { BudgetCeiling, CommitExclusion, GateOutcome, OrchestrationEvent, OrchestrationEventListener, Phase, PhaseGateSpec, PhaseKind, PhaseResult, PhaseRole, PhaseSpec, SerializedWorkItem, SerializedWorkstream, WorkItem, WorkItemSpec, WorkItemState, WorkItemUsage, Workstream, WorkstreamSnapshot, } from './types.js';
+export { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage } from './types.js';
+export type { CreateWorkstreamInput, OrchestrationEngine, OrchestrationEngineDeps } from './engine.js';
+export { createOrchestrationEngine } from './engine.js';
+export type { CancellationRegistry } from './cancellation.js';
+export { createCancellationRegistry } from './cancellation.js';
+export type { BudgetCheck } from './budget.js';
+export { checkBudget } from './budget.js';
+export { deserializeWorkstream, deserializeWorkstreamSnapshot, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstream, serializeWorkstreamSnapshot, writeWorkstreamSnapshot, } from './persistence.js';
+export { fromChainSpec } from './controller-compat.js';
+export type { PhaseRunnerAgentManagerLike, PhaseRunnerDeps, PhaseRunOutcome, WrfcWorktreeOps } from './phase-runner.js';
+export { runPhase } from './phase-runner.js';
+export type { DirtyLaunchSnapshot, ScopedCommitExclusion } from './dirty-guard.js';
+export { excludeUntouchedLaunchResidue, hashWorkingTreeFile, snapshotDirtyTree } from './dirty-guard.js';
+export { computeClaims, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';
+export type { PhaseClaim } from './scheduler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/orchestration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAMrF,YAAY,EACV,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,0BAA0B,EAC1B,KAAK,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iCAAiC,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEnF,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACvG,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAExD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAE/D,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,EACzB,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,YAAY,EAAE,2BAA2B,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACxH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzG,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/platform/orchestration/index.js

@@ -0,0 +1,10 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export { CURRENT_WORKSTREAM_SCHEMA_VERSION, emptyWorkItemUsage } from './types.js';
+export { createOrchestrationEngine } from './engine.js';
+export { createCancellationRegistry } from './cancellation.js';
+export { checkBudget } from './budget.js';
+export { deserializeWorkstream, deserializeWorkstreamSnapshot, listSnapshotWorkstreamIds, loadWorkstreamSnapshot, serializeWorkstream, serializeWorkstreamSnapshot, writeWorkstreamSnapshot, } from './persistence.js';
+export { fromChainSpec } from './controller-compat.js';
+export { runPhase } from './phase-runner.js';
+export { excludeUntouchedLaunchResidue, hashWorkingTreeFile, snapshotDirtyTree } from './dirty-guard.js';
+export { computeClaims, firstPhase, nextPhaseAfter, phaseById, reviewPhaseBefore, sortedPhases, } from './scheduler.js';

package/dist/platform/orchestration/persistence.d.ts

@@ -0,0 +1,24 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+import { type OrchestrationEvent, type PhaseResult, type SerializedWorkstream, type Workstream, type WorkstreamSnapshot } from './types.js';
+export declare function serializeWorkstream(workstream: Workstream): SerializedWorkstream;
+export declare function deserializeWorkstream(serialized: SerializedWorkstream): Workstream;
+/** Mirrors WrfcController.serializeChain: JSON.stringify a schema-versioned envelope. Returns null on serialization failure rather than throwing. */
+export declare function serializeWorkstreamSnapshot(workstream: Workstream, completedResults: readonly PhaseResult[]): string | null;
+/**
+ * Mirrors WrfcController.deserializeChain's future-schemaVersion-reject
+ * guard: a snapshot written by a newer runtime is rejected (fail closed)
+ * rather than partially trusted.
+ */
+export declare function deserializeWorkstreamSnapshot(json: string): WorkstreamSnapshot | null;
+/** Read + quarantine-on-corrupt (never throws, never crashes the caller on a bad file). */
+export declare function loadWorkstreamSnapshot(projectRoot: string, workstreamId: string): WorkstreamSnapshot | null;
+/** List the workstream ids with a snapshot on disk (recognized or not — callers decide via loadWorkstreamSnapshot). */
+export declare function listSnapshotWorkstreamIds(projectRoot: string): string[];
+export declare function writeWorkstreamSnapshot(projectRoot: string, workstream: Workstream, completedResults: readonly PhaseResult[]): void;
+/**
+ * Debounced trailing writer (250ms, exactly like wrfc-persistence.ts
+ * DEBOUNCE_MS), subscribing to engine lifecycle events. Returns an
+ * unsubscribe function that also flushes any pending timers.
+ */
+export declare function attachDebouncedWriter(projectRoot: string, getWorkstream: (workstreamId: string) => Workstream | null, getCompletedResults: (workstreamId: string) => readonly PhaseResult[], subscribe: (listener: (event: OrchestrationEvent) => void) => () => void): () => void;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/platform/orchestration/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/platform/orchestration/persistence.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAerF,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EAEzB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAYpB,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,oBAAoB,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,oBAAoB,GAAG,UAAU,CAElF;AAED,qJAAqJ;AACrJ,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAa3H;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CA6BrF;AAUD,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAsB3G;AAED,uHAAuH;AACvH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvE;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAUnI;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,EAC1D,mBAAmB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,WAAW,EAAE,EACrE,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,KAAK,MAAM,IAAI,GACvE,MAAM,IAAI,CA4BZ"}

package/dist/platform/orchestration/persistence.js

@@ -0,0 +1,176 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Persistence (Wave 4, wo701) — mirrors the WrfcController chain seams
+ * exactly: serializeChain:323 / deserializeChain:345 (including the
+ * future-schemaVersion-reject guard at :364) / importChain:402. Writes to
+ * `.goodvibes/orchestration/<workstreamId>.json` — SEPARATE from the TUI's
+ * `.goodvibes/tui/wrfc-chains.json` (src/runtime/wrfc-persistence.ts), no
+ * path collision. Debounce (250ms) and corrupt-snapshot quarantine
+ * (`<path>.unrecognized`) mirror that same TUI module's conventions.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+import { CURRENT_WORKSTREAM_SCHEMA_VERSION, } from './types.js';
+const DEBOUNCE_MS = 250;
+function serializeWorkItem(item) {
+    return { ...item, visits: Object.fromEntries(item.visits) };
+}
+function deserializeWorkItem(raw) {
+    return { ...raw, visits: new Map(Object.entries(raw.visits)) };
+}
+export function serializeWorkstream(workstream) {
+    return { ...workstream, items: workstream.items.map(serializeWorkItem) };
+}
+export function deserializeWorkstream(serialized) {
+    return { ...serialized, items: serialized.items.map(deserializeWorkItem) };
+}
+/** Mirrors WrfcController.serializeChain: JSON.stringify a schema-versioned envelope. Returns null on serialization failure rather than throwing. */
+export function serializeWorkstreamSnapshot(workstream, completedResults) {
+    const snapshot = {
+        schemaVersion: CURRENT_WORKSTREAM_SCHEMA_VERSION,
+        writtenAt: Date.now(),
+        workstream: serializeWorkstream(workstream),
+        completedResults,
+    };
+    try {
+        return JSON.stringify(snapshot);
+    }
+    catch (error) {
+        logger.error('orchestration persistence: JSON serialization failed', { workstreamId: workstream.id, error: summarizeError(error) });
+        return null;
+    }
+}
+/**
+ * Mirrors WrfcController.deserializeChain's future-schemaVersion-reject
+ * guard: a snapshot written by a newer runtime is rejected (fail closed)
+ * rather than partially trusted.
+ */
+export function deserializeWorkstreamSnapshot(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (error) {
+        logger.error('orchestration persistence: JSON parse failed', { error: summarizeError(error) });
+        return null;
+    }
+    if (raw === null || typeof raw !== 'object') {
+        logger.warn('orchestration persistence: invalid snapshot JSON — not an object');
+        return null;
+    }
+    const candidate = raw;
+    if (typeof candidate.schemaVersion !== 'number') {
+        logger.warn('orchestration persistence: invalid snapshot JSON — missing schemaVersion');
+        return null;
+    }
+    if (candidate.schemaVersion > CURRENT_WORKSTREAM_SCHEMA_VERSION) {
+        logger.error('orchestration persistence: future schemaVersion rejected — upgrade runtime to read this snapshot', {
+            schemaVersion: candidate.schemaVersion,
+            supportedVersion: CURRENT_WORKSTREAM_SCHEMA_VERSION,
+        });
+        return null;
+    }
+    if (!candidate.workstream || typeof candidate.workstream !== 'object' || !Array.isArray(candidate.completedResults)) {
+        logger.warn('orchestration persistence: invalid snapshot JSON — missing workstream/completedResults');
+        return null;
+    }
+    return candidate;
+}
+function orchestrationDir(projectRoot) {
+    return join(projectRoot, '.goodvibes', 'orchestration');
+}
+function snapshotPath(projectRoot, workstreamId) {
+    return join(orchestrationDir(projectRoot), `${workstreamId}.json`);
+}
+/** Read + quarantine-on-corrupt (never throws, never crashes the caller on a bad file). */
+export function loadWorkstreamSnapshot(projectRoot, workstreamId) {
+    const path = snapshotPath(projectRoot, workstreamId);
+    if (!existsSync(path))
+        return null;
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        logger.warn('orchestration persistence: snapshot read failed', { path, error: summarizeError(error) });
+        return null;
+    }
+    const snapshot = deserializeWorkstreamSnapshot(text);
+    if (snapshot === null) {
+        const quarantinePath = `${path}.unrecognized`;
+        try {
+            renameSync(path, quarantinePath);
+            logger.warn('orchestration persistence: quarantined unrecognized snapshot', { path, quarantinePath });
+        }
+        catch (error) {
+            logger.error('orchestration persistence: failed to quarantine unrecognized snapshot', { path, error: summarizeError(error) });
+        }
+        return null;
+    }
+    return snapshot;
+}
+/** List the workstream ids with a snapshot on disk (recognized or not — callers decide via loadWorkstreamSnapshot). */
+export function listSnapshotWorkstreamIds(projectRoot) {
+    const dir = orchestrationDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((entry) => entry.endsWith('.json'))
+            .map((entry) => entry.slice(0, -'.json'.length));
+    }
+    catch (error) {
+        logger.warn('orchestration persistence: failed to list snapshot directory', { dir, error: summarizeError(error) });
+        return [];
+    }
+}
+export function writeWorkstreamSnapshot(projectRoot, workstream, completedResults) {
+    const json = serializeWorkstreamSnapshot(workstream, completedResults);
+    if (json === null)
+        return;
+    const path = snapshotPath(projectRoot, workstream.id);
+    try {
+        mkdirSync(orchestrationDir(projectRoot), { recursive: true });
+        writeFileSync(path, json, 'utf-8');
+    }
+    catch (error) {
+        logger.error('orchestration persistence: snapshot write failed', { path, error: summarizeError(error) });
+    }
+}
+/**
+ * Debounced trailing writer (250ms, exactly like wrfc-persistence.ts
+ * DEBOUNCE_MS), subscribing to engine lifecycle events. Returns an
+ * unsubscribe function that also flushes any pending timers.
+ */
+export function attachDebouncedWriter(projectRoot, getWorkstream, getCompletedResults, subscribe) {
+    const timers = new Map();
+    function scheduleWrite(workstreamId) {
+        const existing = timers.get(workstreamId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            timers.delete(workstreamId);
+            const workstream = getWorkstream(workstreamId);
+            if (!workstream)
+                return;
+            writeWorkstreamSnapshot(projectRoot, workstream, getCompletedResults(workstreamId));
+        }, DEBOUNCE_MS);
+        timer.unref?.();
+        timers.set(workstreamId, timer);
+    }
+    const unsubscribe = subscribe((event) => {
+        // 'dirty-tree-at-launch' (Wave 6, wo-F item 4) is engine-wide, not
+        // workstream-scoped — it has no workstreamId to schedule a write for.
+        if (event.type === 'dirty-tree-at-launch')
+            return;
+        scheduleWrite(event.workstreamId);
+    });
+    return () => {
+        unsubscribe();
+        for (const timer of timers.values())
+            clearTimeout(timer);
+        timers.clear();
+    };
+}