@cleocode/core 2026.4.9 → 2026.4.11

package/dist/system/archive-analytics.js

@@ -0,0 +1,277 @@
+/**
+ * Archive analytics — rich reporting and insights from archived tasks.
+ *
+ * Moved from CLI archive-stats command to core for reuse across
+ * CLI and programmatic consumers.
+ *
+ * @task T4555
+ * @epic T4545
+ */
+import { getAccessor } from '../store/data-accessor.js';
+// ---------------------------------------------------------------------------
+// Internal: task extraction from archive data
+// ---------------------------------------------------------------------------
+/** Type guard for raw objects that have _archive nested metadata (legacy JSON format). */
+function hasNestedArchive(t) {
+    return '_archive' in t && typeof t._archive === 'object';
+}
+/**
+ * Extract archive metadata from a task record.
+ * Handles both:
+ * - Legacy JSON format: { _archive: { archivedAt, cycleTimeDays, archiveSource } }
+ * - SQLite format: { archivedAt, cycleTimeDays, archiveReason } (flat properties on Task)
+ */
+function extractArchiveMetadata(t) {
+    // Legacy JSON nested format
+    if (hasNestedArchive(t)) {
+        return t._archive;
+    }
+    // SQLite flat format — archive fields are tacked onto the Task object
+    const raw = t;
+    return {
+        archivedAt: raw.archivedAt,
+        cycleTimeDays: raw.cycleTimeDays,
+        archiveSource: raw.archiveReason,
+    };
+}
+/** Convert raw Task[] from the accessor into AnalyticsTask[]. */
+function toAnalyticsTasks(tasks) {
+    return tasks.map((t) => ({
+        id: t.id,
+        title: t.title,
+        status: t.status,
+        priority: t.priority,
+        phase: t.phase,
+        labels: t.labels,
+        archive: extractArchiveMetadata(t),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Analysis functions (pure, no I/O)
+// ---------------------------------------------------------------------------
+/** Filter tasks by date range on archivedAt. */
+export function filterByDate(tasks, since, until) {
+    let filtered = tasks;
+    if (since) {
+        const sinceDate = since.includes('T') ? since : `${since}T00:00:00Z`;
+        filtered = filtered.filter((t) => (t.archive.archivedAt ?? '') >= sinceDate);
+    }
+    if (until) {
+        const untilDate = until.includes('T') ? until : `${until}T23:59:59Z`;
+        filtered = filtered.filter((t) => (t.archive.archivedAt ?? '') <= untilDate);
+    }
+    return filtered;
+}
+/** Generate summary statistics. */
+export function summaryReport(tasks) {
+    const byStatus = {};
+    const byPriority = {};
+    const sourceBreakdown = {};
+    const cycleTimes = [];
+    for (const t of tasks) {
+        byStatus[t.status] = (byStatus[t.status] ?? 0) + 1;
+        const prio = t.priority ?? 'unset';
+        byPriority[prio] = (byPriority[prio] ?? 0) + 1;
+        const src = t.archive.archiveSource ?? 'unknown';
+        sourceBreakdown[src] = (sourceBreakdown[src] ?? 0) + 1;
+        if (t.archive.cycleTimeDays != null) {
+            cycleTimes.push(t.archive.cycleTimeDays);
+        }
+    }
+    const sorted = tasks
+        .filter((t) => t.archive.archivedAt)
+        .sort((a, b) => a.archive.archivedAt.localeCompare(b.archive.archivedAt));
+    return {
+        totalArchived: tasks.length,
+        byStatus,
+        byPriority,
+        averageCycleTime: cycleTimes.length > 0
+            ? Math.round((cycleTimes.reduce((a, b) => a + b, 0) / cycleTimes.length) * 100) / 100
+            : null,
+        oldestArchived: sorted[0]?.archive.archivedAt ?? null,
+        newestArchived: sorted[sorted.length - 1]?.archive.archivedAt ?? null,
+        archiveSourceBreakdown: sourceBreakdown,
+    };
+}
+/** Group tasks by phase with cycle time averages. */
+export function byPhaseReport(tasks) {
+    const groups = {};
+    for (const t of tasks) {
+        const phase = t.phase ?? 'unassigned';
+        if (!groups[phase])
+            groups[phase] = [];
+        groups[phase].push(t);
+    }
+    return Object.entries(groups)
+        .map(([phase, items]) => {
+        const cycles = items
+            .map((t) => t.archive.cycleTimeDays)
+            .filter((c) => c != null);
+        return {
+            phase,
+            count: items.length,
+            avgCycleTime: cycles.length > 0
+                ? Math.round((cycles.reduce((a, b) => a + b, 0) / cycles.length) * 100) / 100
+                : null,
+        };
+    })
+        .sort((a, b) => b.count - a.count);
+}
+/** Group tasks by label frequency. */
+export function byLabelReport(tasks) {
+    const counts = {};
+    for (const t of tasks) {
+        for (const label of t.labels ?? []) {
+            counts[label] = (counts[label] ?? 0) + 1;
+        }
+    }
+    return Object.entries(counts)
+        .map(([label, count]) => ({ label, count }))
+        .sort((a, b) => b.count - a.count);
+}
+/** Group tasks by priority with cycle time averages. */
+export function byPriorityReport(tasks) {
+    const PRIO_ORDER = ['critical', 'high', 'medium', 'low', 'unset'];
+    const groups = {};
+    for (const t of tasks) {
+        const prio = t.priority ?? 'unset';
+        if (!groups[prio])
+            groups[prio] = [];
+        groups[prio].push(t);
+    }
+    return Object.entries(groups)
+        .map(([priority, items]) => {
+        const cycles = items
+            .map((t) => t.archive.cycleTimeDays)
+            .filter((c) => c != null);
+        return {
+            priority,
+            count: items.length,
+            avgCycleTime: cycles.length > 0
+                ? Math.round((cycles.reduce((a, b) => a + b, 0) / cycles.length) * 100) / 100
+                : null,
+        };
+    })
+        .sort((a, b) => PRIO_ORDER.indexOf(a.priority) - PRIO_ORDER.indexOf(b.priority));
+}
+/** Compute cycle time statistics with distribution buckets. */
+export function cycleTimesReport(tasks) {
+    const times = tasks
+        .map((t) => t.archive.cycleTimeDays)
+        .filter((c) => c != null)
+        .sort((a, b) => a - b);
+    if (times.length === 0) {
+        return {
+            count: 0,
+            min: null,
+            max: null,
+            avg: null,
+            median: null,
+            distribution: { '0-1 days': 0, '2-7 days': 0, '8-30 days': 0, '30+ days': 0 },
+        };
+    }
+    const median = times.length % 2 === 0
+        ? (times[times.length / 2 - 1] + times[times.length / 2]) / 2
+        : times[Math.floor(times.length / 2)];
+    const percentile = (p) => times[Math.floor(times.length * p)] ?? null;
+    return {
+        count: times.length,
+        min: times[0],
+        max: times[times.length - 1],
+        avg: Math.round((times.reduce((a, b) => a + b, 0) / times.length) * 100) / 100,
+        median,
+        distribution: {
+            '0-1 days': times.filter((t) => t <= 1).length,
+            '2-7 days': times.filter((t) => t > 1 && t <= 7).length,
+            '8-30 days': times.filter((t) => t > 7 && t <= 30).length,
+            '30+ days': times.filter((t) => t > 30).length,
+        },
+        percentiles: {
+            p25: percentile(0.25),
+            p50: percentile(0.5),
+            p75: percentile(0.75),
+            p90: percentile(0.9),
+        },
+    };
+}
+/** Compute archive trends by day and month. */
+export function trendsReport(tasks) {
+    const withDate = tasks.filter((t) => t.archive.archivedAt);
+    const byDay = {};
+    for (const t of withDate) {
+        const date = t.archive.archivedAt.slice(0, 10);
+        byDay[date] = (byDay[date] ?? 0) + 1;
+    }
+    const dailyEntries = Object.entries(byDay)
+        .map(([date, count]) => ({ date, count }))
+        .sort((a, b) => a.date.localeCompare(b.date));
+    const byMonth = {};
+    for (const { date, count } of dailyEntries) {
+        const month = date.slice(0, 7);
+        byMonth[month] = (byMonth[month] ?? 0) + count;
+    }
+    const monthlyEntries = Object.entries(byMonth).map(([month, count]) => ({
+        month,
+        count,
+    }));
+    const totalPeriod = dailyEntries.reduce((sum, d) => sum + d.count, 0);
+    return {
+        byDay: dailyEntries,
+        byMonth: monthlyEntries,
+        totalPeriod,
+        averagePerDay: dailyEntries.length > 0 ? Math.round((totalPeriod / dailyEntries.length) * 100) / 100 : 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API — orchestrates data loading + report generation
+// ---------------------------------------------------------------------------
+/**
+ * Analyze archived tasks and produce a report.
+ *
+ * This is the primary entry point for archive analytics. It loads archive
+ * data from the DataAccessor, normalizes task records, applies date filters,
+ * and delegates to the appropriate report function.
+ */
+export async function analyzeArchive(opts, accessor) {
+    const acc = accessor ?? (await getAccessor(opts.cwd));
+    const data = await acc.loadArchive();
+    const reportType = opts.report ?? 'summary';
+    if (!data || !data.archivedTasks?.length) {
+        return {
+            report: reportType,
+            filters: null,
+            data: { totalArchived: 0, message: 'No archived tasks found' },
+        };
+    }
+    const tasks = toAnalyticsTasks(data.archivedTasks);
+    const filtered = filterByDate(tasks, opts.since, opts.until);
+    let reportData;
+    switch (reportType) {
+        case 'summary':
+            reportData = summaryReport(filtered);
+            break;
+        case 'by-phase':
+            reportData = byPhaseReport(filtered);
+            break;
+        case 'by-label':
+            reportData = byLabelReport(filtered);
+            break;
+        case 'by-priority':
+            reportData = byPriorityReport(filtered);
+            break;
+        case 'cycle-times':
+            reportData = cycleTimesReport(filtered);
+            break;
+        case 'trends':
+            reportData = trendsReport(filtered);
+            break;
+        default:
+            reportData = summaryReport(filtered);
+    }
+    return {
+        report: reportType,
+        filters: opts.since || opts.until ? { since: opts.since ?? null, until: opts.until ?? null } : null,
+        data: reportData,
+    };
+}
+//# sourceMappingURL=archive-analytics.js.map

package/dist/system/archive-analytics.js.map

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

package/dist/system/archive-stats.js

@@ -0,0 +1,64 @@
+/**
+ * Archive statistics core module.
+ * @task T4783
+ */
+import { getAccessor } from '../store/data-accessor.js';
+/** Get archive statistics. */
+export async function getArchiveStats(opts, accessor) {
+    const periodDays = opts.period ?? 30;
+    const cutoff = new Date(Date.now() - periodDays * 86400000).toISOString();
+    const acc = accessor ?? (await getAccessor(opts.cwd));
+    const archive = await acc.loadArchive();
+    if (!archive?.archivedTasks) {
+        return {
+            totalArchived: 0,
+            byReason: {},
+            averageCycleTimeDays: null,
+            archiveRate: { periodDays, archivedInPeriod: 0 },
+            lastArchived: null,
+        };
+    }
+    // ArchivedTask extends Task with _archive metadata; safe narrowing from Task[]
+    const archived = archive.archivedTasks;
+    // By reason
+    const byReason = {};
+    for (const t of archived) {
+        const reason = t._archive?.archiveReason || 'unknown';
+        byReason[reason] = (byReason[reason] ?? 0) + 1;
+    }
+    // Average cycle time
+    let totalCycleDays = 0;
+    let samples = 0;
+    for (const t of archived) {
+        if (t.createdAt && t.completedAt) {
+            const created = new Date(t.createdAt).getTime();
+            const completed = new Date(t.completedAt).getTime();
+            if (completed > created) {
+                totalCycleDays += (completed - created) / 86400000;
+                samples++;
+            }
+        }
+    }
+    const averageCycleTimeDays = samples > 0 ? Math.round((totalCycleDays / samples) * 100) / 100 : null;
+    // Archive rate
+    const archivedInPeriod = archived.filter((t) => {
+        const archivedAt = t._archive?.archivedAt;
+        return archivedAt && archivedAt >= cutoff;
+    }).length;
+    // Find the most recent archived-at timestamp
+    let lastArchived = null;
+    for (const t of archived) {
+        const at = t._archive?.archivedAt;
+        if (at && (!lastArchived || at > lastArchived)) {
+            lastArchived = at;
+        }
+    }
+    return {
+        totalArchived: archived.length,
+        byReason,
+        averageCycleTimeDays,
+        archiveRate: { periodDays, archivedInPeriod },
+        lastArchived,
+    };
+}
+//# sourceMappingURL=archive-stats.js.map

package/dist/system/archive-stats.js.map

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

package/dist/system/audit.js

@@ -0,0 +1,145 @@
+/**
+ * Data integrity audit core module.
+ * @task T4783
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getAccessor } from '../store/data-accessor.js';
+/** Audit data integrity. */
+export async function auditData(projectRoot, opts) {
+    const cleoDir = join(projectRoot, '.cleo');
+    const scope = opts?.scope ?? 'all';
+    const issues = [];
+    if (scope === 'all' || scope === 'tasks') {
+        const tasksDbPath = join(cleoDir, 'tasks.db');
+        if (existsSync(tasksDbPath)) {
+            try {
+                const accessor = await getAccessor(projectRoot);
+                const queryResult = await accessor.queryTasks({});
+                const tasks = queryResult.tasks ?? [];
+                const idSet = new Set();
+                for (const t of tasks) {
+                    if (idSet.has(t.id)) {
+                        issues.push({
+                            severity: 'error',
+                            category: 'tasks',
+                            message: `Duplicate task ID: ${t.id}`,
+                        });
+                    }
+                    idSet.add(t.id);
+                }
+                for (const t of tasks) {
+                    if (t.parentId && !idSet.has(t.parentId)) {
+                        issues.push({
+                            severity: 'warning',
+                            category: 'tasks',
+                            message: `Task ${t.id} references non-existent parent: ${t.parentId}`,
+                        });
+                    }
+                }
+                for (const t of tasks) {
+                    if (!t.title)
+                        issues.push({
+                            severity: 'error',
+                            category: 'tasks',
+                            message: `Task ${t.id} missing title`,
+                        });
+                    if (!t.status)
+                        issues.push({
+                            severity: 'error',
+                            category: 'tasks',
+                            message: `Task ${t.id} missing status`,
+                        });
+                }
+                for (const t of tasks) {
+                    if (t.depends) {
+                        for (const dep of t.depends) {
+                            if (!idSet.has(dep)) {
+                                issues.push({
+                                    severity: 'warning',
+                                    category: 'tasks',
+                                    message: `Task ${t.id} depends on non-existent: ${dep}`,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                issues.push({
+                    severity: 'error',
+                    category: 'tasks',
+                    message: `Failed to read tasks.db: ${err}`,
+                });
+            }
+        }
+    }
+    if (scope === 'all' || scope === 'sessions') {
+        const sessPath = join(cleoDir, 'sessions.json');
+        if (existsSync(sessPath)) {
+            try {
+                const data = JSON.parse(readFileSync(sessPath, 'utf-8'));
+                const sessions = data.sessions ?? [];
+                const sessionIds = new Set();
+                for (const s of sessions) {
+                    if (sessionIds.has(s.id)) {
+                        issues.push({
+                            severity: 'error',
+                            category: 'sessions',
+                            message: `Duplicate session ID: ${s.id}`,
+                        });
+                    }
+                    sessionIds.add(s.id);
+                }
+                for (const s of sessions) {
+                    if (!s.scope?.rootTaskId) {
+                        issues.push({
+                            severity: 'warning',
+                            category: 'sessions',
+                            message: `Session ${s.id} missing scope rootTaskId`,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                issues.push({
+                    severity: 'error',
+                    category: 'sessions',
+                    message: `Failed to parse sessions.json: ${err}`,
+                });
+            }
+        }
+    }
+    if (scope === 'all') {
+        const seqPath = join(cleoDir, '.sequence.json');
+        if (existsSync(seqPath)) {
+            try {
+                const seq = JSON.parse(readFileSync(seqPath, 'utf-8'));
+                if (typeof seq.counter !== 'number') {
+                    issues.push({
+                        severity: 'error',
+                        category: 'sequence',
+                        message: 'Sequence counter is not a number',
+                    });
+                }
+            }
+            catch {
+                issues.push({
+                    severity: 'error',
+                    category: 'sequence',
+                    message: 'Failed to parse .sequence.json',
+                });
+            }
+        }
+    }
+    return {
+        scope,
+        issues,
+        summary: {
+            errors: issues.filter((i) => i.severity === 'error').length,
+            warnings: issues.filter((i) => i.severity === 'warning').length,
+            fixed: 0,
+        },
+    };
+}
+//# sourceMappingURL=audit.js.map

package/dist/system/audit.js.map

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

package/dist/system/backup.d.ts

@@ -1,31 +1,108 @@
 /**
  * Backup and restore core module.
+ *
+ * Produces full-`.cleo/` snapshots containing tasks.db, brain.db, config.json
+ * and project-info.json using the safest available method for each file type:
+ *
+ *   - SQLite databases: `VACUUM INTO` via the live native handle (see
+ *     {@link ../store/sqlite-backup.ts}). This is the ONLY safe way to
+ *     snapshot a WAL-mode SQLite database while it is open — raw filesystem
+ *     copies can capture torn writes or stale WAL frames.
+ *
+ *   - JSON files: atomic tmp-then-rename via {@link atomicWrite} so a partial
+ *     write can never corrupt the backup target.
+ *
+ * Snapshots are recorded under `.cleo/backups/{type}/` with a JSON sidecar
+ * (`{backupId}.meta.json`) enumerating which files were captured and how.
+ * Restores read the same sidecars and materialize each file back into the
+ * live `.cleo/` directory.
+ *
+ * This is the backing store for the `cleo backup` and `cleo restore backup`
+ * CLI verbs (see packages/cleo/src/cli/commands/backup.ts and restore.ts).
+ *
  * @task T4783
+ * @task T5158 — extended to use VACUUM INTO for .db files and atomicWrite for JSON
+ * @task T306  — extended to support global-tier scope (nexus.db; epic T299)
  */
+/** Result shape returned by {@link createBackup}. */
 export interface BackupResult {
+    /** Unique backup identifier (timestamped). */
     backupId: string;
+    /** Absolute path to the directory containing the snapshot files. */
     path: string;
+    /** ISO-8601 timestamp when the backup was created. */
     timestamp: string;
+    /** Backup category (`snapshot`, `safety`, `migration`). */
     type: string;
+    /** Files that were successfully captured into this backup. */
     files: string[];
+    /**
+     * Global-tier snapshot results, populated when `opts.includeGlobal` is true.
+     * Key is the DB name (e.g. `'nexus'`), value is the snapshot path or an
+     * empty string when the DB was not initialized.
+     *
+     * @task T306
+     * @epic T299
+     */
+    global?: Record<string, string>;
 }
+/** Result shape returned by {@link restoreBackup}. */
 export interface RestoreResult {
+    /** Whether any files were actually restored (false if none matched). */
     restored: boolean;
+    /** The backup identifier that was restored. */
     backupId: string;
+    /** ISO-8601 timestamp of the original backup. */
     timestamp: string;
+    /** File names that were successfully restored back into `.cleo/`. */
     filesRestored: string[];
 }
-/** Create a backup of CLEO data files. */
+/**
+ * Create a backup of the canonical CLEO data files.
+ *
+ * Produces safe copies via VACUUM INTO (for SQLite) and atomicWrite
+ * (for JSON) into `.cleo/backups/{type}/`. Writes a `{backupId}.meta.json`
+ * sidecar describing the snapshot.
+ *
+ * Opens both `tasks.db` and `brain.db` through their canonical drizzle
+ * accessors before snapshotting so that the native DB handles are live
+ * when `safeSqliteSnapshot` asks for them. This makes the function
+ * self-contained — callers do not need to pre-open the DBs.
+ *
+ * When `opts.includeGlobal` is true, also snapshots global-tier databases
+ * (currently `nexus.db`) via {@link vacuumIntoGlobalBackup}. Global snapshots
+ * are written to `$XDG_DATA_HOME/cleo/backups/sqlite/` and returned in
+ * `result.global`.
+ *
+ * Async because opening the database engines requires async migration
+ * reconciliation (ADR-012). The CLI dispatch layer awaits this result.
+ *
+ * @task T306
+ * @epic T299
+ */
 export declare function createBackup(projectRoot: string, opts?: {
     type?: string;
     note?: string;
-}): BackupResult;
+    /**
+     * When true, also snapshot global-tier databases (nexus.db).
+     * Defaults to false for backwards compatibility.
+     *
+     * @task T306
+     * @epic T299
+     */
+    includeGlobal?: boolean;
+}): Promise<BackupResult>;
 /** A single backup entry returned by listSystemBackups. */
 export interface BackupEntry {
+    /** Unique backup identifier (timestamped). */
     backupId: string;
+    /** Backup category (`snapshot`, `safety`, `migration`). */
     type: string;
+    /** ISO-8601 timestamp when the backup was created. */
     timestamp: string;
+    /** Optional human-readable note attached at creation time. */
     note?: string;
+    /** File names captured in this backup. */
     files: string[];
 }
 /**
@@ -35,7 +112,18 @@ export interface BackupEntry {
  * @task T4783
  */
 export declare function listSystemBackups(projectRoot: string): BackupEntry[];
-/** Restore from a backup. */
+/**
+ * Restore a backup into the live `.cleo/` directory.
+ *
+ * This operation overwrites the in-place copies of the files recorded in
+ * the backup's sidecar. SQLite files are restored via a plain `copyFileSync`
+ * because restore runs BEFORE the next CLEO process opens the database — no
+ * WAL is active at that point — so a filesystem copy is safe. Callers must
+ * ensure no CLEO process is concurrently writing to the target database.
+ *
+ * JSON files are restored via `atomicWrite` (tmp-then-rename) so a crash
+ * mid-restore cannot produce a truncated config.
+ */
 export declare function restoreBackup(projectRoot: string, params: {
     backupId: string;
     force?: boolean;

package/dist/system/backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/system/backup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,YAAY,CAmDd;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAkCpE;AAED,6BAA6B;AAC7B,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C,aAAa,CAkDf"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/system/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAoDH,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GACA,OAAO,CAAC,YAAY,CAAC,CA8HvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAkCpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C,aAAa,CA2Df"}