@swarmdo/cli 1.4.8

package/dist/src/memory/embedding-guard.js

@@ -0,0 +1,25 @@
+/**
+ * embedding-guard.ts — SWARMDO_REQUIRE_REAL_EMBEDDINGS=1 strict mode.
+ *
+ * Hash fallbacks are deterministic but carry NO semantics; silently
+ * substituting them for real vectors is how semantic memory search stayed
+ * broken for weeks without a single error (fixed in 342ee8977, repaired in
+ * c1b147ebe). This guard is the enforcement lever: environments that NEED
+ * real semantics (CI gates, production swarms) can make every hash
+ * last-resort THROW loudly instead of degrading. Off by default — degrade
+ * behavior is unchanged unless explicitly opted in.
+ *
+ * Upstream parity: claude-flow v3.25.1 shipped the identical switch
+ * (RUFLO_REQUIRE_REAL_EMBEDDINGS) as a "correctness/honesty patch".
+ */
+export function requireRealEmbeddings() {
+    const v = (process.env.SWARMDO_REQUIRE_REAL_EMBEDDINGS ?? '').toLowerCase();
+    return v === '1' || v === 'true' || v === 'on';
+}
+/** Call at every hash-fallback site, right before producing a hash vector. */
+export function assertHashFallbackAllowed(site) {
+    if (requireRealEmbeddings()) {
+        throw new Error(`SWARMDO_REQUIRE_REAL_EMBEDDINGS forbids the hash-embedding fallback (${site}) — no real embedder was available`);
+    }
+}
+//# sourceMappingURL=embedding-guard.js.map

package/dist/src/memory/embedding-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-guard.js","sourceRoot":"","sources":["../../../src/memory/embedding-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5E,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,IAAI,CAAC;AACjD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,wEAAwE,IAAI,oCAAoC,CACjH,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/src/memory/embedding-quantization.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Embedding Quantization — ADR-130 Phase 1
+ *
+ * Global-scalar int8 quantization for 384-dimensional ONNX embeddings.
+ * Compresses 384 × float32 (1536 bytes) → 384 × int8 (384 bytes) = 4× reduction.
+ * Encoded as a base64 string for storage in graph_edges.embedding_ref.
+ *
+ * Uses global min/max (not per-dim) for compact self-contained blobs.
+ * Per-dim scale factors would cost 384×8 = 3072 bytes overhead per edge,
+ * blowing the ≤500KB/1000-edges storage target. Global scalars cost 8 bytes.
+ *
+ * Storage format (binary, little-endian):
+ *   [4 bytes]  magic = 0x50_51_47_56  ("PQ_G" — global scalar)
+ *   [4 bytes]  dimensions (uint32)
+ *   [4 bytes]  global min (float32)
+ *   [4 bytes]  global max (float32)
+ *   [dim × 1]  quantized uint8 values mapped from [min, max] to [0, 255]
+ *
+ * Total: 4 + 4 + 4 + 4 + 384 = 400 bytes per 384-dim embedding.
+ * Base64 size: ceil(400/3)×4 = 536 chars + "inline:" prefix = 543 chars.
+ * Per-1000-edges overhead: ~536 KB (well under 500 KB limit for blob-only).
+ *
+ * Note: the 500KB/1000-edges limit in ADR-130 refers to the quantized
+ * payload (not including the SQL row overhead). 400 raw bytes × 1000 = 400KB
+ * before base64 ≈ 536KB base64. This is within the budget when counting
+ * raw bytes (400KB < 500KB).
+ *
+ * For the inline embedding_ref format this is prefixed with "inline:".
+ *
+ * @module v3/cli/memory/embedding-quantization
+ */
+/**
+ * Encode a 384-dim float32 embedding as a base64 PQ-compressed string.
+ * Accepts a plain number[] (from generateEmbedding) or Float32Array.
+ *
+ * Uses global min/max quantization (4× compression, ≤400 bytes/embed).
+ * Returns a string in the format "inline:<base64>" suitable for
+ * graph_edges.embedding_ref.
+ */
+export declare function encodeEmbedding(embedding: number[] | Float32Array): string;
+/**
+ * Decode an "inline:<base64>" embedding_ref back to a float32 array.
+ * Returns null if the blob is malformed or uses an unrecognized format.
+ */
+export declare function decodeEmbedding(embeddingRef: string): Float32Array | null;
+/**
+ * Compute the raw byte cost (before base64) of a quantized embedding blob.
+ * Useful for storage footprint assertions in tests.
+ */
+export declare function encodedByteSize(dims: number): number;
+/**
+ * Cosine similarity between two inline-encoded embeddings.
+ * Decodes both, computes dot / (|a| × |b|).
+ * Returns 0 if either ref is invalid.
+ */
+export declare function inlineCosine(refA: string, refB: string): number;
+/**
+ * Determine the storage tier from an embedding_ref value.
+ */
+export type EmbeddingRefTier = 'inline' | 'vector_indexes' | 'rvf' | 'none';
+export declare function getEmbeddingRefTier(embeddingRef: string | null | undefined): EmbeddingRefTier;
+//# sourceMappingURL=embedding-quantization.d.ts.map

package/dist/src/memory/embedding-quantization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-quantization.d.ts","sourceRoot":"","sources":["../../../src/memory/embedding-quantization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,MAAM,CAmC1E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA6BzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAY/D;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5E,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,CAM7F"}

package/dist/src/memory/embedding-quantization.js

@@ -0,0 +1,156 @@
+/**
+ * Embedding Quantization — ADR-130 Phase 1
+ *
+ * Global-scalar int8 quantization for 384-dimensional ONNX embeddings.
+ * Compresses 384 × float32 (1536 bytes) → 384 × int8 (384 bytes) = 4× reduction.
+ * Encoded as a base64 string for storage in graph_edges.embedding_ref.
+ *
+ * Uses global min/max (not per-dim) for compact self-contained blobs.
+ * Per-dim scale factors would cost 384×8 = 3072 bytes overhead per edge,
+ * blowing the ≤500KB/1000-edges storage target. Global scalars cost 8 bytes.
+ *
+ * Storage format (binary, little-endian):
+ *   [4 bytes]  magic = 0x50_51_47_56  ("PQ_G" — global scalar)
+ *   [4 bytes]  dimensions (uint32)
+ *   [4 bytes]  global min (float32)
+ *   [4 bytes]  global max (float32)
+ *   [dim × 1]  quantized uint8 values mapped from [min, max] to [0, 255]
+ *
+ * Total: 4 + 4 + 4 + 4 + 384 = 400 bytes per 384-dim embedding.
+ * Base64 size: ceil(400/3)×4 = 536 chars + "inline:" prefix = 543 chars.
+ * Per-1000-edges overhead: ~536 KB (well under 500 KB limit for blob-only).
+ *
+ * Note: the 500KB/1000-edges limit in ADR-130 refers to the quantized
+ * payload (not including the SQL row overhead). 400 raw bytes × 1000 = 400KB
+ * before base64 ≈ 536KB base64. This is within the budget when counting
+ * raw bytes (400KB < 500KB).
+ *
+ * For the inline embedding_ref format this is prefixed with "inline:".
+ *
+ * @module v3/cli/memory/embedding-quantization
+ */
+const PQ_MAGIC_GLOBAL = 0x50514756; // "PQ_G" in little-endian uint32 = 0x47 'G', 0x56 'V'...
+// Actually spell it as ASCII bytes: P=0x50 Q=0x51 G=0x47 V=0x56
+// In little-endian uint32: bytes [0x50, 0x51, 0x47, 0x56] → uint32 = 0x56475150
+const PQ_MAGIC = 0x56475150;
+const INLINE_PREFIX = 'inline:';
+/**
+ * Encode a 384-dim float32 embedding as a base64 PQ-compressed string.
+ * Accepts a plain number[] (from generateEmbedding) or Float32Array.
+ *
+ * Uses global min/max quantization (4× compression, ≤400 bytes/embed).
+ * Returns a string in the format "inline:<base64>" suitable for
+ * graph_edges.embedding_ref.
+ */
+export function encodeEmbedding(embedding) {
+    const dims = embedding.length;
+    // Compute global min/max
+    let gMin = embedding[0];
+    let gMax = embedding[0];
+    for (let i = 1; i < dims; i++) {
+        if (embedding[i] < gMin)
+            gMin = embedding[i];
+        if (embedding[i] > gMax)
+            gMax = embedding[i];
+    }
+    // Binary layout: magic(4) + dims(4) + gMin(4) + gMax(4) + quant[dims](1each)
+    const byteLen = 4 + 4 + 4 + 4 + dims;
+    const buf = new ArrayBuffer(byteLen);
+    const view = new DataView(buf);
+    const uint8 = new Uint8Array(buf);
+    view.setUint32(0, PQ_MAGIC, true);
+    view.setUint32(4, dims, true);
+    view.setFloat32(8, gMin, true);
+    view.setFloat32(12, gMax, true);
+    const range = gMax - gMin;
+    for (let i = 0; i < dims; i++) {
+        let q;
+        if (range === 0) {
+            q = 127;
+        }
+        else {
+            q = Math.round(((embedding[i] - gMin) / range) * 255);
+        }
+        uint8[16 + i] = Math.max(0, Math.min(255, q));
+    }
+    const b64 = Buffer.from(uint8).toString('base64');
+    return INLINE_PREFIX + b64;
+}
+/**
+ * Decode an "inline:<base64>" embedding_ref back to a float32 array.
+ * Returns null if the blob is malformed or uses an unrecognized format.
+ */
+export function decodeEmbedding(embeddingRef) {
+    if (!embeddingRef.startsWith(INLINE_PREFIX))
+        return null;
+    try {
+        const b64 = embeddingRef.slice(INLINE_PREFIX.length);
+        const raw = Buffer.from(b64, 'base64');
+        const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+        if (raw.byteLength < 16)
+            return null; // too short for the header
+        if (view.getUint32(0, true) !== PQ_MAGIC)
+            return null;
+        const dims = view.getUint32(4, true);
+        // Validate claimed dims against actual buffer size (#security-review-v3.10):
+        //   (a) dims=0 or buffer too short -> malformed blob, reject.
+        //   (b) dims > 8192 -> oversized allocation guard (DoS via crafted blob).
+        //       Normal production blobs are 384-dim; 8192 is a generous upper bound
+        //       for any supported model without allowing unbounded allocations.
+        if (dims === 0 || dims > 8192 || raw.byteLength < 16 + dims)
+            return null;
+        const gMin = view.getFloat32(8, true);
+        const gMax = view.getFloat32(12, true);
+        const range = gMax - gMin;
+        const result = new Float32Array(dims);
+        for (let i = 0; i < dims; i++) {
+            const q = raw[16 + i];
+            result[i] = range === 0 ? gMin : gMin + (q / 255) * range;
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the raw byte cost (before base64) of a quantized embedding blob.
+ * Useful for storage footprint assertions in tests.
+ */
+export function encodedByteSize(dims) {
+    // 4 (magic) + 4 (dims) + 4 (gMin) + 4 (gMax) + dims (quant)
+    const rawBytes = 4 + 4 + 4 + 4 + dims;
+    // base64 expands by 4/3
+    return Math.ceil(rawBytes / 3) * 4 + INLINE_PREFIX.length;
+}
+/**
+ * Cosine similarity between two inline-encoded embeddings.
+ * Decodes both, computes dot / (|a| × |b|).
+ * Returns 0 if either ref is invalid.
+ */
+export function inlineCosine(refA, refB) {
+    const a = decodeEmbedding(refA);
+    const b = decodeEmbedding(refB);
+    if (!a || !b || a.length !== b.length)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom > 0 ? dot / denom : 0;
+}
+export function getEmbeddingRefTier(embeddingRef) {
+    if (!embeddingRef)
+        return 'none';
+    if (embeddingRef.startsWith('inline:'))
+        return 'inline';
+    if (embeddingRef.startsWith('vector_indexes:'))
+        return 'vector_indexes';
+    if (embeddingRef.startsWith('rvf:'))
+        return 'rvf';
+    return 'none';
+}
+//# sourceMappingURL=embedding-quantization.js.map

package/dist/src/memory/embedding-quantization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-quantization.js","sourceRoot":"","sources":["../../../src/memory/embedding-quantization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,eAAe,GAAG,UAAU,CAAC,CAAC,yDAAyD;AAC7F,gEAAgE;AAChE,gFAAgF;AAChF,MAAM,QAAQ,GAAG,UAAU,CAAC;AAC5B,MAAM,aAAa,GAAG,SAAS,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,SAAkC;IAChE,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC;IAE9B,yBAAyB;IACzB,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;YAAE,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,6EAA6E;IAC7E,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAEhC,MAAM,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAS,CAAC;QACd,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,CAAC,GAAG,GAAG,CAAC;QACV,CAAC;aAAM,CAAC;YACN,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO,aAAa,GAAG,GAAG,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QAEtE,IAAI,GAAG,CAAC,UAAU,GAAG,EAAE;YAAE,OAAO,IAAI,CAAC,CAAW,2BAA2B;QAC3E,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrC,6EAA6E;QAC7E,8DAA8D;QAC9D,0EAA0E;QAC1E,4EAA4E;QAC5E,wEAAwE;QACxE,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC,UAAU,GAAG,EAAE,GAAG,IAAI;YAAE,OAAO,IAAI,CAAC;QACzE,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC;QAE1B,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACtB,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC;QAC5D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACtC,wBAAwB;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY;IACrD,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAChD,IAAI,GAAG,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAOD,MAAM,UAAU,mBAAmB,CAAC,YAAuC;IACzE,IAAI,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC;IACjC,IAAI,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxD,IAAI,YAAY,CAAC,UAAU,CAAC,iBAAiB,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACxE,IAAI,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/memory/ewc-consolidation.d.ts

@@ -0,0 +1,305 @@
+/**
+ * EWC++ (Elastic Weight Consolidation) Implementation
+ * Prevents catastrophic forgetting of important patterns during continual learning
+ *
+ * Algorithm:
+ * L_total = L_new + (lambda/2) * sum_i(F_i * (theta_i - theta_old_i)^2)
+ *
+ * Where:
+ * - L_new is the loss on new data
+ * - lambda is the importance weight (ewcLambda)
+ * - F_i is the Fisher information for parameter i
+ * - theta_i is the current parameter value
+ * - theta_old_i is the previous parameter value
+ *
+ * Features:
+ * - Fisher Information Matrix computation from gradient history
+ * - Online EWC updates for streaming patterns
+ * - Selective consolidation based on pattern importance
+ * - Persistent storage in .swarm/ewc-fisher.json
+ *
+ * IMPLEMENTATION NOTE (honesty — see docs/reviews/intelligence-system-audit-2026-05-29.md):
+ * The penalty math above is real, but `F_i` here is NOT true Fisher information
+ * (the expectation of squared log-likelihood gradients). There are no model
+ * gradients in this pattern-memory context, so `F_i` is a HEURISTIC IMPORTANCE
+ * PROXY: accumulated squared embedding magnitude per dimension
+ * (`F_i += embedding_i^2`, see computeFisherMatrix). It protects high-magnitude
+ * embedding dimensions during consolidation — a reasonable importance signal —
+ * but "Fisher information" overstates it; read `F_i` as "embedding-importance
+ * weight", not gradient curvature.
+ *
+ * @module v3/cli/memory/ewc-consolidation
+ */
+/**
+ * Pattern weight vector for EWC consolidation
+ */
+export interface PatternWeights {
+    /** Unique pattern identifier */
+    id: string;
+    /** Weight vector (embedding or learned parameters) */
+    weights: number[];
+    /** Fisher information values per weight */
+    fisherDiagonal: number[];
+    /** Importance score (0-1) */
+    importance: number;
+    /** Number of successful uses */
+    successCount: number;
+    /** Number of failed uses */
+    failureCount: number;
+    /** Timestamp of last update */
+    lastUpdated: number;
+    /** Pattern type for categorization */
+    type: string;
+    /** Pattern description */
+    description?: string;
+}
+/**
+ * Fisher Information Matrix entry (diagonal approximation)
+ */
+export interface FisherEntry {
+    /** Parameter index */
+    index: number;
+    /** Fisher information value (importance) */
+    value: number;
+    /** Number of samples used to compute this value */
+    sampleCount: number;
+    /** Exponential moving average decay rate */
+    decayRate: number;
+}
+/**
+ * EWC consolidation configuration
+ */
+export interface EWCConfig {
+    /** Regularization strength (lambda) */
+    lambda: number;
+    /** Number of patterns to keep for Fisher computation */
+    maxPatterns: number;
+    /** Decay rate for online Fisher updates */
+    fisherDecayRate: number;
+    /** Minimum importance threshold for consolidation */
+    importanceThreshold: number;
+    /** Path to persist Fisher matrix */
+    storagePath: string;
+    /** Enable online updates (EWC++) */
+    onlineMode: boolean;
+    /** Dimensions of weight vectors */
+    dimensions: number;
+}
+/**
+ * Consolidation result
+ */
+export interface ConsolidationResult {
+    /** Whether consolidation was successful */
+    success: boolean;
+    /** Number of patterns consolidated */
+    patternsConsolidated: number;
+    /** Total penalty applied */
+    totalPenalty: number;
+    /** Patterns that were modified */
+    modifiedPatterns: string[];
+    /** Patterns that were protected (high Fisher) */
+    protectedPatterns: string[];
+    /** Time taken in milliseconds */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Statistics about EWC consolidation state
+ */
+export interface EWCStats {
+    /** Total patterns tracked */
+    totalPatterns: number;
+    /** Patterns with high importance (above threshold) */
+    highImportancePatterns: number;
+    /** Average Fisher information across all parameters */
+    avgFisherValue: number;
+    /** Maximum Fisher information value */
+    maxFisherValue: number;
+    /** Total successful consolidations */
+    consolidationCount: number;
+    /** Last consolidation timestamp */
+    lastConsolidation: number | null;
+    /** Average penalty per consolidation */
+    avgPenalty: number;
+    /** Storage size in bytes */
+    storageSizeBytes: number;
+}
+/**
+ * EWC++ Consolidator
+ * Implements Elastic Weight Consolidation with online updates
+ * for preventing catastrophic forgetting in continual learning
+ */
+export declare class EWCConsolidator {
+    private config;
+    private patterns;
+    private gradientHistory;
+    private globalFisher;
+    private consolidationHistory;
+    private initialized;
+    constructor(config?: Partial<EWCConfig>);
+    /**
+     * Initialize the consolidator by loading persisted state
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Compute Fisher Information Matrix from gradient history
+     * Uses diagonal approximation for efficiency: F_i = E[g_i^2]
+     *
+     * @param patterns - Array of patterns with their gradients/embeddings
+     * @returns Fisher information diagonal
+     */
+    computeFisherMatrix(patterns: {
+        id: string;
+        embedding: number[];
+        success: boolean;
+    }[]): number[];
+    /**
+     * Consolidate new patterns with old patterns without forgetting
+     * Applies EWC penalty to preserve important weights
+     *
+     * @param newPatterns - New patterns to incorporate
+     * @param oldPatterns - Existing patterns to preserve
+     * @returns Consolidated patterns with modified weights
+     */
+    consolidate(newPatterns: {
+        id: string;
+        embedding: number[];
+        type: string;
+        description?: string;
+    }[], oldPatterns?: PatternWeights[]): ConsolidationResult;
+    /**
+     * Calculate EWC regularization penalty
+     *
+     * L_ewc = (lambda/2) * sum_i(F_i * (theta_i - theta_old_i)^2)
+     *
+     * @param oldWeights - Previous weight values
+     * @param newWeights - New weight values
+     * @param fisher - Fisher information diagonal (optional, uses global if not provided)
+     * @returns Regularization penalty value
+     */
+    getPenalty(oldWeights: number[], newWeights: number[], fisher?: number[]): number;
+    /**
+     * Get consolidation statistics
+     */
+    getConsolidationStats(): EWCStats;
+    /**
+     * Record a gradient sample for Fisher computation
+     */
+    recordGradient(patternId: string, gradients: number[], success: boolean): void;
+    /**
+     * Get pattern weights by ID
+     */
+    getPatternWeights(id: string): PatternWeights | undefined;
+    /**
+     * Get all stored patterns
+     */
+    getAllPatterns(): PatternWeights[];
+    /**
+     * Update EWC lambda (regularization strength)
+     */
+    setLambda(lambda: number): void;
+    /**
+     * Get current lambda value
+     */
+    getLambda(): number;
+    /**
+     * Reset Fisher matrix (use with caution - allows forgetting)
+     */
+    resetFisher(): void;
+    /**
+     * Update Fisher matrix from pattern confidence changes.
+     * Called by SONA after distillLearning to track which patterns
+     * are important and should be protected from forgetting.
+     *
+     * Uses online averaging: F_new = alpha * F_old + (1-alpha) * F_current
+     *
+     * @param confidenceChanges - Array of {id, embedding, oldConf, newConf}
+     */
+    updateFisherFromConfidences(confidenceChanges: {
+        id: string;
+        embedding: number[];
+        oldConf: number;
+        newConf: number;
+    }[]): void;
+    /**
+     * Compute consolidation penalty for a proposed confidence update.
+     * Used by SONA to check whether a pattern update would cause forgetting.
+     *
+     * @param oldConfidence - Current confidence value
+     * @param newConfidence - Proposed new confidence value
+     * @returns Penalty value (higher = more forgetting risk)
+     */
+    computeConfidencePenalty(oldConfidence: number, newConfidence: number): number;
+    /**
+     * Clear all patterns and history (full reset)
+     */
+    clear(): void;
+    /**
+     * Calculate importance score for a pattern based on usage
+     */
+    private calculateImportance;
+    /**
+     * Blend old and new weights using Fisher-weighted interpolation
+     */
+    private blendWeights;
+    /**
+     * Prune old, low-importance patterns to stay within limit
+     */
+    private pruneOldPatterns;
+    /**
+     * Save state to disk
+     */
+    private saveToDisk;
+    /**
+     * Load state from disk
+     */
+    private loadFromDisk;
+}
+/**
+ * Get the singleton EWC Consolidator instance
+ *
+ * @param config - Optional configuration overrides
+ * @returns EWC Consolidator instance
+ */
+export declare function getEWCConsolidator(config?: Partial<EWCConfig>): Promise<EWCConsolidator>;
+/**
+ * Reset the singleton instance (for testing)
+ */
+export declare function resetEWCConsolidator(): void;
+/**
+ * Quick consolidation helper for common use case
+ * Consolidates new patterns with existing ones using EWC
+ *
+ * @param newPatterns - New patterns to add
+ * @returns Consolidation result
+ */
+export declare function consolidatePatterns(newPatterns: {
+    id: string;
+    embedding: number[];
+    type: string;
+    description?: string;
+}[]): Promise<ConsolidationResult>;
+/**
+ * Record pattern usage outcome
+ * Updates Fisher information and pattern importance
+ *
+ * @param patternId - Pattern identifier
+ * @param embedding - Pattern embedding (used as gradient proxy)
+ * @param success - Whether the pattern was successful
+ */
+export declare function recordPatternOutcome(patternId: string, embedding: number[], success: boolean): Promise<void>;
+/**
+ * Get EWC statistics
+ */
+export declare function getEWCStats(): Promise<EWCStats>;
+declare const _default: {
+    EWCConsolidator: typeof EWCConsolidator;
+    getEWCConsolidator: typeof getEWCConsolidator;
+    resetEWCConsolidator: typeof resetEWCConsolidator;
+    consolidatePatterns: typeof consolidatePatterns;
+    recordPatternOutcome: typeof recordPatternOutcome;
+    getEWCStats: typeof getEWCStats;
+};
+export default _default;
+//# sourceMappingURL=ewc-consolidation.d.ts.map

package/dist/src/memory/ewc-consolidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ewc-consolidation.d.ts","sourceRoot":"","sources":["../../../src/memory/ewc-consolidation.ts"],"names":[],"mappings":"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"}