@obsidicore/cascade-engine 0.2.0

package/dist/control/kalman.js

@@ -0,0 +1,83 @@
+/**
+ * Kalman Filter — Confidence fusion from multiple noisy sources
+ *
+ * K = P / (P + R)
+ * confidence += K × (measurement - confidence)
+ * uncertainty = (1 - K) × P
+ *
+ * High R (unreliable source) → low K → measurement discounted
+ * High P (uncertain claim) → high K → updated aggressively
+ */
+/**
+ * Create initial Kalman state for a new finding.
+ */
+export function createKalmanState(initialEstimate = 0.5, initialUncertainty = 1.0) {
+    return {
+        estimate: initialEstimate,
+        uncertainty: initialUncertainty,
+    };
+}
+/**
+ * Update Kalman estimate with a new measurement.
+ *
+ * @param state Current Kalman state
+ * @param measurement New confidence measurement (0-1)
+ * @param measurementNoise R — noise of the measurement source (higher = less reliable)
+ * @returns Updated state
+ */
+export function kalmanUpdate(state, measurement, measurementNoise) {
+    // Kalman gain
+    const K = state.uncertainty / (state.uncertainty + measurementNoise);
+    // Update estimate
+    const newEstimate = state.estimate + K * (measurement - state.estimate);
+    // Update uncertainty
+    const newUncertainty = (1 - K) * state.uncertainty;
+    return {
+        estimate: Math.max(0, Math.min(1, newEstimate)),
+        uncertainty: newUncertainty,
+    };
+}
+/**
+ * Fuse multiple measurements at once.
+ * Each measurement has its own noise level based on source reliability.
+ */
+export function fuseConfidence(measurements, initialEstimate = 0.5, initialUncertainty = 1.0) {
+    let state = createKalmanState(initialEstimate, initialUncertainty);
+    for (const m of measurements) {
+        state = kalmanUpdate(state, m.value, m.noise);
+    }
+    return state;
+}
+/**
+ * Map source type to measurement noise.
+ * Lower noise = more trusted source.
+ */
+export function sourceToNoise(sourceType, trustScore) {
+    const baseNoise = {
+        primary: 0.1, // Peer-reviewed → very reliable
+        secondary: 0.3, // Blogs, tutorials
+        tertiary: 0.6, // Forums, social media
+    };
+    const base = baseNoise[sourceType || ''] ?? 0.5;
+    // Modulate by trust score — low trust = higher noise
+    return base * (2 - trustScore); // Range: base*1 to base*2
+}
+/**
+ * Batch update: apply multiple findings' confidence to a single claim.
+ * Returns the fused confidence and remaining uncertainty.
+ */
+export function batchFuseForClaim(existingConfidence, existingUncertainty, newMeasurements) {
+    let state = {
+        estimate: existingConfidence,
+        uncertainty: existingUncertainty,
+    };
+    for (const m of newMeasurements) {
+        const noise = sourceToNoise(m.sourceType, m.trustScore);
+        state = kalmanUpdate(state, m.confidence, noise);
+    }
+    return {
+        confidence: state.estimate,
+        uncertainty: state.uncertainty,
+    };
+}
+//# sourceMappingURL=kalman.js.map

package/dist/control/kalman.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kalman.js","sourceRoot":"","sources":["../../src/control/kalman.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,kBAA0B,GAAG,EAC7B,qBAA6B,GAAG;IAEhC,OAAO;QACL,QAAQ,EAAE,eAAe;QACzB,WAAW,EAAE,kBAAkB;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAkB,EAClB,WAAmB,EACnB,gBAAwB;IAExB,cAAc;IACd,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,gBAAgB,CAAC,CAAC;IAErE,kBAAkB;IAClB,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAExE,qBAAqB;IACrB,MAAM,cAAc,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;IAEnD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAC/C,WAAW,EAAE,cAAc;KAC5B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAgD,EAChD,kBAA0B,GAAG,EAC7B,qBAA6B,GAAG;IAEhC,IAAI,KAAK,GAAG,iBAAiB,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;IAEnE,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,UAA8B,EAAE,UAAkB;IAC9E,MAAM,SAAS,GAA2B;QACxC,OAAO,EAAE,GAAG,EAAM,gCAAgC;QAClD,SAAS,EAAE,GAAG,EAAI,mBAAmB;QACrC,QAAQ,EAAE,GAAG,EAAK,uBAAuB;KAC1C,CAAC;IAEF,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC;IAEhD,qDAAqD;IACrD,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,0BAA0B;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,kBAA0B,EAC1B,mBAA2B,EAC3B,eAAkF;IAElF,IAAI,KAAK,GAAgB;QACvB,QAAQ,EAAE,kBAAkB;QAC5B,WAAW,EAAE,mBAAmB;KACjC,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,eAAe,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;QACxD,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,QAAQ;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;AACJ,CAAC"}

package/dist/control/pid.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PID Controller — Self-regulation for research cascade
+ *
+ * Maps control theory to research strategy:
+ * - Kp (Proportional): Immediate response to knowledge gaps
+ * - Ki (Integral): Breaks out of chronic stagnation loops
+ * - Kd (Derivative): Dampens sudden contradictory information
+ *
+ * Anti-windup cap on integral. Lyapunov stability detection.
+ *
+ * Error signal components:
+ *   error = coverage_gap*0.3 + low_confidence*0.3 + contradictions*0.2 + depth_gap*0.2
+ *
+ * Output maps to: {searchBreadth, searchDepth, explorationRate}
+ */
+export interface PIDState {
+    kp: number;
+    ki: number;
+    kd: number;
+    error: number;
+    prevError: number;
+    integral: number;
+    derivative: number;
+    output: number;
+    integralMax: number;
+    history: number[];
+}
+export interface PIDOutput {
+    searchBreadth: number;
+    searchDepth: number;
+    explorationRate: number;
+}
+export interface ErrorComponents {
+    coverageGap: number;
+    lowConfidence: number;
+    contradictions: number;
+    depthGap: number;
+}
+/**
+ * Create initial PID state with tuned defaults.
+ */
+export declare function createPIDState(kp?: number, ki?: number, kd?: number): PIDState;
+/**
+ * Compute composite error from research state.
+ */
+export declare function computeError(components: ErrorComponents): number;
+/**
+ * Update PID controller with new error measurement.
+ * Returns control output and updated state.
+ */
+export declare function updatePID(state: PIDState, error: number): PIDOutput;
+/**
+ * Auto-tune Kp when oscillation detected.
+ * Reduces Kp by 0.7× on alternating error signs.
+ */
+export declare function autoTuneKp(state: PIDState): boolean;
+//# sourceMappingURL=pid.d.ts.map

package/dist/control/pid.js

@@ -0,0 +1,95 @@
+/**
+ * PID Controller — Self-regulation for research cascade
+ *
+ * Maps control theory to research strategy:
+ * - Kp (Proportional): Immediate response to knowledge gaps
+ * - Ki (Integral): Breaks out of chronic stagnation loops
+ * - Kd (Derivative): Dampens sudden contradictory information
+ *
+ * Anti-windup cap on integral. Lyapunov stability detection.
+ *
+ * Error signal components:
+ *   error = coverage_gap*0.3 + low_confidence*0.3 + contradictions*0.2 + depth_gap*0.2
+ *
+ * Output maps to: {searchBreadth, searchDepth, explorationRate}
+ */
+/**
+ * Create initial PID state with tuned defaults.
+ */
+export function createPIDState(kp = 1.2, ki = 0.05, kd = 0.1) {
+    return {
+        kp, ki, kd,
+        error: 0,
+        prevError: 0,
+        integral: 0,
+        derivative: 0,
+        output: 0.5, // Start neutral
+        integralMax: 2.0,
+        history: [],
+    };
+}
+/**
+ * Compute composite error from research state.
+ */
+export function computeError(components) {
+    return (components.coverageGap * 0.3 +
+        components.lowConfidence * 0.3 +
+        components.contradictions * 0.2 +
+        components.depthGap * 0.2);
+}
+/**
+ * Update PID controller with new error measurement.
+ * Returns control output and updated state.
+ */
+export function updatePID(state, error) {
+    // Proportional
+    const P = state.kp * error;
+    // Integral with anti-windup
+    state.integral = clamp(state.integral + error, -state.integralMax, state.integralMax);
+    const I = state.ki * state.integral;
+    // Derivative (using previous call's error)
+    state.derivative = error - state.error;
+    const D = state.kd * state.derivative;
+    // Combined output, clamped 0-1
+    state.output = clamp(P + I + D, 0, 1);
+    state.prevError = state.error;
+    state.error = error;
+    state.history.push(error);
+    // Keep history bounded
+    if (state.history.length > 20)
+        state.history.shift();
+    // Map output to research parameters
+    return mapOutputToStrategy(state.output);
+}
+/**
+ * Map PID output (0-1) to concrete research strategy parameters.
+ */
+function mapOutputToStrategy(output) {
+    return {
+        searchBreadth: clamp(output * 0.8 + 0.1, 0, 1), // 0.1-0.9 range
+        searchDepth: clamp((1 - output) * 0.8 + 0.1, 0, 1), // Inverse of breadth
+        explorationRate: clamp(output, 0, 1),
+    };
+}
+/**
+ * Auto-tune Kp when oscillation detected.
+ * Reduces Kp by 0.7× on alternating error signs.
+ */
+export function autoTuneKp(state) {
+    if (state.history.length < 4)
+        return false;
+    const recent = state.history.slice(-4);
+    const signs = recent.map((v, i) => i > 0 ? Math.sign(v - recent[i - 1]) : 0).slice(1);
+    // Check for alternating signs (oscillation)
+    const isOscillating = signs.length >= 3 &&
+        signs[0] !== signs[1] && signs[1] !== signs[2];
+    if (isOscillating) {
+        state.kp *= 0.7;
+        return true;
+    }
+    return false;
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+//# sourceMappingURL=pid.js.map

package/dist/control/pid.js.map

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

package/dist/control/stability.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lyapunov Stability Detection
+ *
+ * Monitors cascade convergence by tracking a Lyapunov-like function:
+ * V(t) = weighted sum of error metrics
+ *
+ * ΔV < 0 → converging (good)
+ * ΔV alternating signs → oscillating (reduce Kp by 0.7×)
+ * ΔV all positive → diverging (emergency synthesis)
+ */
+export type StabilityState = 'converging' | 'oscillating' | 'diverging' | 'insufficient_data';
+export interface StabilityAnalysis {
+    state: StabilityState;
+    lyapunovValues: number[];
+    deltas: number[];
+    trend: number;
+    recommendation: string;
+}
+/**
+ * Compute Lyapunov-like function from error components.
+ * V(t) = Σ wᵢ × eᵢ²  (quadratic form — always non-negative)
+ */
+export declare function computeLyapunov(errors: {
+    coverageGap: number;
+    lowConfidence: number;
+    contradictions: number;
+    depthGap: number;
+}): number;
+/**
+ * Analyze stability from a sequence of Lyapunov values.
+ * Requires at least 3 data points.
+ */
+export declare function analyzeStability(lyapunovHistory: number[]): StabilityAnalysis;
+/**
+ * Check if the cascade has reached a convergence criterion.
+ * Uses both Lyapunov stability AND absolute error threshold.
+ */
+export declare function hasConverged(lyapunovHistory: number[], absoluteThreshold?: number): {
+    converged: boolean;
+    reason: string;
+};
+//# sourceMappingURL=stability.d.ts.map

package/dist/control/stability.js

@@ -0,0 +1,117 @@
+/**
+ * Lyapunov Stability Detection
+ *
+ * Monitors cascade convergence by tracking a Lyapunov-like function:
+ * V(t) = weighted sum of error metrics
+ *
+ * ΔV < 0 → converging (good)
+ * ΔV alternating signs → oscillating (reduce Kp by 0.7×)
+ * ΔV all positive → diverging (emergency synthesis)
+ */
+/**
+ * Compute Lyapunov-like function from error components.
+ * V(t) = Σ wᵢ × eᵢ²  (quadratic form — always non-negative)
+ */
+export function computeLyapunov(errors) {
+    return (0.3 * errors.coverageGap ** 2 +
+        0.3 * errors.lowConfidence ** 2 +
+        0.2 * errors.contradictions ** 2 +
+        0.2 * errors.depthGap ** 2);
+}
+/**
+ * Analyze stability from a sequence of Lyapunov values.
+ * Requires at least 3 data points.
+ */
+export function analyzeStability(lyapunovHistory) {
+    if (lyapunovHistory.length < 3) {
+        return {
+            state: 'insufficient_data',
+            lyapunovValues: lyapunovHistory,
+            deltas: [],
+            trend: 0,
+            recommendation: 'Need at least 3 rounds of data for stability analysis.',
+        };
+    }
+    // Compute deltas: ΔV = V(t) - V(t-1)
+    const deltas = [];
+    for (let i = 1; i < lyapunovHistory.length; i++) {
+        deltas.push(lyapunovHistory[i] - lyapunovHistory[i - 1]);
+    }
+    // Overall trend (simple linear regression slope)
+    const n = deltas.length;
+    const sumX = n * (n - 1) / 2;
+    const sumY = deltas.reduce((s, d) => s + d, 0);
+    const sumXY = deltas.reduce((s, d, i) => s + i * d, 0);
+    const sumX2 = deltas.reduce((s, _, i) => s + i * i, 0);
+    const trend = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX || 1);
+    // Check recent deltas (last 3)
+    const recent = deltas.slice(-3);
+    const allNegative = recent.every(d => d < -0.001);
+    const allPositive = recent.every(d => d > 0.001);
+    const alternating = recent.length >= 2 &&
+        recent.slice(1).every((d, i) => Math.sign(d) !== Math.sign(recent[i]));
+    let state;
+    let recommendation;
+    if (allNegative) {
+        state = 'converging';
+        recommendation = 'Research is converging. Continue current strategy.';
+    }
+    else if (allPositive) {
+        state = 'diverging';
+        recommendation = 'DIVERGING — errors growing. Trigger emergency synthesis. Reduce scope, increase validation.';
+    }
+    else if (alternating) {
+        state = 'oscillating';
+        recommendation = 'OSCILLATING — reduce Kp by 0.7×. The cascade is flip-flopping between states.';
+    }
+    else {
+        // Mixed signals — use trend
+        if (trend < -0.01) {
+            state = 'converging';
+            recommendation = 'Generally converging despite some noise. Continue.';
+        }
+        else if (trend > 0.01) {
+            state = 'diverging';
+            recommendation = 'Trending toward divergence. Consider narrowing scope.';
+        }
+        else {
+            state = 'converging'; // Flat = stable
+            recommendation = 'Stable plateau. May be approaching saturation — check stopping gates.';
+        }
+    }
+    return {
+        state,
+        lyapunovValues: lyapunovHistory,
+        deltas,
+        trend,
+        recommendation,
+    };
+}
+/**
+ * Check if the cascade has reached a convergence criterion.
+ * Uses both Lyapunov stability AND absolute error threshold.
+ */
+export function hasConverged(lyapunovHistory, absoluteThreshold = 0.05) {
+    if (lyapunovHistory.length === 0) {
+        return { converged: false, reason: 'No data' };
+    }
+    const latest = lyapunovHistory[lyapunovHistory.length - 1];
+    // Absolute convergence: V(t) below threshold
+    if (latest < absoluteThreshold) {
+        return { converged: true, reason: `Lyapunov V(t)=${latest.toFixed(4)} < threshold ${absoluteThreshold}` };
+    }
+    // Rate convergence: ΔV approaching zero
+    if (lyapunovHistory.length >= 3) {
+        const recentDeltas = [];
+        for (let i = lyapunovHistory.length - 3; i < lyapunovHistory.length; i++) {
+            if (i > 0)
+                recentDeltas.push(Math.abs(lyapunovHistory[i] - lyapunovHistory[i - 1]));
+        }
+        const avgDelta = recentDeltas.reduce((s, d) => s + d, 0) / recentDeltas.length;
+        if (avgDelta < 0.005) {
+            return { converged: true, reason: `Average ΔV=${avgDelta.toFixed(5)} — compression progress exhausted` };
+        }
+    }
+    return { converged: false, reason: `V(t)=${latest.toFixed(4)}, still above threshold` };
+}
+//# sourceMappingURL=stability.js.map

package/dist/control/stability.js.map

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

package/dist/db/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SQLite database wrapper for Research Cascade knowledge store.
+ * Uses synchronous better-sqlite3 (no async race conditions with JSONL state).
+ * WAL mode, single writer + multiple readers.
+ */
+import Database from 'better-sqlite3';
+export interface DatabaseOptions {
+    dbPath?: string;
+    readonly?: boolean;
+}
+/** For testing only — inject an in-memory DB */
+export declare function __setTestDb(db: Database.Database | null): void;
+export declare function getDb(options?: DatabaseOptions): Database.Database;
+export declare function closeDb(): void;
+/**
+ * Check WAL size and run passive checkpoint if > threshold.
+ * Call periodically (e.g., between cascade rounds).
+ */
+export declare function checkpointIfNeeded(thresholdMB?: number): void;
+/** Generate a content-addressable ID from claim text */
+export declare function contentHash(text: string): string;
+/** Generate a random UUID-like ID */
+export declare function generateId(): string;
+/** Begin an immediate write transaction */
+export declare function withTransaction<T>(fn: () => T): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.js

@@ -0,0 +1,116 @@
+/**
+ * SQLite database wrapper for Research Cascade knowledge store.
+ * Uses synchronous better-sqlite3 (no async race conditions with JSONL state).
+ * WAL mode, single writer + multiple readers.
+ */
+import Database from 'better-sqlite3';
+import { readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, existsSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SCHEMA_PATH = join(__dirname, '..', '..', 'src', 'db', 'schema.sql');
+const SCHEMA_DIST_PATH = join(__dirname, 'schema.sql');
+let _db = null;
+function getDefaultDbPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const dir = join(home, '.cascade-engine');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return join(dir, 'knowledge.db');
+}
+/** For testing only — inject an in-memory DB */
+export function __setTestDb(db) {
+    _db = db;
+}
+export function getDb(options) {
+    if (_db)
+        return _db;
+    const dbPath = options?.dbPath || process.env.CASCADE_DB_PATH || getDefaultDbPath();
+    const dbDir = dirname(dbPath);
+    if (!existsSync(dbDir)) {
+        mkdirSync(dbDir, { recursive: true });
+    }
+    _db = new Database(dbPath, {
+        readonly: options?.readonly ?? false,
+        fileMustExist: false,
+    });
+    // Critical PRAGMAs — order matters
+    _db.pragma('journal_mode = WAL');
+    _db.pragma('busy_timeout = 10000');
+    _db.pragma('synchronous = NORMAL');
+    _db.pragma('cache_size = -64000'); // 64MB
+    _db.pragma('foreign_keys = ON');
+    _db.pragma('temp_store = MEMORY');
+    _db.pragma('mmap_size = 268435456'); // 256MB
+    // Run schema migration
+    migrateSchema(_db);
+    // Register shutdown handler
+    process.on('exit', () => closeDb());
+    return _db;
+}
+function migrateSchema(db) {
+    // Try source path first (dev), then dist path (production)
+    let schemaPath = SCHEMA_PATH;
+    if (!existsSync(schemaPath)) {
+        schemaPath = SCHEMA_DIST_PATH;
+    }
+    if (!existsSync(schemaPath)) {
+        // Inline minimal check — schema.sql should be copied during build
+        console.error('[cascade-engine] Warning: schema.sql not found, skipping migration');
+        return;
+    }
+    const schema = readFileSync(schemaPath, 'utf-8');
+    // Split on semicolons, filter empty, execute each statement
+    // All CREATE statements use IF NOT EXISTS — safe to re-run
+    db.exec(schema);
+}
+export function closeDb() {
+    if (_db) {
+        try {
+            // Optimize before close
+            _db.pragma('optimize');
+            _db.close();
+        }
+        catch {
+            // Already closed or errored — ignore
+        }
+        _db = null;
+    }
+}
+/**
+ * Check WAL size and run passive checkpoint if > threshold.
+ * Call periodically (e.g., between cascade rounds).
+ */
+export function checkpointIfNeeded(thresholdMB = 50) {
+    const db = getDb();
+    const walPath = db.name + '-wal';
+    try {
+        const { size } = statSync(walPath);
+        if (size > thresholdMB * 1024 * 1024) {
+            db.pragma('wal_checkpoint(PASSIVE)');
+        }
+    }
+    catch {
+        // WAL file doesn't exist or can't stat — fine
+    }
+}
+// --- Helpers for common patterns ---
+/** Generate a content-addressable ID from claim text */
+export function contentHash(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/** Generate a random UUID-like ID */
+export function generateId() {
+    return randomBytes(8).toString('hex');
+}
+/** Begin an immediate write transaction */
+export function withTransaction(fn) {
+    const db = getDb();
+    const transaction = db.transaction(fn);
+    return transaction();
+}
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

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