cognitive-core 0.2.5 → 0.3.1

package/dist/eval/task-stream.js

@@ -0,0 +1,99 @@
+import { createTask } from '../types/index.js';
+import { seededRng } from './rng.js';
+/**
+ * Synthetic skill families for the learning-curve eval.
+ *
+ * Each family is a templated task type whose instances are near-identical
+ * (varying only by an index), so the memory retriever reliably surfaces a prior
+ * instance once one has been solved. This isolates the thing under test — does
+ * accumulated experience raise success — from retrieval noise.
+ */
+const SKILL_FAMILIES = [
+    {
+        tag: 'json-parse',
+        domain: 'code',
+        template: 'Parse and validate a malformed JSON config payload',
+    },
+    {
+        tag: 'ts-import-fix',
+        domain: 'code',
+        template: 'Resolve a TypeScript TS2307 missing-module import error',
+    },
+    {
+        tag: 'sql-join',
+        domain: 'data',
+        template: 'Write a multi-table SQL join to aggregate order totals',
+    },
+    {
+        tag: 'regex-extract',
+        domain: 'code',
+        template: 'Build a regex to extract semver tags from release notes',
+    },
+    { tag: 'k8s-deploy', domain: 'devops', template: 'Fix a failing Kubernetes deployment rollout' },
+    {
+        tag: 'auth-flow',
+        domain: 'security',
+        template: 'Debug an OAuth token-refresh authentication flow',
+    },
+    {
+        tag: 'graph-traverse',
+        domain: 'reasoning',
+        template: 'Implement a breadth-first traversal over a dependency graph',
+    },
+    {
+        tag: 'csv-clean',
+        domain: 'data',
+        template: 'Normalize and de-duplicate rows in a messy CSV export',
+    },
+];
+/**
+ * Build a deterministic sequential task stream.
+ *
+ * The stream interleaves `skillCount` skill families over `taskCount` tasks.
+ * The ordering is shuffled deterministically from `seed` so that early tasks
+ * mostly hit unseen skills (cold) while later tasks increasingly repeat seen
+ * skills (warm) — producing an upward learning curve once memory is active.
+ *
+ * The same `seed` always yields the same stream; pass different seeds to vary
+ * the ordering across runs.
+ */
+export function buildTaskStream(opts) {
+    const { taskCount, seed, coldProb, warmProb } = opts;
+    const skillCount = Math.min(opts.skillCount, SKILL_FAMILIES.length);
+    const families = SKILL_FAMILIES.slice(0, skillCount);
+    // Round-robin assign each task to a family, then deterministically shuffle.
+    const rawTags = [];
+    for (let i = 0; i < taskCount; i++) {
+        rawTags.push(families[i % skillCount].tag);
+    }
+    const order = deterministicShuffle(rawTags, seed);
+    const familyByTag = new Map(families.map((f) => [f.tag, f]));
+    return order.map((tag, index) => {
+        const fam = familyByTag.get(tag);
+        // Variant number cycles so descriptions stay near-identical within a family.
+        const variant = Math.floor(index / skillCount);
+        const description = `[skill:${tag}] ${fam.template} (case ${variant})`;
+        const task = createTask({
+            id: `eval-${seed}-${index}-${tag}`,
+            domain: fam.domain,
+            description,
+            metadata: { skillTag: tag, evalIndex: index },
+        });
+        return { task, skillTag: tag, index, coldProb, warmProb };
+    });
+}
+/**
+ * Fisher–Yates shuffle driven by a seeded PRNG (no Math.random — reproducible).
+ */
+function deterministicShuffle(items, seed) {
+    const arr = items.slice();
+    const rng = seededRng('shuffle', seed);
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+/** Number of skill families available for streams. */
+export const MAX_SKILL_FAMILIES = SKILL_FAMILIES.length;
+//# sourceMappingURL=task-stream.js.map

package/dist/eval/task-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-stream.js","sourceRoot":"","sources":["../../src/eval/task-stream.ts"],"names":[],"mappings":"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"}

package/dist/eval/types.d.ts

@@ -0,0 +1,173 @@
+import type { Task } from '../types/index.js';
+import type { MutationActivityStats } from '../learning/unified-pipeline.js';
+/**
+ * Evaluation types for the sequential learning-curve harness.
+ *
+ * The harness measures the core claim of a self-learning system:
+ * "does task success improve as the system accumulates experience?"
+ * It does this by running an ordered stream of tasks through Atlas under
+ * two conditions (learning enabled vs. a no-learning baseline) and comparing
+ * the resulting success curves.
+ */
+/**
+ * A single task in an evaluation stream.
+ *
+ * `skillTag` groups interchangeable tasks: solving one task tagged `json-parse`
+ * should make later `json-parse` tasks easier once the experience is learned.
+ * The tag is also embedded in the task description (as `[skill:<tag>]`) so it
+ * survives into stored experiences and extracted playbooks.
+ */
+export interface EvalTask {
+    task: Task;
+    /** Skill family this task belongs to. */
+    skillTag: string;
+    /** Zero-based position in the stream. */
+    index: number;
+    /**
+     * Base success probability when no relevant prior knowledge is available
+     * (the "cold" probability). Used by the memory-sensitive mock backend; the
+     * live backend ignores this.
+     */
+    coldProb: number;
+    /**
+     * Success probability when a relevant prior success has been surfaced
+     * (the "warm" probability). Mock-only.
+     */
+    warmProb: number;
+    /** Task family for ordered benchmarks (e.g. SkillFlow difficulty groups). */
+    family?: string;
+    /** Difficulty level within a family (0-based, lower = easier). */
+    difficulty?: number;
+    /** Episode index for multi-episode benchmarks (e.g. CL-Bench). */
+    episode?: number;
+    /** Iteration index for iterative benchmarks (e.g. SkillLearnBench). */
+    iteration?: number;
+}
+/** Identifies which experimental arm a result belongs to. */
+export type ConditionLabel = 'learning' | 'no-learning';
+/** Outcome of a single solved task within a run. */
+export interface TaskResult {
+    index: number;
+    taskId: string;
+    skillTag: string;
+    success: boolean;
+    /**
+     * Execution status:
+     *   'success'   — agent completed the task successfully
+     *   'failure'   — agent completed the task but did not succeed
+     *   'env_error' — infrastructure failure (bridge crash, CLI 429/529/timeout,
+     *                 nonzero exit with no output); excluded from success-rate
+     *                 aggregates and learning.
+     */
+    status: 'success' | 'failure' | 'env_error';
+    stepCount: number;
+    /** Whether relevant prior knowledge was surfaced for this task. */
+    knowledgeSurfaced: boolean;
+    /** How many distinct skill families had been seen successfully before this task. */
+    priorSkillCoverage: number;
+    wallTimeMs: number;
+    /** Estimated USD cost for this task (from CLI cost reporting). */
+    costUsd?: number;
+    /** Partial credit score (0.0–1.0), fraction of individual tests passed. */
+    partialScore?: number;
+}
+/** One point on a learning curve (rolling success rate over the stream). */
+export interface CurvePoint {
+    index: number;
+    /** Rolling success rate over a trailing window ending at this index. */
+    rollingSuccessRate: number;
+    /** Cumulative success rate from stream start through this index. */
+    cumulativeSuccessRate: number;
+}
+/** Aggregated results for one condition across one or more seeds. */
+export interface ConditionResult {
+    /** 'learning' / 'no-learning' for the curve eval, or a component key for ablation arms. */
+    label: string;
+    seeds: number[];
+    /** Per-seed, per-task outcomes. results[seedIdx][taskIdx]. */
+    perSeed: TaskResult[][];
+    /** Overall success rate across all tasks and seeds (env_error tasks excluded). */
+    successRate: number;
+    /** Success rate over the first third of the stream (the "pre" / early phase). */
+    earlySuccessRate: number;
+    /** Success rate over the last third of the stream (the "post" / late phase). */
+    lateSuccessRate: number;
+    /** Mean steps per task across all tasks and seeds. */
+    avgSteps: number;
+    /** Learning curve averaged across seeds. */
+    curve: CurvePoint[];
+    /** 95% bootstrap CI on the overall success rate (env_error tasks excluded). */
+    successRateCI: [number, number];
+    /** Fraction of tasks that resulted in an env_error (infra failure). */
+    envErrorRate: number;
+    /** Total USD cost across all tasks and seeds in this arm (when available). */
+    totalCostUsd?: number;
+    /** Mean partial credit score across all tasks (when available). */
+    avgPartialScore?: number;
+    /**
+     * Mutation/merge-proposing maintenance activity accumulated on the learning
+     * arm (summed across seeds). Populated by the live runner so run reports
+     * prove whether the GEPA-style mutation path executed — proposals
+     * considered/accepted/rejected per task, plus skip reasons when the tasks
+     * self-gated. Absent on the cold arm and on runs where no learning-arm
+     * Atlas was built.
+     */
+    mutationActivity?: MutationActivityStats;
+}
+/** Full eval result comparing learning vs. no-learning. */
+export interface EvalResult {
+    config: EvalRunConfig;
+    /** Live benchmark name (e.g. "gsm8k"), when backend is 'live'. */
+    benchmarkName?: string;
+    /** Single-arm run (learning only, no baseline) — for ablation/attribution. */
+    singleArm?: boolean;
+    learning: ConditionResult;
+    noLearning: ConditionResult;
+    /** Difference in overall success rate (learning − noLearning). */
+    successRateDelta: number;
+    /**
+     * Normalized gain g = (post − pre) / (1 − pre), where pre = no-learning late
+     * success rate (a stable baseline) and post = learning late success rate.
+     * Range (−∞, 1]; ≥0.3 medium, ≥0.7 high (Hake convention).
+     */
+    normalizedGain: number;
+    /**
+     * Advisory significance flag: true when the 95% bootstrap CIs are disjoint.
+     * This is a simple proxy — headline significance uses McNemar p < 0.05
+     * (see pairedComparison in metrics.ts for the paired test).
+     * @deprecated Prefer pairedComparison().mcnemarP < 0.05 for significance.
+     */
+    significant: boolean;
+    /**
+     * Alias of `significant` — explicit name to distinguish from McNemar test.
+     * Both fields carry the same value; ciDisjointAdvisory is the preferred name.
+     */
+    ciDisjointAdvisory: boolean;
+    /** Wall-clock for the whole eval in ms. */
+    durationMs: number;
+}
+/** Configuration for an eval run. */
+export interface EvalRunConfig {
+    /** Backend to drive task solving. */
+    backend: 'mock' | 'live';
+    /** Number of tasks in the stream. */
+    taskCount: number;
+    /** Number of distinct skill families. */
+    skillCount: number;
+    /** Seeds to run (one curve per seed, then averaged). */
+    seeds: number[];
+    /** Trailing window size for the rolling success rate. */
+    rollingWindow: number;
+    /** Cold success probability for the mock backend. */
+    coldProb: number;
+    /** Warm success probability for the mock backend. */
+    warmProb: number;
+    /** Force a batch-learning cycle every N tasks (0 = rely on energy trigger only). */
+    forceBatchEvery: number;
+    /** Iterations per task for iterative benchmarks (e.g. SkillLearnBench). */
+    iterationsPerTask?: number;
+    /** Episodes per domain for multi-episode benchmarks (e.g. CL-Bench). */
+    episodesPerDomain?: number;
+}
+export declare const DEFAULT_EVAL_CONFIG: EvalRunConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/eval/types.d.ts.map

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

package/dist/eval/types.js

@@ -0,0 +1,11 @@
+export const DEFAULT_EVAL_CONFIG = {
+    backend: 'mock',
+    taskCount: 60,
+    skillCount: 6,
+    seeds: [1, 2, 3],
+    rollingWindow: 10,
+    coldProb: 0.35,
+    warmProb: 0.9,
+    forceBatchEvery: 0,
+};
+//# sourceMappingURL=types.js.map

package/dist/eval/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/eval/types.ts"],"names":[],"mappings":"AAoLA,MAAM,CAAC,MAAM,mBAAmB,GAAkB;IAChD,OAAO,EAAE,MAAM;IACf,SAAS,EAAE,EAAE;IACb,UAAU,EAAE,CAAC;IACb,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAChB,aAAa,EAAE,EAAE;IACjB,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,GAAG;IACb,eAAe,EAAE,CAAC;CACnB,CAAC"}

package/dist/experimental/causal-store.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CausalStore — First-class queryable store for causal relationships.
+ *
+ * Promotes causal edges (cause → effect) extracted from trajectories
+ * to a searchable store backed by SqlitePersistence + InvertedIndex.
+ *
+ * Supports:
+ * - Similarity search on cause/effect descriptions
+ * - Chain traversal (walk from one edge to connected edges)
+ * - Domain-scoped retrieval
+ * - Confidence-weighted deduplication (same pattern seen multiple times)
+ */
+import type { SqlitePersistence } from '../persistence/index.js';
+/**
+ * A causal edge: cause → effect with evidence
+ */
+export interface CausalEdge {
+    id: string;
+    /** Description of the cause */
+    cause: string;
+    /** Description of the effect */
+    effect: string;
+    /** Confidence in this causal relationship (0-1) */
+    confidence: number;
+    /** Domain this edge belongs to */
+    domain: string;
+    /** Trajectory IDs that provide evidence for this edge */
+    sourceTrajectoryIds: string[];
+    /** How many times this pattern was observed */
+    observedCount: number;
+    /** When this edge was first created */
+    createdAt: Date;
+    /** When this edge was last updated */
+    updatedAt: Date;
+}
+/**
+ * CausalStore — queryable store for causal relationships
+ */
+export declare class CausalStore {
+    private persistence;
+    private index;
+    private initialized;
+    private _resolver;
+    constructor(persistence: SqlitePersistence);
+    init(): Promise<void>;
+    /**
+     * Add a causal edge. If a similar edge already exists (same cause+effect
+     * pattern above similarity threshold), merge by incrementing observedCount
+     * and boosting confidence.
+     */
+    add(edge: CausalEdge): Promise<void>;
+    /**
+     * Find causal edges similar to a query string.
+     */
+    findSimilar(query: string, options?: {
+        k?: number;
+    }): Promise<CausalEdge[]>;
+    /**
+     * Get a chain of causal edges starting from a given edge ID.
+     * Follows effect → cause links by text similarity.
+     */
+    getChain(startId: string, maxDepth?: number): Promise<CausalEdge[]>;
+    /**
+     * Get all causal edges for a domain.
+     */
+    getByDomain(domain: string): Promise<CausalEdge[]>;
+    /**
+     * Get a single edge by ID.
+     */
+    get(id: string): Promise<CausalEdge | undefined>;
+    /**
+     * Get all edges.
+     */
+    getAll(): Promise<CausalEdge[]>;
+    /**
+     * Get total count.
+     */
+    count(): Promise<number>;
+    /**
+     * Close the store (no-op — SqlitePersistence lifecycle is managed externally).
+     */
+    close(): Promise<void>;
+    /**
+     * Find an existing edge that matches the new one (for merging).
+     * Uses high similarity threshold on both cause AND effect.
+     */
+    private findExistingMatch;
+    /**
+     * Synchronous helper: get all edges from SQLite.
+     */
+    private getAllSync;
+}
+/**
+ * Create a CausalStore instance
+ */
+export declare function createCausalStore(persistence: SqlitePersistence): CausalStore;
+//# sourceMappingURL=causal-store.d.ts.map

package/dist/experimental/causal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-store.d.ts","sourceRoot":"","sources":["../../src/experimental/causal-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,yBAAyB,CAAC;AAMhF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,SAAS,EAAE,IAAI,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,IAAI,CAAC;CACjB;AAmBD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAA2B;gBAEhC,WAAW,EAAE,iBAAiB;IAWpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;;;OAIG;IACG,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B1C;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA2BjF;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCpE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAKxD;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAMtD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAKrC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,iBAAiB,GAAG,WAAW,CAE7E"}

package/dist/experimental/causal-store.js

@@ -0,0 +1,213 @@
+/**
+ * CausalStore — First-class queryable store for causal relationships.
+ *
+ * Promotes causal edges (cause → effect) extracted from trajectories
+ * to a searchable store backed by SqlitePersistence + InvertedIndex.
+ *
+ * Supports:
+ * - Similarity search on cause/effect descriptions
+ * - Chain traversal (walk from one edge to connected edges)
+ * - Domain-scoped retrieval
+ * - Confidence-weighted deduplication (same pattern seen multiple times)
+ */
+import { fromJSON, fromISO } from '../persistence/index.js';
+import { InvertedIndex } from '../embeddings/inverted-index.js';
+import { textSimilarity } from '../utils/similarity.js';
+import { getCandidates } from '../memory/candidate-retrieval.js';
+/**
+ * Convert a CausalEdgeRow to a CausalEdge.
+ */
+function rowToEdge(row) {
+    return {
+        id: row.id,
+        cause: row.cause,
+        effect: row.effect,
+        confidence: row.confidence,
+        domain: row.domain,
+        sourceTrajectoryIds: fromJSON(row.source_trajectory_ids, []),
+        observedCount: row.observed_count,
+        createdAt: fromISO(row.created_at) ?? new Date(),
+        updatedAt: fromISO(row.updated_at) ?? new Date(),
+    };
+}
+/**
+ * CausalStore — queryable store for causal relationships
+ */
+export class CausalStore {
+    persistence;
+    index = new InvertedIndex();
+    initialized = false;
+    _resolver;
+    constructor(persistence) {
+        this.persistence = persistence;
+        this._resolver = {
+            get: (id) => {
+                const row = this.persistence.getCausalEdge(id);
+                return row ? rowToEdge(row) : undefined;
+            },
+            values: () => this.getAllSync(),
+        };
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        // Build inverted index from all causal edges in DB
+        const ids = this.persistence.getCausalEdgeIds();
+        for (const { id, cause, effect } of ids) {
+            this.index.add(id, `${cause} ${effect}`);
+        }
+        this.initialized = true;
+    }
+    /**
+     * Add a causal edge. If a similar edge already exists (same cause+effect
+     * pattern above similarity threshold), merge by incrementing observedCount
+     * and boosting confidence.
+     */
+    async add(edge) {
+        await this.init();
+        // Check for existing similar edge to merge with
+        const existing = this.findExistingMatch(edge);
+        if (existing) {
+            // Merge: bump count, boost confidence, add trajectory evidence
+            existing.observedCount += 1;
+            existing.confidence = Math.min(1, existing.confidence + 0.05);
+            existing.updatedAt = new Date();
+            for (const tid of edge.sourceTrajectoryIds) {
+                if (!existing.sourceTrajectoryIds.includes(tid)) {
+                    existing.sourceTrajectoryIds.push(tid);
+                }
+            }
+            this.persistence.insertCausalEdge(existing); // Write-through
+        }
+        else {
+            // New edge
+            this.persistence.insertCausalEdge(edge);
+            this.index.add(edge.id, `${edge.cause} ${edge.effect}`);
+        }
+    }
+    /**
+     * Find causal edges similar to a query string.
+     */
+    async findSimilar(query, options) {
+        await this.init();
+        const k = options?.k ?? 5;
+        // Use shared candidate retrieval with inverted index
+        const candidates = getCandidates(query, this.index, this._resolver, {
+            k,
+            candidateMultiplier: 5,
+            minCandidates: 30,
+        });
+        // Score by similarity to both cause and effect
+        const scored = candidates.map((edge) => {
+            const causeSim = textSimilarity(query, edge.cause);
+            const effectSim = textSimilarity(query, edge.effect);
+            const combinedSim = textSimilarity(query, `${edge.cause} ${edge.effect}`);
+            return {
+                edge,
+                score: Math.max(causeSim, effectSim, combinedSim),
+            };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k).map((s) => s.edge);
+    }
+    /**
+     * Get a chain of causal edges starting from a given edge ID.
+     * Follows effect → cause links by text similarity.
+     */
+    async getChain(startId, maxDepth = 5) {
+        await this.init();
+        const startRow = this.persistence.getCausalEdge(startId);
+        if (!startRow)
+            return [];
+        const start = rowToEdge(startRow);
+        const chain = [start];
+        const visited = new Set([startId]);
+        let current = start;
+        for (let depth = 0; depth < maxDepth; depth++) {
+            // Find edges where cause is similar to current effect
+            const allEdges = this.getAllSync();
+            let bestMatch;
+            let bestScore = 0;
+            for (const edge of allEdges) {
+                if (visited.has(edge.id))
+                    continue;
+                const score = textSimilarity(current.effect, edge.cause);
+                if (score > bestScore && score > 0.4) {
+                    bestScore = score;
+                    bestMatch = edge;
+                }
+            }
+            if (!bestMatch)
+                break;
+            chain.push(bestMatch);
+            visited.add(bestMatch.id);
+            current = bestMatch;
+        }
+        return chain;
+    }
+    /**
+     * Get all causal edges for a domain.
+     */
+    async getByDomain(domain) {
+        await this.init();
+        return this.persistence.getCausalEdgesByDomain(domain).map(rowToEdge);
+    }
+    /**
+     * Get a single edge by ID.
+     */
+    async get(id) {
+        await this.init();
+        const row = this.persistence.getCausalEdge(id);
+        return row ? rowToEdge(row) : undefined;
+    }
+    /**
+     * Get all edges.
+     */
+    async getAll() {
+        await this.init();
+        return this.getAllSync();
+    }
+    /**
+     * Get total count.
+     */
+    async count() {
+        await this.init();
+        return this.persistence.getAllCausalEdges().length;
+    }
+    /**
+     * Close the store (no-op — SqlitePersistence lifecycle is managed externally).
+     */
+    async close() {
+        // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
+    }
+    /**
+     * Find an existing edge that matches the new one (for merging).
+     * Uses high similarity threshold on both cause AND effect.
+     */
+    findExistingMatch(newEdge) {
+        const MERGE_THRESHOLD = 0.7;
+        for (const edge of this.getAllSync()) {
+            if (edge.domain !== newEdge.domain)
+                continue;
+            const causeSim = textSimilarity(newEdge.cause, edge.cause);
+            const effectSim = textSimilarity(newEdge.effect, edge.effect);
+            if (causeSim >= MERGE_THRESHOLD && effectSim >= MERGE_THRESHOLD) {
+                return edge;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Synchronous helper: get all edges from SQLite.
+     */
+    getAllSync() {
+        return this.persistence.getAllCausalEdges().map(rowToEdge);
+    }
+}
+/**
+ * Create a CausalStore instance
+ */
+export function createCausalStore(persistence) {
+    return new CausalStore(persistence);
+}
+//# sourceMappingURL=causal-store.js.map

package/dist/experimental/causal-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-store.js","sourceRoot":"","sources":["../../src/experimental/causal-store.ts"],"names":[],"mappings":"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"}

package/dist/experimental/graph-layers/base.d.ts

@@ -0,0 +1,29 @@
+import type { GraphEdge, GraphLayerOperations } from '../knowledge-graph-types.js';
+import type { GraphLayerName, KnowledgeNote, LinkRelation } from '../../types/knowledge.js';
+/**
+ * Base implementation for a graph layer.
+ *
+ * Uses an in-memory adjacency list for O(1) edge lookups.
+ * Subclasses only override the set of valid relation types for their layer.
+ */
+export declare abstract class BaseGraphLayer implements GraphLayerOperations {
+    abstract readonly name: GraphLayerName;
+    readonly enabled: boolean;
+    /** Outgoing edges: nodeId → edges[] */
+    protected outgoing: Map<string, GraphEdge[]>;
+    /** Incoming edges: nodeId → edges[] */
+    protected incoming: Map<string, GraphEdge[]>;
+    /** Which relation types belong to this layer */
+    protected abstract readonly validRelations: readonly LinkRelation[];
+    constructor(enabled?: boolean);
+    getEdges(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both'): GraphEdge[];
+    neighbors(nodeId: string, depth?: number): string[];
+    pathBetween(fromId: string, toId: string): string[] | null;
+    addEdge(edge: GraphEdge): void;
+    removeEdge(fromId: string, toId: string, relation: string): void;
+    getAllEdges(): GraphEdge[];
+    edgeCount(): number;
+    rebuild(notes: KnowledgeNote[]): void;
+    clear(): void;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/experimental/graph-layers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/experimental/graph-layers/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG5F;;;;;GAKG;AACH,8BAAsB,cAAe,YAAW,oBAAoB;IAClE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,uCAAuC;IACvC,SAAS,CAAC,QAAQ,2BAAkC;IACpD,uCAAuC;IACvC,SAAS,CAAC,QAAQ,2BAAkC;IAEpD,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,YAAY,EAAE,CAAC;gBAExD,OAAO,GAAE,OAAc;IAInC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,UAAU,GAAG,UAAU,GAAG,MAAe,GAAG,SAAS,EAAE;IAW3F,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,MAAM,EAAE;IAuBtD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAqC1D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAc9B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAchE,WAAW,IAAI,SAAS,EAAE;IAQ1B,SAAS,IAAI,MAAM;IAQnB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI;IAwBrC,KAAK,IAAI,IAAI;CAId"}