claude-flow 3.22.0 → 3.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.22.0",
+  "version": "3.24.0",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/commands/memory-backup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * V3 CLI `memory backup` command.
+ *
+ * WAL-safe snapshot of the vector-memory DB (`.swarm/memory.db`) with rotation
+ * and optional GCS offsite. Thin surface over ../services/memory-backup.js; the
+ * daemon's nightly `backup` worker calls the same service.
+ */
+import type { Command } from '../types.js';
+export declare const backupCommand: Command;
+export default backupCommand;
+//# sourceMappingURL=memory-backup.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/memory-backup.js

@@ -0,0 +1,46 @@
+import { output } from '../output.js';
+import { backupMemoryDb, defaultMemoryDbPath } from '../services/memory-backup.js';
+export const backupCommand = {
+    name: 'backup',
+    description: 'Snapshot the vector-memory DB (.swarm/memory.db) — WAL-safe, rotated, optional GCS offsite',
+    options: [
+        { name: 'db', description: 'Source DB (default: .swarm/memory.db)', type: 'string' },
+        { name: 'dir', description: 'Destination dir (default: .swarm/backups)', type: 'string' },
+        { name: 'keep', description: 'Rotation — keep the newest N snapshots (default 7)', type: 'number', default: 7 },
+        { name: 'gcs', description: 'Also upload the snapshot to a gs://bucket/prefix (offsite)', type: 'string' },
+        { name: 'verbose', short: 'v', description: 'Verbose logging', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'claude-flow memory backup', description: 'Snapshot to .swarm/backups, keep last 7' },
+        { command: 'claude-flow memory backup --keep 30', description: 'Keep a month of nightly snapshots' },
+        { command: 'claude-flow memory backup --gcs gs://my-bucket/ruflo-backups', description: 'Also upload offsite to GCS' },
+    ],
+    action: async (ctx) => {
+        const r = await backupMemoryDb({
+            dbPath: ctx.flags.db || defaultMemoryDbPath(ctx.cwd),
+            destDir: ctx.flags.dir,
+            keep: typeof ctx.flags.keep === 'number' ? ctx.flags.keep : 7,
+            gcs: ctx.flags.gcs,
+            verbose: ctx.flags.verbose === true,
+        });
+        if (!r.backedUp) {
+            // no-db is a benign "nothing to back up yet"; anything else is a real skip.
+            if (r.skipped === 'no-db') {
+                output.printWarning('No memory DB found to back up (.swarm/memory.db). Nothing to do.');
+                return { success: true, data: r };
+            }
+            output.printError(`Backup skipped: ${r.skipped}`);
+            return { success: false, exitCode: 1, data: r };
+        }
+        output.writeln();
+        output.writeln(output.success(`Backed up → ${r.path}`));
+        output.printList([
+            `Size:      ${Math.round((r.sizeBytes ?? 0) / 1024)} KB`,
+            `Rotated:   ${r.rotatedAway?.length ?? 0} old snapshot(s) removed`,
+            ...(r.gcsUri ? [`Offsite:   ${r.gcsUri}`] : []),
+        ]);
+        return { success: true, data: r };
+    },
+};
+export default backupCommand;
+//# sourceMappingURL=memory-backup.js.map

package/v3/@claude-flow/cli/dist/src/commands/memory.js

@@ -6,6 +6,7 @@ import { output } from '../output.js';
 import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { distillCommand } from './memory-distill.js';
+import { backupCommand } from './memory-backup.js';
 // Memory backends
 const BACKENDS = [
     { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
@@ -1472,7 +1473,7 @@ const initMemoryCommand = {
 export const memoryCommand = {
     name: 'memory',
     description: 'Memory management commands',
-    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand],
+    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },

package/v3/@claude-flow/cli/dist/src/config/harness-feedback-applier.d.ts

@@ -0,0 +1,50 @@
+export declare const ADOPTED_CONFIG_FILE = "proven-config.json";
+export declare const ACTIVE_POLICY_FILE = "harness-active-policy.json";
+export interface ActivePolicy {
+    championId: string;
+    provenanceTier: string;
+    layer?: string;
+    appliedAt: number;
+    previous?: string | null;
+    rolledBack?: boolean;
+    params?: Record<string, unknown>;
+}
+export interface ApplyResult {
+    applied: boolean;
+    from?: string | null;
+    to?: string;
+    reason?: string;
+}
+/**
+ * Apply the adopted champion to the active harness policy. Idempotent (applying
+ * the same champion is a no-op), reversible (records the superseded champion),
+ * best-effort. `now` is injectable for tests.
+ */
+export declare function applyChampion(cwd: string, opts?: {
+    now?: number;
+}): ApplyResult;
+/**
+ * Apply a champion directly by its config payload (local self-optimization,
+ * ADR-176 flywheel). Unlike applyChampion (which reads a propagated, signed,
+ * adopted record), this activates a LOCALLY-mined champion that just cleared the
+ * install's own measured gate — no signing, because nothing is propagated. Still
+ * reversible (records `previous`) and idempotent. Consumers read `params`.
+ */
+export declare function applyChampionParams(cwd: string, opts: {
+    championId: string;
+    params?: Record<string, unknown>;
+    layer?: string;
+    previous?: string | null;
+    now?: number;
+}): ApplyResult;
+/**
+ * Reverse the last apply: point the active policy back at its `previous`
+ * champion (reversibility, ADR-177 rollback pointer). No-op if there is no
+ * previous. The previous champion's policy is fetched by ref by consumers.
+ */
+export declare function rollbackActivePolicy(cwd: string, opts?: {
+    now?: number;
+}): ApplyResult;
+/** The champion routing/agents should currently use, or null. */
+export declare function activeChampion(cwd: string): ActivePolicy | null;
+//# sourceMappingURL=harness-feedback-applier.d.ts.map

package/v3/@claude-flow/cli/dist/src/config/harness-feedback-applier.js

@@ -0,0 +1,122 @@
+/**
+ * Feedback applier — close the loop (ADR-176 phase 9).
+ *
+ * A proven champion adopted by the propagation channel (ADR-177,
+ * proven-config-refresh.ts writes `.claude/proven-config.json`) is inert until
+ * something *applies* it to what ruflo actually runs. This applier promotes the
+ * adopted champion to the ACTIVE harness policy that routing/agents consume —
+ * reversibly (keeps the previous pointer) and provenance-tagged (ADR-171), so
+ * it composes with the promote-gate discipline rather than bypassing it. It only
+ * ever sets a pointer to a proven, signed champion; it never invents config.
+ * Zero deps, $0.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const ADOPTED_CONFIG_FILE = 'proven-config.json'; // written by proven-config-refresh (in .claude)
+export const ACTIVE_POLICY_FILE = 'harness-active-policy.json'; // consumed by routing/agents (in .claude-flow)
+function readJson(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Apply the adopted champion to the active harness policy. Idempotent (applying
+ * the same champion is a no-op), reversible (records the superseded champion),
+ * best-effort. `now` is injectable for tests.
+ */
+export function applyChampion(cwd, opts = {}) {
+    try {
+        const claudeDir = path.join(cwd, '.claude');
+        const adopted = readJson(path.join(claudeDir, ADOPTED_CONFIG_FILE));
+        if (!adopted?.championId)
+            return { applied: false, reason: 'no adopted champion' };
+        const cfDir = path.join(cwd, '.claude-flow');
+        const activePath = path.join(cfDir, ACTIVE_POLICY_FILE);
+        const current = readJson(activePath);
+        if (current?.championId === adopted.championId && !current.rolledBack) {
+            return { applied: false, reason: 'already active' }; // idempotent
+        }
+        const active = {
+            championId: adopted.championId,
+            // A champion only reaches adoption if it cleared the promote-gate, so it is
+            // oracle/judge-backed; proxy can never be here (ADR-171). Default oracle.
+            provenanceTier: 'oracle:test-exec',
+            layer: adopted.manifest?.layer,
+            appliedAt: opts.now ?? Date.now(),
+            previous: current?.championId ?? adopted.previous ?? null,
+            params: adopted.manifest?.policy?.value,
+        };
+        fs.mkdirSync(cfDir, { recursive: true });
+        fs.writeFileSync(activePath, JSON.stringify(active, null, 2), 'utf-8');
+        return { applied: true, from: active.previous, to: active.championId };
+    }
+    catch (e) {
+        return { applied: false, reason: `error: ${e?.message ?? e}` };
+    }
+}
+/**
+ * Apply a champion directly by its config payload (local self-optimization,
+ * ADR-176 flywheel). Unlike applyChampion (which reads a propagated, signed,
+ * adopted record), this activates a LOCALLY-mined champion that just cleared the
+ * install's own measured gate — no signing, because nothing is propagated. Still
+ * reversible (records `previous`) and idempotent. Consumers read `params`.
+ */
+export function applyChampionParams(cwd, opts) {
+    try {
+        const cfDir = path.join(cwd, '.claude-flow');
+        const activePath = path.join(cfDir, ACTIVE_POLICY_FILE);
+        const current = readJson(activePath);
+        if (current?.championId === opts.championId && !current.rolledBack)
+            return { applied: false, reason: 'already active' };
+        const active = {
+            championId: opts.championId,
+            provenanceTier: 'oracle:test-exec', // only a gate-cleared champion reaches here
+            layer: opts.layer,
+            appliedAt: opts.now ?? Date.now(),
+            previous: opts.previous ?? current?.championId ?? null,
+            params: opts.params,
+        };
+        fs.mkdirSync(cfDir, { recursive: true });
+        fs.writeFileSync(activePath, JSON.stringify(active, null, 2), 'utf-8');
+        return { applied: true, from: active.previous, to: active.championId };
+    }
+    catch (e) {
+        return { applied: false, reason: `error: ${e?.message ?? e}` };
+    }
+}
+/**
+ * Reverse the last apply: point the active policy back at its `previous`
+ * champion (reversibility, ADR-177 rollback pointer). No-op if there is no
+ * previous. The previous champion's policy is fetched by ref by consumers.
+ */
+export function rollbackActivePolicy(cwd, opts = {}) {
+    try {
+        const activePath = path.join(cwd, '.claude-flow', ACTIVE_POLICY_FILE);
+        const current = readJson(activePath);
+        if (!current)
+            return { applied: false, reason: 'no active policy' };
+        if (!current.previous)
+            return { applied: false, reason: 'no previous to roll back to' };
+        const reverted = {
+            championId: current.previous,
+            provenanceTier: current.provenanceTier,
+            layer: current.layer,
+            appliedAt: opts.now ?? Date.now(),
+            previous: null,
+            rolledBack: true,
+        };
+        fs.writeFileSync(activePath, JSON.stringify(reverted, null, 2), 'utf-8');
+        return { applied: true, from: current.championId, to: reverted.championId };
+    }
+    catch (e) {
+        return { applied: false, reason: `error: ${e?.message ?? e}` };
+    }
+}
+/** The champion routing/agents should currently use, or null. */
+export function activeChampion(cwd) {
+    return readJson(path.join(cwd, '.claude-flow', ACTIVE_POLICY_FILE));
+}
+//# sourceMappingURL=harness-feedback-applier.js.map

package/v3/@claude-flow/cli/dist/src/config/proven-config-refresh.d.ts

@@ -0,0 +1,39 @@
+import { type InstallEnv, type SignedProvenConfig } from './proven-config.js';
+export declare const PROVEN_CONFIG_STAMP = ".proven-config-version";
+/** The signed champion manifest shipped in the package (metadata; the RVFA payload rides alongside). */
+export declare const PROVEN_CONFIG_FILE = "proven-config.signed.json";
+/** The RVFA-packaged champion (ADR-177 final phase). Preferred when present. */
+export declare const PROVEN_CONFIG_RVFA_FILE = "proven-config.signed.rvf";
+/** Where an adopted champion is recorded in the project (consumed by the feedback applier, ADR-176 phase 9). */
+export declare const ADOPTED_CONFIG_FILE = "proven-config.json";
+/**
+ * Read a shipped champion from either packaging. `.rvf` → unpack the RVFA
+ * envelope (integrity-checked); anything else → parse as signed JSON. Returns
+ * null (never throws) on any failure. The Ed25519 signature is still verified
+ * downstream by adoptSignedConfig — this only decodes the transport.
+ */
+export declare function loadShippedChampion(srcPath: string): SignedProvenConfig | null;
+/** Build the local environment the champion's constraints are checked against. */
+export declare function currentInstallEnv(cwd?: string): InstallEnv;
+export interface AdoptResult {
+    adopted: boolean;
+    from?: string;
+    to?: string;
+    reason?: string;
+    skipped?: string;
+}
+/**
+ * The testable adoption core: given a signed champion and the local env, adopt
+ * it into `cwd/.claude` iff it is newer than the stamp AND passes both gates.
+ * Fail-closed; never throws. `pubkeyPem` is injectable for tests.
+ */
+export declare function adoptSignedConfig(cwd: string, signed: SignedProvenConfig, env: InstallEnv, opts?: {
+    pubkeyPem?: string;
+}): AdoptResult;
+/**
+ * On CLI startup: if the package ships a signed champion newer than the
+ * project's stamp, adopt it when authentic + suitable. Best-effort, never
+ * throws. No-op when no manifest ships or the project isn't initialized.
+ */
+export declare function autoAdoptProvenConfigIfStale(cwd?: string): Promise<AdoptResult>;
+//# sourceMappingURL=proven-config-refresh.d.ts.map

package/v3/@claude-flow/cli/dist/src/config/proven-config-refresh.js

@@ -0,0 +1,154 @@
+/**
+ * Proven-configuration propagation to existing installs (ADR-177).
+ *
+ * A SIBLING of the helper auto-refresh (ADR-174), deliberately independent so it
+ * never touches the hook-code channel that older CLIs verify:
+ *   - its own stamp file (`.proven-config-version`, the adopted champion id),
+ *   - its own trust root (RUFLO_CONFIG_PUBKEY),
+ *   - additive-only: a project with no shipped manifest is a no-op.
+ *
+ * On a CLI command, if the package ships a signed champion newer than the
+ * project's stamp, it is adopted ONLY when both gates pass (ADR-177):
+ * authenticity (Ed25519) AND suitability (host/platform/compatibility/layer).
+ * A signed-but-unsuitable champion is a SAFE skip (not an error), which is also
+ * the backwards-compatibility version gate. Zero deps on the decision path.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+import { evaluateForAdoption } from './proven-config.js';
+import { unpackProvenConfigRvfa } from './proven-config-rvfa.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PROVEN_CONFIG_STAMP = '.proven-config-version';
+/** The signed champion manifest shipped in the package (metadata; the RVFA payload rides alongside). */
+export const PROVEN_CONFIG_FILE = 'proven-config.signed.json';
+/** The RVFA-packaged champion (ADR-177 final phase). Preferred when present. */
+export const PROVEN_CONFIG_RVFA_FILE = 'proven-config.signed.rvf';
+/** Where an adopted champion is recorded in the project (consumed by the feedback applier, ADR-176 phase 9). */
+export const ADOPTED_CONFIG_FILE = 'proven-config.json';
+/**
+ * Locate the package's shipped signed champion, if any. Null when none ships.
+ * The RVFA package is preferred over the raw JSON when both are present.
+ */
+function findPackageProvenConfig() {
+    const dirs = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = path.dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        dirs.push(path.join(pkgRoot, '.claude'));
+    }
+    catch { /* not resolvable */ }
+    dirs.push(path.resolve(__dirname, '..', '..', '..', '.claude'));
+    // RVFA form first (ruvnet-native envelope), then the raw signed JSON fallback.
+    for (const d of dirs) {
+        const rvf = path.join(d, PROVEN_CONFIG_RVFA_FILE);
+        if (fs.existsSync(rvf))
+            return rvf;
+        const json = path.join(d, PROVEN_CONFIG_FILE);
+        if (fs.existsSync(json))
+            return json;
+    }
+    return null;
+}
+/**
+ * Read a shipped champion from either packaging. `.rvf` → unpack the RVFA
+ * envelope (integrity-checked); anything else → parse as signed JSON. Returns
+ * null (never throws) on any failure. The Ed25519 signature is still verified
+ * downstream by adoptSignedConfig — this only decodes the transport.
+ */
+export function loadShippedChampion(srcPath) {
+    try {
+        if (srcPath.endsWith('.rvf')) {
+            return unpackProvenConfigRvfa(fs.readFileSync(srcPath));
+        }
+        return JSON.parse(fs.readFileSync(srcPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the local environment the champion's constraints are checked against. */
+export function currentInstallEnv(cwd = process.cwd()) {
+    const env = {
+        platform: process.platform,
+        versions: { ruflo: getInstalledCliVersion() },
+    };
+    // Layer, if the project declares one (ADR-176 hierarchy). Optional.
+    try {
+        const layerFile = path.join(cwd, '.claude', '.harness-layer');
+        if (fs.existsSync(layerFile))
+            env.layer = fs.readFileSync(layerFile, 'utf-8').trim();
+    }
+    catch { /* none */ }
+    return env;
+}
+/**
+ * The testable adoption core: given a signed champion and the local env, adopt
+ * it into `cwd/.claude` iff it is newer than the stamp AND passes both gates.
+ * Fail-closed; never throws. `pubkeyPem` is injectable for tests.
+ */
+export function adoptSignedConfig(cwd, signed, env, opts = {}) {
+    try {
+        const claudeDir = path.join(cwd, '.claude');
+        if (!fs.existsSync(claudeDir))
+            return { adopted: false }; // not a ruflo project
+        const championId = signed.manifest?.policy?.ref;
+        if (!championId)
+            return { adopted: false, skipped: 'manifest missing policy.ref' };
+        let stamped = '';
+        try {
+            stamped = fs.readFileSync(path.join(claudeDir, PROVEN_CONFIG_STAMP), 'utf-8').trim();
+        }
+        catch { /* unstamped */ }
+        if (stamped === championId)
+            return { adopted: false }; // already current — fast path
+        const decision = evaluateForAdoption(signed, env, opts.pubkeyPem);
+        if (!decision.adopt) {
+            // A safe skip (unsuitable) or a refusal (bad signature). Do NOT advance the stamp.
+            return { adopted: false, skipped: decision.reason };
+        }
+        // Adopt: record the champion for the feedback applier + retain the previous (rollback pointer).
+        const record = {
+            adoptedAt: Date.now(),
+            championId,
+            manifest: decision.manifest,
+            previous: signed.manifest.rollback?.previousManifest ?? stamped ?? null,
+        };
+        try {
+            fs.writeFileSync(path.join(claudeDir, ADOPTED_CONFIG_FILE), JSON.stringify(record, null, 2), 'utf-8');
+        }
+        catch { /* */ }
+        try {
+            fs.writeFileSync(path.join(claudeDir, PROVEN_CONFIG_STAMP), championId, 'utf-8');
+        }
+        catch { /* */ }
+        return { adopted: true, from: stamped || '(none)', to: championId };
+    }
+    catch {
+        return { adopted: false };
+    }
+}
+/**
+ * On CLI startup: if the package ships a signed champion newer than the
+ * project's stamp, adopt it when authentic + suitable. Best-effort, never
+ * throws. No-op when no manifest ships or the project isn't initialized.
+ */
+export async function autoAdoptProvenConfigIfStale(cwd = process.cwd()) {
+    try {
+        if (!fs.existsSync(path.join(cwd, '.claude')))
+            return { adopted: false };
+        const src = findPackageProvenConfig();
+        if (!src)
+            return { adopted: false }; // no champion ships → no-op (additive)
+        const signed = loadShippedChampion(src);
+        if (!signed)
+            return { adopted: false, skipped: 'unreadable manifest' };
+        return adoptSignedConfig(cwd, signed, currentInstallEnv(cwd));
+    }
+    catch {
+        return { adopted: false };
+    }
+}
+//# sourceMappingURL=proven-config-refresh.js.map

package/v3/@claude-flow/cli/dist/src/config/proven-config-rvfa.d.ts

@@ -0,0 +1,23 @@
+import type { SignedProvenConfig } from './proven-config.js';
+/** The single RVFA section id that carries the signed manifest JSON. */
+export declare const PROVEN_CONFIG_SECTION = "proven-config";
+/** Header capability marker so a reader can tell this appliance apart. */
+export declare const PROVEN_CONFIG_CAPABILITY = "proven-config";
+/**
+ * Pack a signed proven-config manifest into an RVFA appliance binary.
+ *
+ * The whole SignedProvenConfig (manifest + signature + algorithm) becomes the
+ * payload, so the config-root signature travels inside the envelope. The RVFA
+ * layer contributes integrity (footer + section hash), not authenticity.
+ */
+export declare function packProvenConfigRvfa(signed: SignedProvenConfig): Buffer;
+/** True if `buf` looks like an RVFA container (starts with the RVFA magic). */
+export declare function isProvenConfigRvfa(buf: Buffer): boolean;
+/**
+ * Unpack + integrity-check an RVFA-packed champion. Returns the inner
+ * SignedProvenConfig, or null on ANY failure (bad magic, corrupt footer,
+ * missing section, malformed JSON). Fail-closed — does NOT verify the Ed25519
+ * signature; that stays with adoptSignedConfig (single config trust root).
+ */
+export declare function unpackProvenConfigRvfa(buf: Buffer): SignedProvenConfig | null;
+//# sourceMappingURL=proven-config-rvfa.d.ts.map

package/v3/@claude-flow/cli/dist/src/config/proven-config-rvfa.js

@@ -0,0 +1,73 @@
+/**
+ * RVFA packaging for proven-configuration manifests (ADR-177, final phase).
+ *
+ * Keeps champion propagation inside the ruvnet RVFA ecosystem: the *already
+ * config-signed* SignedProvenConfig is carried as the sole section of a small
+ * RVFA appliance binary. This adds a ruvnet-native transport + tamper-evident
+ * envelope (RVFA's SHA256 footer + per-section hash) WITHOUT a second trust
+ * root — adoption still verifies the inner manifest's Ed25519 signature against
+ * RUFLO_CONFIG_PUBKEY (see adoptSignedConfig). Signed ≠ suitable is unchanged:
+ * unpack → verifyProvenConfig → isSuitable, fail-closed at every step.
+ *
+ * Pure Node (RvfaWriter/RvfaReader) — no LLM, no network, $0. Additive: a raw
+ * `.signed.json` champion still adopts exactly as before; the `.rvf` form is a
+ * second, optional packaging the same adopt path understands.
+ */
+import { RvfaWriter, RvfaReader, RVFA_MAGIC } from '../appliance/rvfa-format.js';
+/** The single RVFA section id that carries the signed manifest JSON. */
+export const PROVEN_CONFIG_SECTION = 'proven-config';
+/** Header capability marker so a reader can tell this appliance apart. */
+export const PROVEN_CONFIG_CAPABILITY = 'proven-config';
+/**
+ * Pack a signed proven-config manifest into an RVFA appliance binary.
+ *
+ * The whole SignedProvenConfig (manifest + signature + algorithm) becomes the
+ * payload, so the config-root signature travels inside the envelope. The RVFA
+ * layer contributes integrity (footer + section hash), not authenticity.
+ */
+export function packProvenConfigRvfa(signed) {
+    const m = signed.manifest;
+    const writer = new RvfaWriter({
+        name: `proven-config:${m.policy?.ref ?? 'unknown'}`,
+        // Carry the compat floor for humans/tools; the real gate is isSuitable.
+        appVersion: m.compatibility?.ruflo ?? '0',
+        platform: m.platform?.[0] ?? 'any',
+        arch: 'any',
+        profile: 'offline',
+        capabilities: [PROVEN_CONFIG_CAPABILITY],
+    });
+    writer.addSection(PROVEN_CONFIG_SECTION, Buffer.from(JSON.stringify(signed), 'utf-8'), {
+        compression: 'gzip',
+        type: 'application/json',
+    });
+    return writer.build();
+}
+/** True if `buf` looks like an RVFA container (starts with the RVFA magic). */
+export function isProvenConfigRvfa(buf) {
+    return buf.length >= RVFA_MAGIC.length && buf.subarray(0, RVFA_MAGIC.length).equals(RVFA_MAGIC);
+}
+/**
+ * Unpack + integrity-check an RVFA-packed champion. Returns the inner
+ * SignedProvenConfig, or null on ANY failure (bad magic, corrupt footer,
+ * missing section, malformed JSON). Fail-closed — does NOT verify the Ed25519
+ * signature; that stays with adoptSignedConfig (single config trust root).
+ */
+export function unpackProvenConfigRvfa(buf) {
+    try {
+        if (!isProvenConfigRvfa(buf))
+            return null;
+        const reader = RvfaReader.fromBuffer(buf);
+        const integrity = reader.verify();
+        if (!integrity.valid)
+            return null; // tampered envelope → reject
+        const payload = reader.extractSection(PROVEN_CONFIG_SECTION);
+        const signed = JSON.parse(payload.toString('utf-8'));
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        return signed;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=proven-config-rvfa.js.map

package/v3/@claude-flow/cli/dist/src/config/proven-config.d.ts

@@ -0,0 +1,86 @@
+/** Ruflo config-signing PUBLIC key (safe to commit). Private half in GCP Secret Manager (ruflo-config-signing-key). */
+export declare const RUFLO_CONFIG_PUBKEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA3zr3BLCFKyrjvjZg9BXxchXIuGYwYwq21FYCjTpQO6A=\n-----END PUBLIC KEY-----";
+/** The receipt bundle (ADR-176) — reproducible proof-of-work summary. */
+export interface ProvenConfigReceipt {
+    heldOutDelta?: number;
+    redblue?: 'PASS' | 'FAIL' | 'SKIPPED';
+    drift?: number;
+    canary?: {
+        rollbackRate?: number;
+        latencyP95?: number;
+        costPerTask?: number;
+    };
+    receiptCoverage?: number;
+}
+/** The constraint contract (ADR-177 §signed != suitable) + policy reference + receipt. */
+export interface ProvenConfigManifest {
+    schema: string;
+    policy: {
+        ref: string;
+        value?: Record<string, unknown>;
+    };
+    host?: Record<string, string>;
+    platform?: string[];
+    compatibility?: Record<string, string>;
+    benchmark?: {
+        corpus: string;
+        corpusHash: string;
+    };
+    layer?: string;
+    receipt?: ProvenConfigReceipt;
+    rollback?: {
+        previousManifest?: string;
+    };
+}
+export interface SignedProvenConfig {
+    manifest: ProvenConfigManifest;
+    signature: string;
+    algorithm: 'ed25519';
+}
+/** The local environment a manifest's constraints are checked against. */
+export interface InstallEnv {
+    platform: string;
+    hosts?: Record<string, string>;
+    versions?: Record<string, string>;
+    layer?: string;
+}
+export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic canonical bytes — recursively sorted object keys so signer and
+ * verifier agree byte-for-byte regardless of insertion order.
+ */
+export declare function canonicalManifestBytes(m: ProvenConfigManifest): Buffer;
+/** Sign a manifest (publish-time; key from GCP via scripts). */
+export declare function signProvenConfig(manifest: ProvenConfigManifest, privateKeyPem: string): SignedProvenConfig;
+/**
+ * Verify a signed manifest against ruflo's config public key. Returns the
+ * manifest on success, or null on ANY failure (bad signature, malformed JSON,
+ * wrong algorithm, missing fields). Fail-closed.
+ */
+export declare function verifyProvenConfig(signedJson: string | SignedProvenConfig, pubkeyPem?: string): ProvenConfigManifest | null;
+/**
+ * Minimal semver-range satisfier for the compat contract. Supports `>=X`, `>X`,
+ * `<=X`, `<X`, `=X`, and a bare version `X` (treated as `>=X`). Deliberately
+ * small — the manifest contract only uses min-version bounds.
+ */
+export declare function satisfiesRange(installed: string, range: string): boolean;
+export interface SuitabilityResult {
+    suitable: boolean;
+    reason?: string;
+}
+/**
+ * Check a manifest's constraint contract against the local environment.
+ * Fail-closed: a missing/unsatisfiable constraint => not suitable (safe skip).
+ * A constraint the manifest doesn't declare is not required.
+ */
+export declare function isSuitable(manifest: ProvenConfigManifest, env: InstallEnv): SuitabilityResult;
+/**
+ * The combined adoption decision (ADR-177): a manifest is adoptable iff it is
+ * both authentic (signature verifies) AND suitable (constraints satisfied).
+ */
+export declare function evaluateForAdoption(signedJson: string | SignedProvenConfig, env: InstallEnv, pubkeyPem?: string): {
+    adopt: boolean;
+    manifest?: ProvenConfigManifest;
+    reason: string;
+};
+//# sourceMappingURL=proven-config.d.ts.map