🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(flywheel): align ADR-322 safety envelope with the policy surface it guards (#2836)
Dragan Spiridonov342dc22fc3c4
diff --git a/v3/@claude-flow/cli/__tests__/flywheel-envelope-proposer-contract.test.ts b/v3/@claude-flow/cli/__tests__/flywheel-envelope-proposer-contract.test.tsnew file mode 100644index 0000000000..da12ba22f7--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/flywheel-envelope-proposer-contract.test.ts@@ -0,0 +1,90 @@+/**+ * ADR-322 regression: the REAL local proposer against the REAL production+ * safety envelope.+ *+ * The shipped v1 envelope allowed `['alpha','topK','rerank','mmrLambda']` while+ * `retrievalPolicyNeighbors` emits full `RetrievalConfig` snapshots keyed+ * `alpha, subjectWeight, mmrLambda, bodyWeight, typePenaltyFactor`. Since+ * `validateCandidate` rejects a candidate when ANY of its keys is outside the+ * allowlist, every locally-proposed candidate was inadmissible and+ * `runFlywheelWorker` always returned+ * `{ran:false, reason:'proposer archive contained no admissible candidates'}`.+ *+ * The existing suites could not catch this: `flywheel-proposer.test.ts` builds a+ * synthetic `allowedPolicyKeys: ['alpha']` envelope with synthetic alpha-only+ * candidates, and `harness-flywheel.test.ts` calls `runFlywheelTick` directly,+ * bypassing the proposer archive. Nothing bound the two real pieces together.+ * These tests do exactly that.+ */+import { describe, it, expect } from 'vitest';+import { DEFAULT_CONFIG, retrievalPolicyNeighbors, type RetrievalConfig } from '../src/services/harness-flywheel.js';+import { proposeFlywheelCandidates } from '../src/services/flywheel-proposer.js';+import { retrievalSafetyEnvelope } from '../src/services/harness-flywheel-runtime.js';++const ZERO_RESOURCES = {+ p95LatencyMicros: 0,+ costMicrosPerTask: 0,+ tokensPerTask: 0,+ failureRate: 0,+ evaluationCostMicros: 0,+};++const proposeReal = (baseline: RetrievalConfig) => proposeFlywheelCandidates({+ mode: 'local',+ baselinePolicy: baseline as unknown as Record<string, unknown>,+ safetyEnvelope: retrievalSafetyEnvelope(),+ seed: 1,+ localProposer: () => retrievalPolicyNeighbors(baseline).map((policy) => ({+ policy: policy as unknown as Record<string, unknown>,+ resources: { ...ZERO_RESOURCES },+ })),+});++describe('ADR-322 envelope <-> local proposer contract', () => {+ it('should admit locally-proposed candidates when baseline is DEFAULT_CONFIG', async () => {+ const archive = await proposeReal(DEFAULT_CONFIG);++ expect(archive.candidates.length).toBeGreaterThan(0);+ expect(archive.admissibleCandidates.length).toBeGreaterThan(0);+ });++ it('should yield a non-empty Pareto front, which runFlywheelWorker requires to proceed', async () => {+ const archive = await proposeReal(DEFAULT_CONFIG);++ expect(archive.paretoCandidates.length).toBeGreaterThan(0);+ });++ it('should allow exactly the keys the proposer emits', () => {+ const envelope = retrievalSafetyEnvelope();+ const emittedKeys = Object.keys(retrievalPolicyNeighbors(DEFAULT_CONFIG)[0]).sort();++ expect([...envelope.allowedPolicyKeys].sort()).toEqual(emittedKeys);+ });++ it('should bound every allowed key, since an unbounded key is never range-checked', () => {+ const envelope = retrievalSafetyEnvelope();++ for (const key of envelope.allowedPolicyKeys) {+ const bounds = envelope.numericBounds?.[key];+ expect(bounds, `${key} has no numeric bounds`).toBeDefined();+ expect(Number.isFinite(bounds?.min), `${key} min is not finite`).toBe(true);+ expect(Number.isFinite(bounds?.max), `${key} max is not finite`).toBe(true);+ }+ });++ it('should reject an out-of-range weight on a previously unbounded axis', async () => {+ const archive = await proposeFlywheelCandidates({+ mode: 'local',+ baselinePolicy: DEFAULT_CONFIG as unknown as Record<string, unknown>,+ safetyEnvelope: retrievalSafetyEnvelope(),+ seed: 1,+ localProposer: () => [{+ policy: { ...DEFAULT_CONFIG, subjectWeight: 1e9 } as unknown as Record<string, unknown>,+ resources: { ...ZERO_RESOURCES },+ }],+ });++ expect(archive.admissibleCandidates).toHaveLength(0);+ expect(archive.candidates[0].rejectionReasons).toContain('subjectWeight above maximum');+ });+});diff --git a/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts b/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.tsindex 062e67f8f4..2eefef56f2 100644--- a/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts+++ b/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts@@ -39,6 +39,52 @@ const ANCHOR: AnchorTask[] = [['security hardening crypto random IDs', ['cwe-347', 'crypto.randomuuid', 'security fix', 'random id', 'crypto random']],].map(([q, labels], i) => ({ id: `q${String(i).padStart(2, '0')}`, input: { id: `q${String(i).padStart(2, '0')}`, q: q as string }, expected: labels as string[] }));+/**+ * The ADR-322 retrieval safety envelope.+ *+ * It MUST describe the policy surface the proposer actually emits —+ * `RetrievalConfig`. The v1 envelope allowed `topK`/`rerank`, which are+ * `neural_patterns` search-call arguments not representable in+ * `RetrievalConfig`, while omitting the three weight axes that+ * `retrievalPolicyNeighbors` does mutate. Because `validateCandidate` checks+ * EVERY key of a candidate policy (candidates are full snapshots, not deltas),+ * that drift made every locally-proposed candidate inadmissible and the local+ * evaluation path unreachable — no receipt, therefore no promotion, ever.+ *+ * Every axis carries a finite bound: an allowed key WITHOUT bounds is an+ * unbounded key, because `validateCandidate` applies bounds only when present.+ * A Darwin proposer could otherwise submit arbitrary weights on the three axes.+ *+ * Exported so tests can bind the REAL envelope to the REAL proposer; the drift+ * survived review precisely because no test wired those two together.+ */+export function retrievalSafetyEnvelope(ref?: string): SafetyEnvelope {+ const allowedPolicyKeys = ['alpha', 'subjectWeight', 'mmrLambda', 'bodyWeight', 'typePenaltyFactor'];+ const numericBounds = {+ alpha: { min: 0.1, max: 0.9 },+ subjectWeight: { min: 0.1, max: 10 },+ mmrLambda: { min: 0.3, max: 0.9 },+ bodyWeight: { min: 0.1, max: 10 },+ typePenaltyFactor: { min: 0.1, max: 10 },+ };+ return {+ ref: ref ?? sha256Ref(JSON.stringify({+ schema: 'ruflo.retrieval-safety-envelope/v2',+ allowedPolicyKeys,+ numericBounds,+ })),+ allowedPolicyKeys,+ numericBounds,+ // 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,+ };+}+/*** 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.@@ -84,30 +130,7 @@ export async function runFlywheelWorker(...DEFAULT_CONFIG,...((applier.activeChampion(projectRoot)?.params as Partial<RetrievalConfig>) ?? {}),};- const safetyEnvelope: 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 safetyEnvelope = retrievalSafetyEnvelope(opts.safetyEnvelopeRef);// CLI flag opts.proposer takes precedence over RUFLO_FLYWHEEL_PROPOSER.const proposerMode = opts.proposer?? ((process.env.RUFLO_FLYWHEEL_PROPOSER as ProposerMode | undefined) ?? 'auto');