openplanr 1.13.2 → 1.14.0

package/dist/services/operate/engine.js

@@ -0,0 +1,1097 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadConfig } from '../config-service.js';
+import { advisorFailureGaps, buildAdvisorOperatingContext, configuredAdvisorProviderPolicy, createConfiguredStructuredAdapter, createOfflineAdvisorAdapter, dispatchOperatingAdvisors, ensureOperatingProviderConsent, } from './advisors.js';
+import { canonicalDigest, canonicalize } from './canonical.js';
+import { operatingProjectKey, validateOperatingConfiguration } from './config.js';
+import { consolidateOperatingResults } from './consolidation.js';
+import { OperatingEventStore } from './event-store.js';
+import { collectOperatingEvidence, evidenceProjectionSources, unqualifiedCommercialEvidenceGaps, } from './evidence.js';
+import { OperatingEvidenceCache } from './evidence-cache.js';
+import { evaluateEvidenceReadiness } from './evidence-readiness.js';
+import { nextCycleId } from './ids.js';
+import { applyJournalTransaction, prepareJournalTransaction, readJournal, rollbackJournalTransaction, } from './journal.js';
+import { reconcileOperatingDecisionDeadlines } from './lifecycle.js';
+import { withOperatingLock } from './lock-service.js';
+import { reconcileOperatingOutcomeFiles } from './outcomes.js';
+import { persistOperatingProjections } from './projection-persistence.js';
+import { assertOperatingArtifact, loadOperatingProtocol } from './protocol.js';
+import { maximumSensitivity } from './redaction.js';
+import { createOperatingRoutePlan, nextOperatingSpecOrdinal } from './routes.js';
+import { OPERATE_PROTOCOL_VERSION, OPERATE_SCHEMA_VERSION, OperateError, } from './types.js';
+import { assertOperatingProject, refreshOperatingWorkspaceManifest, resolveOperatingPaths, } from './workspace.js';
+const PRODUCT_VERSION = '1.14.0';
+function normalizeFocus(focus) {
+    const supported = new Set(['strategy', 'product', 'growth', 'operations', 'technology', 'all']);
+    const normalized = [...new Set((focus ?? []).map(String))]
+        .filter((value) => supported.has(value))
+        .sort();
+    return normalized.length > 0 ? normalized : ['all'];
+}
+function loadJson(target) {
+    return readFile(target, 'utf8').then((raw) => JSON.parse(raw));
+}
+async function snapshotWorkspace(projectRoot, localRoot) {
+    return refreshOperatingWorkspaceManifest(projectRoot, { localRoot });
+}
+async function readPreferences(projectRoot, localRoot) {
+    const paths = resolveOperatingPaths(projectRoot, { localRoot });
+    return loadJson(path.join(paths.localRoot, 'preferences.json')).catch(() => ({
+        runtime: 'auto',
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        sensitivityCeiling: 'internal',
+        evidenceTtlMs: 7 * 24 * 60 * 60 * 1_000,
+        enabledSources: [],
+    }));
+}
+function activeCycle(state) {
+    return (state.cycles.find((cycle) => !['closed', 'cancelled', 'failed'].includes(cycle.state)) ?? null);
+}
+function maximumOrdinal(records, prefix) {
+    return records.reduce((maximum, record) => {
+        const match = String(record.id ?? '').match(new RegExp(`^${prefix}-(\\d+)$`));
+        return Math.max(maximum, match ? Number(match[1]) : 0);
+    }, 0);
+}
+async function remapReadinessGaps(readiness, state) {
+    let ordinal = maximumOrdinal(state.dataGaps, 'GAP');
+    const remapped = {
+        ...readiness,
+        roles: readiness.roles.map((role) => ({
+            ...role,
+            gapId: role.gapId
+                ? (state.dataGaps.find((gap) => gap.cycleId === readiness.cycleId &&
+                    !['closed', 'superseded'].includes(String(gap.status)) &&
+                    Array.isArray(gap.affectedRoles) &&
+                    gap.affectedRoles.includes(role.roleId))?.id ?? `GAP-${String(++ordinal).padStart(3, '0')}`)
+                : null,
+        })),
+    };
+    return assertOperatingArtifact('operating-evidence-readiness', remapped);
+}
+function readinessGaps(readiness, decisionOwner, now) {
+    return readiness.roles
+        .filter((role) => role.gapId)
+        .map((role) => ({
+        kind: 'operating-data-gap',
+        schemaVersion: OPERATE_SCHEMA_VERSION,
+        protocolVersion: OPERATE_PROTOCOL_VERSION,
+        id: role.gapId,
+        cycleId: readiness.cycleId,
+        question: `What evidence is required for ${role.roleId}?`,
+        reason: role.missingEvidence.join('; ') || 'Minimum evidence was not available.',
+        unblocks: [],
+        affectedRoles: [role.roleId],
+        status: 'open',
+        owner: decisionOwner,
+        evidenceRefs: [...role.evidenceRefs],
+        createdAt: now,
+        updatedAt: now,
+    }));
+}
+function requiredOpenEvidenceRefs(state) {
+    const records = [
+        ...state.findings.filter((finding) => !['done', 'rejected', 'superseded'].includes(String(finding.status))),
+        ...state.decisions.filter((decision) => !['closed', 'superseded'].includes(String(decision.status))),
+        ...state.outcomes.filter((outcome) => ['pending', 'observing', 'inconclusive'].includes(String(outcome.status))),
+    ];
+    return [
+        ...new Set(records.flatMap((record) => Array.isArray(record.evidenceRefs)
+            ? record.evidenceRefs.filter((reference) => typeof reference === 'string')
+            : [])),
+    ].sort();
+}
+export function buildChairEvidence(evidence, results, now) {
+    const evidenceById = new Map(evidence.items.map((item) => [item.id, item]));
+    const synthetic = results.flatMap((result) => {
+        const evidenceRefs = [
+            ...new Set(result.proposals.flatMap((proposal) => proposal.evidenceRefs)),
+        ].sort();
+        const missingRefs = evidenceRefs.filter((reference) => !evidenceById.has(reference));
+        if (missingRefs.length > 0) {
+            throw new OperateError('E_OPERATE_EVIDENCE_REJECTED', `${result.roleId} advisor result cites unavailable evidence: ${missingRefs.join(', ')}.`);
+        }
+        const sensitivity = maximumSensitivity([
+            'internal',
+            ...evidenceRefs.map((reference) => evidenceById.get(reference)?.sensitivity ?? 'public'),
+        ]);
+        const bodies = [
+            {
+                id: `EVD-advisor-results-${result.roleId}-context`,
+                location: `${result.roleId}/context`,
+                body: {
+                    roleId: result.roleId,
+                    outcome: result.outcome,
+                    gaps: [...new Set(result.gaps)].sort(),
+                    conflicts: [...new Set(result.conflicts)].sort(),
+                },
+            },
+            ...result.proposals.map((proposal) => ({
+                id: `EVD-advisor-results-${result.roleId}-${proposal.proposalKey}`,
+                location: `${result.roleId}/proposals/${proposal.proposalKey}`,
+                body: {
+                    roleId: result.roleId,
+                    proposal: structuredClone(proposal),
+                },
+            })),
+        ];
+        return bodies.map(({ id, location, body }) => ({
+            id,
+            source: 'advisor-results',
+            location,
+            digest: canonicalDigest(body),
+            collectedAt: now,
+            observedFrom: now,
+            observedTo: now,
+            freshness: 'fresh',
+            sensitivity,
+            claimTypes: ['verified-advisor-result'],
+            summary: canonicalize(body),
+        }));
+    });
+    return {
+        ...evidence,
+        items: [...evidence.items, ...synthetic],
+        fingerprint: canonicalDigest({
+            source: evidence.fingerprint,
+            advisors: synthetic
+                .map(({ id, digest, sensitivity }) => ({ id, digest, sensitivity }))
+                .sort((left, right) => left.id.localeCompare(right.id)),
+        }),
+    };
+}
+const SENSITIVE_ROUTE_LANGUAGE = /\b(?:payment|billing|security|privacy|legal|tenant|isolation|destructive|delete|purge|credential|secret)\b/i;
+function containsSensitiveRouteProposal(results) {
+    return results.some((result) => result.proposals.some((proposal) => SENSITIVE_ROUTE_LANGUAGE.test(`${proposal.type} ${proposal.title} ${proposal.problem} ${proposal.proposal}`)));
+}
+async function createCycleManifest(input) {
+    return assertOperatingArtifact('operating-cycle-manifest', {
+        kind: 'operating-cycle-manifest',
+        schemaVersion: OPERATE_SCHEMA_VERSION,
+        protocolVersion: OPERATE_PROTOCOL_VERSION,
+        id: input.id,
+        state: input.state,
+        depth: input.depth,
+        focus: input.focus,
+        inputDigest: input.inputDigest,
+        enabledRoles: [...input.enabledRoles],
+        enabledProviders: [...input.enabledProviders],
+        createdAt: input.now,
+        updatedAt: input.now,
+        producer: {
+            product: 'openplanr',
+            version: PRODUCT_VERSION,
+            runtime: input.runtime,
+        },
+    });
+}
+async function appendLocked(store, lock, head, input) {
+    const event = await store.append({ ...input, expectedHead: head.hash });
+    const next = { sequence: event.sequence, hash: event.eventHash };
+    await lock.advanceEventHead(head, next);
+    return { event, head: next };
+}
+function remapConsolidation(state, findings, parked, decisions, gaps) {
+    let findingOrdinal = maximumOrdinal(state.findings, 'FND');
+    let decisionOrdinal = maximumOrdinal(state.decisions, 'DEC');
+    let gapOrdinal = maximumOrdinal(state.dataGaps, 'GAP');
+    const findingIds = new Map();
+    for (const finding of [...findings, ...parked]) {
+        findingIds.set(finding.id, `FND-${String(++findingOrdinal).padStart(3, '0')}`);
+    }
+    const remapFinding = (finding) => ({
+        ...finding,
+        id: findingIds.get(finding.id),
+        dependsOn: finding.dependsOn.map((dependency) => findingIds.get(dependency) ?? dependency),
+    });
+    return {
+        findings: findings.map(remapFinding),
+        parked: parked.map(remapFinding),
+        decisions: decisions.map((decision) => ({
+            ...decision,
+            id: `DEC-${String(++decisionOrdinal).padStart(3, '0')}`,
+        })),
+        gaps: gaps.map((gap) => ({
+            ...gap,
+            id: `GAP-${String(++gapOrdinal).padStart(3, '0')}`,
+        })),
+    };
+}
+function findingIdentity(value) {
+    const finding = value;
+    if (typeof finding.fingerprint === 'string' &&
+        /^sha256:[a-f0-9]{64}$/.test(finding.fingerprint)) {
+        return finding.fingerprint;
+    }
+    return canonicalDigest({
+        title: String(finding.title ?? '')
+            .trim()
+            .toLowerCase(),
+        lane: String(finding.lane ?? ''),
+        owner: String(finding.owner ?? ''),
+    });
+}
+function suppressRepeatedFindings(state, findings, cycleId) {
+    const priorByIdentity = new Map(state.findings
+        .filter((finding) => finding.cycleId !== cycleId)
+        .map((finding) => [findingIdentity(finding), finding]));
+    let suppressed = 0;
+    const retained = [];
+    for (const finding of findings) {
+        const prior = priorByIdentity.get(findingIdentity(finding));
+        if (!prior) {
+            retained.push(finding);
+            continue;
+        }
+        const priorEvidence = Array.isArray(prior.evidenceRefs)
+            ? [...prior.evidenceRefs].sort()
+            : [];
+        const currentEvidence = [...finding.evidenceRefs].sort();
+        if (canonicalDigest(priorEvidence) === canonicalDigest(currentEvidence)) {
+            suppressed += 1;
+            continue;
+        }
+        retained.push({
+            ...finding,
+            dependsOn: [...new Set([...finding.dependsOn, String(prior.id)])].sort(),
+        });
+    }
+    return { findings: retained, suppressed };
+}
+function committedCycleFindings(events, cycleId) {
+    return events
+        .filter((event) => event.type === 'finding.proposed' &&
+        event.cycleId === cycleId &&
+        event.payload.record &&
+        typeof event.payload.record === 'object')
+        .map((event) => structuredClone(event.payload.record));
+}
+function reconcileCycleFindings(events, cycleId, findings) {
+    const existing = committedCycleFindings(events, cycleId);
+    const existingByIdentity = new Map(existing.map((finding) => [findingIdentity(finding), finding]));
+    return findings.map((finding) => {
+        const prior = existingByIdentity.get(findingIdentity(finding));
+        if (!prior)
+            return finding;
+        return canonicalDigest([...prior.evidenceRefs].sort()) ===
+            canonicalDigest([...finding.evidenceRefs].sort())
+            ? prior
+            : finding;
+    });
+}
+function recordContent(value) {
+    return structuredClone(value);
+}
+async function persistedCycleEvidence(store, events, cycleId) {
+    const event = [...events]
+        .reverse()
+        .find((candidate) => candidate.cycleId === cycleId &&
+        candidate.type === 'evidence.collected' &&
+        typeof candidate.payload.recordDigest === 'string');
+    if (!event)
+        return null;
+    const record = await store.readRecord(event.payload.recordDigest);
+    if (record.recordType !== 'evidence-metadata') {
+        throw new OperateError('E_OPERATE_STATE_INVALID', `Cycle ${cycleId} evidence event references a ${record.recordType} record.`);
+    }
+    return assertOperatingArtifact('operating-evidence', record.content);
+}
+async function persistedCycleRoleResults(store, events, cycleId) {
+    const byRole = new Map();
+    for (const event of events) {
+        if (event.cycleId !== cycleId ||
+            event.type !== 'advisory.recorded' ||
+            typeof event.payload.recordDigest !== 'string') {
+            continue;
+        }
+        const record = await store.readRecord(event.payload.recordDigest);
+        if (record.recordType !== 'advisor-result') {
+            throw new OperateError('E_OPERATE_STATE_INVALID', `Cycle ${cycleId} advisory event references a ${record.recordType} record.`);
+        }
+        const result = await assertOperatingArtifact('operating-role-result', record.content);
+        (await loadOperatingProtocol()).validateOperatingRoleResultDigest(result);
+        if (result.cycleId !== cycleId) {
+            throw new OperateError('E_OPERATE_STATE_INVALID', `Advisor result ${result.roleId} belongs to another cycle.`);
+        }
+        byRole.set(result.roleId, result);
+    }
+    return [...byRole.values()].sort((left, right) => left.roleId.localeCompare(right.roleId));
+}
+/**
+ * Full evidence → advisors → deterministic consolidation lifecycle. All
+ * mutations are serialized under the process-identity lease; preview and
+ * dry-run never enter the mutating branch.
+ */
+export async function runOperatingCycle(input) {
+    const projectRoot = await assertOperatingProject(input.projectRoot);
+    const config = await validateOperatingConfiguration(projectRoot);
+    const paths = resolveOperatingPaths(projectRoot, { localRoot: input.localRoot });
+    const initializedWorkspace = await loadJson(paths.workspace);
+    await assertOperatingArtifact('operating-workspace-manifest', initializedWorkspace);
+    const preferences = await readPreferences(projectRoot, input.localRoot);
+    const store = new OperatingEventStore(projectRoot, { localRoot: input.localRoot });
+    const now = input.now ?? new Date();
+    const deadlineReconciliation = !input.preview && !input.dryRun
+        ? await reconcileOperatingDecisionDeadlines({
+            projectRoot,
+            localRoot: input.localRoot,
+            now,
+        })
+        : { transitioned: 0 };
+    const initial = await store.replay();
+    const initialState = await store.state();
+    const current = activeCycle(initialState);
+    const timestamp = now.toISOString();
+    if (input.reviewOnly) {
+        const persisted = initialState.cycles.at(-1);
+        if (!persisted) {
+            throw new OperateError('E_OPERATE_STATE_INVALID', 'Review-only mode requires at least one committed operating cycle.');
+        }
+        const persistedCycle = await assertOperatingArtifact('operating-cycle-manifest', persisted);
+        const reconciled = input.dryRun
+            ? { reconciled: 0, shipObserved: 0, state: initialState }
+            : await reconcileOperatingOutcomeFiles({
+                projectRoot,
+                localRoot: input.localRoot,
+            });
+        return {
+            preview: false,
+            dryRun: Boolean(input.dryRun),
+            cycle: persistedCycle,
+            provider: null,
+            state: reconciled.state,
+            modelCalls: 0,
+            warnings: [
+                `Review-only mode reconciled ${reconciled.reconciled} outcome observation(s) without evidence or model calls.`,
+                ...(deadlineReconciliation.transitioned > 0
+                    ? [
+                        `Marked ${deadlineReconciliation.transitioned} elapsed decision deadline(s) default-due without executing an action.`,
+                    ]
+                    : []),
+            ],
+        };
+    }
+    const resumableStates = new Set([
+        'preparing',
+        'collecting',
+        'advising',
+        'consolidating',
+        'blocked',
+    ]);
+    if (current && !resumableStates.has(current.state)) {
+        throw new OperateError('E_OPERATE_CYCLE_ACTIVE', `Operating cycle ${current.id} is already ${current.state}; close or cancel it before starting another.`);
+    }
+    const depth = input.depth ?? current?.depth ?? 'standard';
+    const focus = normalizeFocus(input.focus ?? current?.focus);
+    const resolvedRuntime = input.runtime && input.runtime !== 'auto' ? input.runtime : preferences.runtime;
+    const cycleStart = current
+        ? initial.events.find((event) => event.type === 'cycle.preparing' &&
+            event.cycleId === current.id &&
+            event.entityId === current.id)
+        : null;
+    if (current && !cycleStart) {
+        throw new OperateError('E_OPERATE_STATE_INVALID', `Operating cycle ${current.id} has no canonical preparing event.`);
+    }
+    const inputHead = cycleStart
+        ? {
+            sequence: cycleStart.sequence - 1,
+            hash: cycleStart.previousEventHash,
+        }
+        : initial.eventHead;
+    // Preview is intentionally machine-state-free: it does not require local
+    // component-root mappings and binds only a prospective digest. A committed
+    // cycle always snapshots the live roots at its actual start.
+    const workspace = input.preview
+        ? initializedWorkspace
+        : await snapshotWorkspace(projectRoot, input.localRoot);
+    const inputDigest = canonicalDigest({
+        workspaceDigest: workspace.workspaceDigest,
+        config: canonicalDigest(config),
+        eventHead: inputHead,
+        depth,
+        focus,
+        runtime: resolvedRuntime,
+    });
+    if (current && current.inputDigest !== inputDigest) {
+        throw new OperateError('E_OPERATE_CYCLE_INPUT_CONFLICT', `Operating cycle ${current.id} can resume only with its original workspace, configuration, depth, and focus.`, {
+            cycleId: current.id,
+            expectedInputDigest: current.inputDigest,
+            actualInputDigest: inputDigest,
+        });
+    }
+    const cycle = current
+        ? await assertOperatingArtifact('operating-cycle-manifest', current)
+        : await createCycleManifest({
+            id: nextCycleId(initialState),
+            state: 'preparing',
+            depth,
+            focus,
+            inputDigest,
+            enabledRoles: config.enabledRoles,
+            enabledProviders: config.enabledProviders,
+            runtime: resolvedRuntime,
+            now: timestamp,
+        });
+    if (input.preview) {
+        return {
+            preview: true,
+            dryRun: false,
+            cycle,
+            provider: null,
+            modelCalls: 0,
+            warnings: [],
+        };
+    }
+    const assertCycleWorkspace = async () => {
+        const observed = await snapshotWorkspace(projectRoot, input.localRoot);
+        if (observed.workspaceDigest !== workspace.workspaceDigest) {
+            throw new OperateError('E_OPERATE_HEAD_DIVERGED', 'Workspace revisions, branches, remotes, or material dirty fingerprints changed during the operating cycle.', {
+                expectedWorkspaceDigest: workspace.workspaceDigest,
+                actualWorkspaceDigest: observed.workspaceDigest,
+            });
+        }
+    };
+    const existingEvidence = current && current.state !== 'blocked'
+        ? await persistedCycleEvidence(store, initial.events, cycle.id)
+        : null;
+    const existingRoleResults = current
+        ? await persistedCycleRoleResults(store, initial.events, cycle.id)
+        : [];
+    const advisorContext = await buildAdvisorOperatingContext({
+        charterPath: paths.charter,
+        state: initialState,
+        cycleId: cycle.id,
+    });
+    const evaluate = async (persist) => {
+        await assertCycleWorkspace();
+        const evidence = existingEvidence ??
+            (await collectOperatingEvidence({
+                projectRoot,
+                cycleId: cycle.id,
+                workspace,
+                providers: config.enabledProviders,
+                sensitivityCeiling: preferences.sensitivityCeiling,
+                budgets: {
+                    ...config.budgets,
+                    maxItemBytes: Math.min(config.budgets.maxBytes, 256 * 1024),
+                },
+                localRoot: input.localRoot,
+                now,
+                incremental: depth === 'standard',
+                persistIncremental: persist && depth === 'standard',
+                requiredEvidenceRefs: requiredOpenEvidenceRefs(initialState),
+            }));
+        const evidenceGaps = await unqualifiedCommercialEvidenceGaps({
+            cycleId: cycle.id,
+            evidence,
+            owner: config.decisionOwner,
+            now: timestamp,
+        });
+        const nonChair = config.enabledRoles.filter((role) => role !== 'chair');
+        let readiness = await evaluateEvidenceReadiness({
+            cycleId: cycle.id,
+            evidence,
+            enabledRoles: nonChair,
+            now,
+        });
+        readiness = await remapReadinessGaps(readiness, initialState);
+        let adapter = input.adapter ?? null;
+        let provider = null;
+        const resolveAdapter = async () => {
+            if (adapter)
+                return adapter;
+            if (input.offline) {
+                adapter = createOfflineAdvisorAdapter();
+                return adapter;
+            }
+            adapter = await createConfiguredStructuredAdapter(projectRoot, {
+                quiet: input.quiet,
+            });
+            const openPlanrConfig = await loadConfig(projectRoot);
+            const consent = await ensureOperatingProviderConsent({
+                projectRoot,
+                provider: configuredAdvisorProviderPolicy({
+                    config: openPlanrConfig,
+                    adapterId: adapter.id,
+                    runtime: resolvedRuntime,
+                }),
+                confirmed: Boolean(input.confirmed),
+                persist,
+                now: timestamp,
+            });
+            provider = consent.manifest;
+            return adapter;
+        };
+        const existingByRole = new Map(existingRoleResults.map((result) => [result.roleId, result]));
+        const missingNonChair = readiness.roles.filter((role) => role.roleId !== 'chair' && !existingByRole.has(role.roleId));
+        const runnableMissingNonChair = missingNonChair.filter((role) => role.modelCallAllowed);
+        if (input.deferAdvisors && runnableMissingNonChair.length > 0) {
+            return {
+                preview: false,
+                dryRun: false,
+                cycle,
+                evidence,
+                readiness,
+                roleResults: existingRoleResults.filter((result) => result.roleId !== 'chair'),
+                findings: [],
+                decisions: [],
+                gaps: readinessGaps(readiness, config.decisionOwner, timestamp),
+                routes: [],
+                provider: null,
+                modelCalls: 0,
+                warnings: ['Native advisor execution is required before consolidation.'],
+                nativeHandoff: {
+                    phase: 'advisors',
+                    cycleId: cycle.id,
+                    evidenceDigest: evidence.fingerprint,
+                    roles: runnableMissingNonChair.map((role) => role.roleId).sort(),
+                },
+            };
+        }
+        await assertCycleWorkspace();
+        const first = missingNonChair.length > 0
+            ? await dispatchOperatingAdvisors({
+                cycleId: cycle.id,
+                evidence,
+                readiness: { ...readiness, roles: missingNonChair },
+                context: advisorContext,
+                adapter: await resolveAdapter(),
+                depth,
+                runtime: resolvedRuntime,
+            })
+            : { results: [], modelCalls: 0, blocked: false, skipped: [], failed: [] };
+        let roleResults = [
+            ...existingRoleResults.filter((result) => result.roleId !== 'chair'),
+            ...first.results,
+        ];
+        let modelCalls = first.modelCalls;
+        let blocked = first.blocked;
+        const skipped = [...first.skipped];
+        const failed = [...first.failed];
+        let consolidationEvidence = evidence;
+        if (config.enabledRoles.includes('chair')) {
+            const chairEvidence = buildChairEvidence(evidence, roleResults, timestamp);
+            consolidationEvidence = chairEvidence;
+            let chairReadiness = await evaluateEvidenceReadiness({
+                cycleId: cycle.id,
+                evidence: chairEvidence,
+                enabledRoles: ['chair'],
+                now,
+            });
+            chairReadiness = await remapReadinessGaps(chairReadiness, {
+                ...initialState,
+                dataGaps: [
+                    ...initialState.dataGaps,
+                    ...readiness.roles
+                        .filter((role) => role.gapId)
+                        .map((role) => ({ id: role.gapId, status: 'open' })),
+                ],
+            });
+            readiness = {
+                ...readiness,
+                roles: [...readiness.roles, ...chairReadiness.roles],
+            };
+            await assertOperatingArtifact('operating-evidence-readiness', readiness);
+            await assertCycleWorkspace();
+            const persistedChair = existingByRole.get('chair');
+            const runnableChair = chairReadiness.roles.filter((role) => role.modelCallAllowed && !persistedChair);
+            if (input.deferAdvisors && runnableChair.length > 0) {
+                return {
+                    preview: false,
+                    dryRun: false,
+                    cycle,
+                    evidence,
+                    readiness,
+                    roleResults,
+                    findings: [],
+                    decisions: [],
+                    gaps: readinessGaps(readiness, config.decisionOwner, timestamp),
+                    routes: [],
+                    provider: null,
+                    modelCalls,
+                    warnings: ['Native Chair execution is required before consolidation.'],
+                    nativeHandoff: {
+                        phase: 'chair',
+                        cycleId: cycle.id,
+                        evidenceDigest: evidence.fingerprint,
+                        roles: ['chair'],
+                    },
+                };
+            }
+            const chair = persistedChair
+                ? {
+                    results: [persistedChair],
+                    modelCalls: 0,
+                    blocked: false,
+                    skipped: [],
+                    failed: [],
+                }
+                : await dispatchOperatingAdvisors({
+                    cycleId: cycle.id,
+                    evidence: chairEvidence,
+                    readiness: chairReadiness,
+                    context: advisorContext,
+                    adapter: await resolveAdapter(),
+                    depth,
+                    runtime: resolvedRuntime,
+                });
+            roleResults = [...roleResults, ...chair.results];
+            modelCalls += chair.modelCalls;
+            skipped.push(...chair.skipped);
+            failed.push(...chair.failed);
+            blocked ||= chair.blocked || chairReadiness.roles.some((role) => !role.modelCallAllowed);
+        }
+        const technologyRiskReady = readiness.roles.some((role) => role.roleId === 'technology-risk' && role.modelCallAllowed);
+        const technologyRiskFailed = failed.some((entry) => entry.roleId === 'technology-risk');
+        const sensitiveRouteBlocked = containsSensitiveRouteProposal(roleResults) && (!technologyRiskReady || technologyRiskFailed);
+        blocked ||= sensitiveRouteBlocked;
+        const consolidated = await consolidateOperatingResults({
+            cycleId: cycle.id,
+            results: roleResults,
+            evidence: consolidationEvidence,
+            config,
+            now: timestamp,
+            existingGapCount: initialState.dataGaps.length,
+        });
+        const failureGaps = await advisorFailureGaps({
+            cycleId: cycle.id,
+            failed,
+            readiness,
+            owner: config.decisionOwner,
+            now: timestamp,
+        });
+        const surfacedDedup = suppressRepeatedFindings(initialState, consolidated.findings, cycle.id);
+        const overflowDedup = suppressRepeatedFindings(initialState, consolidated.criticalOverflow, cycle.id);
+        const parkedDedup = suppressRepeatedFindings(initialState, consolidated.parked, cycle.id);
+        const suppressedFindings = surfacedDedup.suppressed + overflowDedup.suppressed + parkedDedup.suppressed;
+        const criticalOverflowCount = overflowDedup.findings.length;
+        blocked ||= criticalOverflowCount > 0;
+        const remapped = remapConsolidation({
+            ...initialState,
+            dataGaps: [
+                ...initialState.dataGaps,
+                ...readiness.roles
+                    .filter((role) => role.gapId)
+                    .map((role) => ({ id: role.gapId, status: 'open' })),
+            ],
+        }, [...surfacedDedup.findings, ...overflowDedup.findings], parkedDedup.findings, consolidated.decisions, [...evidenceGaps, ...consolidated.gaps, ...failureGaps]);
+        const warnings = [
+            ...evidence.warnings,
+            ...(evidenceGaps.length > 0
+                ? [
+                    `${evidenceGaps.length} numeric commercial evidence item(s) require query and observation-window identity.`,
+                ]
+                : []),
+            ...skipped.map((entry) => `${entry.roleId} not evaluated: ${entry.reason}`),
+            ...failed.map((entry) => `${entry.roleId} failed: ${entry.message}`),
+            ...(sensitiveRouteBlocked
+                ? [
+                    'Sensitive payment/security/privacy/legal/tenant/destructive routing is blocked until technology-risk completes.',
+                ]
+                : []),
+            ...(criticalOverflowCount > 0
+                ? [
+                    `${criticalOverflowCount} verified critical finding(s) exceeded a configured cap; the cycle is blocked instead of parking them.`,
+                ]
+                : []),
+            ...(suppressedFindings > 0
+                ? [
+                    `${suppressedFindings} unchanged cross-cycle finding(s) were suppressed instead of duplicated.`,
+                ]
+                : []),
+        ];
+        if (blocked)
+            warnings.push('The cycle is blocked by required advisor evidence or failure.');
+        const reconciledFindings = reconcileCycleFindings(initial.events, cycle.id, remapped.findings);
+        const reconciledParked = reconcileCycleFindings(initial.events, cycle.id, remapped.parked);
+        return {
+            preview: false,
+            dryRun: !persist,
+            cycle,
+            evidence,
+            readiness,
+            roleResults,
+            findings: [...reconciledFindings, ...reconciledParked],
+            decisions: remapped.decisions,
+            gaps: [...readinessGaps(readiness, config.decisionOwner, timestamp), ...remapped.gaps],
+            routes: [],
+            provider,
+            modelCalls,
+            warnings,
+        };
+    };
+    if (input.dryRun)
+        return evaluate(false);
+    return withOperatingLock(projectRoot, {
+        projectKey: operatingProjectKey(projectRoot),
+        expectedEventHead: initial.eventHead,
+        currentEventHead: initial.eventHead,
+        localRoot: input.localRoot,
+    }, async (lock) => {
+        const latest = await store.replay();
+        if (latest.eventHead.sequence !== initial.eventHead.sequence ||
+            latest.eventHead.hash !== initial.eventHead.hash) {
+            throw new OperateError('E_OPERATE_HEAD_DIVERGED', 'Operating state changed while preparing the cycle.');
+        }
+        let head = initial.eventHead;
+        let started = Boolean(current);
+        let phase = current?.state ?? null;
+        const correlationId = randomUUID();
+        try {
+            await assertCycleWorkspace();
+            if (!current) {
+                const prepared = await appendLocked(store, lock, head, {
+                    type: 'cycle.preparing',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: { record: cycle },
+                });
+                started = true;
+                head = prepared.head;
+                phase = 'preparing';
+            }
+            if (phase === 'preparing' || phase === 'blocked') {
+                const collecting = await appendLocked(store, lock, head, {
+                    type: 'cycle.collecting',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: {},
+                });
+                head = collecting.head;
+                phase = 'collecting';
+            }
+            const evaluated = await evaluate(true);
+            await assertCycleWorkspace();
+            const evidence = evaluated.evidence;
+            if (phase === 'collecting') {
+                if (!existingEvidence) {
+                    const evidenceRecord = await store.putRecord('evidence-metadata', recordContent(evidence), { correlationId, createdAt: timestamp });
+                    const cache = new OperatingEvidenceCache(resolveOperatingPaths(projectRoot, { localRoot: input.localRoot }).evidence, preferences.sensitivityCeiling);
+                    await cache.put(evidence.fingerprint.slice('sha256:'.length), evidence, preferences.evidenceTtlMs, now);
+                    const evidenceEvent = await appendLocked(store, lock, head, {
+                        type: 'evidence.collected',
+                        cycleId: cycle.id,
+                        entityId: cycle.id,
+                        correlationId,
+                        evidenceRefs: evidence.items.map((item) => item.id),
+                        payload: {
+                            recordDigest: evidenceRecord.digest,
+                            sources: evidenceProjectionSources(evidence),
+                        },
+                    });
+                    head = evidenceEvent.head;
+                }
+                const advising = await appendLocked(store, lock, head, {
+                    type: 'cycle.advising',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: {},
+                });
+                head = advising.head;
+                phase = 'advising';
+            }
+            if (phase === 'advising' && evaluated.nativeHandoff) {
+                const state = await store.state();
+                await store.writeCheckpoint(state);
+                await persistOperatingProjections({
+                    projectRoot,
+                    localRoot: input.localRoot,
+                    state,
+                    revalidateEventHead: async () => (await store.replay()).eventHead,
+                });
+                return { ...evaluated, state };
+            }
+            if (phase === 'advising') {
+                const recordedRoles = new Set(existingRoleResults.map((result) => result.roleId));
+                for (const result of evaluated.roleResults ?? []) {
+                    if (recordedRoles.has(result.roleId))
+                        continue;
+                    const record = await store.putRecord('advisor-result', recordContent(result), {
+                        correlationId,
+                        createdAt: timestamp,
+                    });
+                    const appended = await appendLocked(store, lock, head, {
+                        type: 'advisory.recorded',
+                        cycleId: cycle.id,
+                        entityId: `${cycle.id}-${result.roleId}`,
+                        correlationId,
+                        evidenceRefs: result.proposals.flatMap((proposal) => proposal.evidenceRefs),
+                        payload: { recordDigest: record.digest },
+                    });
+                    head = appended.head;
+                }
+                const existingGapIds = new Set(initialState.dataGaps.filter((gap) => gap.cycleId === cycle.id).map((gap) => gap.id));
+                for (const gap of evaluated.gaps ?? []) {
+                    if (existingGapIds.has(gap.id))
+                        continue;
+                    await assertOperatingArtifact('operating-data-gap', gap);
+                    await store.putRecord('data-gap', recordContent(gap), {
+                        correlationId,
+                        createdAt: timestamp,
+                    });
+                    const appended = await appendLocked(store, lock, head, {
+                        type: 'gap.open',
+                        cycleId: cycle.id,
+                        entityId: gap.id,
+                        correlationId,
+                        evidenceRefs: gap.evidenceRefs,
+                        payload: { record: gap },
+                    });
+                    head = appended.head;
+                }
+            }
+            if (phase === 'advising' &&
+                evaluated.warnings.some((warning) => warning.includes('cycle is blocked'))) {
+                const blocked = await appendLocked(store, lock, head, {
+                    type: 'cycle.blocked',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: { patch: { health: 'blocked' }, warnings: evaluated.warnings },
+                });
+                head = blocked.head;
+                const state = await store.state();
+                await store.writeCheckpoint(state);
+                await persistOperatingProjections({
+                    projectRoot,
+                    localRoot: input.localRoot,
+                    state,
+                    revalidateEventHead: async () => (await store.replay()).eventHead,
+                });
+                return { ...evaluated, state };
+            }
+            if (phase === 'advising') {
+                const consolidating = await appendLocked(store, lock, head, {
+                    type: 'cycle.consolidating',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: {},
+                });
+                head = consolidating.head;
+                phase = 'consolidating';
+            }
+            const existingFindingIds = new Set(initialState.findings
+                .filter((finding) => finding.cycleId === cycle.id)
+                .map((finding) => finding.id));
+            for (const finding of evaluated.findings ?? []) {
+                if (existingFindingIds.has(finding.id))
+                    continue;
+                await store.putRecord('finding', recordContent(finding), {
+                    correlationId,
+                    createdAt: timestamp,
+                });
+                const appended = await appendLocked(store, lock, head, {
+                    type: 'finding.proposed',
+                    cycleId: cycle.id,
+                    entityId: finding.id,
+                    correlationId,
+                    evidenceRefs: finding.evidenceRefs,
+                    payload: { record: finding },
+                });
+                head = appended.head;
+            }
+            const existingDecisionQuestions = new Set(initialState.decisions
+                .filter((decision) => decision.cycleId === cycle.id)
+                .map((decision) => String(decision.question ?? '')));
+            for (const decision of evaluated.decisions ?? []) {
+                if (existingDecisionQuestions.has(decision.question))
+                    continue;
+                await store.putRecord('decision', recordContent(decision), {
+                    correlationId,
+                    createdAt: timestamp,
+                });
+                const appended = await appendLocked(store, lock, head, {
+                    type: 'decision.open',
+                    cycleId: cycle.id,
+                    entityId: decision.id,
+                    correlationId,
+                    evidenceRefs: decision.evidenceRefs,
+                    payload: { record: decision },
+                });
+                head = appended.head;
+            }
+            const routeBase = await store.state();
+            const providerDigest = evaluated.provider?.policyDigest ?? canonicalDigest({ provider: 'offline' });
+            const routes = [];
+            let routeOrdinal = maximumOrdinal(routeBase.routes, 'ACT');
+            let specOrdinal = await nextOperatingSpecOrdinal(projectRoot);
+            const existingRoutedFindingIds = new Set(initial.events
+                .filter((event) => event.type === 'route.proposed' &&
+                event.payload.record &&
+                typeof event.payload.record === 'object')
+                .flatMap((event) => {
+                const record = event.payload.record;
+                return (record.actions ?? [])
+                    .map((action) => action.findingId)
+                    .filter((findingId) => Boolean(findingId));
+            }));
+            for (const finding of (evaluated.findings ?? []).filter((candidate) => !candidate.parked && !existingRoutedFindingIds.has(candidate.id))) {
+                const isDev = finding.lane === 'DEV';
+                routes.push(await createOperatingRoutePlan({
+                    projectRoot,
+                    cycleId: cycle.id,
+                    finding,
+                    config,
+                    workspace,
+                    eventHead: head,
+                    evidenceDigest: evidence.fingerprint,
+                    providerDigest,
+                    sequence: ++routeOrdinal,
+                    localRoot: input.localRoot,
+                    ...(isDev ? { specId: `SPEC-${String(specOrdinal++).padStart(3, '0')}` } : {}),
+                    now: timestamp,
+                }));
+            }
+            if (routes.length > 0) {
+                await assertCycleWorkspace();
+                for (const route of routes) {
+                    const relativePath = `.planr/operate/routes/${route.id}.json`;
+                    const content = `${canonicalize(route)}\n`;
+                    const transactionId = `TXN-${cycle.id}-${route.id}-proposal`;
+                    const transactionRoot = path.join(resolveOperatingPaths(projectRoot, { localRoot: input.localRoot }).transactions, transactionId);
+                    const manifestPath = path.join(transactionRoot, 'journal.json');
+                    const existingBytes = await readFile(path.join(projectRoot, relativePath), 'utf8').catch((error) => {
+                        if (error.code === 'ENOENT')
+                            return null;
+                        throw error;
+                    });
+                    const journal = existingBytes === null
+                        ? await prepareJournalTransaction(projectRoot, {
+                            writes: [
+                                {
+                                    relativePath,
+                                    operation: 'create',
+                                    content,
+                                },
+                            ],
+                            eventHead: head,
+                            previewDigest: route.previewDigest,
+                            transactionId,
+                            localRoot: input.localRoot,
+                        })
+                        : {
+                            root: transactionRoot,
+                            manifestPath,
+                            record: await readJournal(manifestPath),
+                        };
+                    if (existingBytes !== null) {
+                        if (existingBytes !== content ||
+                            journal.record.state !== 'committed' ||
+                            journal.record.previewDigest !== route.previewDigest) {
+                            throw new OperateError('E_OPERATE_TRANSACTION_INVALID', `Orphaned route proposal ${route.id} does not match its committed journal.`);
+                        }
+                    }
+                    else {
+                        await applyJournalTransaction(projectRoot, journal, {
+                            currentEventHead: head,
+                            revalidateEventHead: async () => (await store.replay()).eventHead,
+                        });
+                    }
+                    try {
+                        await store.putRecord('route', recordContent(route), {
+                            correlationId,
+                            createdAt: timestamp,
+                        });
+                        const appended = await appendLocked(store, lock, head, {
+                            type: 'route.proposed',
+                            cycleId: cycle.id,
+                            entityId: route.id,
+                            correlationId,
+                            evidenceRefs: route.actions.flatMap((action) => action.evidenceRefs),
+                            payload: { record: route },
+                        });
+                        head = appended.head;
+                    }
+                    catch (error) {
+                        await rollbackJournalTransaction(projectRoot, journal).catch(() => undefined);
+                        throw error;
+                    }
+                }
+            }
+            const quiet = (evaluated.findings?.length ?? 0) === 0 &&
+                (evaluated.decisions?.length ?? 0) === 0 &&
+                (evaluated.gaps?.length ?? 0) === 0;
+            const health = quiet ? 'quiet' : evaluated.warnings.length > 0 ? 'partial' : 'normal';
+            const reviewable = await appendLocked(store, lock, head, {
+                type: 'cycle.reviewable',
+                cycleId: cycle.id,
+                entityId: cycle.id,
+                correlationId,
+                payload: {
+                    patch: {
+                        health,
+                    },
+                    warnings: evaluated.warnings,
+                },
+            });
+            head = reviewable.head;
+            if (quiet) {
+                const closed = await appendLocked(store, lock, head, {
+                    type: 'cycle.closed',
+                    cycleId: cycle.id,
+                    entityId: cycle.id,
+                    correlationId,
+                    payload: {
+                        patch: {
+                            health,
+                            completedAt: timestamp,
+                        },
+                    },
+                });
+                head = closed.head;
+            }
+            const state = await store.state();
+            await store.writeCheckpoint(state);
+            await persistOperatingProjections({
+                projectRoot,
+                localRoot: input.localRoot,
+                state,
+                revalidateEventHead: async () => (await store.replay()).eventHead,
+            });
+            await mkdir(resolveOperatingPaths(projectRoot).cycles, {
+                recursive: true,
+                mode: 0o700,
+            });
+            return { ...evaluated, routes, state };
+        }
+        catch (error) {
+            if (started) {
+                const currentHead = await store.replay();
+                try {
+                    const blockedByCriticalCap = error instanceof OperateError && error.code === 'E_OPERATE_CRITICAL_CAP';
+                    const failed = await appendLocked(store, lock, currentHead.eventHead, {
+                        type: blockedByCriticalCap ? 'cycle.blocked' : 'cycle.failed',
+                        cycleId: cycle.id,
+                        entityId: cycle.id,
+                        correlationId,
+                        payload: {
+                            patch: { health: 'blocked' },
+                            errorCode: error instanceof OperateError ? error.code : 'E_OPERATE_STATE_INVALID',
+                            ...(blockedByCriticalCap ? { details: error.details } : {}),
+                        },
+                    });
+                    head = failed.head;
+                    const failedState = await store.state();
+                    await store.writeCheckpoint(failedState);
+                    await persistOperatingProjections({
+                        projectRoot,
+                        localRoot: input.localRoot,
+                        state: failedState,
+                        revalidateEventHead: async () => (await store.replay()).eventHead,
+                    });
+                }
+                catch {
+                    // Preserve the original failure; integrity diagnostics will expose
+                    // any inability to append the terminal audit event.
+                }
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=engine.js.map