causantic 0.2.0

package/dist/storage/cluster-store.js

@@ -0,0 +1,219 @@
+/**
+ * CRUD operations for clusters and chunk-cluster assignments.
+ */
+import { getDb, generateId } from './db.js';
+/**
+ * Create or update a cluster.
+ */
+export function upsertCluster(input) {
+    const db = getDb();
+    const id = input.id || generateId();
+    const now = new Date().toISOString();
+    // Check if exists
+    const existing = db.prepare('SELECT id FROM clusters WHERE id = ?').get(id);
+    if (existing) {
+        // Update
+        const updates = [];
+        const params = [];
+        if (input.name !== undefined) {
+            updates.push('name = ?');
+            params.push(input.name);
+        }
+        if (input.description !== undefined) {
+            updates.push('description = ?');
+            params.push(input.description);
+        }
+        if (input.centroid !== undefined) {
+            updates.push('centroid = ?');
+            params.push(serializeCentroid(input.centroid));
+        }
+        if (input.exemplarIds !== undefined) {
+            updates.push('exemplar_ids = ?');
+            params.push(JSON.stringify(input.exemplarIds));
+        }
+        if (input.membershipHash !== undefined) {
+            updates.push('membership_hash = ?');
+            params.push(input.membershipHash);
+        }
+        if (input.description !== undefined) {
+            updates.push('refreshed_at = ?');
+            params.push(now);
+        }
+        if (updates.length > 0) {
+            params.push(id);
+            db.prepare(`UPDATE clusters SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        }
+    }
+    else {
+        // Insert
+        db.prepare(`
+      INSERT INTO clusters (
+        id, name, description, centroid, exemplar_ids,
+        membership_hash, created_at, refreshed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.name ?? null, input.description ?? null, input.centroid ? serializeCentroid(input.centroid) : null, input.exemplarIds ? JSON.stringify(input.exemplarIds) : null, input.membershipHash ?? null, now, input.description ? now : null);
+    }
+    return id;
+}
+/**
+ * Get a cluster by ID.
+ */
+export function getClusterById(id) {
+    const db = getDb();
+    const row = db.prepare('SELECT * FROM clusters WHERE id = ?').get(id);
+    if (!row) {
+        return null;
+    }
+    return rowToCluster(row);
+}
+/**
+ * Get all clusters.
+ */
+export function getAllClusters() {
+    const db = getDb();
+    const rows = db.prepare('SELECT * FROM clusters ORDER BY created_at').all();
+    return rows.map(rowToCluster);
+}
+/**
+ * Get clusters that need refresh (stale descriptions).
+ * A cluster is stale if its membership_hash doesn't match current members
+ * or if it has never been refreshed.
+ */
+export function getStaleClusters(maxAge) {
+    const db = getDb();
+    let query = 'SELECT * FROM clusters WHERE refreshed_at IS NULL';
+    const params = [];
+    if (maxAge !== undefined) {
+        const cutoff = new Date(Date.now() - maxAge).toISOString();
+        query += ' OR refreshed_at < ?';
+        params.push(cutoff);
+    }
+    const rows = db.prepare(query).all(...params);
+    return rows.map(rowToCluster);
+}
+/**
+ * Assign a chunk to a cluster.
+ */
+export function assignChunkToCluster(chunkId, clusterId, distance) {
+    const db = getDb();
+    db.prepare(`
+    INSERT OR REPLACE INTO chunk_clusters (chunk_id, cluster_id, distance)
+    VALUES (?, ?, ?)
+  `).run(chunkId, clusterId, distance);
+}
+/**
+ * Assign multiple chunks to clusters in a transaction.
+ */
+export function assignChunksToClusters(assignments) {
+    const db = getDb();
+    const stmt = db.prepare(`
+    INSERT OR REPLACE INTO chunk_clusters (chunk_id, cluster_id, distance)
+    VALUES (?, ?, ?)
+  `);
+    const insertMany = db.transaction((assignments) => {
+        for (const a of assignments) {
+            stmt.run(a.chunkId, a.clusterId, a.distance);
+        }
+    });
+    insertMany(assignments);
+}
+/**
+ * Get cluster assignments for a chunk.
+ */
+export function getChunkClusterAssignments(chunkId) {
+    const db = getDb();
+    const rows = db
+        .prepare('SELECT * FROM chunk_clusters WHERE chunk_id = ? ORDER BY distance')
+        .all(chunkId);
+    return rows.map((r) => ({
+        chunkId: r.chunk_id,
+        clusterId: r.cluster_id,
+        distance: r.distance,
+    }));
+}
+/**
+ * Get all chunk IDs in a cluster.
+ */
+export function getClusterChunkIds(clusterId) {
+    const db = getDb();
+    const rows = db
+        .prepare('SELECT chunk_id FROM chunk_clusters WHERE cluster_id = ? ORDER BY distance')
+        .all(clusterId);
+    return rows.map((r) => r.chunk_id);
+}
+/**
+ * Remove all cluster assignments for a chunk.
+ */
+export function removeChunkAssignments(chunkId) {
+    const db = getDb();
+    const result = db.prepare('DELETE FROM chunk_clusters WHERE chunk_id = ?').run(chunkId);
+    return result.changes;
+}
+/**
+ * Remove all assignments for a cluster.
+ */
+export function clearClusterAssignments(clusterId) {
+    const db = getDb();
+    const result = db.prepare('DELETE FROM chunk_clusters WHERE cluster_id = ?').run(clusterId);
+    return result.changes;
+}
+/**
+ * Delete a cluster and its assignments.
+ */
+export function deleteCluster(id) {
+    const db = getDb();
+    const deleteAll = db.transaction(() => {
+        db.prepare('DELETE FROM chunk_clusters WHERE cluster_id = ?').run(id);
+        return db.prepare('DELETE FROM clusters WHERE id = ?').run(id);
+    });
+    const result = deleteAll();
+    return result.changes > 0;
+}
+/**
+ * Delete all clusters and assignments.
+ */
+export function clearAllClusters() {
+    const db = getDb();
+    db.transaction(() => {
+        db.exec('DELETE FROM chunk_clusters');
+        db.exec('DELETE FROM clusters');
+    })();
+}
+/**
+ * Get cluster count.
+ */
+export function getClusterCount() {
+    const db = getDb();
+    const row = db.prepare('SELECT COUNT(*) as count FROM clusters').get();
+    return row.count;
+}
+/**
+ * Compute membership hash for staleness detection.
+ */
+export function computeMembershipHash(chunkIds) {
+    const sorted = [...chunkIds].sort();
+    // Simple hash: join and use first 16 chars of base64
+    const str = sorted.join(',');
+    return Buffer.from(str).toString('base64').slice(0, 16);
+}
+function rowToCluster(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        centroid: row.centroid ? deserializeCentroid(row.centroid) : null,
+        exemplarIds: row.exemplar_ids ? JSON.parse(row.exemplar_ids) : [],
+        membershipHash: row.membership_hash,
+        createdAt: row.created_at,
+        refreshedAt: row.refreshed_at,
+    };
+}
+function serializeCentroid(centroid) {
+    const float32 = new Float32Array(centroid);
+    return Buffer.from(float32.buffer);
+}
+function deserializeCentroid(buffer) {
+    const float32 = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / Float32Array.BYTES_PER_ELEMENT);
+    return Array.from(float32);
+}
+//# sourceMappingURL=cluster-store.js.map

package/dist/storage/cluster-store.js.map

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

package/dist/storage/db.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SQLite database connection management.
+ *
+ * Supports optional encryption using better-sqlite3-multiple-ciphers.
+ * Schema loading and migrations are handled by schema-loader.ts and migrations.ts.
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+/**
+ * Set a custom database instance (for testing).
+ */
+export declare function setDb(database: Database.Database): void;
+/**
+ * Reset the database to default behavior.
+ */
+export declare function resetDb(): void;
+/**
+ * Get the database encryption key asynchronously.
+ */
+export declare function getDbKeyAsync(): Promise<string | undefined>;
+/**
+ * Set the cached database key.
+ */
+export declare function setDbKey(key: string): void;
+/**
+ * Store the database key in the secret store.
+ */
+export declare function storeDbKey(key: string): Promise<void>;
+/**
+ * Initialize and return the database connection.
+ */
+export declare function getDb(dbPath?: string): Database.Database;
+/**
+ * Close the database connection.
+ */
+export declare function closeDb(): void;
+/**
+ * Get current schema version.
+ */
+export declare function getSchemaVersion(database?: Database.Database): number;
+/**
+ * Clear all data (for testing).
+ */
+export declare function clearAllData(database?: Database.Database): void;
+/**
+ * Get database statistics.
+ */
+export declare function getDbStats(database?: Database.Database): {
+    chunks: number;
+    edges: number;
+    clusters: number;
+    assignments: number;
+};
+/**
+ * Generate a unique ID.
+ */
+export declare function generateId(): string;
+//# sourceMappingURL=db.d.ts.map

package/dist/storage/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/storage/db.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AAkDvD;;GAEG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAEvD;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAU9B;AAkDD;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA+BjE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3D;AAiBD;;GAEG;AACH,wBAAgB,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAwCxD;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,IAAI,CAK9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAMrE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAM/D;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAa1E;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/storage/db.js

@@ -0,0 +1,249 @@
+/**
+ * SQLite database connection management.
+ *
+ * Supports optional encryption using better-sqlite3-multiple-ciphers.
+ * Schema loading and migrations are handled by schema-loader.ts and migrations.ts.
+ */
+import Database from 'better-sqlite3-multiple-ciphers';
+import { existsSync, mkdirSync } from 'fs';
+import { execFileSync, spawnSync } from 'child_process';
+import { dirname } from 'path';
+import { resolvePath } from '../config/memory-config.js';
+import { loadConfig } from '../config/loader.js';
+import { createSecretStore } from '../utils/secret-store.js';
+import { withSecureBufferSync } from '../utils/secure-buffer.js';
+import { logAudit } from './audit-log.js';
+import { runMigrations } from './migrations.js';
+/** Key name in secret store for database encryption */
+const DB_KEY_NAME = 'causantic-db-key';
+let db = null;
+let customDb = null;
+/** Cached encryption key (only set when keySource is not 'prompt') */
+let cachedDbKey = null;
+/** Service name for keychain storage */
+const KEYCHAIN_SERVICE = 'causantic';
+/**
+ * Get key from OS keychain synchronously.
+ * Supports macOS Keychain and Linux secret-tool.
+ */
+function getKeyFromKeychainSync() {
+    try {
+        if (process.platform === 'darwin') {
+            const result = execFileSync('security', ['find-generic-password', '-a', DB_KEY_NAME, '-s', KEYCHAIN_SERVICE, '-w'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            return result.trim() || null;
+        }
+        else if (process.platform === 'linux') {
+            const result = spawnSync('secret-tool', ['lookup', 'service', KEYCHAIN_SERVICE, 'account', DB_KEY_NAME], { encoding: 'utf-8' });
+            return (result.status === 0 && result.stdout?.trim()) || null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Set a custom database instance (for testing).
+ */
+export function setDb(database) {
+    customDb = database;
+}
+/**
+ * Reset the database to default behavior.
+ */
+export function resetDb() {
+    if (customDb) {
+        customDb = null;
+    }
+    if (db) {
+        logAudit('close', 'Database closed');
+        db.close();
+        db = null;
+    }
+    cachedDbKey = null;
+}
+/**
+ * Get the database encryption key synchronously.
+ */
+function getDbKeySync() {
+    const config = loadConfig();
+    if (!config.encryption?.enabled) {
+        return undefined;
+    }
+    if (cachedDbKey) {
+        return cachedDbKey;
+    }
+    const keySource = config.encryption.keySource ?? 'keychain';
+    switch (keySource) {
+        case 'env': {
+            const key = process.env.CAUSANTIC_DB_KEY;
+            if (key) {
+                cachedDbKey = key;
+                logAudit('key-access', 'Key retrieved from environment');
+            }
+            return key;
+        }
+        case 'keychain': {
+            const keychainKey = getKeyFromKeychainSync();
+            if (keychainKey) {
+                cachedDbKey = keychainKey;
+                logAudit('key-access', 'Key retrieved from keychain');
+                return keychainKey;
+            }
+            const envKey = process.env.CAUSANTIC_DB_KEY;
+            if (envKey) {
+                cachedDbKey = envKey;
+                logAudit('key-access', 'Key retrieved from environment (keychain fallback)');
+                return envKey;
+            }
+            return undefined;
+        }
+        case 'prompt':
+            throw new Error('Database encryption with keySource=prompt requires running causantic init or causantic encryption unlock first');
+        default:
+            return undefined;
+    }
+}
+/**
+ * Get the database encryption key asynchronously.
+ */
+export async function getDbKeyAsync() {
+    const config = loadConfig();
+    if (!config.encryption?.enabled) {
+        return undefined;
+    }
+    const keySource = config.encryption.keySource ?? 'keychain';
+    switch (keySource) {
+        case 'env': {
+            const key = process.env.CAUSANTIC_DB_KEY;
+            if (key) {
+                cachedDbKey = key;
+                logAudit('key-access', 'Key retrieved from environment');
+            }
+            return key;
+        }
+        case 'keychain': {
+            const store = createSecretStore();
+            const key = await store.get(DB_KEY_NAME);
+            if (key) {
+                cachedDbKey = key;
+                logAudit('key-access', 'Key retrieved from keychain');
+            }
+            return key ?? undefined;
+        }
+        case 'prompt':
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Set the cached database key.
+ */
+export function setDbKey(key) {
+    cachedDbKey = key;
+}
+/**
+ * Store the database key in the secret store.
+ */
+export async function storeDbKey(key) {
+    const store = createSecretStore();
+    await store.set(DB_KEY_NAME, key);
+    cachedDbKey = key;
+    logAudit('key-access', 'Key stored in keychain');
+}
+/**
+ * Apply encryption to a database connection.
+ */
+function applyEncryption(database, key) {
+    const config = loadConfig();
+    const cipher = config.encryption?.cipher ?? 'chacha20';
+    withSecureBufferSync(key, (secureKey) => {
+        database.pragma(`cipher = '${cipher}'`);
+        database.pragma(`key = '${secureKey.toString()}'`);
+    });
+    logAudit('open', `Database opened with ${cipher} encryption`);
+}
+/**
+ * Initialize and return the database connection.
+ */
+export function getDb(dbPath) {
+    if (customDb) {
+        return customDb;
+    }
+    if (db) {
+        return db;
+    }
+    const config = loadConfig();
+    const resolvedPath = resolvePath(dbPath ?? config.storage?.dbPath ?? '~/.causantic/memory.db');
+    const dir = dirname(resolvedPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    db = new Database(resolvedPath);
+    if (config.encryption?.enabled) {
+        const key = getDbKeySync();
+        if (key) {
+            applyEncryption(db, key);
+        }
+        else {
+            logAudit('failed', 'No encryption key available');
+            throw new Error('Database encryption is enabled but no key is available. ' +
+                'Run "causantic encryption setup" or set CAUSANTIC_DB_KEY environment variable.');
+        }
+    }
+    else {
+        logAudit('open', 'Database opened (unencrypted)');
+    }
+    db.pragma('foreign_keys = ON');
+    db.pragma('journal_mode = WAL');
+    runMigrations(db);
+    return db;
+}
+/**
+ * Close the database connection.
+ */
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+/**
+ * Get current schema version.
+ */
+export function getSchemaVersion(database) {
+    const d = database ?? getDb();
+    const row = d.prepare('SELECT MAX(version) as version FROM schema_version').get();
+    return row?.version ?? 0;
+}
+/**
+ * Clear all data (for testing).
+ */
+export function clearAllData(database) {
+    const d = database ?? getDb();
+    d.exec('DELETE FROM chunk_clusters');
+    d.exec('DELETE FROM edges');
+    d.exec('DELETE FROM chunks');
+    d.exec('DELETE FROM clusters');
+}
+/**
+ * Get database statistics.
+ */
+export function getDbStats(database) {
+    const d = database ?? getDb();
+    const chunks = d.prepare('SELECT COUNT(*) as count FROM chunks').get()
+        .count;
+    const edges = d.prepare('SELECT COUNT(*) as count FROM edges').get().count;
+    const clusters = d.prepare('SELECT COUNT(*) as count FROM clusters').get()
+        .count;
+    const assignments = d.prepare('SELECT COUNT(*) as count FROM chunk_clusters').get().count;
+    return { chunks, edges, clusters, assignments };
+}
+/**
+ * Generate a unique ID.
+ */
+export function generateId() {
+    return crypto.randomUUID();
+}
+//# sourceMappingURL=db.js.map

package/dist/storage/db.js.map

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

package/dist/storage/decay.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Decay weight calculation for edges.
+ * Supports both time-based decay (legacy) and vector clock-based decay.
+ */
+import type { DecayModelConfig } from '../core/decay-types.js';
+import { type VectorClock } from '../temporal/vector-clock.js';
+/**
+ * Edge direction for hop decay.
+ */
+export type EdgeDirection = 'backward' | 'forward';
+/**
+ * Hop decay curve type.
+ */
+export type HopDecayType = 'exponential' | 'linear' | 'delayed-linear';
+/**
+ * Configuration for hop-based decay curves.
+ * Different curves are optimal for different directions:
+ * - Backward (4-20 hops): Linear dies@10 (MRR=0.688)
+ * - Forward (1-20 hops): Delayed linear 5h/dies@20 (MRR=0.849)
+ */
+export interface HopDecayConfig {
+    /** Decay curve type */
+    type: HopDecayType;
+    /** For exponential: weight = weightPerHop^hops */
+    weightPerHop?: number;
+    /** For linear/delayed-linear: decay rate per hop */
+    decayPerHop?: number;
+    /** For delayed-linear: hold full weight for N hops */
+    holdHops?: number;
+    /** Minimum weight before edge is considered dead */
+    minWeight: number;
+}
+/**
+ * Backward hop decay: Linear (dies@10)
+ * Optimal for retrieving causally-related context 4-20 hops back.
+ * MRR=0.688 (+35% vs exponential 0.80)
+ */
+export declare const BACKWARD_HOP_DECAY: HopDecayConfig;
+/**
+ * Forward hop decay: Delayed linear (5-hop hold, dies@20)
+ * Optimal for predicting future context 1-20 hops forward.
+ * MRR=0.849 (+271% vs exponential 0.80)
+ */
+export declare const FORWARD_HOP_DECAY: HopDecayConfig;
+/**
+ * Legacy configuration for vector clock-based decay (exponential only).
+ * @deprecated Use HopDecayConfig with direction-specific curves instead.
+ */
+export interface VectorDecayConfig {
+    /** Weight multiplier per hop (e.g., 0.85 = 15% decay per hop) */
+    weightPerHop: number;
+    /** Minimum weight before edge is considered dead */
+    minWeight: number;
+}
+/**
+ * Default vector decay configuration (legacy exponential).
+ * @deprecated Use BACKWARD_HOP_DECAY or FORWARD_HOP_DECAY instead.
+ */
+export declare const DEFAULT_VECTOR_DECAY: VectorDecayConfig;
+/**
+ * Calculate hop-based decay weight using direction-specific curves.
+ *
+ * @param hops - Number of hops from reference point
+ * @param config - Hop decay configuration
+ * @returns Weight value (0 to 1), or 0 if below minWeight
+ */
+export declare function calculateHopDecayWeight(hops: number, config: HopDecayConfig): number;
+/**
+ * Calculate decay weight for an edge based on direction.
+ *
+ * @param edgeClock - Vector clock stamped on the edge
+ * @param referenceClock - Current reference clock for the project
+ * @param direction - Edge direction ('backward' or 'forward')
+ * @returns Weight value (0 to 1), or 0 if below minWeight
+ */
+export declare function calculateDirectionalDecayWeight(edgeClock: VectorClock, referenceClock: VectorClock, direction: EdgeDirection): number;
+/**
+ * Calculate decay weight based on vector clock hop count.
+ * @deprecated Use calculateDirectionalDecayWeight for direction-specific curves.
+ *
+ * @param edgeClock - Vector clock stamped on the edge
+ * @param referenceClock - Current reference clock for the project
+ * @param config - Vector decay configuration
+ * @returns Weight value (0 to 1), or 0 if below minWeight
+ */
+export declare function calculateVectorDecayWeight(edgeClock: VectorClock, referenceClock: VectorClock, config?: VectorDecayConfig): number;
+/**
+ * Calculate decay weight with fallback for legacy edges.
+ * Uses vector clock decay if available, falls back to time-based decay.
+ *
+ * @param edgeClockJson - JSON serialized vector clock (may be null for legacy edges)
+ * @param referenceClock - Current reference clock for the project
+ * @param direction - Edge direction for curve selection
+ * @param createdAtMs - Edge creation time in milliseconds (for fallback)
+ * @param queryTimeMs - Query time in milliseconds (for fallback)
+ * @param timeConfig - Time-based decay configuration (for fallback)
+ * @returns Computed weight value
+ */
+export declare function calculateDecayWeightWithFallback(edgeClockJson: string | null, referenceClock: VectorClock, direction: EdgeDirection, createdAtMs: number, queryTimeMs: number, timeConfig: DecayModelConfig): number;
+/**
+ * @deprecated Use calculateDecayWeightWithFallback with direction parameter.
+ */
+export declare function calculateDecayWeightWithFallbackLegacy(edgeClockJson: string | null, referenceClock: VectorClock, vectorConfig: VectorDecayConfig, createdAtMs: number, queryTimeMs: number, timeConfig: DecayModelConfig): number;
+/**
+ * Calculate boosted weight for edges with multiple links.
+ * Edges that have been created multiple times (same source/target pair)
+ * get a boost to resist decay.
+ *
+ * @param baseWeight - Base weight after decay
+ * @param linkCount - Number of times this edge was created
+ * @returns Boosted weight
+ */
+export declare function applyLinkBoost(baseWeight: number, linkCount: number): number;
+/**
+ * Calculate the decay weight at a given age.
+ * @param config - Decay model configuration
+ * @param ageMs - Age of the edge in milliseconds
+ * @returns Weight value (0 to initialWeight)
+ */
+export declare function calculateDecayWeight(config: DecayModelConfig, ageMs: number): number;
+/**
+ * Calculate the time when weight reaches zero (or null if asymptotic).
+ */
+export declare function getDeathTime(config: DecayModelConfig): number | null;
+//# sourceMappingURL=decay.d.ts.map