@eddacraft/kindling-core 0.1.0

package/dist/capsule/manager.js

@@ -0,0 +1,113 @@
+/**
+ * Capsule manager implementation
+ *
+ * Manages capsule lifecycle with in-memory caching for fast lookup.
+ */
+import { openCapsule, closeCapsule, getCapsule, getOpenCapsule } from './lifecycle.js';
+/**
+ * Default capsule manager implementation
+ *
+ * Features:
+ * - In-memory cache for active capsules
+ * - Thread-safe operations (via synchronous store calls)
+ * - Automatic cache invalidation on close
+ */
+export class CapsuleManager {
+    store;
+    activeCache;
+    constructor(store) {
+        this.store = store;
+        this.activeCache = new Map();
+    }
+    /**
+     * Open a new capsule
+     *
+     * @param options - Capsule creation options
+     * @returns The created capsule
+     * @throws Error if validation fails or duplicate open capsule exists
+     */
+    open(options) {
+        const capsule = openCapsule(this.store, options);
+        // Cache for fast lookup
+        this.activeCache.set(capsule.id, capsule);
+        return capsule;
+    }
+    /**
+     * Close an open capsule
+     *
+     * @param capsuleId - ID of capsule to close
+     * @param signals - Closure signals/metadata
+     * @returns The closed capsule
+     * @throws Error if capsule not found or already closed
+     */
+    close(capsuleId, signals) {
+        const capsule = closeCapsule(this.store, capsuleId, signals);
+        // Remove from active cache
+        this.activeCache.delete(capsuleId);
+        return capsule;
+    }
+    /**
+     * Get a capsule by ID
+     *
+     * Checks cache first, falls back to store.
+     *
+     * @param capsuleId - Capsule ID to lookup
+     * @returns Capsule or undefined if not found
+     */
+    get(capsuleId) {
+        // Check cache first
+        const cached = this.activeCache.get(capsuleId);
+        if (cached) {
+            return cached;
+        }
+        // Fall back to store
+        return getCapsule(this.store, capsuleId);
+    }
+    /**
+     * Get the open capsule for a scope (if any)
+     *
+     * Currently only supports session-scoped lookup.
+     *
+     * @param scopeIds - Partial scope to match
+     * @returns Open capsule or undefined
+     */
+    getOpen(scopeIds) {
+        // Only session-scoped lookup is supported for now
+        if (!scopeIds.sessionId) {
+            throw new Error('getOpen currently only supports sessionId lookup');
+        }
+        return getOpenCapsule(this.store, scopeIds.sessionId);
+    }
+    /**
+     * Notify that an observation was attached to a capsule
+     *
+     * Updates the cached capsule's observationIds if the capsule is in the cache.
+     *
+     * @param capsuleId - Capsule that received the observation
+     * @param observationId - Observation that was attached
+     */
+    notifyObservationAttached(capsuleId, observationId) {
+        const cached = this.activeCache.get(capsuleId);
+        if (cached) {
+            // Update the cached capsule's observationIds
+            cached.observationIds.push(observationId);
+        }
+    }
+    /**
+     * Clear the active capsule cache
+     *
+     * Useful for testing or manual cache invalidation.
+     */
+    clearCache() {
+        this.activeCache.clear();
+    }
+    /**
+     * Get count of cached active capsules
+     *
+     * Useful for debugging and monitoring.
+     */
+    getCacheSize() {
+        return this.activeCache.size;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/capsule/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/capsule/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IACjB,KAAK,CAAe;IACpB,WAAW,CAAmB;IAEtC,YAAY,KAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAA2B;QAC9B,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAEjD,wBAAwB;QACxB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAE1C,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAa,EAAE,OAA6B;QAChD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAE7D,2BAA2B;QAC3B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,SAAa;QACf,oBAAoB;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,qBAAqB;QACrB,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,QAA2B;QACjC,kDAAkD;QAClD,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;QAED,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;OAOG;IACH,yBAAyB,CAAC,SAAa,EAAE,aAAiB;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,MAAM,EAAE,CAAC;YACX,6CAA6C;YAC7C,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;CACF"}

package/dist/capsule/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Capsule lifecycle types and interfaces
+ */
+import type { ID, ScopeIds } from '../types/common.js';
+import type { Capsule, CapsuleType } from '../types/capsule.js';
+/**
+ * Options for opening a new capsule
+ */
+export interface OpenCapsuleOptions {
+    /** Type of capsule (session, task, etc.) */
+    type: CapsuleType;
+    /** Human-readable intent/purpose */
+    intent: string;
+    /** Scope dimensions for isolation */
+    scopeIds: ScopeIds;
+    /** Optional pre-generated ID */
+    id?: ID;
+}
+/**
+ * Signals/metadata for closing a capsule
+ */
+export interface CloseCapsuleSignals {
+    /** Reason for closure (completion, timeout, error, etc.) */
+    reason?: string;
+    /** Optional summary content to generate on close */
+    summaryContent?: string;
+    /** Confidence score for summary (0.0-1.0) */
+    summaryConfidence?: number;
+    /** Evidence observation IDs that support the summary */
+    evidenceRefs?: ID[];
+}
+/**
+ * Capsule manager interface
+ *
+ * Manages capsule lifecycle: opening, closing, and lookup
+ */
+export interface CapsuleManager {
+    /**
+     * Open a new capsule
+     *
+     * @param options - Capsule creation options
+     * @returns The created capsule
+     * @throws Error if a capsule is already open for the same scope (session type)
+     */
+    open(options: OpenCapsuleOptions): Capsule;
+    /**
+     * Close an open capsule
+     *
+     * @param capsuleId - ID of capsule to close
+     * @param signals - Closure signals/metadata
+     * @returns The closed capsule
+     * @throws Error if capsule not found or already closed
+     */
+    close(capsuleId: ID, signals?: CloseCapsuleSignals): Capsule;
+    /**
+     * Get a capsule by ID
+     *
+     * @param capsuleId - Capsule ID to lookup
+     * @returns Capsule or undefined if not found
+     */
+    get(capsuleId: ID): Capsule | undefined;
+    /**
+     * Get the open capsule for a scope (if any)
+     *
+     * @param scopeIds - Partial scope to match
+     * @returns Open capsule or undefined
+     */
+    getOpen(scopeIds: Partial<ScopeIds>): Capsule | undefined;
+    /**
+     * Notify that an observation was attached to a capsule
+     *
+     * Updates any cached capsule state to include the new observation.
+     *
+     * @param capsuleId - Capsule that received the observation
+     * @param observationId - Observation that was attached
+     */
+    notifyObservationAttached(capsuleId: ID, observationId: ID): void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/capsule/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,WAAW,CAAC;IAElB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,gCAAgC;IAChC,EAAE,CAAC,EAAE,EAAE,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC;IAE3C;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC;IAE7D;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC;IAExC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,GAAG,SAAS,CAAC;IAE1D;;;;;;;OAOG;IACH,yBAAyB,CAAC,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC;CACnE"}

package/dist/capsule/types.js

@@ -0,0 +1,5 @@
+/**
+ * Capsule lifecycle types and interfaces
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/capsule/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capsule/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/export/bundle.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Service-level export coordination
+ *
+ * Provides high-level export API for backup and portability.
+ * Builds on store-level export primitives from STORAGE-005.
+ */
+import type { ScopeIds } from '../types/common.js';
+import type { Observation, Capsule, Summary, Pin } from '../types/index.js';
+/**
+ * Store interface for export operations
+ */
+export interface ExportStore {
+    /**
+     * Export database to a dataset
+     */
+    exportDatabase(options?: {
+        scope?: Partial<ScopeIds>;
+        includeRedacted?: boolean;
+        limit?: number;
+    }): {
+        version: string;
+        exportedAt: number;
+        scope?: Partial<ScopeIds>;
+        observations: Observation[];
+        capsules: Capsule[];
+        summaries: Summary[];
+        pins: Pin[];
+    };
+}
+/**
+ * Export options
+ */
+export interface ExportBundleOptions {
+    /** Optional scope filter */
+    scope?: Partial<ScopeIds>;
+    /** Include redacted observations (default: false) */
+    includeRedacted?: boolean;
+    /** Maximum observations to export */
+    limit?: number;
+    /** Bundle metadata */
+    metadata?: {
+        description?: string;
+        tags?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Export bundle with metadata
+ */
+export interface ExportBundle {
+    /** Bundle format version */
+    bundleVersion: string;
+    /** Export timestamp */
+    exportedAt: number;
+    /** Optional metadata */
+    metadata?: {
+        description?: string;
+        tags?: string[];
+        [key: string]: unknown;
+    };
+    /** Dataset with entities */
+    dataset: {
+        version: string;
+        exportedAt: number;
+        scope?: Partial<ScopeIds>;
+        observations: Observation[];
+        capsules: Capsule[];
+        summaries: Summary[];
+        pins: Pin[];
+    };
+}
+/**
+ * Export bundle statistics
+ */
+export interface ExportStats {
+    observations: number;
+    capsules: number;
+    summaries: number;
+    pins: number;
+    totalSize: number;
+}
+/**
+ * Create an export bundle
+ *
+ * Coordinates export from store with optional metadata and validation.
+ *
+ * @param store - Export store
+ * @param options - Export options
+ * @returns Export bundle with dataset and metadata
+ */
+export declare function createExportBundle(store: ExportStore, options?: ExportBundleOptions): ExportBundle;
+/**
+ * Get statistics for an export bundle
+ *
+ * @param bundle - Export bundle
+ * @returns Statistics about bundle contents
+ */
+export declare function getBundleStats(bundle: ExportBundle): ExportStats;
+/**
+ * Validate export bundle structure
+ *
+ * @param bundle - Bundle to validate
+ * @returns Validation result with errors if any
+ */
+export declare function validateBundle(bundle: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Serialize export bundle to JSON string
+ *
+ * @param bundle - Bundle to serialize
+ * @param pretty - Use pretty formatting (default: false)
+ * @returns JSON string
+ */
+export declare function serializeBundle(bundle: ExportBundle, pretty?: boolean): string;
+/**
+ * Deserialize export bundle from JSON string
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed bundle
+ * @throws Error if JSON is invalid
+ */
+export declare function deserializeBundle(json: string): ExportBundle;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/export/bundle.d.ts.map

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

package/dist/export/bundle.js

@@ -0,0 +1,136 @@
+/**
+ * Service-level export coordination
+ *
+ * Provides high-level export API for backup and portability.
+ * Builds on store-level export primitives from STORAGE-005.
+ */
+/**
+ * Create an export bundle
+ *
+ * Coordinates export from store with optional metadata and validation.
+ *
+ * @param store - Export store
+ * @param options - Export options
+ * @returns Export bundle with dataset and metadata
+ */
+export function createExportBundle(store, options = {}) {
+    const { scope, includeRedacted = false, limit, metadata } = options;
+    // Export dataset from store
+    const dataset = store.exportDatabase({
+        scope,
+        includeRedacted,
+        limit,
+    });
+    // Create bundle with metadata
+    const bundle = {
+        bundleVersion: '1.0',
+        exportedAt: Date.now(),
+        dataset,
+    };
+    if (metadata) {
+        bundle.metadata = metadata;
+    }
+    return bundle;
+}
+/**
+ * Get statistics for an export bundle
+ *
+ * @param bundle - Export bundle
+ * @returns Statistics about bundle contents
+ */
+export function getBundleStats(bundle) {
+    const { dataset } = bundle;
+    // Estimate size (JSON string length approximation)
+    const totalSize = JSON.stringify(bundle).length;
+    return {
+        observations: dataset.observations.length,
+        capsules: dataset.capsules.length,
+        summaries: dataset.summaries.length,
+        pins: dataset.pins.length,
+        totalSize,
+    };
+}
+/**
+ * Validate export bundle structure
+ *
+ * @param bundle - Bundle to validate
+ * @returns Validation result with errors if any
+ */
+export function validateBundle(bundle) {
+    const errors = [];
+    if (!bundle || typeof bundle !== 'object') {
+        return { valid: false, errors: ['Bundle must be an object'] };
+    }
+    const b = bundle;
+    // Check bundle version
+    if (!b.bundleVersion || typeof b.bundleVersion !== 'string') {
+        errors.push('Missing or invalid bundleVersion');
+    }
+    else if (b.bundleVersion !== '1.0') {
+        errors.push(`Unsupported bundle version: ${b.bundleVersion}`);
+    }
+    // Check exportedAt
+    if (!b.exportedAt || typeof b.exportedAt !== 'number') {
+        errors.push('Missing or invalid exportedAt');
+    }
+    // Check dataset
+    if (!b.dataset || typeof b.dataset !== 'object') {
+        errors.push('Missing or invalid dataset');
+    }
+    else {
+        const ds = b.dataset;
+        if (!ds.version || typeof ds.version !== 'string') {
+            errors.push('Missing or invalid dataset.version');
+        }
+        if (!Array.isArray(ds.observations)) {
+            errors.push('dataset.observations must be an array');
+        }
+        if (!Array.isArray(ds.capsules)) {
+            errors.push('dataset.capsules must be an array');
+        }
+        if (!Array.isArray(ds.summaries)) {
+            errors.push('dataset.summaries must be an array');
+        }
+        if (!Array.isArray(ds.pins)) {
+            errors.push('dataset.pins must be an array');
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Serialize export bundle to JSON string
+ *
+ * @param bundle - Bundle to serialize
+ * @param pretty - Use pretty formatting (default: false)
+ * @returns JSON string
+ */
+export function serializeBundle(bundle, pretty = false) {
+    return JSON.stringify(bundle, null, pretty ? 2 : 0);
+}
+/**
+ * Deserialize export bundle from JSON string
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed bundle
+ * @throws Error if JSON is invalid
+ */
+export function deserializeBundle(json) {
+    try {
+        const bundle = JSON.parse(json);
+        const validation = validateBundle(bundle);
+        if (!validation.valid) {
+            throw new Error(`Invalid bundle: ${validation.errors.join(', ')}`);
+        }
+        return bundle;
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`Invalid JSON: ${err.message}`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=bundle.js.map

package/dist/export/bundle.js.map

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

package/dist/export/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Export/import coordination
+ *
+ * Service-level APIs for backup, portability, and data migration.
+ */
+export * from './bundle.js';
+export * from './restore.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/export/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/export/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/export/index.js

@@ -0,0 +1,8 @@
+/**
+ * Export/import coordination
+ *
+ * Service-level APIs for backup, portability, and data migration.
+ */
+export * from './bundle.js';
+export * from './restore.js';
+//# sourceMappingURL=index.js.map

package/dist/export/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/export/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/export/restore.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Service-level import coordination
+ *
+ * Provides high-level import API for restoring from export bundles.
+ */
+import type { ExportBundle } from './bundle.js';
+import type { ScopeIds, Observation, Capsule, Summary, Pin } from '../types/index.js';
+/**
+ * Store interface for import operations
+ */
+export interface ImportStore {
+    /**
+     * Import dataset into database
+     */
+    importDatabase(dataset: {
+        version: string;
+        exportedAt: number;
+        scope?: Partial<ScopeIds>;
+        observations: Observation[];
+        capsules: Capsule[];
+        summaries: Summary[];
+        pins: Pin[];
+    }): {
+        observations: number;
+        capsules: number;
+        summaries: number;
+        pins: number;
+        errors: string[];
+    };
+}
+/**
+ * Import options
+ */
+export interface ImportOptions {
+    /** Skip validation (default: false) */
+    skipValidation?: boolean;
+    /** Dry run (validate only, don't import) */
+    dryRun?: boolean;
+}
+/**
+ * Import result
+ */
+export interface ImportResult {
+    /** Number of observations imported */
+    observations: number;
+    /** Number of capsules imported */
+    capsules: number;
+    /** Number of summaries imported */
+    summaries: number;
+    /** Number of pins imported */
+    pins: number;
+    /** Any errors encountered */
+    errors: string[];
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+/**
+ * Restore from export bundle
+ *
+ * Coordinates import with validation and error handling.
+ *
+ * @param store - Import store
+ * @param bundle - Export bundle to restore
+ * @param options - Import options
+ * @returns Import result with counts and errors
+ */
+export declare function restoreFromBundle(store: ImportStore, bundle: ExportBundle, options?: ImportOptions): ImportResult;
+/**
+ * Merge multiple export bundles
+ *
+ * Combines datasets from multiple bundles into a single bundle.
+ * Useful for consolidating exports from different sources.
+ *
+ * @param bundles - Bundles to merge
+ * @param metadata - Optional metadata for merged bundle
+ * @returns Merged bundle
+ */
+export declare function mergeBundles(bundles: ExportBundle[], metadata?: {
+    description?: string;
+    tags?: string[];
+}): ExportBundle;
+/**
+ * Compare two bundles for differences
+ *
+ * @param bundle1 - First bundle
+ * @param bundle2 - Second bundle
+ * @returns Difference summary
+ */
+export declare function compareBundles(bundle1: ExportBundle, bundle2: ExportBundle): {
+    observations: {
+        added: number;
+        removed: number;
+        common: number;
+    };
+    capsules: {
+        added: number;
+        removed: number;
+        common: number;
+    };
+    summaries: {
+        added: number;
+        removed: number;
+        common: number;
+    };
+    pins: {
+        added: number;
+        removed: number;
+        common: number;
+    };
+};
+//# sourceMappingURL=restore.d.ts.map

package/dist/export/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../src/export/restore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAEtF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1B,YAAY,EAAE,WAAW,EAAE,CAAC;QAC5B,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,SAAS,EAAE,OAAO,EAAE,CAAC;QACrB,IAAI,EAAE,GAAG,EAAE,CAAC;KACb,GAAG;QACF,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAqCd;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD,YAAY,CAgDd;AA0BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,GACpB;IACD,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D,CAqBA"}