@quereus/sync-coordinator 0.6.0 → 0.8.0

package/dist/src/service/s3-config.d.ts

@@ -0,0 +1,81 @@
+/**
+ * S3 configuration for durable batch storage.
+ *
+ * Supports both AWS S3 and S3-compatible services like MinIO.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * S3 storage configuration.
+ */
+export interface S3StorageConfig {
+    /** S3 bucket name for storing sync batches */
+    bucket: string;
+    /** AWS region (e.g., 'us-east-1') */
+    region: string;
+    /**
+     * Optional endpoint URL for S3-compatible services (e.g., MinIO).
+     * If not provided, uses AWS S3.
+     *
+     * @example 'http://localhost:9000' for local MinIO
+     */
+    endpoint?: string;
+    /**
+     * AWS credentials. If not provided, uses default credential chain.
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    /**
+     * Force path-style URLs (required for MinIO and some S3-compatible services).
+     * Default: false (uses virtual-hosted style for AWS S3)
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Key prefix for all objects in the bucket.
+     * Useful for organizing data or sharing a bucket across environments.
+     *
+     * @example 'sync-batches/' or 'dev/sync-batches/'
+     */
+    keyPrefix?: string;
+}
+/**
+ * Create an S3 client from configuration.
+ */
+export declare function createS3Client(config: S3StorageConfig): S3Client;
+/**
+ * Build the S3 key for a sync batch.
+ *
+ * Key format: <prefix><storagePath>/batches/<timestamp>_<batch_id>.json
+ *
+ * @param config - S3 storage configuration
+ * @param storagePath - Storage path for the database (e.g., 'org123/s_abc123')
+ * @param batchId - Unique batch identifier
+ * @param timestamp - Batch timestamp (ISO format)
+ */
+export declare function buildBatchKey(config: S3StorageConfig, storagePath: string, batchId: string, timestamp: string): string;
+/**
+ * Build the S3 key for a database snapshot.
+ *
+ * Key format: <prefix><storagePath>/snapshots/<timestamp>_<snapshot_id>.json
+ *
+ * @param config - S3 storage configuration
+ * @param storagePath - Storage path for the database (e.g., 'org123/s_abc123')
+ * @param snapshotId - Unique snapshot identifier
+ * @param timestamp - Snapshot timestamp (ISO format)
+ */
+export declare function buildSnapshotKey(config: S3StorageConfig, storagePath: string, snapshotId: string, timestamp: string): string;
+/**
+ * Parse S3 configuration from environment variables.
+ *
+ * Environment variables:
+ * - S3_BUCKET: Bucket name (required)
+ * - S3_REGION: AWS region (default: 'us-east-1')
+ * - S3_ENDPOINT: Custom endpoint for MinIO/compatible services
+ * - S3_ACCESS_KEY_ID: Access key (optional, uses default chain if not set)
+ * - S3_SECRET_ACCESS_KEY: Secret key (optional)
+ * - S3_FORCE_PATH_STYLE: Set to 'true' for MinIO
+ * - S3_KEY_PREFIX: Key prefix for all objects
+ */
+export declare function parseS3ConfigFromEnv(): S3StorageConfig | undefined;
+//# sourceMappingURL=s3-config.d.ts.map

package/dist/src/service/s3-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-config.d.ts","sourceRoot":"","sources":["../../../src/service/s3-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAuB,MAAM,oBAAoB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IAEF;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,CAkBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAIR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,GAAG,SAAS,CA+BlE"}

package/dist/src/service/s3-config.js

@@ -0,0 +1,94 @@
+/**
+ * S3 configuration for durable batch storage.
+ *
+ * Supports both AWS S3 and S3-compatible services like MinIO.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Create an S3 client from configuration.
+ */
+export function createS3Client(config) {
+    const clientConfig = {
+        region: config.region,
+    };
+    if (config.endpoint) {
+        clientConfig.endpoint = config.endpoint;
+    }
+    if (config.credentials) {
+        clientConfig.credentials = config.credentials;
+    }
+    if (config.forcePathStyle) {
+        clientConfig.forcePathStyle = true;
+    }
+    return new S3Client(clientConfig);
+}
+/**
+ * Build the S3 key for a sync batch.
+ *
+ * Key format: <prefix><storagePath>/batches/<timestamp>_<batch_id>.json
+ *
+ * @param config - S3 storage configuration
+ * @param storagePath - Storage path for the database (e.g., 'org123/s_abc123')
+ * @param batchId - Unique batch identifier
+ * @param timestamp - Batch timestamp (ISO format)
+ */
+export function buildBatchKey(config, storagePath, batchId, timestamp) {
+    const prefix = config.keyPrefix ?? '';
+    // Use timestamp prefix for chronological ordering in S3 listings
+    const timestampPrefix = timestamp.replace(/[:.]/g, '-');
+    return `${prefix}${storagePath}/batches/${timestampPrefix}_${batchId}.json`;
+}
+/**
+ * Build the S3 key for a database snapshot.
+ *
+ * Key format: <prefix><storagePath>/snapshots/<timestamp>_<snapshot_id>.json
+ *
+ * @param config - S3 storage configuration
+ * @param storagePath - Storage path for the database (e.g., 'org123/s_abc123')
+ * @param snapshotId - Unique snapshot identifier
+ * @param timestamp - Snapshot timestamp (ISO format)
+ */
+export function buildSnapshotKey(config, storagePath, snapshotId, timestamp) {
+    const prefix = config.keyPrefix ?? '';
+    const timestampPrefix = timestamp.replace(/[:.]/g, '-');
+    return `${prefix}${storagePath}/snapshots/${timestampPrefix}_${snapshotId}.json`;
+}
+/**
+ * Parse S3 configuration from environment variables.
+ *
+ * Environment variables:
+ * - S3_BUCKET: Bucket name (required)
+ * - S3_REGION: AWS region (default: 'us-east-1')
+ * - S3_ENDPOINT: Custom endpoint for MinIO/compatible services
+ * - S3_ACCESS_KEY_ID: Access key (optional, uses default chain if not set)
+ * - S3_SECRET_ACCESS_KEY: Secret key (optional)
+ * - S3_FORCE_PATH_STYLE: Set to 'true' for MinIO
+ * - S3_KEY_PREFIX: Key prefix for all objects
+ */
+export function parseS3ConfigFromEnv() {
+    const bucket = process.env.S3_BUCKET;
+    if (!bucket) {
+        return undefined;
+    }
+    const config = {
+        bucket,
+        region: process.env.S3_REGION ?? 'us-east-1',
+    };
+    if (process.env.S3_ENDPOINT) {
+        config.endpoint = process.env.S3_ENDPOINT;
+    }
+    if (process.env.S3_ACCESS_KEY_ID && process.env.S3_SECRET_ACCESS_KEY) {
+        config.credentials = {
+            accessKeyId: process.env.S3_ACCESS_KEY_ID,
+            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+        };
+    }
+    if (process.env.S3_FORCE_PATH_STYLE === 'true') {
+        config.forcePathStyle = true;
+    }
+    if (process.env.S3_KEY_PREFIX) {
+        config.keyPrefix = process.env.S3_KEY_PREFIX;
+    }
+    return config;
+}
+//# sourceMappingURL=s3-config.js.map

package/dist/src/service/s3-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-config.js","sourceRoot":"","sources":["../../../src/service/s3-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAuB,MAAM,oBAAoB,CAAC;AA2CnE;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAuB;IACpD,MAAM,YAAY,GAAmB;QACnC,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC;IAEF,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,YAAY,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC1C,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,YAAY,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IAChD,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC1B,YAAY,CAAC,cAAc,GAAG,IAAI,CAAC;IACrC,CAAC;IAED,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAuB,EACvB,WAAmB,EACnB,OAAe,EACf,SAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;IACtC,iEAAiE;IACjE,MAAM,eAAe,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,GAAG,MAAM,GAAG,WAAW,YAAY,eAAe,IAAI,OAAO,OAAO,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAuB,EACvB,WAAmB,EACnB,UAAkB,EAClB,SAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;IACtC,MAAM,eAAe,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,GAAG,MAAM,GAAG,WAAW,cAAc,eAAe,IAAI,UAAU,OAAO,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAoB;QAC9B,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,WAAW;KAC7C,CAAC;IAEF,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QAC5B,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACrE,MAAM,CAAC,WAAW,GAAG;YACnB,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACzC,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;SAClD,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,MAAM,EAAE,CAAC;QAC/C,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC/C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/service/s3-snapshot-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * S3 Snapshot Store - Full database snapshots for faster restore.
+ *
+ * Stores periodic full snapshots to S3 at:
+ *   <prefix><storage_path>/snapshots/<timestamp>_<snapshot_id>.json.gz
+ *
+ * Snapshots are triggered by:
+ * - Time interval (e.g., every 5 minutes)
+ * - Change volume threshold (e.g., every 1000 changes)
+ */
+import { type S3Client } from '@aws-sdk/client-s3';
+import { type S3StorageConfig } from './s3-config.js';
+import type { SyncManager } from '@quereus/sync';
+/**
+ * Snapshot metadata stored alongside the snapshot.
+ */
+export interface SnapshotMetadata {
+    /** Unique snapshot identifier */
+    snapshotId: string;
+    /** Database ID this snapshot belongs to */
+    databaseId: string;
+    /** Timestamp when snapshot was created */
+    timestamp: string;
+    /** Total number of rows in the snapshot */
+    totalRows: number;
+    /** Total number of tables in the snapshot */
+    totalTables: number;
+    /** Compressed size in bytes */
+    compressedSizeBytes: number;
+    /** HLC timestamp of latest change in snapshot */
+    hlcTimestamp?: string;
+}
+/**
+ * Configuration for periodic snapshots.
+ */
+export interface SnapshotScheduleConfig {
+    /** Interval in milliseconds between snapshots (default: 5 minutes) */
+    intervalMs: number;
+    /** Change count threshold to trigger snapshot (default: 1000) */
+    changeThreshold: number;
+    /** Maximum number of snapshots to retain per database (default: 5) */
+    maxRetained: number;
+}
+/**
+ * Tracker for pending snapshot operations.
+ */
+interface DatabaseSnapshotState {
+    lastSnapshotAt: number;
+    changesSinceSnapshot: number;
+    snapshotInProgress: boolean;
+}
+/**
+ * Function to resolve a database ID to a storage path for S3 keys.
+ */
+export type StoragePathResolver = (databaseId: string) => string;
+/**
+ * S3 Snapshot Store for full database snapshots.
+ */
+export declare class S3SnapshotStore {
+    private readonly client;
+    private readonly config;
+    private readonly scheduleConfig;
+    private readonly resolveStoragePath;
+    private readonly databaseStates;
+    private checkTimer;
+    constructor(client: S3Client, config: S3StorageConfig, scheduleConfig?: Partial<SnapshotScheduleConfig>, resolveStoragePath?: StoragePathResolver);
+    /**
+     * Start periodic snapshot checks.
+     */
+    start(): void;
+    /**
+     * Stop periodic snapshot checks.
+     */
+    stop(): void;
+    /**
+     * Record that changes have been applied to a database.
+     */
+    recordChanges(databaseId: string, changeCount: number): void;
+    /**
+     * Check if a database needs a snapshot based on time or change volume.
+     */
+    needsSnapshot(databaseId: string): boolean;
+    /**
+     * Check all tracked databases for scheduled snapshots.
+     */
+    private checkScheduledSnapshots;
+    /**
+     * Create and store a full snapshot for a database.
+     */
+    createSnapshot(databaseId: string, syncManager: SyncManager): Promise<SnapshotMetadata>;
+    /**
+     * Type guard to check if a chunk is a column-versions chunk.
+     */
+    private isColumnVersionsChunk;
+    /**
+     * Check if a snapshot exists for a database.
+     */
+    hasSnapshot(databaseId: string): Promise<boolean>;
+    /**
+     * Compress data using gzip.
+     */
+    private compressData;
+    /**
+     * Get databases that need snapshots (for external scheduling).
+     */
+    getDatabasesNeedingSnapshot(): string[];
+    /**
+     * Force a snapshot for a database (ignoring schedule).
+     */
+    forceSnapshot(databaseId: string, syncManager: SyncManager): Promise<SnapshotMetadata>;
+    /**
+     * Get snapshot state for a database.
+     */
+    getState(databaseId: string): DatabaseSnapshotState | undefined;
+}
+/**
+ * Create an S3 snapshot store from configuration.
+ */
+export declare function createS3SnapshotStore(client: S3Client, config: S3StorageConfig, scheduleConfig?: Partial<SnapshotScheduleConfig>, resolveStoragePath?: StoragePathResolver): S3SnapshotStore;
+export {};
+//# sourceMappingURL=s3-snapshot-store.d.ts.map

package/dist/src/service/s3-snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-snapshot-store.d.ts","sourceRoot":"","sources":["../../../src/service/s3-snapshot-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIrE,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAA8C,MAAM,eAAe,CAAC;AAE7F;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IAEnB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAElB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IAEpB,+BAA+B;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAE5B,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IAEnB,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;IAExB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD;;GAEG;AACH,UAAU,qBAAqB;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;AASjE;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4C;IAC3E,OAAO,CAAC,UAAU,CAA+C;gBAG/D,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,eAAe,EACvB,cAAc,GAAE,OAAO,CAAC,sBAAsB,CAAM,EACpD,kBAAkB,CAAC,EAAE,mBAAmB;IAQ1C;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAa5D;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAoB1C;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;OAEG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,gBAAgB,CAAC;IA2E5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASvD;;OAEG;YACW,YAAY;IAa1B;;OAEG;IACH,2BAA2B,IAAI,MAAM,EAAE;IAUvC;;OAEG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI5F;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;CAGhE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,eAAe,EACvB,cAAc,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,EAChD,kBAAkB,CAAC,EAAE,mBAAmB,GACvC,eAAe,CAEjB"}

package/dist/src/service/s3-snapshot-store.js

@@ -0,0 +1,236 @@
+/**
+ * S3 Snapshot Store - Full database snapshots for faster restore.
+ *
+ * Stores periodic full snapshots to S3 at:
+ *   <prefix><storage_path>/snapshots/<timestamp>_<snapshot_id>.json.gz
+ *
+ * Snapshots are triggered by:
+ * - Time interval (e.g., every 5 minutes)
+ * - Change volume threshold (e.g., every 1000 changes)
+ */
+import { PutObjectCommand } from '@aws-sdk/client-s3';
+import { randomUUID } from 'node:crypto';
+import { createGzip } from 'node:zlib';
+import { serviceLog } from '../common/logger.js';
+import { buildSnapshotKey } from './s3-config.js';
+const DEFAULT_SCHEDULE_CONFIG = {
+    intervalMs: 5 * 60 * 1000, // 5 minutes
+    changeThreshold: 1000,
+    maxRetained: 5,
+};
+/**
+ * Default storage path resolver - sanitizes databaseId for use as S3 path.
+ */
+function defaultStoragePathResolver(databaseId) {
+    return databaseId.replace(/:/g, '/').replace(/[^a-zA-Z0-9/_-]/g, '_');
+}
+/**
+ * S3 Snapshot Store for full database snapshots.
+ */
+export class S3SnapshotStore {
+    client;
+    config;
+    scheduleConfig;
+    resolveStoragePath;
+    databaseStates = new Map();
+    checkTimer = null;
+    constructor(client, config, scheduleConfig = {}, resolveStoragePath) {
+        this.client = client;
+        this.config = config;
+        this.scheduleConfig = { ...DEFAULT_SCHEDULE_CONFIG, ...scheduleConfig };
+        this.resolveStoragePath = resolveStoragePath ?? defaultStoragePathResolver;
+    }
+    /**
+     * Start periodic snapshot checks.
+     */
+    start() {
+        if (this.checkTimer)
+            return;
+        // Check every 30 seconds for databases needing snapshots
+        this.checkTimer = setInterval(() => this.checkScheduledSnapshots(), 30_000);
+        serviceLog('S3SnapshotStore started with interval=%dms, threshold=%d', this.scheduleConfig.intervalMs, this.scheduleConfig.changeThreshold);
+    }
+    /**
+     * Stop periodic snapshot checks.
+     */
+    stop() {
+        if (this.checkTimer) {
+            clearInterval(this.checkTimer);
+            this.checkTimer = null;
+        }
+    }
+    /**
+     * Record that changes have been applied to a database.
+     */
+    recordChanges(databaseId, changeCount) {
+        let state = this.databaseStates.get(databaseId);
+        if (!state) {
+            state = {
+                lastSnapshotAt: 0,
+                changesSinceSnapshot: 0,
+                snapshotInProgress: false,
+            };
+            this.databaseStates.set(databaseId, state);
+        }
+        state.changesSinceSnapshot += changeCount;
+    }
+    /**
+     * Check if a database needs a snapshot based on time or change volume.
+     */
+    needsSnapshot(databaseId) {
+        const state = this.databaseStates.get(databaseId);
+        if (!state || state.snapshotInProgress)
+            return false;
+        const now = Date.now();
+        const timeSinceSnapshot = now - state.lastSnapshotAt;
+        // Check time interval
+        if (timeSinceSnapshot >= this.scheduleConfig.intervalMs) {
+            return true;
+        }
+        // Check change threshold
+        if (state.changesSinceSnapshot >= this.scheduleConfig.changeThreshold) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check all tracked databases for scheduled snapshots.
+     */
+    checkScheduledSnapshots() {
+        for (const databaseId of this.databaseStates.keys()) {
+            if (this.needsSnapshot(databaseId)) {
+                serviceLog('Scheduled snapshot triggered for: %s', databaseId);
+                // Note: actual snapshot creation requires the SyncManager,
+                // which should be called by the coordinator
+            }
+        }
+    }
+    /**
+     * Create and store a full snapshot for a database.
+     */
+    async createSnapshot(databaseId, syncManager) {
+        const state = this.databaseStates.get(databaseId) ?? {
+            lastSnapshotAt: 0,
+            changesSinceSnapshot: 0,
+            snapshotInProgress: false,
+        };
+        this.databaseStates.set(databaseId, state);
+        if (state.snapshotInProgress) {
+            throw new Error(`Snapshot already in progress for ${databaseId}`);
+        }
+        state.snapshotInProgress = true;
+        const snapshotId = randomUUID();
+        const timestamp = new Date().toISOString();
+        try {
+            const storagePath = this.resolveStoragePath(databaseId);
+            const key = buildSnapshotKey(this.config, storagePath, snapshotId, timestamp);
+            // Stream snapshot chunks through gzip compression
+            let totalEntries = 0;
+            let totalTables = 0;
+            const chunks = [];
+            for await (const chunk of syncManager.getSnapshotStream()) {
+                chunks.push(chunk);
+                if (this.isColumnVersionsChunk(chunk)) {
+                    totalEntries += chunk.entries?.length ?? 0;
+                }
+                else if (chunk.type === 'table-start') {
+                    totalTables++;
+                }
+            }
+            // Serialize and compress
+            const jsonData = JSON.stringify({ snapshotId, databaseId, timestamp, chunks });
+            const compressed = await this.compressData(jsonData);
+            // Upload to S3
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.config.bucket,
+                Key: key,
+                Body: compressed,
+                ContentType: 'application/gzip',
+                ContentEncoding: 'gzip',
+                Metadata: {
+                    'x-snapshot-id': snapshotId,
+                    'x-database-id': databaseId,
+                    'x-entry-count': String(totalEntries),
+                    'x-table-count': String(totalTables),
+                },
+            }));
+            const metadata = {
+                snapshotId,
+                databaseId,
+                timestamp,
+                totalRows: totalEntries, // Using entries count as "rows"
+                totalTables,
+                compressedSizeBytes: compressed.length,
+            };
+            serviceLog('Snapshot created: %s (%d entries, %d tables, %d bytes)', snapshotId, totalEntries, totalTables, compressed.length);
+            // Update state
+            state.lastSnapshotAt = Date.now();
+            state.changesSinceSnapshot = 0;
+            return metadata;
+        }
+        finally {
+            state.snapshotInProgress = false;
+        }
+    }
+    /**
+     * Type guard to check if a chunk is a column-versions chunk.
+     */
+    isColumnVersionsChunk(chunk) {
+        return chunk.type === 'column-versions';
+    }
+    /**
+     * Check if a snapshot exists for a database.
+     */
+    async hasSnapshot(databaseId) {
+        const storagePath = this.resolveStoragePath(databaseId);
+        // Check for latest snapshot pattern
+        const prefix = this.config.keyPrefix ?? '';
+        void `${prefix}${storagePath}/snapshots/`; // Key pattern for listing
+        // Would need list operation to check, simplified for now
+        return false;
+    }
+    /**
+     * Compress data using gzip.
+     */
+    async compressData(data) {
+        const gzip = createGzip();
+        const buffers = [];
+        gzip.on('data', (chunk) => buffers.push(chunk));
+        return new Promise((resolve, reject) => {
+            gzip.on('end', () => resolve(Buffer.concat(buffers)));
+            gzip.on('error', reject);
+            gzip.end(Buffer.from(data, 'utf-8'));
+        });
+    }
+    /**
+     * Get databases that need snapshots (for external scheduling).
+     */
+    getDatabasesNeedingSnapshot() {
+        const result = [];
+        for (const databaseId of this.databaseStates.keys()) {
+            if (this.needsSnapshot(databaseId)) {
+                result.push(databaseId);
+            }
+        }
+        return result;
+    }
+    /**
+     * Force a snapshot for a database (ignoring schedule).
+     */
+    async forceSnapshot(databaseId, syncManager) {
+        return this.createSnapshot(databaseId, syncManager);
+    }
+    /**
+     * Get snapshot state for a database.
+     */
+    getState(databaseId) {
+        return this.databaseStates.get(databaseId);
+    }
+}
+/**
+ * Create an S3 snapshot store from configuration.
+ */
+export function createS3SnapshotStore(client, config, scheduleConfig, resolveStoragePath) {
+    return new S3SnapshotStore(client, config, scheduleConfig, resolveStoragePath);
+}
+//# sourceMappingURL=s3-snapshot-store.js.map

package/dist/src/service/s3-snapshot-store.js.map

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

package/dist/src/service/store-manager.d.ts

@@ -4,6 +4,9 @@
  * Manages lazy loading and cleanup of per-database LevelDB stores.
  * Each database gets its own isolated store, opened on-demand and
  * closed after idle timeout.
+ *
+ * This is a generic implementation. Applications provide custom database ID
+ * parsing and path resolution via hooks in StoreManagerConfig.
  */
 import { StoreEventEmitter } from '@quereus/store';
 import { LevelDBStore } from '@quereus/plugin-leveldb';

package/dist/src/service/store-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store-manager.d.ts","sourceRoot":"","sources":["../../../src/service/store-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,MAAM,CAAC;IAE5E;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC;CAC7E;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,UAAU,CAAC,EAAE;QACX,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,qCAAqC;IACrC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAgCD;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyD;IAC5F,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0D;IAC5F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,eAAe,CAA8B;gBAEzC,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAMpD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB9E;;OAEG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IASjC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO;IAIvE;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YA0BjB,SAAS;IA6BvB;;OAEG;YACW,OAAO;IAmBrB;;OAEG;YACW,QAAQ;IAoBtB;;OAEG;YACW,UAAU;CAYzB"}
+{"version":3,"file":"store-manager.d.ts","sourceRoot":"","sources":["../../../src/service/store-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,MAAM,CAAC;IAE5E;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC;CAC7E;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,UAAU,CAAC,EAAE;QACX,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,qCAAqC;IACrC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AA0CD;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyD;IAC5F,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0D;IAC5F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,eAAe,CAA8B;gBAEzC,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAMpD;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB9E;;OAEG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IASjC;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI/C;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;OAIG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO;IAIvE;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YA0BjB,SAAS;IAiCvB;;OAEG;YACW,OAAO;IAmBrB;;OAEG;YACW,QAAQ;IAoBtB;;OAEG;YACW,UAAU;CAYzB"}

package/dist/src/service/store-manager.js

@@ -4,31 +4,45 @@
  * Manages lazy loading and cleanup of per-database LevelDB stores.
  * Each database gets its own isolated store, opened on-demand and
  * closed after idle timeout.
+ *
+ * This is a generic implementation. Applications provide custom database ID
+ * parsing and path resolution via hooks in StoreManagerConfig.
  */
 import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
 import { StoreEventEmitter } from '@quereus/store';
 import { LevelDBStore } from '@quereus/plugin-leveldb';
 import { createSyncModule, } from '@quereus/sync';
 import { serviceLog } from '../common/logger.js';
 /**
- * Sanitize a database ID for use as a filesystem path.
+ * Sanitize a string for use as a filesystem path component.
  * Replaces unsafe characters with underscores.
  */
-function sanitizeDatabaseId(databaseId) {
+function sanitizePathComponent(value) {
     // Allow alphanumeric, dash, underscore; replace others with underscore
-    return databaseId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return value.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
 /**
- * Default storage path resolver - just uses the sanitized database ID.
+ * Default storage path resolver - simple sanitized passthrough.
+ *
+ * Applications can provide a custom resolveStoragePath hook for
+ * org-based folder structures or other custom layouts.
  */
 function defaultResolveStoragePath(databaseId, _context) {
-    return sanitizeDatabaseId(databaseId);
+    return sanitizePathComponent(databaseId);
 }
 /**
- * Default database ID validator - accepts non-empty strings.
+ * Default database ID validator - accepts any non-empty string with safe characters.
+ *
+ * Applications can provide a custom isValidDatabaseId hook for
+ * stricter validation (e.g., org:type_id format).
  */
 function defaultIsValidDatabaseId(databaseId, _context) {
-    return typeof databaseId === 'string' && databaseId.length > 0;
+    if (typeof databaseId !== 'string' || databaseId.length === 0) {
+        return false;
+    }
+    // Accept alphanumeric with common separators
+    return /^[a-zA-Z0-9_:.-]+$/.test(databaseId);
 }
 const DEFAULT_CONFIG = {
     dataDir: './data',
@@ -154,6 +168,9 @@ export class StoreManager {
         }
         const storagePath = this.resolveStoragePath(databaseId, context);
         const fullPath = join(this.config.dataDir, storagePath);
+        // Ensure parent directories exist (org folder for new org-based format)
+        const parentPath = join(this.config.dataDir, storagePath.split('/')[0]);
+        await mkdir(parentPath, { recursive: true });
         serviceLog('Opening store at: %s', fullPath);
         const store = await LevelDBStore.open({
             path: fullPath,