@beingmartinbmc/ojas 0.2.0

package/dist/nidra/index.js

@@ -0,0 +1,889 @@
+"use strict";
+/**
+ * Ojas Nidra (ओजस निद्रा) — AI Recovery & Consolidation System
+ *
+ * Governs how AI agents recover, stabilize, and evolve.
+ * Provides memory consolidation, cognitive recovery,
+ * and reflective learning cycles.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Nidra = void 0;
+const types_1 = require("../types");
+const id_1 = require("../util/id");
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function now() {
+    return new Date().toISOString();
+}
+function healthScore(value, source) {
+    return { value: clamp(value), timestamp: now(), source };
+}
+function clamp(v, min = 0, max = 1) {
+    return Math.max(min, Math.min(max, v));
+}
+function uuid() {
+    return (0, id_1.newId)('nidra');
+}
+/** Earliest ISO timestamp across the given traces, or `undefined` for empty input. */
+function earliestTimestamp(traces) {
+    if (traces.length === 0)
+        return undefined;
+    let earliest = traces[0].timestamp;
+    for (let i = 1; i < traces.length; i++) {
+        if (traces[i].timestamp < earliest)
+            earliest = traces[i].timestamp;
+    }
+    return earliest;
+}
+/** True iff the two applicability lists share at least one element. */
+function applicabilityOverlaps(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return false;
+    const setA = new Set(a);
+    for (const x of b)
+        if (setA.has(x))
+            return true;
+    return false;
+}
+// ─── Nidra Engine ────────────────────────────────────────────────────────────
+class Nidra {
+    policy;
+    traces = [];
+    memories = [];
+    cycleHistory = [];
+    lastRecovery = null;
+    /**
+     * Trace IDs that have been processed by a recovery cycle — regardless of
+     * whether they produced a retained memory. Without this set, low-confidence
+     * traces would be reprocessed forever because the prior implementation only
+     * treated a trace as "processed" if it ended up inside a kept memory.
+     */
+    processedTraceIds = new Set();
+    /**
+     * IDs of memories that have already emitted a `memory_cold` event
+     * during the current run, so we don't re-emit on every `assess()`
+     * pass while the temperature stays below the cold threshold.
+     * Cleared when a memory is re-warmed via `touchMemory`.
+     */
+    coldNotifiedIds = new Set();
+    /**
+     * IDs of memories pruned in this Nidra's lifetime, kept so
+     * `getMemoryDelta()` can report them under `removedIds`.
+     * Bounded by `maxProcessedTraceIds` to avoid unbounded growth.
+     */
+    prunedMemoryIds = [];
+    constructor(policy = {}) {
+        this.policy = this.validatePolicy({ ...types_1.DEFAULT_RECOVERY_POLICY, ...policy });
+    }
+    // ── Memory Temperature (Block 3 — Nidra upgrades) ────────────────────────
+    /**
+     * Mark a memory as accessed: bump its temperature toward `1.0` and
+     * stamp the touch timestamp. Used by agents when they actually read
+     * a memory; `Aahar.filter()` integrations can also call this when a
+     * memory makes it into the context window.
+     *
+     * Returns `true` if the touched memory was previously below the
+     * cold threshold (i.e. the touch *re-warmed* it). Callers may
+     * choose to suppress next-cycle `memory_cold` emission in that case.
+     */
+    touchMemory(id) {
+        const m = this.memories.find((x) => x.id === id);
+        if (!m)
+            return false;
+        const decayed = this.computeDecayedTemperature(m);
+        const boost = this.policy.temperatureBoostOnTouch ?? 0;
+        const newTemp = Math.min(1, decayed + boost);
+        const wasCold = decayed < (this.policy.coldTemperatureThreshold ?? 0.15);
+        m.temperature = newTemp;
+        m.temperatureUpdatedAt = now();
+        if (wasCold) {
+            // Allow a future cold-crossing to emit again now that we've re-warmed.
+            this.coldNotifiedIds.delete(id);
+        }
+        return wasCold;
+    }
+    /**
+     * Current temperature of `id`, with decay applied since the last
+     * touch. Returns `undefined` for unknown memory IDs.
+     */
+    getMemoryTemperature(id) {
+        const m = this.memories.find((x) => x.id === id);
+        if (!m)
+            return undefined;
+        return this.computeDecayedTemperature(m);
+    }
+    /**
+     * Decay model: exponential half-life. Given `temperature` last
+     * updated at `temperatureUpdatedAt`, returns the current decayed
+     * value. The half-life is configurable via
+     * `RecoveryPolicy.temperatureHalfLifeSec` (default one week).
+     */
+    computeDecayedTemperature(m) {
+        if (m.temperature === undefined)
+            return 0.5; // untracked = "warm"
+        const halfLife = this.policy.temperatureHalfLifeSec ?? 7 * 24 * 60 * 60;
+        if (halfLife <= 0)
+            return m.temperature; // decay disabled
+        const last = m.temperatureUpdatedAt ? Date.parse(m.temperatureUpdatedAt) : Date.parse(m.createdAt);
+        if (!Number.isFinite(last))
+            return m.temperature;
+        const dtSec = Math.max(0, (Date.now() - last) / 1000);
+        const decayFactor = Math.pow(0.5, dtSec / halfLife);
+        return clamp(m.temperature * decayFactor);
+    }
+    /**
+     * Returns memories whose decayed temperature is now below the cold
+     * threshold. The set is *idempotent across calls* via the
+     * `coldNotifiedIds` set, so this can be called from a periodic
+     * `assess()` pass without spamming the agent.
+     *
+     * The returned shape is the data needed to construct a `memory_cold`
+     * Pulse event; Ojas wires the actual emission in `Ojas.healthCheck()`.
+     */
+    detectColdMemories() {
+        const threshold = this.policy.coldTemperatureThreshold ?? 0.15;
+        const out = [];
+        for (const m of this.memories) {
+            if (m.temperature === undefined)
+                continue;
+            const decayed = this.computeDecayedTemperature(m);
+            if (decayed < threshold && !this.coldNotifiedIds.has(m.id)) {
+                out.push({ id: m.id, temperature: decayed, abstraction: m.abstraction });
+                this.coldNotifiedIds.add(m.id);
+            }
+        }
+        return out;
+    }
+    // ── Delta sync (Block 3 — Nidra upgrades) ────────────────────────────────
+    /**
+     * Cursor representing the agent's view of the memory set right now.
+     * The hash collapses a fingerprint of every active memory's
+     * `(id, createdAt, invalidatedAt?, content)` tuple so any change
+     * produces a different cursor.
+     */
+    getMemoryCursor() {
+        return {
+            cursorHash: this.computeMemoryHash(),
+            issuedAt: now(),
+        };
+    }
+    /**
+     * Return only the memories that changed since `cursor`. If the
+     * cursor is unknown (the agent is calling for the first time, or
+     * its cursor is older than our pruned-id horizon), the response is
+     * a full resync.
+     */
+    getMemoryDelta(cursor) {
+        const currentHash = this.computeMemoryHash();
+        const nextCursor = { cursorHash: currentHash, issuedAt: now() };
+        if (!cursor) {
+            return {
+                added: [...this.memories],
+                modified: [],
+                removedIds: [],
+                nextCursor,
+                fullResync: true,
+            };
+        }
+        if (cursor.cursorHash === currentHash) {
+            return { added: [], modified: [], removedIds: [], nextCursor, fullResync: false };
+        }
+        // We don't keep per-cursor snapshots — that would be O(N * cursors).
+        // Instead we use timestamps: anything created after `cursor.issuedAt`
+        // is `added`; anything updated after `cursor.issuedAt` (but created
+        // before) is `modified`; anything in `prunedMemoryIds` whose prune
+        // event was after `cursor.issuedAt` is `removed`. This is a
+        // best-effort delta — callers needing strict consistency should
+        // request a full resync via `getMemoryDelta()` with no argument.
+        const since = Date.parse(cursor.issuedAt);
+        if (!Number.isFinite(since)) {
+            return {
+                added: [...this.memories],
+                modified: [],
+                removedIds: [],
+                nextCursor,
+                fullResync: true,
+            };
+        }
+        const added = [];
+        const modified = [];
+        for (const m of this.memories) {
+            const createdAt = Date.parse(m.createdAt);
+            const invalidatedAt = m.invalidatedAt ? Date.parse(m.invalidatedAt) : 0;
+            const lastChange = Math.max(createdAt, invalidatedAt);
+            if (createdAt > since)
+                added.push(m);
+            else if (lastChange > since)
+                modified.push(m);
+        }
+        return {
+            added,
+            modified,
+            removedIds: [...this.prunedMemoryIds], // best-effort: all known prunes
+            nextCursor,
+            fullResync: false,
+        };
+    }
+    /**
+     * Cheap hash for `MemoryCursor.cursorHash`. We just sum a per-memory
+     * fingerprint into a 32-bit accumulator. Not collision-resistant in
+     * the cryptographic sense — but the cursor only needs to detect
+     * "anything changed since last time", and per-id IDs are already
+     * unique.
+     */
+    computeMemoryHash() {
+        let acc = 0xcafe;
+        for (const m of this.memories) {
+            const sig = `${m.id}|${m.createdAt}|${m.invalidatedAt ?? ''}|${m.confidence.toFixed(3)}`;
+            for (let i = 0; i < sig.length; i += 1) {
+                acc = ((acc * 33) ^ sig.charCodeAt(i)) >>> 0;
+            }
+        }
+        return acc.toString(36).padStart(8, '0');
+    }
+    /**
+     * Reject malformed RecoveryPolicy fields at the boundary so a buggy
+     * caller can't poison division by `0`, blow up `Math.exp(NaN)`, or
+     * silently disable retention with `-1`.
+     */
+    validatePolicy(policy) {
+        const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+        if (!Number.isInteger(policy.minTracesForConsolidation) || policy.minTracesForConsolidation < 0) {
+            throw new Error('Nidra: minTracesForConsolidation must be a non-negative integer');
+        }
+        if (!finite(policy.recoveryIntervalSec) || policy.recoveryIntervalSec < 0) {
+            throw new Error('Nidra: recoveryIntervalSec must be a non-negative finite number');
+        }
+        if (!finite(policy.maxDriftThreshold) || policy.maxDriftThreshold < 0 || policy.maxDriftThreshold > 1) {
+            throw new Error('Nidra: maxDriftThreshold must be a finite number in [0,1]');
+        }
+        if (!Number.isInteger(policy.failureWindowSize) || policy.failureWindowSize <= 0) {
+            throw new Error('Nidra: failureWindowSize must be a positive integer');
+        }
+        if (!finite(policy.retentionConfidence) || policy.retentionConfidence < 0 || policy.retentionConfidence > 1) {
+            throw new Error('Nidra: retentionConfidence must be a finite number in [0,1]');
+        }
+        if (policy.supersessionConfidenceDelta !== undefined) {
+            const d = policy.supersessionConfidenceDelta;
+            if (!finite(d) || d < 0 || d > 1) {
+                throw new Error('Nidra: supersessionConfidenceDelta must be a finite number in [0,1] if set');
+            }
+        }
+        for (const cap of ['maxTraces', 'maxMemories', 'maxProcessedTraceIds', 'maxCycleHistory']) {
+            const v = policy[cap];
+            if (v !== undefined && (!Number.isInteger(v) || v < 0)) {
+                throw new Error(`Nidra: ${cap} must be a non-negative integer if set`);
+            }
+        }
+        return policy;
+    }
+    // ── Trace Ingestion ──────────────────────────────────────────────────────
+    /**
+     * Record an execution trace for later consolidation. Evicts the oldest
+     * traces (and any matching processed-id markers) once the configured
+     * retention cap is hit, so long-running agents stay bounded in memory.
+     */
+    recordTrace(trace) {
+        this.traces.push(trace);
+        this.enforceTraceRetention();
+    }
+    /** Record multiple traces at once. */
+    recordTraces(traces) {
+        this.traces.push(...traces);
+        this.enforceTraceRetention();
+    }
+    enforceTraceRetention() {
+        const cap = this.policy.maxTraces ?? 0;
+        if (cap > 0 && this.traces.length > cap) {
+            const drop = this.traces.length - cap;
+            const dropped = this.traces.splice(0, drop);
+            // Also drop any processed-id markers that referenced the evicted
+            // traces so the set itself stays bounded.
+            for (const t of dropped)
+                this.processedTraceIds.delete(t.id);
+        }
+        // Independent processed-id cap in case it grew via other paths.
+        const idCap = this.policy.maxProcessedTraceIds ?? 0;
+        if (idCap > 0 && this.processedTraceIds.size > idCap) {
+            const it = this.processedTraceIds.values();
+            const drop = this.processedTraceIds.size - idCap;
+            for (let i = 0; i < drop; i++) {
+                const next = it.next();
+                if (next.done)
+                    break;
+                this.processedTraceIds.delete(next.value);
+            }
+        }
+    }
+    enforceMemoryAndCycleRetention() {
+        const mCap = this.policy.maxMemories ?? 0;
+        if (mCap > 0 && this.memories.length > mCap) {
+            const evicted = this.memories.splice(0, this.memories.length - mCap);
+            // Remember evicted IDs so `getMemoryDelta()` can report removals.
+            // Cap the pruned-id list at the processed-trace-ids horizon so it
+            // doesn't grow without bound.
+            for (const m of evicted)
+                this.prunedMemoryIds.push(m.id);
+            const idsHorizon = this.policy.maxProcessedTraceIds ?? 10_000;
+            if (this.prunedMemoryIds.length > idsHorizon) {
+                this.prunedMemoryIds.splice(0, this.prunedMemoryIds.length - idsHorizon);
+            }
+        }
+        const cCap = this.policy.maxCycleHistory ?? 0;
+        if (cCap > 0 && this.cycleHistory.length > cCap) {
+            this.cycleHistory.splice(0, this.cycleHistory.length - cCap);
+        }
+    }
+    // ── Memory Consolidation ─────────────────────────────────────────────────
+    /**
+     * Analyse unprocessed traces without committing anything. The returned
+     * envelope can be inspected, passed to `agent.injectMemory()`, and then
+     * finalised via `commitAnalysis()`. This is the building block for
+     * transactional recovery — see `Ojas.recover()` for the canonical use.
+     *
+     * `estimatedHealthAfter` is a forward-looking projection from the same
+     * pre-mutation state; for a true post-state, call `assess()` after
+     * committing.
+     */
+    analyseUnprocessed() {
+        const cycleId = uuid();
+        const startedAt = now();
+        const healthBefore = this.assess();
+        const unprocessed = this.getUnprocessedTraces();
+        const clusters = this.clusterTraces(unprocessed);
+        const memories = this.consolidateClusters(clusters);
+        const patterns = this.identifyPatterns(clusters);
+        const driftBefore = this.measureDrift(unprocessed);
+        // Identical to healthBefore here because we haven't mutated anything yet.
+        // It's named `estimatedHealthAfter` to signal that callers wanting the real
+        // post-state must re-assess after applying side effects.
+        const estimatedHealthAfter = healthBefore;
+        return {
+            cycleId,
+            startedAt,
+            tracesProcessed: unprocessed.length,
+            coveredTraceIds: unprocessed.map((t) => t.id),
+            memories,
+            patterns,
+            healthBefore,
+            estimatedHealthAfter,
+            driftBefore,
+        };
+    }
+    /**
+     * Pure preview: returns the memories, patterns, and drift estimate a
+     * commit would produce, with NO mutation. Memories are not appended,
+     * `lastRecovery` is unchanged, no trace IDs are marked processed, and
+     * no cycle is added to history. `healthAfter` is an estimate — for the
+     * true post-commit state, call `runRecoveryCycle()`.
+     *
+     * `supersededMemoryIds` lists the IDs that a commit WOULD invalidate
+     * given current state, so operators can see the impact of running
+     * the cycle without taking the side effect.
+     */
+    previewRecoveryCycle() {
+        const a = this.analyseUnprocessed();
+        const supersessionPlan = this.computeSupersessions(a.memories);
+        return {
+            cycleId: a.cycleId,
+            startedAt: a.startedAt,
+            completedAt: now(),
+            tracesProcessed: a.tracesProcessed,
+            memoriesConsolidated: a.memories,
+            patternsIdentified: a.patterns,
+            driftReduction: Math.max(0, a.driftBefore - a.estimatedHealthAfter.driftScore),
+            healthBefore: a.healthBefore,
+            healthAfter: a.estimatedHealthAfter,
+            mode: 'preview',
+            healthAfterEstimated: true,
+            supersededMemoryIds: supersessionPlan.map((p) => p.existingId),
+        };
+    }
+    /**
+     * Commit a precomputed `RecoveryAnalysis`. This is the side-effecting
+     * half of the analyse/commit pair: appends memories, marks traces
+     * processed, updates `lastRecovery`, and records the cycle. Use this
+     * directly to interleave external side effects (e.g. injecting memories
+     * into an agent) between analysis and commit, so a failure in those
+     * side effects leaves Nidra state untouched.
+     *
+     * `healthAfter` is captured AFTER mutation, so `driftReduction`
+     * reflects the real change.
+     *
+     * **Stale-analysis semantics.** Between `analyseUnprocessed()` and
+     * `commitAnalysis()`, new traces may arrive (carried over to next
+     * cycle — fine) AND existing traces may be evicted by retention caps
+     * if the trace store filled up. We mark any covered trace ID as
+     * processed regardless, because the analysis already encoded what
+     * those traces meant. The result reports `coveredTraceIdsStillRetained`
+     * vs `coveredTraceIdsEvicted` so the caller can tell when memories
+     * reference source traces that are no longer in `getTraces()`.
+     */
+    commitAnalysis(a) {
+        // Snapshot retained-trace IDs BEFORE applying retention so we can
+        // attribute eviction correctly.
+        const retainedIds = new Set(this.traces.map((t) => t.id));
+        const stillRetained = [];
+        const evicted = [];
+        for (const id of a.coveredTraceIds) {
+            if (retainedIds.has(id))
+                stillRetained.push(id);
+            else
+                evicted.push(id);
+        }
+        // Stamp provenance on each memory: 'degraded' if any of its
+        // sourceTraces are no longer in the trace store, 'full' otherwise.
+        // sourceTracesEvicted is the exact subset that's now ungrabbable.
+        const evictedSet = new Set(evicted);
+        const initialTemp = 0.5; // fresh memories start "warm"
+        for (const m of a.memories) {
+            const evictedSources = (m.sourceTraces ?? []).filter((id) => evictedSet.has(id));
+            if (evictedSources.length > 0) {
+                m.provenance = 'degraded';
+                m.sourceTracesEvicted = evictedSources;
+            }
+            else {
+                m.provenance = 'full';
+            }
+            // Initialise temperature tracking on every newly committed memory.
+            // Existing memories without this field are still supported — `getMemoryTemperature`
+            // returns `undefined` for them, and `detectColdMemories` skips them.
+            if (m.temperature === undefined) {
+                m.temperature = initialTemp;
+                m.temperatureUpdatedAt = now();
+            }
+        }
+        // Compute supersession against CURRENT state BEFORE pushing new
+        // memories, so we only consider prior memories, not the new batch's
+        // siblings. Mutations are applied here — not in `computeSupersessions`
+        // — because we want one consistent `supersessionTime` per cycle.
+        const supersessionPlan = this.computeSupersessions(a.memories);
+        const supersessionTime = now();
+        const memoryById = new Map();
+        for (const m of this.memories)
+            memoryById.set(m.id, m);
+        for (const { existingId, supersededBy } of supersessionPlan) {
+            const existing = memoryById.get(existingId);
+            if (existing) {
+                existing.invalidatedAt = supersessionTime;
+                existing.supersededBy = supersededBy;
+            }
+        }
+        // Commit mutations.
+        this.memories.push(...a.memories);
+        for (const id of a.coveredTraceIds)
+            this.processedTraceIds.add(id);
+        this.lastRecovery = now();
+        this.enforceTraceRetention();
+        this.enforceMemoryAndCycleRetention();
+        // Capture true post-mutation state.
+        const healthAfter = this.assess();
+        const result = {
+            cycleId: a.cycleId,
+            startedAt: a.startedAt,
+            completedAt: now(),
+            tracesProcessed: a.tracesProcessed,
+            memoriesConsolidated: a.memories,
+            patternsIdentified: a.patterns,
+            driftReduction: Math.max(0, a.driftBefore - healthAfter.driftScore),
+            healthBefore: a.healthBefore,
+            healthAfter,
+            mode: 'committed',
+            healthAfterEstimated: false,
+            coveredTracesEvicted: evicted.length,
+            coveredTracesRetained: stillRetained.length,
+            supersededMemoryIds: supersessionPlan.map((p) => p.existingId),
+        };
+        this.cycleHistory.push(result);
+        this.enforceMemoryAndCycleRetention();
+        return result;
+    }
+    /**
+     * Run a full recovery cycle in-process: analyse, then commit. Equivalent
+     * to `commitAnalysis(analyseUnprocessed())`. Convenient when there are
+     * no external side effects to sequence in between.
+     */
+    runRecoveryCycle() {
+        return this.commitAnalysis(this.analyseUnprocessed());
+    }
+    /**
+     * Cluster traces by action pattern for consolidation.
+     */
+    clusterTraces(traces) {
+        const groups = new Map();
+        for (const trace of traces) {
+            const key = trace.action;
+            if (!groups.has(key))
+                groups.set(key, []);
+            groups.get(key).push(trace);
+        }
+        const clusters = [];
+        for (const [pattern, groupTraces] of groups) {
+            const successes = groupTraces.filter((t) => t.success).length;
+            clusters.push({
+                pattern,
+                traces: groupTraces,
+                frequency: groupTraces.length,
+                successRate: groupTraces.length > 0 ? successes / groupTraces.length : 0,
+            });
+        }
+        return clusters.sort((a, b) => b.frequency - a.frequency);
+    }
+    /**
+     * Convert pattern clusters into consolidated memories.
+     */
+    consolidateClusters(clusters) {
+        const memories = [];
+        for (const cluster of clusters) {
+            if (cluster.traces.length < 2)
+                continue;
+            const confidence = this.computeConfidence(cluster);
+            if (confidence < this.policy.retentionConfidence)
+                continue;
+            const heuristic = this.extractHeuristic(cluster);
+            const abstraction = this.extractAbstraction(cluster);
+            memories.push({
+                id: uuid(),
+                kind: 'procedural',
+                createdAt: now(),
+                observedAt: earliestTimestamp(cluster.traces),
+                sourceTraces: cluster.traces.map((t) => t.id),
+                heuristic,
+                confidence,
+                applicability: [cluster.pattern],
+                abstraction,
+            });
+        }
+        return memories;
+    }
+    /**
+     * Pure planning step: compute which existing *active* memories would
+     * be superseded by the given new memories. Does **not** mutate. Used
+     * by `commitAnalysis()` to invalidate prior memories, and by
+     * `previewRecoveryCycle()` to surface the same plan without applying
+     * it.
+     *
+     * A new memory supersedes an existing one when ALL of:
+     *   - existing.invalidatedAt is unset (still active);
+     *   - kinds match (defaulting to `'procedural'` when unset);
+     *   - `applicability` lists share at least one element;
+     *   - `|existing.confidence - new.confidence|` ≥ the policy's
+     *     `supersessionConfidenceDelta` (default 0.15).
+     *
+     * Each existing memory is claimed by at most one new memory per batch.
+     */
+    computeSupersessions(newMemories) {
+        const delta = this.policy.supersessionConfidenceDelta ?? 0.15;
+        const plan = [];
+        const claimed = new Set();
+        for (const newMem of newMemories) {
+            for (const existing of this.memories) {
+                if (existing.invalidatedAt)
+                    continue;
+                if (claimed.has(existing.id))
+                    continue;
+                if ((existing.kind ?? 'procedural') !== (newMem.kind ?? 'procedural'))
+                    continue;
+                if (!applicabilityOverlaps(existing.applicability, newMem.applicability))
+                    continue;
+                if (Math.abs(existing.confidence - newMem.confidence) < delta)
+                    continue;
+                plan.push({ existingId: existing.id, supersededBy: newMem.id });
+                claimed.add(existing.id);
+            }
+        }
+        return plan;
+    }
+    /**
+     * Compute confidence for a pattern cluster.
+     */
+    computeConfidence(cluster) {
+        const frequencyScore = Math.min(1, cluster.frequency / 10);
+        const successScore = cluster.successRate;
+        const consistencyScore = this.measureConsistency(cluster.traces);
+        return (frequencyScore * 0.3) + (successScore * 0.4) + (consistencyScore * 0.3);
+    }
+    /**
+     * Measure consistency of outcomes within a cluster.
+     */
+    measureConsistency(traces) {
+        if (traces.length < 2)
+            return 0;
+        const durations = traces.map((t) => t.durationMs);
+        const mean = durations.reduce((a, b) => a + b, 0) / durations.length;
+        const variance = durations.reduce((sum, d) => sum + (d - mean) ** 2, 0) / durations.length;
+        const cv = mean > 0 ? Math.sqrt(variance) / mean : 0;
+        // Lower coefficient of variation = higher consistency
+        return clamp(1 - cv);
+    }
+    /**
+     * Extract a heuristic from a pattern cluster.
+     */
+    extractHeuristic(cluster) {
+        const successRate = (cluster.successRate * 100).toFixed(0);
+        const avgDuration = (cluster.traces.reduce((s, t) => s + t.durationMs, 0) / cluster.traces.length).toFixed(0);
+        if (cluster.successRate >= 0.8) {
+            return `Action "${cluster.pattern}" is reliable (${successRate}% success, avg ${avgDuration}ms). Prefer for similar tasks.`;
+        }
+        else if (cluster.successRate >= 0.5) {
+            return `Action "${cluster.pattern}" is partially reliable (${successRate}% success). Use with verification.`;
+        }
+        else {
+            const errors = cluster.traces
+                .filter((t) => !t.success && t.error)
+                .map((t) => t.error)
+                .slice(0, 3);
+            return `Action "${cluster.pattern}" is unreliable (${successRate}% success). Common errors: ${errors.join('; ') || 'unknown'}. Avoid or redesign.`;
+        }
+    }
+    /**
+     * Extract a higher-level abstraction from a cluster.
+     */
+    extractAbstraction(cluster) {
+        const avgDuration = cluster.traces.reduce((s, t) => s + t.durationMs, 0) / cluster.traces.length;
+        const hasErrors = cluster.traces.some((t) => !t.success);
+        return [
+            `Pattern: ${cluster.pattern}`,
+            `Observations: ${cluster.frequency}`,
+            `Success: ${(cluster.successRate * 100).toFixed(0)}%`,
+            `Avg duration: ${avgDuration.toFixed(0)}ms`,
+            hasErrors ? 'Has failure modes — requires error handling' : 'Stable execution pattern',
+        ].join('. ');
+    }
+    // ── Pattern Identification ───────────────────────────────────────────────
+    /**
+     * Identify recurring patterns across trace clusters.
+     */
+    identifyPatterns(clusters) {
+        const patterns = [];
+        // Repeated failure pattern
+        const failingActions = clusters.filter((c) => c.successRate < 0.5 && c.frequency >= 3);
+        for (const c of failingActions) {
+            patterns.push(`REPEATED_FAILURE: "${c.pattern}" fails ${((1 - c.successRate) * 100).toFixed(0)}% of the time over ${c.frequency} attempts`);
+        }
+        // High-frequency actions
+        const frequent = clusters.filter((c) => c.frequency >= 5);
+        for (const c of frequent) {
+            patterns.push(`HIGH_FREQUENCY: "${c.pattern}" executed ${c.frequency} times — consider optimization`);
+        }
+        // Slow actions
+        const slow = clusters.filter((c) => {
+            const avg = c.traces.reduce((s, t) => s + t.durationMs, 0) / c.traces.length;
+            return avg > 5000;
+        });
+        for (const c of slow) {
+            const avg = c.traces.reduce((s, t) => s + t.durationMs, 0) / c.traces.length;
+            patterns.push(`SLOW_ACTION: "${c.pattern}" averages ${avg.toFixed(0)}ms — bottleneck candidate`);
+        }
+        return patterns;
+    }
+    // ── Drift Measurement ────────────────────────────────────────────────────
+    /**
+     * Measure cognitive drift: how much recent behavior deviates
+     * from stable patterns. Higher = more drift.
+     */
+    measureDrift(traces) {
+        const source = traces || this.traces;
+        if (source.length < 2)
+            return 0;
+        const recent = source.slice(-this.policy.failureWindowSize);
+        const recentFailRate = recent.filter((t) => !t.success).length / recent.length;
+        // Check for increasing failure trend
+        const halfIdx = Math.floor(recent.length / 2);
+        const firstHalf = recent.slice(0, halfIdx);
+        const secondHalf = recent.slice(halfIdx);
+        const firstFailRate = firstHalf.length > 0
+            ? firstHalf.filter((t) => !t.success).length / firstHalf.length
+            : 0;
+        const secondFailRate = secondHalf.length > 0
+            ? secondHalf.filter((t) => !t.success).length / secondHalf.length
+            : 0;
+        const trendDrift = Math.max(0, secondFailRate - firstFailRate);
+        return clamp((recentFailRate * 0.6) + (trendDrift * 0.4));
+    }
+    // ── Health Assessment ────────────────────────────────────────────────────
+    /**
+     * Produce a complete recovery health report.
+     *
+     * `memoryConsolidation` is computed against *active* memories only
+     * (those with no `invalidatedAt`). Counting superseded memories
+     * would inflate the ratio as the agent revises its beliefs, hiding
+     * that the live memory store has actually grown leaner.
+     */
+    assess() {
+        const drift = this.measureDrift();
+        const activeMemoryCount = this.memories.filter((m) => !m.invalidatedAt).length;
+        const consolidationRatio = this.traces.length > 0
+            ? activeMemoryCount / Math.max(1, Math.floor(this.traces.length / this.policy.minTracesForConsolidation))
+            : 1;
+        const recentCycles = this.cycleHistory.slice(-5);
+        const avgDriftReduction = recentCycles.length > 0
+            ? recentCycles.reduce((s, c) => s + c.driftReduction, 0) / recentCycles.length
+            : 0;
+        return {
+            memoryConsolidation: healthScore(clamp(consolidationRatio), 'nidra.consolidation'),
+            cognitiveStability: healthScore(1 - drift, 'nidra.stability'),
+            learningRate: healthScore(avgDriftReduction, 'nidra.learning'),
+            driftScore: drift,
+            lastRecoveryCycle: this.lastRecovery,
+        };
+    }
+    // ── Recommendations ──────────────────────────────────────────────────────
+    recommend() {
+        const recs = [];
+        const health = this.assess();
+        if (health.driftScore > this.policy.maxDriftThreshold) {
+            recs.push({
+                module: 'nidra',
+                severity: 'critical',
+                message: `Cognitive drift at ${(health.driftScore * 100).toFixed(1)}% — exceeds threshold.`,
+                action: 'Initiate immediate recovery cycle.',
+            });
+        }
+        const unprocessed = this.getUnprocessedTraces();
+        if (unprocessed.length >= this.policy.minTracesForConsolidation) {
+            recs.push({
+                module: 'nidra',
+                severity: 'warning',
+                message: `${unprocessed.length} traces awaiting consolidation.`,
+                action: 'Run recovery cycle to consolidate memories.',
+            });
+        }
+        if (health.cognitiveStability.value < 0.5) {
+            recs.push({
+                module: 'nidra',
+                severity: 'critical',
+                message: 'Cognitive stability is critically low.',
+                action: 'Reduce task load and initiate recovery.',
+            });
+        }
+        if (recs.length === 0) {
+            recs.push({
+                module: 'nidra',
+                severity: 'info',
+                message: 'Recovery health is stable.',
+            });
+        }
+        return recs;
+    }
+    // ── Accessors ────────────────────────────────────────────────────────────
+    /**
+     * Returns true if enough traces exist to justify a recovery cycle.
+     */
+    needsRecovery() {
+        const unprocessed = this.getUnprocessedTraces();
+        const drift = this.measureDrift();
+        return (unprocessed.length >= this.policy.minTracesForConsolidation ||
+            drift > this.policy.maxDriftThreshold);
+    }
+    getUnprocessedTraces() {
+        return this.traces.filter((t) => !this.processedTraceIds.has(t.id));
+    }
+    /**
+     * All memories ever consolidated by this Nidra instance, including
+     * those that have been invalidated by supersession. Use this for
+     * audit / replay; use `getActiveMemories()` for the "what's true now"
+     * view and `findMemories(query)` for richer queries.
+     */
+    getMemories() {
+        return this.memories.map((m) => ({ ...m, sourceTraces: [...m.sourceTraces], applicability: [...m.applicability] }));
+    }
+    /**
+     * The currently authoritative memories — those with no
+     * `invalidatedAt` set. This is the live view a consumer should
+     * inject into an agent or surface on a dashboard. Memories that
+     * have been superseded are excluded but remain in `getMemories()`
+     * for provenance.
+     */
+    getActiveMemories() {
+        return this.getMemories().filter((m) => !m.invalidatedAt);
+    }
+    /**
+     * Bi-temporal / kind-aware query over the memory store: "what was
+     * true at any point in time".
+     *
+     * - `asOf` (ISO timestamp; default = now): include only memories
+     *   that were valid at that instant — `createdAt <= asOf` AND
+     *   (`invalidatedAt` is unset OR `invalidatedAt > asOf`). Set
+     *   `includeInvalidated` to `true` to drop the invalidation cutoff
+     *   and see every memory created on or before `asOf`.
+     * - `kind`: restrict to one or more memory kinds. Memories with no
+     *   explicit `kind` are treated as `'procedural'`.
+     * - `applicability`: exact match against any element of the
+     *   memory's `applicability` list.
+     * - `minConfidence`: drop memories below this confidence.
+     * - `limit`: cap the result length (no cap if undefined).
+     *
+     * Results are returned in insertion order (oldest first).
+     */
+    findMemories(query = {}) {
+        const asOf = query.asOf ?? now();
+        const kinds = query.kind === undefined
+            ? null
+            : new Set(Array.isArray(query.kind) ? query.kind : [query.kind]);
+        const out = [];
+        for (const m of this.memories) {
+            if (m.createdAt > asOf)
+                continue;
+            if (!query.includeInvalidated && m.invalidatedAt && m.invalidatedAt <= asOf)
+                continue;
+            if (kinds && !kinds.has((m.kind ?? 'procedural')))
+                continue;
+            if (query.applicability !== undefined && !m.applicability.includes(query.applicability))
+                continue;
+            if (query.minConfidence !== undefined && m.confidence < query.minConfidence)
+                continue;
+            out.push({ ...m, sourceTraces: [...m.sourceTraces], applicability: [...m.applicability] });
+            if (query.limit !== undefined && out.length >= query.limit)
+                break;
+        }
+        return out;
+    }
+    getTraces() {
+        return this.traces.map((t) => ({
+            ...t,
+            failures: t.failures?.map((f) => ({ ...f, metadata: f.metadata ? { ...f.metadata } : undefined })),
+        }));
+    }
+    getCycleHistory() {
+        return structuredClone(this.cycleHistory);
+    }
+    exportState() {
+        return {
+            traces: [...this.getTraces()],
+            memories: [...this.getMemories()],
+            cycleHistory: structuredClone(this.cycleHistory),
+            lastRecovery: this.lastRecovery,
+            processedTraceIds: Array.from(this.processedTraceIds),
+            coldNotifiedIds: Array.from(this.coldNotifiedIds),
+            prunedMemoryIds: [...this.prunedMemoryIds],
+        };
+    }
+    importState(snapshot) {
+        if (!snapshot)
+            return;
+        this.traces = (snapshot.traces ?? []).map((t) => ({
+            ...t,
+            failures: t.failures?.map((f) => ({ ...f, metadata: f.metadata ? { ...f.metadata } : undefined })),
+        }));
+        this.memories = (snapshot.memories ?? []).map((m) => ({
+            ...m,
+            sourceTraces: [...m.sourceTraces],
+            applicability: [...m.applicability],
+        }));
+        this.cycleHistory = structuredClone(snapshot.cycleHistory ?? []);
+        this.lastRecovery = snapshot.lastRecovery ?? null;
+        this.processedTraceIds = new Set(snapshot.processedTraceIds ?? []);
+        this.coldNotifiedIds = new Set(snapshot.coldNotifiedIds ?? []);
+        this.prunedMemoryIds = [...(snapshot.prunedMemoryIds ?? [])];
+    }
+    getPolicy() {
+        return { ...this.policy };
+    }
+    updatePolicy(updates) {
+        this.policy = this.validatePolicy({ ...this.policy, ...updates });
+        this.enforceTraceRetention();
+        this.enforceMemoryAndCycleRetention();
+    }
+}
+exports.Nidra = Nidra;
+//# sourceMappingURL=index.js.map