claude-flow 3.28.0 → 3.29.0

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

@@ -0,0 +1,238 @@
+/**
+ * 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

@@ -0,0 +1,172 @@
+/**
+ * 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