Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
index 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');