claude-flow 3.25.6 → 3.26.0

package/v3/@claude-flow/guidance/dist/proof.js

@@ -1,238 +0,0 @@
-/**
- * Proof Envelope - Cryptographic Evidence Trail
- *
- * Makes every run auditable and tamper-evident by producing a hash-chained,
- * HMAC-signed envelope for each RunEvent. Each envelope captures:
- *
- * - SHA-256 content hash of the run event
- * - Hash chain linking to the previous envelope (genesis = '0' x 64)
- * - Individual tool call hashes
- * - Memory lineage (reads/writes with value hashes)
- * - HMAC-SHA256 signature over the entire envelope body
- *
- * @module @claude-flow/guidance/proof
- */
-import { createHash, createHmac, randomUUID } from 'node:crypto';
-import { timingSafeEqual } from './crypto-utils.js';
-// ============================================================================
-// Constants
-// ============================================================================
-const GENESIS_HASH = '0'.repeat(64);
-const SERIALIZATION_VERSION = 1;
-// ============================================================================
-// ProofChain
-// ============================================================================
-/**
- * A tamper-evident, hash-chained sequence of ProofEnvelopes.
- *
- * Each envelope links to the previous one via `previousHash`, forming
- * a blockchain-like structure. Every envelope is HMAC-signed so any
- * modification to the chain can be detected.
- */
-export class ProofChain {
-    envelopes = [];
-    signingKey;
-    constructor(signingKey) {
-        if (!signingKey) {
-            throw new Error('ProofChain requires an explicit signingKey — hardcoded defaults are not secure');
-        }
-        this.signingKey = signingKey;
-    }
-    /**
-     * Append a new ProofEnvelope to the chain.
-     *
-     * @param runEvent - The RunEvent to wrap
-     * @param toolCalls - Tool call records from the run
-     * @param memoryOps - Memory operations from the run
-     * @param metadata - Optional metadata overrides
-     * @returns The newly created and signed ProofEnvelope
-     */
-    append(runEvent, toolCalls = [], memoryOps = [], metadata) {
-        const previousHash = this.envelopes.length > 0
-            ? this.envelopes[this.envelopes.length - 1].contentHash
-            : GENESIS_HASH;
-        const contentHash = this.computeContentHash(runEvent);
-        const toolCallHashes = {};
-        for (const call of toolCalls) {
-            toolCallHashes[call.callId] = this.computeToolCallHash(call);
-        }
-        const memoryLineage = memoryOps.map(op => ({
-            key: op.key,
-            namespace: op.namespace,
-            operation: op.operation,
-            hash: op.valueHash,
-        }));
-        const envelope = {
-            envelopeId: randomUUID(),
-            runEventId: runEvent.eventId,
-            timestamp: new Date().toISOString(),
-            contentHash,
-            previousHash,
-            toolCallHashes,
-            guidanceHash: runEvent.guidanceHash,
-            memoryLineage,
-            signature: '', // placeholder; signed below
-            metadata: {
-                agentId: metadata?.agentId ?? 'unknown',
-                sessionId: metadata?.sessionId ?? runEvent.sessionId ?? 'unknown',
-                parentEnvelopeId: metadata?.parentEnvelopeId,
-            },
-        };
-        envelope.signature = this.signEnvelope(envelope);
-        this.envelopes.push(envelope);
-        return envelope;
-    }
-    /**
-     * Verify a single envelope's HMAC signature and hash chain link.
-     *
-     * @returns true if the signature is valid and the previousHash is correct
-     */
-    verify(envelope) {
-        // Verify HMAC signature
-        const expectedSignature = this.signEnvelope(envelope);
-        if (!timingSafeEqual(envelope.signature, expectedSignature)) {
-            return false;
-        }
-        // Verify hash chain linkage
-        const index = this.envelopes.findIndex(e => e.envelopeId === envelope.envelopeId);
-        if (index === -1) {
-            // Envelope not in this chain; verify signature only
-            return true;
-        }
-        if (index === 0) {
-            return envelope.previousHash === GENESIS_HASH;
-        }
-        return envelope.previousHash === this.envelopes[index - 1].contentHash;
-    }
-    /**
-     * Verify the entire chain from genesis to tip.
-     *
-     * Checks that every envelope:
-     * 1. Has a valid HMAC signature
-     * 2. Links correctly to the previous envelope's contentHash
-     *
-     * @returns true if the full chain is intact
-     */
-    verifyChain() {
-        if (this.envelopes.length === 0) {
-            return true;
-        }
-        for (let i = 0; i < this.envelopes.length; i++) {
-            const envelope = this.envelopes[i];
-            // Verify signature (constant-time comparison)
-            const expectedSignature = this.signEnvelope(envelope);
-            if (!timingSafeEqual(envelope.signature, expectedSignature)) {
-                return false;
-            }
-            // Verify hash chain
-            if (i === 0) {
-                if (envelope.previousHash !== GENESIS_HASH) {
-                    return false;
-                }
-            }
-            else {
-                if (envelope.previousHash !== this.envelopes[i - 1].contentHash) {
-                    return false;
-                }
-            }
-        }
-        return true;
-    }
-    /**
-     * Retrieve an envelope by its ID.
-     */
-    getEnvelope(id) {
-        return this.envelopes.find(e => e.envelopeId === id);
-    }
-    /**
-     * Get the most recent envelope in the chain.
-     */
-    getChainTip() {
-        return this.envelopes.length > 0
-            ? this.envelopes[this.envelopes.length - 1]
-            : undefined;
-    }
-    /**
-     * Get the number of envelopes in the chain.
-     */
-    getChainLength() {
-        return this.envelopes.length;
-    }
-    /**
-     * Export the chain as a serializable object.
-     */
-    export() {
-        return {
-            envelopes: this.envelopes.map(e => ({ ...e })),
-            createdAt: new Date().toISOString(),
-            version: SERIALIZATION_VERSION,
-        };
-    }
-    /**
-     * Restore the chain from a previously exported object.
-     *
-     * Replaces the current chain contents entirely.
-     */
-    import(data) {
-        if (data.version !== SERIALIZATION_VERSION) {
-            throw new Error(`Unsupported proof chain version: ${data.version} (expected ${SERIALIZATION_VERSION})`);
-        }
-        this.envelopes = data.envelopes.map(e => ({ ...e }));
-    }
-    // ===========================================================================
-    // Private helpers
-    // ===========================================================================
-    /**
-     * Compute the SHA-256 content hash of a RunEvent.
-     */
-    computeContentHash(event) {
-        const payload = JSON.stringify(event, Object.keys(event).sort());
-        return createHash('sha256').update(payload).digest('hex');
-    }
-    /**
-     * Compute the SHA-256 hash of a single tool call.
-     *
-     * Hash = SHA-256(toolName + JSON(params) + JSON(result))
-     */
-    computeToolCallHash(call) {
-        const payload = call.toolName
-            + JSON.stringify(call.params)
-            + JSON.stringify(call.result);
-        return createHash('sha256').update(payload).digest('hex');
-    }
-    /**
-     * Produce the HMAC-SHA256 signature for an envelope.
-     *
-     * The signature covers every field except `signature` itself.
-     */
-    signEnvelope(envelope) {
-        const body = {
-            envelopeId: envelope.envelopeId,
-            runEventId: envelope.runEventId,
-            timestamp: envelope.timestamp,
-            contentHash: envelope.contentHash,
-            previousHash: envelope.previousHash,
-            toolCallHashes: envelope.toolCallHashes,
-            guidanceHash: envelope.guidanceHash,
-            memoryLineage: envelope.memoryLineage,
-            metadata: envelope.metadata,
-        };
-        const payload = JSON.stringify(body);
-        return createHmac('sha256', this.signingKey).update(payload).digest('hex');
-    }
-}
-// ============================================================================
-// Factory
-// ============================================================================
-/**
- * Create a new ProofChain instance.
- *
- * @param config - Configuration with a required `signingKey` for HMAC signing.
- *   Callers that previously relied on the optional signature must now provide
- *   an explicit key (see ADR-G026).
- * @returns A fresh ProofChain
- */
-export function createProofChain(config) {
-    return new ProofChain(config.signingKey);
-}
-//# sourceMappingURL=proof.js.map

package/v3/@claude-flow/guidance/dist/retriever.d.ts

@@ -1,172 +0,0 @@
-/**
- * Task Intent Classifier + Shard Retriever
- *
- * Stores rule shards in vector storage with embeddings and metadata.
- * At task start, retrieves the top N shards by semantic similarity
- * with hard filters by risk class and repo scope.
- *
- * Retrieval contract:
- * 1. Always include the constitution
- * 2. Retrieve up to 5 shards by semantic similarity
- * 3. Add hard filters by risk class and repo scope
- * 4. Contradiction check: prefer higher-priority rule ID
- *
- * @module @claude-flow/guidance/retriever
- */
-import type { PolicyBundle, Constitution, TaskIntent, RetrievalRequest, RetrievalResult } from './types.js';
-export interface IEmbeddingProvider {
-    embed(text: string): Promise<Float32Array>;
-    batchEmbed(texts: string[]): Promise<Float32Array[]>;
-}
-/**
- * Deterministic hash-based embedding provider — **test-only**.
- *
- * Produces fixed-dimension vectors from a simple character-hash → sin()
- * transform.  The resulting embeddings have no real semantic meaning;
- * they are stable and fast, which makes them useful for unit/integration
- * tests that need a concrete {@link IEmbeddingProvider} without loading
- * an ONNX model.
- *
- * **Do NOT use in production** — replace with a real model-backed
- * provider (e.g. the agentic-flow ONNX integration).
- */
-export declare class HashEmbeddingProvider implements IEmbeddingProvider {
-    private dimensions;
-    private cache;
-    constructor(dimensions?: number);
-    embed(text: string): Promise<Float32Array>;
-    batchEmbed(texts: string[]): Promise<Float32Array[]>;
-    private hashEmbed;
-}
-export declare class ShardRetriever {
-    private shards;
-    private constitution;
-    private embeddingProvider;
-    private indexed;
-    private globCache;
-    private packedEmbeddings;
-    private packedDim;
-    private packedShardCount;
-    private packedSignatures;
-    private wordsPerSig;
-    constructor(embeddingProvider?: IEmbeddingProvider);
-    /**
-     * Load a compiled policy bundle
-     */
-    loadBundle(bundle: PolicyBundle): Promise<void>;
-    /**
-     * Index all shards by generating embeddings.
-     *
-     * M3 substrate — also packs every shard embedding into a single
-     * contiguous Float32Array (`packedEmbeddings`) so scoreShards can run
-     * the cosine as a vectorized matrix-vector dot in cache-friendly
-     * sequential memory rather than chasing per-shard heap pointers.
-     * Costs O(n × dim) at index time (one-shot) for an O(n) scan win
-     * on every query.
-     */
-    indexShards(): Promise<void>;
-    /**
-     * Build a 1-bit sign signature for the query vector. Matches the
-     * packed-shard format produced in indexShards above.
-     */
-    private buildQuerySignature;
-    /**
-     * Hamming-Weight popcount on a single 32-bit word (Wegner / Wilkes).
-     * Tested at ~1 ns on V8 — no native popcnt instruction exposed.
-     */
-    private static popcount32;
-    /**
-     * Classify task intent
-     */
-    classifyIntent(taskDescription: string): {
-        intent: TaskIntent;
-        confidence: number;
-    };
-    /**
-     * Retrieve relevant shards for a task
-     *
-     * Contract:
-     * 1. Always include the constitution
-     * 2. Up to maxShards by semantic similarity
-     * 3. Hard filters by risk class and repo scope
-     * 4. Contradiction check: prefer higher priority
-     */
-    retrieve(request: RetrievalRequest): Promise<RetrievalResult>;
-    /**
-     * Score all shards against the query.
-     *
-     * M3 perf substrate — three changes from the baseline:
-     *
-     *   1. Filter FIRST, cosine SECOND. The old code computed cosine for
-     *      every shard regardless of whether riskFilter/repoScope would
-     *      throw it away. We now decide eligibility first and only do
-     *      the 384-dim multiply for survivors.
-     *
-     *   2. Packed-matrix cosine — when `packedEmbeddings` is current and
-     *      dim matches, compute the dot directly from contiguous memory
-     *      (one allocation, sequential reads) instead of dereferencing
-     *      `shard.embedding` per call. Embeddings are always unit-
-     *      normalised so cosine === dot + clamp.
-     *
-     *   3. Top-K partial selection — when the caller only wants `maxShards`
-     *      results (typical), don't `.sort()` the entire candidate list.
-     *      Maintain a fixed-size heap of size K and only compare/swap
-     *      against its current minimum. Drops the final step from
-     *      O(n log n) to O(n log K).
-     */
-    private scoreShards;
-    /**
-     * Select top N shards with contradiction checking
-     * When two rules contradict, keep the one with higher priority
-     */
-    private selectWithContradictionCheck;
-    /**
-     * Check if two rules are contradictory
-     */
-    private areContradictory;
-    /**
-     * Count contradictions in selected set
-     */
-    private countContradictions;
-    /**
-     * Build combined policy text for injection
-     */
-    private buildPolicyText;
-    /**
-     * Simple glob matching (supports * and **).
-     * Compiled regexes are cached per glob to avoid re-compiling on every call.
-     */
-    private matchGlob;
-    /**
-     * Cosine similarity between two vectors.
-     *
-     * Phase 1 perf — the embeddings this retriever consumes are always
-     * unit-normalised at production time:
-     *   - HashEmbeddingProvider divides by L2 norm before returning
-     *     (this file, line 134)
-     *   - ONNX providers (all-MiniLM-L6-v2 and friends) emit unit vectors
-     *     by design
-     * That means `sqrt(normA) * sqrt(normB) === 1` and the only useful
-     * computation per pair is the dot product. The old 3-accumulator
-     * version computed dot + both norms + two sqrts + a div + a clamp —
-     * for a result the math already guarantees lies in [-1, 1]. We drop
-     * to pure dot + a defensive clamp.
-     *
-     * This compounds: every `scoreShards()` call ran `O(shards)` of these,
-     * and `retrieveForTask()` runs it per query.
-     */
-    private cosineSimilarity;
-    /**
-     * Get current shard count
-     */
-    get shardCount(): number;
-    /**
-     * Get constitution
-     */
-    getConstitution(): Constitution | null;
-}
-/**
- * Create a retriever instance
- */
-export declare function createRetriever(embeddingProvider?: IEmbeddingProvider): ShardRetriever;
-//# sourceMappingURL=retriever.d.ts.map