@claude-flow/cli 3.32.24 → 3.32.26

package/dist/src/services/flywheel-transaction.js

@@ -0,0 +1,378 @@
+/**
+ * ADR-322A promotion transaction.
+ *
+ * A single atomic state file is the authority for active champion, receipt
+ * consumption, lineage head, and serving epoch. Cross-process mutation is
+ * serialized with an O_EXCL lock; atomic rename commits all authoritative state
+ * at once. Runtime policy materialization is derived and recoverable.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { applyChampionParams } from '../config/harness-feedback-applier.js';
+import { GENESIS_LEDGER_HEAD, canonicalizeJcs, sha256Ref, uuidV7, verifyFlywheelReceipt, } from './flywheel-receipt.js';
+const STATE_VERSION = 1;
+const STATE_DIR = ['.claude-flow', 'flywheel-v1'];
+const STATE_FILE = 'transaction-state.json';
+const LOCK_FILE = 'transaction-state.lock';
+const RECEIPTS_DIR = 'receipts';
+const LOCK_TIMEOUT_MS = 10_000;
+const LOCK_STALE_MS = 60_000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function stateDir(root) {
+    return path.join(root, ...STATE_DIR);
+}
+function statePath(root) {
+    return path.join(stateDir(root), STATE_FILE);
+}
+function lockPath(root) {
+    return path.join(stateDir(root), LOCK_FILE);
+}
+function receiptDir(root) {
+    return path.join(stateDir(root), RECEIPTS_DIR);
+}
+function assertSafeFile(file) {
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            throw new Error(`refusing symlink: ${file}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+function ensureDir(root) {
+    fs.mkdirSync(receiptDir(root), { recursive: true, mode: 0o700 });
+    assertSafeFile(statePath(root));
+    assertSafeFile(lockPath(root));
+}
+function emptyState() {
+    return {
+        version: STATE_VERSION,
+        activeChampionRef: null,
+        activePolicy: null,
+        activeGateVersion: null,
+        activePolicySchemaVersion: null,
+        activeSafetyEnvelopeRef: null,
+        ledgerHead: GENESIS_LEDGER_HEAD,
+        servingEpoch: 0,
+        materializedServingEpoch: 0,
+        servedChampionRef: null,
+        receiptStates: {},
+        commits: [],
+    };
+}
+export function readFlywheelTransactionState(root) {
+    try {
+        assertSafeFile(statePath(root));
+        const parsed = JSON.parse(fs.readFileSync(statePath(root), 'utf8'));
+        if (parsed.version !== STATE_VERSION || !parsed.receiptStates || !Array.isArray(parsed.commits))
+            return emptyState();
+        return parsed;
+    }
+    catch {
+        return emptyState();
+    }
+}
+function atomicWriteJson(file, value) {
+    assertSafeFile(file);
+    const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+    const fd = fs.openSync(tmp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+    try {
+        fs.writeFileSync(fd, `${canonicalizeJcs(value)}\n`, 'utf8');
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, file);
+    const dirFd = fs.openSync(path.dirname(file), fs.constants.O_RDONLY);
+    try {
+        fs.fsyncSync(dirFd);
+    }
+    finally {
+        fs.closeSync(dirFd);
+    }
+}
+async function withStateLock(root, fn) {
+    ensureDir(root);
+    const lock = lockPath(root);
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const fd = fs.openSync(lock, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+            fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }), 'utf8');
+            fs.closeSync(fd);
+            try {
+                return await fn();
+            }
+            finally {
+                try {
+                    fs.unlinkSync(lock);
+                }
+                catch { /* lock already gone */ }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                const stat = fs.lstatSync(lock);
+                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                    fs.unlinkSync(lock);
+                    continue;
+                }
+            }
+            catch { /* raced with owner */ }
+            if (Date.now() >= deadline)
+                throw new Error('timed out acquiring flywheel transaction lock');
+            await delay(5);
+        }
+    }
+}
+function validateReceiptId(receiptId) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(receiptId))
+        throw new Error('invalid receipt ID');
+}
+function receiptPath(root, receiptId) {
+    validateReceiptId(receiptId);
+    return path.join(receiptDir(root), `${receiptId.slice('sha256:'.length)}.json`);
+}
+export function readFlywheelReceipt(root, receiptId) {
+    try {
+        const file = receiptPath(root, receiptId);
+        assertSafeFile(file);
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function registerFlywheelReceipt(root, receipt, now = Date.now()) {
+    ensureDir(root);
+    validateReceiptId(receipt.payload.receiptId);
+    const file = receiptPath(root, receipt.payload.receiptId);
+    if (!fs.existsSync(file))
+        atomicWriteJson(file, receipt);
+    return withStateLock(root, () => {
+        const state = readFlywheelTransactionState(root);
+        const existing = state.receiptStates[receipt.payload.receiptId];
+        if (existing)
+            return existing;
+        const record = {
+            receiptId: receipt.payload.receiptId,
+            status: 'evaluated',
+            registeredAt: now,
+            promotedAt: null,
+            promotionTransactionId: null,
+        };
+        state.receiptStates[receipt.payload.receiptId] = record;
+        atomicWriteJson(statePath(root), state);
+        return record;
+    });
+}
+function materialize(root, state, now, applyFn) {
+    if (!state.activeChampionRef || !state.activePolicy)
+        return { applied: false, reason: 'no active champion' };
+    const previous = state.servedChampionRef;
+    const apply = applyFn ?? ((projectRoot, policy, championRef, prior, appliedAt) => applyChampionParams(projectRoot, {
+        championId: championRef,
+        params: policy,
+        layer: 'repo/local',
+        previous: prior,
+        now: appliedAt,
+    }));
+    return apply(root, state.activePolicy, state.activeChampionRef, previous, now);
+}
+export async function recoverFlywheelMaterialization(root, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const before = readFlywheelTransactionState(root);
+    if (!before.activeChampionRef || before.servingEpoch === before.materializedServingEpoch) {
+        return { success: true, idempotent: true, reason: 'materialization current', materialized: true };
+    }
+    const applied = materialize(root, before, now, opts.applyFn);
+    if (!applied.applied && applied.reason !== 'already active') {
+        return {
+            success: false,
+            idempotent: false,
+            reason: 'promotion committed; materialization pending',
+            championRef: before.activeChampionRef,
+            servingEpoch: before.servingEpoch,
+            materialized: false,
+            materializeReason: applied.reason,
+        };
+    }
+    await withStateLock(root, () => {
+        const state = readFlywheelTransactionState(root);
+        if (state.activeChampionRef === before.activeChampionRef && state.servingEpoch === before.servingEpoch) {
+            state.materializedServingEpoch = state.servingEpoch;
+            state.servedChampionRef = state.activeChampionRef;
+            atomicWriteJson(statePath(root), state);
+        }
+    });
+    return {
+        success: true,
+        idempotent: !applied.applied,
+        reason: 'materialized',
+        championRef: before.activeChampionRef,
+        servingEpoch: before.servingEpoch,
+        materialized: true,
+    };
+}
+export async function promoteFlywheelCandidate(root, receiptId, options) {
+    if (!options.confirm)
+        return { success: false, idempotent: false, reason: 'explicit confirmation required' };
+    if (!options.trustedPublicKeys?.size) {
+        return { success: false, idempotent: false, reason: 'at least one trusted receipt signer is required' };
+    }
+    const receipt = readFlywheelReceipt(root, receiptId);
+    if (!receipt)
+        return { success: false, idempotent: false, reason: 'receipt not found' };
+    const verification = verifyFlywheelReceipt(receipt, options.trustedPublicKeys);
+    if (!verification.valid) {
+        return { success: false, idempotent: false, reason: `receipt verification failed: ${verification.errors.join(', ')}` };
+    }
+    const now = options.now ?? Date.now();
+    const transaction = await withStateLock(root, () => {
+        const state = readFlywheelTransactionState(root);
+        const receiptState = state.receiptStates[receiptId];
+        if (!receiptState)
+            return { success: false, idempotent: false, reason: 'receipt is not registered' };
+        if (receiptState.status === 'consumed' && receiptState.promotionTransactionId) {
+            const prior = state.commits.find((c) => c.transactionId === receiptState.promotionTransactionId);
+            return {
+                success: true,
+                idempotent: true,
+                reason: 'already promoted',
+                transactionId: prior?.transactionId,
+                receiptId,
+                championRef: prior?.candidateId ?? state.activeChampionRef ?? undefined,
+                ledgerHead: state.ledgerHead,
+                servingEpoch: prior?.servingEpoch ?? state.servingEpoch,
+            };
+        }
+        if (receiptState.status !== 'evaluated' || receiptState.promotedAt !== null) {
+            return { success: false, idempotent: false, reason: `receipt state is ${receiptState.status}` };
+        }
+        if (receipt.payload.decision !== 'accepted')
+            return { success: false, idempotent: false, reason: 'receipt decision is not accepted' };
+        if (Date.parse(receipt.payload.expiresAt) <= now)
+            return { success: false, idempotent: false, reason: 'receipt expired' };
+        if (state.activeChampionRef === null) {
+            state.activeChampionRef = receipt.payload.baselineRef;
+            state.activeGateVersion = receipt.payload.gateVersion;
+            state.activePolicySchemaVersion = receipt.payload.policySchemaVersion;
+            state.activeSafetyEnvelopeRef = receipt.payload.safetyEnvelopeRef;
+        }
+        if (state.activeChampionRef !== receipt.payload.baselineRef)
+            return { success: false, idempotent: false, reason: 'stale baseline' };
+        if (state.ledgerHead !== receipt.payload.expectedLedgerHead)
+            return { success: false, idempotent: false, reason: 'stale ledger head' };
+        if (state.activeGateVersion !== receipt.payload.gateVersion)
+            return { success: false, idempotent: false, reason: 'gate version changed' };
+        if (state.activePolicySchemaVersion !== receipt.payload.policySchemaVersion)
+            return { success: false, idempotent: false, reason: 'policy schema changed' };
+        if (state.activeSafetyEnvelopeRef !== receipt.payload.safetyEnvelopeRef)
+            return { success: false, idempotent: false, reason: 'safety envelope changed' };
+        if (receipt.payload.proposerSubstitution
+            && !options.allowedProposerSubstitutions?.has(receipt.payload.proposerSubstitution))
+            return { success: false, idempotent: false, reason: 'proposer substitution is evaluation-only' };
+        const verificationByTerm = new Map(receipt.payload.termVerification.map((term) => [term.term, term]));
+        for (const [term, passed] of Object.entries(receipt.payload.gates)) {
+            if (!passed)
+                continue;
+            const evidence = verificationByTerm.get(term);
+            if (!evidence)
+                return { success: false, idempotent: false, reason: `missing verification for gate: ${term}` };
+            if (evidence.verification === 'trusted-assertion'
+                && (!evidence.attestor || !options.approvedAttestors?.has(evidence.attestor)))
+                return { success: false, idempotent: false, reason: `unapproved evidence attestor for gate: ${term}` };
+        }
+        if (options.faultAt === 'before-commit')
+            throw new Error('fault injection: before-commit');
+        const transactionId = uuidV7(now);
+        const commitCore = {
+            transactionId,
+            receiptId,
+            lineageId: receipt.payload.lineageId,
+            sequence: state.commits.length + 1,
+            previousLedgerHead: state.ledgerHead,
+            baselineRef: receipt.payload.baselineRef,
+            candidateId: receipt.payload.candidateId,
+            servingEpoch: state.servingEpoch + 1,
+            proposer: receipt.payload.effectiveProposer,
+            ...(receipt.payload.proposerSubstitution ? { proposerSubstitution: receipt.payload.proposerSubstitution } : {}),
+            promotedAt: now,
+        };
+        const commit = { ...commitCore, commitId: sha256Ref(canonicalizeJcs(commitCore)) };
+        const nextHead = sha256Ref(canonicalizeJcs({ previous: state.ledgerHead, commitId: commit.commitId }));
+        state.commits.push(commit);
+        state.ledgerHead = nextHead;
+        state.activeChampionRef = receipt.payload.candidateId;
+        state.activePolicy = receipt.payload.candidatePolicy;
+        state.servingEpoch = commit.servingEpoch;
+        receiptState.status = 'consumed';
+        receiptState.promotedAt = now;
+        receiptState.promotionTransactionId = transactionId;
+        atomicWriteJson(statePath(root), state);
+        return {
+            success: true,
+            idempotent: false,
+            reason: 'promotion committed',
+            transactionId,
+            receiptId,
+            championRef: commit.candidateId,
+            ledgerHead: nextHead,
+            servingEpoch: commit.servingEpoch,
+        };
+    });
+    if (!transaction.success || transaction.idempotent) {
+        if (transaction.success) {
+            const recovered = await recoverFlywheelMaterialization(root, options);
+            return { ...transaction, materialized: recovered.materialized, materializeReason: recovered.materializeReason };
+        }
+        return transaction;
+    }
+    if (options.faultAt === 'after-commit-before-materialize') {
+        throw new Error('fault injection: after-commit-before-materialize');
+    }
+    const recovered = await recoverFlywheelMaterialization(root, options);
+    return { ...transaction, materialized: recovered.materialized, materializeReason: recovered.materializeReason };
+}
+export function listFlywheelReceipts(root) {
+    const state = readFlywheelTransactionState(root);
+    try {
+        return fs.readdirSync(receiptDir(root))
+            .filter((file) => /^[a-f0-9]{64}\.json$/.test(file))
+            .map((file) => {
+            const receipt = JSON.parse(fs.readFileSync(path.join(receiptDir(root), file), 'utf8'));
+            return { receipt, state: state.receiptStates[receipt.payload.receiptId] ?? null };
+        })
+            .sort((a, b) => a.receipt.payload.issuedAt.localeCompare(b.receipt.payload.issuedAt));
+    }
+    catch {
+        return [];
+    }
+}
+export function verifyFlywheelLedger(root) {
+    const state = readFlywheelTransactionState(root);
+    const errors = [];
+    let head = GENESIS_LEDGER_HEAD;
+    for (let i = 0; i < state.commits.length; i++) {
+        const commit = state.commits[i];
+        const { commitId, ...core } = commit;
+        if (commit.sequence !== i + 1)
+            errors.push(`sequence mismatch at ${i + 1}`);
+        if (commit.previousLedgerHead !== head)
+            errors.push(`parent mismatch at ${i + 1}`);
+        if (sha256Ref(canonicalizeJcs(core)) !== commitId)
+            errors.push(`commit hash mismatch at ${i + 1}`);
+        head = sha256Ref(canonicalizeJcs({ previous: head, commitId }));
+    }
+    if (head !== state.ledgerHead)
+        errors.push('ledger head mismatch');
+    if (state.commits.length && state.commits[state.commits.length - 1].candidateId !== state.activeChampionRef) {
+        errors.push('active champion does not match ledger head');
+    }
+    return { valid: errors.length === 0, errors, commits: state.commits.length, head };
+}
+//# sourceMappingURL=flywheel-transaction.js.map

package/dist/src/services/harness-flywheel-runtime.d.ts

@@ -1,5 +1,6 @@
 import { type FlywheelResult } from './harness-flywheel.js';
 import { type GenerationResult } from './harness-flywheel-generations.js';
+import { type DarwinInvoker, type ProposerMode } from './flywheel-proposer.js';
 /**
  * Run one live flywheel tick against `projectRoot`. Opt-in + $0 default: with
  * RUFLO_HARNESS_LOOP unset it is a no-op. Best-effort; never throws.
@@ -8,6 +9,14 @@ export declare function runFlywheelWorker(projectRoot: string, opts?: {
     sample?: number;
     optInOverride?: boolean;
     now?: number;
+    receiptPrivateKeyPem?: string;
+    receiptPublicKeyPem?: string;
+    lineageId?: string;
+    evaluationRunId?: string;
+    safetyEnvelopeRef?: string;
+    proposer?: ProposerMode;
+    darwinInvoker?: DarwinInvoker;
+    allowSubstitutionPromotion?: boolean;
 }): Promise<FlywheelResult>;
 /**
  * Run ONE live COMPOUNDING generation against the persisted lineage (ADR-176

package/dist/src/services/harness-flywheel-runtime.js

@@ -5,9 +5,11 @@
  * pays the ONNX cost only when actually running a tick. Never throws.
  */
 import { harnessLoopOptedIn } from './harness-worker.js';
-import { runFlywheelTick } from './harness-flywheel.js';
+import { DEFAULT_CONFIG, retrievalPolicyNeighbors, runFlywheelTick, } from './harness-flywheel.js';
 import { runFlywheelGeneration, checkServedChampionDrift } from './harness-flywheel-generations.js';
 import { loadFrozenHumanEval } from './harness-frozen-eval.js';
+import { proposeFlywheelCandidates, } from './flywheel-proposer.js';
+import { sha256Ref } from './flywheel-receipt.js';
 /** The human-labeled ADR-081 anchor — the never-regress relevance set. */
 const ANCHOR = [
     ['how was the Opus model alias fixed', ['opus 4.8', 'opus alias', 'opus model alias', '#2232']],
@@ -34,6 +36,60 @@ export async function runFlywheelWorker(projectRoot, opts = {}) {
         const tool = neural.neuralTools.find((t) => t.name === 'neural_patterns');
         if (!tool)
             return { ran: false, reason: 'neural_patterns tool unavailable' };
+        const baseline = {
+            ...DEFAULT_CONFIG,
+            ...(applier.activeChampion(projectRoot)?.params ?? {}),
+        };
+        const safetyEnvelope = {
+            ref: opts.safetyEnvelopeRef ?? sha256Ref(JSON.stringify({
+                schema: 'ruflo.retrieval-safety-envelope/v1',
+                allowedPolicyKeys: ['alpha', 'topK', 'rerank', 'mmrLambda'],
+                numericBounds: {
+                    alpha: { min: 0.1, max: 0.9 },
+                    topK: { min: 5, max: 20 },
+                    mmrLambda: { min: 0.3, max: 0.9 },
+                },
+            })),
+            allowedPolicyKeys: ['alpha', 'topK', 'rerank', 'mmrLambda'],
+            numericBounds: {
+                alpha: { min: 0.1, max: 0.9 },
+                topK: { min: 5, max: 20 },
+                mmrLambda: { min: 0.3, max: 0.9 },
+            },
+            // Retrieval evaluations are local and report zero provider spend today;
+            // finite ceilings make any future resource evidence fail closed.
+            maxP95LatencyMicros: 5_000_000,
+            maxCostMicrosPerTask: 10_000,
+            maxTokensPerTask: 100_000,
+            maxFailureRate: 0.01,
+            maxEvaluationCostMicros: 1_000_000,
+        };
+        const proposerMode = opts.proposer
+            ?? (process.env.RUFLO_FLYWHEEL_PROPOSER ?? 'auto');
+        if (!['auto', 'local', 'darwin'].includes(proposerMode)) {
+            return { ran: false, reason: `invalid proposer mode: ${proposerMode}` };
+        }
+        const archive = await proposeFlywheelCandidates({
+            mode: proposerMode,
+            baselinePolicy: baseline,
+            safetyEnvelope,
+            seed: opts.now ?? Date.now(),
+            localProposer: () => retrievalPolicyNeighbors(baseline).map((policy) => ({
+                policy: policy,
+                resources: {
+                    p95LatencyMicros: 0,
+                    costMicrosPerTask: 0,
+                    tokensPerTask: 0,
+                    failureRate: 0,
+                    evaluationCostMicros: 0,
+                },
+            })),
+            darwinInvoker: opts.darwinInvoker,
+            allowSubstitutionPromotion: opts.allowSubstitutionPromotion,
+        });
+        const candidatePolicies = archive.paretoCandidates.map((candidate) => candidate.policy);
+        if (!candidatePolicies.length)
+            return { ran: false, reason: 'proposer archive contained no admissible candidates' };
         const deps = {
             getPatterns: () => neural.getStorePatterns(),
             search: async (query, cfg) => {
@@ -41,9 +97,18 @@ export async function runFlywheelWorker(projectRoot, opts = {}) {
                 return (r.results || []).slice(0, 5).map((m) => ({ id: m?.id ?? '', name: m?.name ?? '' }));
             },
             anchorTasks: ANCHOR,
-            activeParams: () => applier.activeChampion(projectRoot)?.params ?? null,
+            activeParams: () => baseline,
             sample: opts.sample ?? 40,
             now: opts.now,
+            receiptPrivateKeyPem: opts.receiptPrivateKeyPem,
+            receiptPublicKeyPem: opts.receiptPublicKeyPem,
+            lineageId: opts.lineageId,
+            evaluationRunId: opts.evaluationRunId,
+            safetyEnvelopeRef: safetyEnvelope.ref,
+            requestedProposer: archive.requestedProposer,
+            effectiveProposer: archive.effectiveProposer,
+            proposerSubstitution: archive.proposerSubstitution,
+            candidatePolicies,
         };
         return await runFlywheelTick(projectRoot, deps);
     }

package/dist/src/services/harness-flywheel.d.ts

@@ -1,4 +1,5 @@
 import { type HarvestPattern } from './harness-corpus-harvester.js';
+import { type FlywheelEvaluationReceipt } from './flywheel-receipt.js';
 export interface RetrievalConfig {
     alpha: number;
     subjectWeight: number;
@@ -26,6 +27,17 @@ export interface FlywheelDeps {
     activeParams?: () => Partial<RetrievalConfig> | null;
     sample?: number;
     now?: number;
+    lineageId?: string;
+    evaluationRunId?: string;
+    safetyEnvelopeRef?: string;
+    requestedProposer?: 'auto' | 'local' | 'darwin';
+    effectiveProposer?: 'local' | 'darwin';
+    proposerSubstitution?: string;
+    receiptPrivateKeyPem?: string;
+    receiptPublicKeyPem?: string;
+    bootstrapIterations?: number;
+    /** Candidate policies supplied by an external proposer archive (ADR-322B). */
+    candidatePolicies?: RetrievalConfig[];
 }
 export interface FlywheelResult {
     ran: boolean;
@@ -38,11 +50,22 @@ export interface FlywheelResult {
     anchorRegressed?: boolean;
     championRef?: string;
     corpusVersion?: string;
+    candidateConfig?: RetrievalConfig;
+    receiptId?: string;
+    receipt?: FlywheelEvaluationReceipt;
+    promotable?: boolean;
+    legacyDeprecation?: boolean;
 }
+export declare function retrievalPolicyNeighbors(base: RetrievalConfig): RetrievalConfig[];
 /**
  * Run one flywheel tick against `projectRoot`. Best-effort; never throws.
  * Returns a rich result AND (as a side effect) appends to the improvement ledger
  * and — on accept — applies the champion locally + chains it.
  */
+export declare function evaluateFlywheelCandidate(projectRoot: string, deps: FlywheelDeps): Promise<FlywheelResult>;
+/**
+ * Compatibility wrapper. New callers get evaluation-only semantics. The legacy
+ * implicit apply path exists for one release behind an explicit opt-in flag.
+ */
 export declare function runFlywheelTick(projectRoot: string, deps: FlywheelDeps): Promise<FlywheelResult>;
 //# sourceMappingURL=harness-flywheel.d.ts.map