@defai.digital/cross-cutting 13.0.3

package/dist/idempotency-manager.js

@@ -0,0 +1,220 @@
+/**
+ * Idempotency Manager Implementation
+ *
+ * Prevents duplicate request processing using idempotency keys.
+ * Ensures operations are safely retryable without side effects.
+ *
+ * Invariants:
+ * - INV-ID-001: Same idempotency key returns cached response
+ * - INV-ID-002: Different request with same key is rejected (conflict)
+ * - INV-ID-003: Cache entries expire after TTL
+ */
+import { createDefaultIdempotencyConfig, calculateExpiration, isEntryExpired, IdempotencyErrorCodes, } from '@defai.digital/contracts';
+/**
+ * Creates an in-memory idempotency storage
+ */
+export function createInMemoryIdempotencyStorage() {
+    const entries = new Map();
+    return {
+        async get(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return null;
+            // Check if expired
+            if (isEntryExpired(entry)) {
+                entries.delete(key);
+                return null;
+            }
+            return entry;
+        },
+        async set(entry) {
+            entries.set(entry.key, entry);
+        },
+        async delete(key) {
+            return entries.delete(key);
+        },
+        async deleteExpired() {
+            let deleted = 0;
+            for (const [key, entry] of entries) {
+                if (isEntryExpired(entry)) {
+                    entries.delete(key);
+                    deleted++;
+                }
+            }
+            return deleted;
+        },
+    };
+}
+/**
+ * Creates an idempotency manager
+ */
+export function createIdempotencyManager(storage, config = {}) {
+    const cfg = { ...createDefaultIdempotencyConfig(), ...config };
+    return {
+        getConfig() {
+            return { ...cfg };
+        },
+        async check(key, requestHash) {
+            if (!cfg.enabled) {
+                return { status: 'new' };
+            }
+            const entry = await storage.get(key);
+            if (!entry) {
+                return { status: 'new' };
+            }
+            // INV-ID-001: Same key returns cached response
+            if (entry.status === 'completed') {
+                // INV-ID-002: Different request with same key is rejected
+                if (entry.requestHash !== requestHash) {
+                    return {
+                        status: 'conflict',
+                        error: 'Request hash mismatch for idempotency key',
+                    };
+                }
+                return {
+                    status: 'cached',
+                    response: entry.response,
+                    cachedAt: entry.createdAt,
+                };
+            }
+            // Request is being processed
+            if (entry.status === 'processing') {
+                const lockExpiry = new Date(entry.createdAt).getTime() + cfg.lockTimeoutMs;
+                const now = Date.now();
+                if (now < lockExpiry) {
+                    return {
+                        status: 'processing',
+                        lockExpiresInMs: lockExpiry - now,
+                    };
+                }
+                // Lock expired, allow new processing
+                return { status: 'new' };
+            }
+            // Failed - allow retry with same hash
+            if (entry.status === 'failed') {
+                if (entry.requestHash !== requestHash) {
+                    return {
+                        status: 'conflict',
+                        error: 'Request hash mismatch for idempotency key',
+                    };
+                }
+                return { status: 'new' };
+            }
+            return { status: 'new' };
+        },
+        async startProcessing(key, requestHash) {
+            if (!cfg.enabled) {
+                return true;
+            }
+            const existing = await storage.get(key);
+            // Check if already processing (and not expired)
+            if (existing?.status === 'processing') {
+                const lockExpiry = new Date(existing.createdAt).getTime() + cfg.lockTimeoutMs;
+                if (Date.now() < lockExpiry) {
+                    return false; // Still locked
+                }
+            }
+            // Check if already completed
+            if (existing?.status === 'completed') {
+                return false;
+            }
+            // INV-ID-003: Set expiration
+            const expiresAt = calculateExpiration(cfg.ttlSeconds);
+            const entry = {
+                key,
+                requestHash,
+                response: null,
+                createdAt: new Date().toISOString(),
+                expiresAt,
+                status: 'processing',
+            };
+            await storage.set(entry);
+            return true;
+        },
+        async completeProcessing(key, response) {
+            const existing = await storage.get(key);
+            if (!existing) {
+                // Entry was deleted or expired during processing.
+                // Don't create a new entry with empty requestHash as this would
+                // violate INV-ID-002 (hash mismatch detection). Future requests
+                // with this key will simply reprocess, which is safe.
+                return;
+            }
+            const entry = {
+                ...existing,
+                response,
+                status: 'completed',
+                updatedAt: new Date().toISOString(),
+            };
+            await storage.set(entry);
+        },
+        async failProcessing(key, error) {
+            const existing = await storage.get(key);
+            if (!existing) {
+                return; // Allow silent failure
+            }
+            const entry = {
+                ...existing,
+                status: 'failed',
+                error,
+                updatedAt: new Date().toISOString(),
+            };
+            await storage.set(entry);
+        },
+        async getEntry(key) {
+            return storage.get(key);
+        },
+        async cleanup() {
+            return storage.deleteExpired();
+        },
+    };
+}
+/**
+ * Wrapper for idempotent operations
+ */
+export async function withIdempotency(manager, key, requestHash, operation) {
+    // Check for duplicate
+    const check = await manager.check(key, requestHash);
+    if (check.status === 'cached' && check.response !== undefined) {
+        return check.response;
+    }
+    if (check.status === 'processing') {
+        throw new IdempotencyError(IdempotencyErrorCodes.LOCK_TIMEOUT, 'Operation already in progress');
+    }
+    if (check.status === 'conflict') {
+        throw new IdempotencyError(IdempotencyErrorCodes.KEY_CONFLICT, check.error ?? 'Request hash mismatch');
+    }
+    // Start processing
+    const started = await manager.startProcessing(key, requestHash);
+    if (!started) {
+        throw new IdempotencyError(IdempotencyErrorCodes.KEY_CONFLICT, 'Could not acquire lock for idempotent operation');
+    }
+    try {
+        const result = await operation();
+        await manager.completeProcessing(key, result);
+        return result;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        await manager.failProcessing(key, errorMessage);
+        throw error;
+    }
+}
+/**
+ * Idempotency error
+ */
+export class IdempotencyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? `Idempotency error: ${code}`);
+        this.code = code;
+        this.name = 'IdempotencyError';
+    }
+    static keyConflict(key) {
+        return new IdempotencyError(IdempotencyErrorCodes.KEY_CONFLICT, `Idempotency key conflict: ${key}`);
+    }
+    static lockTimeout(key) {
+        return new IdempotencyError(IdempotencyErrorCodes.LOCK_TIMEOUT, `Lock timeout for idempotency key: ${key}`);
+    }
+}
+//# sourceMappingURL=idempotency-manager.js.map

package/dist/idempotency-manager.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @defai.digital/cross-cutting
+ *
+ * Cross-Cutting Concerns Domain
+ *
+ * Provides Dead Letter Queue, Saga pattern, and Idempotency
+ * for robust, fault-tolerant system operations.
+ */
+export { createDeadLetterQueue, createInMemoryDeadLetterStorage, DeadLetterQueueError, processRetry, type DeadLetterQueue, type DeadLetterStorage, } from './dead-letter-queue.js';
+export { createSagaManager, defineSaga, SagaError, type SagaManager, type SagaStepExecutor, type CompensationExecutor, } from './saga-manager.js';
+export { createIdempotencyManager, createInMemoryIdempotencyStorage, withIdempotency, IdempotencyError, type IdempotencyManager, type IdempotencyStorage, } from './idempotency-manager.js';
+export { createRetentionManager, createInMemoryRetentionStore, createInMemoryArchiver, RetentionError, type RetentionManager, type RetentionStore, type RetentionEntry, type DataArchiver, } from './retention-manager.js';
+export type { IdempotencyCheckResult, DLQStats, SagaResult, RetentionPolicy, RetentionRunResult, RetentionSummary, } from '@defai.digital/contracts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,oBAAoB,EACpB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,eAAe,EACf,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,sBAAsB,EACtB,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @defai.digital/cross-cutting
+ *
+ * Cross-Cutting Concerns Domain
+ *
+ * Provides Dead Letter Queue, Saga pattern, and Idempotency
+ * for robust, fault-tolerant system operations.
+ */
+// Dead Letter Queue
+export { createDeadLetterQueue, createInMemoryDeadLetterStorage, DeadLetterQueueError, processRetry, } from './dead-letter-queue.js';
+// Saga Manager
+export { createSagaManager, defineSaga, SagaError, } from './saga-manager.js';
+// Idempotency Manager
+export { createIdempotencyManager, createInMemoryIdempotencyStorage, withIdempotency, IdempotencyError, } from './idempotency-manager.js';
+// Retention Manager
+export { createRetentionManager, createInMemoryRetentionStore, createInMemoryArchiver, RetentionError, } from './retention-manager.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oBAAoB;AACpB,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,oBAAoB,EACpB,YAAY,GAGb,MAAM,wBAAwB,CAAC;AAEhC,eAAe;AACf,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,GAIV,MAAM,mBAAmB,CAAC;AAE3B,sBAAsB;AACtB,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,eAAe,EACf,gBAAgB,GAGjB,MAAM,0BAA0B,CAAC;AAElC,oBAAoB;AACpB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,sBAAsB,EACtB,cAAc,GAKf,MAAM,wBAAwB,CAAC"}

package/dist/retention-manager.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Retention Manager Implementation
+ *
+ * Manages data retention policies for automatic cleanup of old data.
+ * Supports archiving before deletion and conditional retention.
+ *
+ * Invariants:
+ * - INV-RT-001: Retention policies applied per data type
+ * - INV-RT-002: Archive before delete when configured
+ * - INV-RT-003: Conditions respected during cleanup
+ */
+import { type RetentionPolicy, type RetentionRunResult, type RetentionSummary, type RetentionDataType, type RetentionConditions, type ArchiveEntry } from '@defai.digital/contracts';
+/**
+ * Retention store interface for data access
+ */
+export interface RetentionStore {
+    /** Find entries older than cutoff date */
+    findExpired(cutoffDate: string, conditions?: RetentionConditions): Promise<RetentionEntry[]>;
+    /** Delete entry by ID */
+    delete(id: string): Promise<void>;
+    /** Get entry size in bytes */
+    getSize(id: string): Promise<number>;
+}
+/**
+ * Entry returned by retention store
+ */
+export interface RetentionEntry {
+    id: string;
+    createdAt: string;
+    status?: string;
+    tags?: string[];
+    lastAccessedAt?: string;
+    [key: string]: unknown;
+}
+/**
+ * Data archiver interface
+ */
+export interface DataArchiver {
+    /** Archive an entry */
+    archive(dataType: RetentionDataType, entry: RetentionEntry, format: 'json' | 'csv' | 'parquet', path?: string): Promise<ArchiveEntry>;
+}
+/**
+ * Retention manager interface
+ */
+export interface RetentionManager {
+    /** Get all policies */
+    getPolicies(): RetentionPolicy[];
+    /** Get policy by ID */
+    getPolicy(policyId: string): RetentionPolicy | null;
+    /** Add policy */
+    addPolicy(policy: RetentionPolicy): void;
+    /** Remove policy */
+    removePolicy(policyId: string): boolean;
+    /** Update policy */
+    updatePolicy(policyId: string, updates: Partial<RetentionPolicy>): boolean;
+    /** Run a specific policy */
+    runPolicy(policyId: string): Promise<RetentionRunResult>;
+    /** Run all enabled policies */
+    runAllPolicies(): Promise<RetentionRunResult[]>;
+    /** Get summary of all retention operations */
+    getSummary(): RetentionSummary;
+    /** Register store for a data type */
+    registerStore(dataType: RetentionDataType, store: RetentionStore): void;
+}
+/**
+ * Creates a retention manager
+ */
+export declare function createRetentionManager(archiver?: DataArchiver): RetentionManager;
+/**
+ * Creates an in-memory retention store (for testing)
+ */
+export declare function createInMemoryRetentionStore(entries: Map<string, RetentionEntry>): RetentionStore;
+/**
+ * Creates an in-memory archiver (for testing)
+ */
+export declare function createInMemoryArchiver(): DataArchiver & {
+    getArchives(): ArchiveEntry[];
+};
+/**
+ * Retention error
+ */
+export declare class RetentionError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+    static policyNotFound(policyId: string): RetentionError;
+    static archiveFailed(entryId: string, error: string): RetentionError;
+    static deleteFailed(entryId: string, error: string): RetentionError;
+}
+//# sourceMappingURL=retention-manager.d.ts.map

package/dist/retention-manager.d.ts.map

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

package/dist/retention-manager.js

@@ -0,0 +1,308 @@
+/**
+ * Retention Manager Implementation
+ *
+ * Manages data retention policies for automatic cleanup of old data.
+ * Supports archiving before deletion and conditional retention.
+ *
+ * Invariants:
+ * - INV-RT-001: Retention policies applied per data type
+ * - INV-RT-002: Archive before delete when configured
+ * - INV-RT-003: Conditions respected during cleanup
+ */
+import { calculateRetentionCutoff, RetentionErrorCodes, } from '@defai.digital/contracts';
+/**
+ * Creates a retention manager
+ */
+export function createRetentionManager(archiver) {
+    const policies = new Map();
+    const stores = new Map();
+    const lastRuns = new Map();
+    let totalStorageReclaimed = 0;
+    let totalEntriesDeleted = 0;
+    /**
+     * Check if entry matches conditions (INV-RT-003)
+     */
+    function matchesConditions(entry, conditions) {
+        if (!conditions)
+            return true;
+        // Check status condition
+        if (conditions.status && conditions.status.length > 0) {
+            if (!entry.status || !conditions.status.includes(entry.status)) {
+                return false;
+            }
+        }
+        // Check exclude tags
+        if (conditions.excludeTags && conditions.excludeTags.length > 0) {
+            if (entry.tags?.some((tag) => conditions.excludeTags?.includes(tag))) {
+                return false;
+            }
+        }
+        // Check include tags
+        if (conditions.includeTags && conditions.includeTags.length > 0) {
+            if (!entry.tags?.some((tag) => conditions.includeTags?.includes(tag))) {
+                return false;
+            }
+        }
+        // Check minimum age
+        if (conditions.minAgeHours !== undefined && conditions.minAgeHours > 0) {
+            const entryAge = Date.now() - new Date(entry.createdAt).getTime();
+            const minAgeMs = conditions.minAgeHours * 60 * 60 * 1000;
+            if (entryAge < minAgeMs) {
+                return false;
+            }
+        }
+        // Check last accessed time
+        if (conditions.keepIfAccessedWithinHours !== undefined &&
+            conditions.keepIfAccessedWithinHours > 0 &&
+            entry.lastAccessedAt) {
+            const lastAccess = new Date(entry.lastAccessedAt).getTime();
+            const keepThreshold = Date.now() - conditions.keepIfAccessedWithinHours * 60 * 60 * 1000;
+            if (lastAccess > keepThreshold) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return {
+        getPolicies() {
+            return Array.from(policies.values());
+        },
+        getPolicy(policyId) {
+            return policies.get(policyId) ?? null;
+        },
+        addPolicy(policy) {
+            // Validate archive path if archiving enabled (INV-RT-002)
+            if (policy.archiveBeforeDelete && !policy.archivePath) {
+                throw new RetentionError(RetentionErrorCodes.ARCHIVE_PATH_REQUIRED, 'archivePath required when archiveBeforeDelete is true');
+            }
+            policies.set(policy.policyId, policy);
+        },
+        removePolicy(policyId) {
+            return policies.delete(policyId);
+        },
+        updatePolicy(policyId, updates) {
+            const existing = policies.get(policyId);
+            if (!existing)
+                return false;
+            const updated = { ...existing, ...updates };
+            // Validate archive path if archiving enabled
+            if (updated.archiveBeforeDelete && !updated.archivePath) {
+                throw new RetentionError(RetentionErrorCodes.ARCHIVE_PATH_REQUIRED, 'archivePath required when archiveBeforeDelete is true');
+            }
+            policies.set(policyId, updated);
+            return true;
+        },
+        // INV-RT-001: Retention policies applied per data type
+        async runPolicy(policyId) {
+            const policy = policies.get(policyId);
+            if (!policy) {
+                throw new RetentionError(RetentionErrorCodes.POLICY_NOT_FOUND, `Policy not found: ${policyId}`);
+            }
+            const store = stores.get(policy.dataType);
+            if (!store) {
+                throw new RetentionError(RetentionErrorCodes.DELETE_FAILED, `No store registered for data type: ${policy.dataType}`);
+            }
+            const runId = crypto.randomUUID();
+            const startedAt = new Date().toISOString();
+            const errors = [];
+            let entriesProcessed = 0;
+            let entriesDeleted = 0;
+            let entriesArchived = 0;
+            let entriesSkipped = 0;
+            let storageReclaimedBytes = 0;
+            try {
+                // Calculate cutoff date
+                const cutoffDate = calculateRetentionCutoff(policy.retentionDays);
+                // Find expired entries
+                const entries = await store.findExpired(cutoffDate.toISOString(), policy.conditions);
+                entriesProcessed = entries.length;
+                for (const entry of entries) {
+                    try {
+                        // Check conditions (INV-RT-003)
+                        if (!matchesConditions(entry, policy.conditions)) {
+                            entriesSkipped++;
+                            continue;
+                        }
+                        // Get entry size for metrics
+                        let entrySize = 0;
+                        try {
+                            entrySize = await store.getSize(entry.id);
+                        }
+                        catch {
+                            // Size tracking is optional
+                        }
+                        // Archive before delete if configured (INV-RT-002)
+                        if (policy.archiveBeforeDelete && archiver) {
+                            try {
+                                await archiver.archive(policy.dataType, entry, policy.archiveFormat, policy.archivePath);
+                                entriesArchived++;
+                            }
+                            catch (archiveError) {
+                                const msg = archiveError instanceof Error
+                                    ? archiveError.message
+                                    : 'Unknown archive error';
+                                errors.push(`Archive failed for ${entry.id}: ${msg}`);
+                                // Skip deletion if archive fails
+                                continue;
+                            }
+                        }
+                        // Delete entry
+                        await store.delete(entry.id);
+                        entriesDeleted++;
+                        storageReclaimedBytes += entrySize;
+                    }
+                    catch (entryError) {
+                        const msg = entryError instanceof Error
+                            ? entryError.message
+                            : 'Unknown error';
+                        errors.push(`Failed to process ${entry.id}: ${msg}`);
+                    }
+                }
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : 'Unknown error';
+                errors.push(`Policy execution failed: ${msg}`);
+            }
+            const result = {
+                runId,
+                policyId,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                entriesProcessed,
+                entriesDeleted,
+                entriesArchived,
+                entriesSkipped,
+                errors,
+                success: errors.length === 0,
+                storageReclaimedBytes,
+            };
+            // Update tracking
+            lastRuns.set(policyId, result);
+            totalStorageReclaimed += storageReclaimedBytes;
+            totalEntriesDeleted += entriesDeleted;
+            return result;
+        },
+        async runAllPolicies() {
+            const results = [];
+            // Get enabled policies sorted by priority (higher first)
+            const enabledPolicies = Array.from(policies.values())
+                .filter((p) => p.enabled)
+                .sort((a, b) => b.priority - a.priority);
+            for (const policy of enabledPolicies) {
+                try {
+                    const result = await this.runPolicy(policy.policyId);
+                    results.push(result);
+                }
+                catch (error) {
+                    // Create error result for failed policy
+                    const result = {
+                        runId: crypto.randomUUID(),
+                        policyId: policy.policyId,
+                        startedAt: new Date().toISOString(),
+                        completedAt: new Date().toISOString(),
+                        entriesProcessed: 0,
+                        entriesDeleted: 0,
+                        entriesArchived: 0,
+                        entriesSkipped: 0,
+                        errors: [
+                            error instanceof Error ? error.message : 'Unknown error',
+                        ],
+                        success: false,
+                    };
+                    results.push(result);
+                    lastRuns.set(policy.policyId, result);
+                }
+            }
+            return results;
+        },
+        getSummary() {
+            const allPolicies = Array.from(policies.values());
+            const enabledCount = allPolicies.filter((p) => p.enabled).length;
+            const lastRunsRecord = {};
+            for (const [policyId, result] of lastRuns) {
+                lastRunsRecord[policyId] = result;
+            }
+            return {
+                totalPolicies: allPolicies.length,
+                enabledPolicies: enabledCount,
+                lastRuns: lastRunsRecord,
+                totalStorageReclaimedBytes: totalStorageReclaimed,
+                totalEntriesDeleted,
+            };
+        },
+        registerStore(dataType, store) {
+            stores.set(dataType, store);
+        },
+    };
+}
+/**
+ * Creates an in-memory retention store (for testing)
+ */
+export function createInMemoryRetentionStore(entries) {
+    return {
+        async findExpired(cutoffDate, _conditions) {
+            const cutoff = new Date(cutoffDate).getTime();
+            const result = [];
+            for (const entry of entries.values()) {
+                const entryTime = new Date(entry.createdAt).getTime();
+                if (entryTime < cutoff) {
+                    result.push(entry);
+                }
+            }
+            return result;
+        },
+        async delete(id) {
+            entries.delete(id);
+        },
+        async getSize(id) {
+            const entry = entries.get(id);
+            if (!entry)
+                return 0;
+            return JSON.stringify(entry).length;
+        },
+    };
+}
+/**
+ * Creates an in-memory archiver (for testing)
+ */
+export function createInMemoryArchiver() {
+    const archives = [];
+    return {
+        async archive(dataType, entry, format, path) {
+            const archiveEntry = {
+                originalId: entry.id,
+                dataType,
+                archivedAt: new Date().toISOString(),
+                policyId: 'archive',
+                archivePath: path ?? `/archives/${dataType}/${entry.id}.${format}`,
+                sizeBytes: JSON.stringify(entry).length,
+            };
+            archives.push(archiveEntry);
+            return archiveEntry;
+        },
+        getArchives() {
+            return [...archives];
+        },
+    };
+}
+/**
+ * Retention error
+ */
+export class RetentionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message ?? `Retention error: ${code}`);
+        this.code = code;
+        this.name = 'RetentionError';
+    }
+    static policyNotFound(policyId) {
+        return new RetentionError(RetentionErrorCodes.POLICY_NOT_FOUND, `Policy not found: ${policyId}`);
+    }
+    static archiveFailed(entryId, error) {
+        return new RetentionError(RetentionErrorCodes.ARCHIVE_FAILED, `Archive failed for ${entryId}: ${error}`);
+    }
+    static deleteFailed(entryId, error) {
+        return new RetentionError(RetentionErrorCodes.DELETE_FAILED, `Delete failed for ${entryId}: ${error}`);
+    }
+}
+//# sourceMappingURL=retention-manager.js.map