@quereus/plugin-sync 0.3.1

package/README.md

@@ -0,0 +1,154 @@
+# @quereus/plugin-sync
+
+CRDT-based multi-master sync plugin for [Quereus](https://github.com/gotchoices/quereus). Enables offline-first applications with automatic conflict resolution.
+
+## Features
+
+- **Multi-master replication**: Any replica can write, changes merge automatically
+- **Column-level LWW**: Last-Write-Wins at the column level for fine-grained conflict resolution
+- **Hybrid Logical Clocks**: Causally-ordered timestamps that work offline
+- **Transport agnostic**: Bring your own WebSocket, HTTP, or WebRTC transport
+- **Offline-first**: Local changes sync when connectivity returns
+- **Schema sync**: DDL changes (CREATE TABLE, ALTER TABLE) propagate across replicas
+
+## Installation
+
+```bash
+npm install @quereus/plugin-sync @quereus/plugin-store
+```
+
+## Quick Start
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { StoreEventEmitter, LevelDBStore } from '@quereus/plugin-store';
+import { createSyncModule, createStoreAdapter } from '@quereus/plugin-sync';
+
+// Create the store with event emitter
+const storeEvents = new StoreEventEmitter();
+const store = await LevelDBStore.open({ path: './data' });
+
+// Create sync-enabled module
+const { syncModule, syncManager, syncEvents } = createSyncModule(store, storeEvents);
+
+// Register with database
+const db = new Database();
+db.registerVtabModule('store', syncModule);
+
+// Create tables and use normally - all changes are tracked
+await db.exec(`
+  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)
+  USING store
+`);
+
+await db.exec(`INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com')`);
+
+// Get changes to send to another replica
+const changes = await syncManager.getChangesSince(peerSiteId);
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Application                             │
+├─────────────────────────────────────────────────────────────┤
+│  SyncManager                                                 │
+│  ├── HLCManager (Hybrid Logical Clock)                      │
+│  ├── ColumnVersionStore (LWW metadata)                      │
+│  ├── TombstoneStore (deletion tracking)                     │
+│  ├── ChangeLogStore (HLC-indexed changes)                   │
+│  └── PeerStateStore (delta sync state)                      │
+├─────────────────────────────────────────────────────────────┤
+│  @quereus/plugin-store (KVStore)                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Sync Protocol
+
+### Delta Sync
+
+When replicas have synced before:
+
+```typescript
+// Get changes since last sync
+const changes = await syncManager.getChangesSince(peerSiteId);
+
+// Apply received changes
+const result = await syncManager.applyChanges(changeSets, applyToStoreCallback);
+```
+
+### Snapshot Sync
+
+For new replicas or when delta sync isn't available:
+
+```typescript
+// Stream snapshot chunks
+for await (const chunk of syncManager.streamSnapshot({ chunkSize: 1000 })) {
+  sendToPeer(chunk);
+}
+
+// Apply received snapshot
+await syncManager.applyStreamedSnapshot(chunks, applyToStoreCallback);
+```
+
+## Events
+
+Subscribe to sync events for UI updates:
+
+```typescript
+syncEvents.onLocalChange((event) => {
+  console.log('Local change:', event.tableName, event.type);
+});
+
+syncEvents.onRemoteChange((event) => {
+  console.log('Remote change:', event.tableName, event.type);
+  refreshUI();
+});
+
+syncEvents.onConflict((event) => {
+  console.log('Conflict resolved:', event.resolution);
+});
+```
+
+## Conflict Resolution
+
+Conflicts are resolved automatically using Last-Write-Wins at the column level:
+
+- Each column has an associated HLC timestamp
+- When merging, the column with the higher HLC wins
+- Ties are broken by site ID (deterministic ordering)
+
+This means concurrent updates to *different* columns of the same row both apply, while updates to the *same* column use the latest value.
+
+## API
+
+### Core Exports
+
+- `createSyncModule(store, storeEvents, config?)` - Factory to create sync-enabled store module
+- `createStoreAdapter(db, store, storeEvents)` - Adapter for applying remote changes to store
+- `SyncManager` - Main sync coordination interface
+- `SyncEventEmitter` - Event subscription interface
+
+### Clock Exports
+
+- `HLCManager` - Hybrid Logical Clock manager
+- `generateSiteId()` - Generate unique 16-byte site identifier
+- `siteIdToBase64(id)` / `siteIdFromBase64(str)` - Site ID serialization
+
+### Protocol Types
+
+- `ChangeSet` - Collection of changes from one transaction
+- `Change` - Single column or row change
+- `SchemaMigration` - Schema change (CREATE/ALTER/DROP TABLE)
+- `SnapshotChunk` - Streaming snapshot data
+
+## Related Packages
+
+- [`@quereus/plugin-store`](../quereus-plugin-store/) - Storage layer (required)
+- [`@quereus/sync-coordinator`](../sync-coordinator/) - Server-side coordinator
+
+## License
+
+MIT
+

package/dist/src/clock/hlc.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Hybrid Logical Clock (HLC) implementation.
+ *
+ * HLC combines physical time with a logical counter to provide:
+ * - Monotonically increasing timestamps
+ * - Causality tracking across distributed nodes
+ * - Bounded clock drift tolerance
+ *
+ * Ordering: (wallTime, counter, siteId) compared lexicographically
+ */
+import type { SiteId } from './site.js';
+/**
+ * Hybrid Logical Clock timestamp.
+ */
+export interface HLC {
+    /** Physical wall time in milliseconds since epoch */
+    readonly wallTime: bigint;
+    /** Logical counter for events in the same millisecond (0-65535) */
+    readonly counter: number;
+    /** 16-byte UUID identifying the replica */
+    readonly siteId: SiteId;
+}
+/**
+ * Compare two HLCs for ordering.
+ * Returns negative if a < b, positive if a > b, zero if equal.
+ */
+export declare function compareHLC(a: HLC, b: HLC): number;
+/**
+ * Check if two HLCs are equal.
+ */
+export declare function hlcEquals(a: HLC, b: HLC): boolean;
+/**
+ * Create a new HLC with the given values.
+ */
+export declare function createHLC(wallTime: bigint, counter: number, siteId: SiteId): HLC;
+/**
+ * Serialize HLC to a Uint8Array for storage.
+ * Format: 8 bytes wallTime (BE) + 2 bytes counter (BE) + 16 bytes siteId = 26 bytes
+ */
+export declare function serializeHLC(hlc: HLC): Uint8Array;
+/**
+ * Deserialize HLC from a Uint8Array.
+ */
+export declare function deserializeHLC(buffer: Uint8Array): HLC;
+/**
+ * JSON-serializable representation of an HLC.
+ * Uses strings for bigint and base64url for binary data.
+ */
+export interface SerializedHLC {
+    /** Wall time in milliseconds (string to preserve bigint precision) */
+    wallTime: string;
+    /** Logical counter (0-65535) */
+    counter: number;
+    /** Site ID as 22-character base64url string */
+    siteId: string;
+}
+/**
+ * Convert HLC to a JSON-serializable object.
+ * Useful for schema seeds, HTTP transport, or debugging.
+ */
+export declare function hlcToJson(hlc: HLC): SerializedHLC;
+/**
+ * Parse HLC from a JSON-serializable object.
+ */
+export declare function hlcFromJson(json: SerializedHLC): HLC;
+/**
+ * HLC Manager - maintains clock state for a single replica.
+ */
+export declare class HLCManager {
+    private wallTime;
+    private counter;
+    private readonly siteId;
+    constructor(siteId: SiteId, initialState?: {
+        wallTime: bigint;
+        counter: number;
+    });
+    /**
+     * Get the current site ID.
+     */
+    getSiteId(): SiteId;
+    /**
+     * Get current clock state (for persistence).
+     */
+    getState(): {
+        wallTime: bigint;
+        counter: number;
+    };
+    /**
+     * Generate a new HLC for a local event.
+     * Advances the clock and returns the new timestamp.
+     */
+    tick(): HLC;
+    /**
+     * Update clock state upon receiving a remote HLC.
+     * Ensures our clock is always >= received clock.
+     * Returns a new HLC for the local receive event.
+     */
+    receive(remote: HLC): HLC;
+    /**
+     * Create an HLC at the current clock state without advancing.
+     * Useful for read operations.
+     */
+    now(): HLC;
+}
+//# sourceMappingURL=hlc.d.ts.map

package/dist/src/clock/hlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../../../src/clock/hlc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAaD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAWjD;AAcD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAEhF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAcjD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,GAAG,CAYtD;AAMD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,CAMjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAMpD;AAkDD;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAMhF;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,QAAQ,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAIjD;;;OAGG;IACH,IAAI,IAAI,GAAG;IAoBX;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG;IAuCzB;;;OAGG;IACH,GAAG,IAAI,GAAG;CAGX"}

package/dist/src/clock/hlc.js

@@ -0,0 +1,251 @@
+/**
+ * Hybrid Logical Clock (HLC) implementation.
+ *
+ * HLC combines physical time with a logical counter to provide:
+ * - Monotonically increasing timestamps
+ * - Causality tracking across distributed nodes
+ * - Bounded clock drift tolerance
+ *
+ * Ordering: (wallTime, counter, siteId) compared lexicographically
+ */
+/**
+ * Maximum counter value before forcing time advancement.
+ */
+const MAX_COUNTER = 0xFFFF;
+/**
+ * Maximum allowed clock drift in milliseconds (1 minute).
+ * Rejects remote timestamps that are too far in the future.
+ */
+const MAX_DRIFT_MS = 60000n;
+/**
+ * Compare two HLCs for ordering.
+ * Returns negative if a < b, positive if a > b, zero if equal.
+ */
+export function compareHLC(a, b) {
+    // First compare wall time
+    if (a.wallTime < b.wallTime)
+        return -1;
+    if (a.wallTime > b.wallTime)
+        return 1;
+    // Same wall time: compare counter
+    if (a.counter < b.counter)
+        return -1;
+    if (a.counter > b.counter)
+        return 1;
+    // Same counter: compare site ID lexicographically
+    return compareSiteIds(a.siteId, b.siteId);
+}
+/**
+ * Compare two site IDs lexicographically.
+ */
+function compareSiteIds(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    return a.length - b.length;
+}
+/**
+ * Check if two HLCs are equal.
+ */
+export function hlcEquals(a, b) {
+    return compareHLC(a, b) === 0;
+}
+/**
+ * Create a new HLC with the given values.
+ */
+export function createHLC(wallTime, counter, siteId) {
+    return Object.freeze({ wallTime, counter, siteId });
+}
+/**
+ * Serialize HLC to a Uint8Array for storage.
+ * Format: 8 bytes wallTime (BE) + 2 bytes counter (BE) + 16 bytes siteId = 26 bytes
+ */
+export function serializeHLC(hlc) {
+    const buffer = new Uint8Array(26);
+    const view = new DataView(buffer.buffer);
+    // Wall time as big-endian 64-bit
+    view.setBigUint64(0, hlc.wallTime, false);
+    // Counter as big-endian 16-bit
+    view.setUint16(8, hlc.counter, false);
+    // Site ID (16 bytes)
+    buffer.set(hlc.siteId, 10);
+    return buffer;
+}
+/**
+ * Deserialize HLC from a Uint8Array.
+ */
+export function deserializeHLC(buffer) {
+    if (buffer.length !== 26) {
+        throw new Error(`Invalid HLC buffer length: ${buffer.length}, expected 26`);
+    }
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const wallTime = view.getBigUint64(0, false);
+    const counter = view.getUint16(8, false);
+    const siteId = new Uint8Array(buffer.slice(10, 26));
+    return createHLC(wallTime, counter, siteId);
+}
+/**
+ * Convert HLC to a JSON-serializable object.
+ * Useful for schema seeds, HTTP transport, or debugging.
+ */
+export function hlcToJson(hlc) {
+    return {
+        wallTime: hlc.wallTime.toString(),
+        counter: hlc.counter,
+        siteId: siteIdToBase64Local(hlc.siteId),
+    };
+}
+/**
+ * Parse HLC from a JSON-serializable object.
+ */
+export function hlcFromJson(json) {
+    return createHLC(BigInt(json.wallTime), json.counter, siteIdFromBase64Local(json.siteId));
+}
+// Base64url alphabet (RFC 4648 Section 5)
+const BASE64URL_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/**
+ * Convert site ID to base64url string (local helper to avoid circular import).
+ */
+function siteIdToBase64Local(siteId) {
+    let result = '';
+    for (let i = 0; i < siteId.length; i += 3) {
+        const byte1 = siteId[i];
+        const byte2 = i + 1 < siteId.length ? siteId[i + 1] : 0;
+        const byte3 = i + 2 < siteId.length ? siteId[i + 2] : 0;
+        const triplet = (byte1 << 16) | (byte2 << 8) | byte3;
+        result += BASE64URL_CHARS[(triplet >>> 18) & 0x3f];
+        result += BASE64URL_CHARS[(triplet >>> 12) & 0x3f];
+        if (i + 1 < siteId.length)
+            result += BASE64URL_CHARS[(triplet >>> 6) & 0x3f];
+        if (i + 2 < siteId.length)
+            result += BASE64URL_CHARS[triplet & 0x3f];
+    }
+    return result;
+}
+/**
+ * Parse site ID from base64url string (local helper to avoid circular import).
+ */
+function siteIdFromBase64Local(base64) {
+    if (base64.length !== 22) {
+        throw new Error(`Invalid site ID base64 length: ${base64.length}, expected 22`);
+    }
+    // Build reverse lookup table
+    const lookup = {};
+    for (let i = 0; i < BASE64URL_CHARS.length; i++) {
+        lookup[BASE64URL_CHARS[i]] = i;
+    }
+    const result = new Uint8Array(16);
+    let writePos = 0;
+    for (let i = 0; i < base64.length; i += 4) {
+        const c1 = lookup[base64[i]] ?? 0;
+        const c2 = lookup[base64[i + 1]] ?? 0;
+        const c3 = i + 2 < base64.length ? lookup[base64[i + 2]] ?? 0 : 0;
+        const c4 = i + 3 < base64.length ? lookup[base64[i + 3]] ?? 0 : 0;
+        const triplet = (c1 << 18) | (c2 << 12) | (c3 << 6) | c4;
+        if (writePos < 16)
+            result[writePos++] = (triplet >>> 16) & 0xff;
+        if (writePos < 16)
+            result[writePos++] = (triplet >>> 8) & 0xff;
+        if (writePos < 16)
+            result[writePos++] = triplet & 0xff;
+    }
+    return result;
+}
+/**
+ * HLC Manager - maintains clock state for a single replica.
+ */
+export class HLCManager {
+    wallTime;
+    counter;
+    siteId;
+    constructor(siteId, initialState) {
+        this.siteId = siteId;
+        this.wallTime = initialState?.wallTime ?? 0n;
+        this.counter = initialState?.counter ?? 0;
+    }
+    /**
+     * Get the current site ID.
+     */
+    getSiteId() {
+        return this.siteId;
+    }
+    /**
+     * Get current clock state (for persistence).
+     */
+    getState() {
+        return { wallTime: this.wallTime, counter: this.counter };
+    }
+    /**
+     * Generate a new HLC for a local event.
+     * Advances the clock and returns the new timestamp.
+     */
+    tick() {
+        const now = BigInt(Date.now());
+        if (now > this.wallTime) {
+            // Physical time has advanced
+            this.wallTime = now;
+            this.counter = 0;
+        }
+        else {
+            // Same or earlier physical time, increment counter
+            this.counter++;
+            if (this.counter > MAX_COUNTER) {
+                // Counter overflow: force time advancement
+                this.wallTime++;
+                this.counter = 0;
+            }
+        }
+        return createHLC(this.wallTime, this.counter, this.siteId);
+    }
+    /**
+     * Update clock state upon receiving a remote HLC.
+     * Ensures our clock is always >= received clock.
+     * Returns a new HLC for the local receive event.
+     */
+    receive(remote) {
+        const now = BigInt(Date.now());
+        // Check for excessive drift
+        if (remote.wallTime > now + MAX_DRIFT_MS) {
+            throw new Error(`Remote clock too far in future: ${remote.wallTime - now}ms ahead (max ${MAX_DRIFT_MS}ms)`);
+        }
+        // Merge: take max of local, remote, and now
+        const maxWall = now > this.wallTime
+            ? (now > remote.wallTime ? now : remote.wallTime)
+            : (this.wallTime > remote.wallTime ? this.wallTime : remote.wallTime);
+        if (maxWall === this.wallTime && maxWall === remote.wallTime) {
+            // All three are equal: take max counter + 1
+            this.counter = Math.max(this.counter, remote.counter) + 1;
+        }
+        else if (maxWall === this.wallTime) {
+            // Local wins: increment local counter
+            this.counter++;
+        }
+        else if (maxWall === remote.wallTime) {
+            // Remote wins: take remote counter + 1
+            this.wallTime = remote.wallTime;
+            this.counter = remote.counter + 1;
+        }
+        else {
+            // Physical time wins: reset counter
+            this.wallTime = maxWall;
+            this.counter = 0;
+        }
+        if (this.counter > MAX_COUNTER) {
+            this.wallTime++;
+            this.counter = 0;
+        }
+        return createHLC(this.wallTime, this.counter, this.siteId);
+    }
+    /**
+     * Create an HLC at the current clock state without advancing.
+     * Useful for read operations.
+     */
+    now() {
+        return createHLC(this.wallTime, this.counter, this.siteId);
+    }
+}
+//# sourceMappingURL=hlc.js.map

package/dist/src/clock/hlc.js.map

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

package/dist/src/clock/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Clock module exports.
+ */
+export * from './hlc.js';
+export * from './site.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/clock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clock/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/src/clock/index.js

@@ -0,0 +1,6 @@
+/**
+ * Clock module exports.
+ */
+export * from './hlc.js';
+export * from './site.js';
+//# sourceMappingURL=index.js.map

package/dist/src/clock/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/clock/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/src/clock/site.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Site ID management - unique identifier for each replica.
+ *
+ * Site IDs are 16-byte UUIDs that uniquely identify a replica in the
+ * distributed system. They are used for:
+ * - Breaking ties in HLC comparison
+ * - Tracking which changes came from which replica
+ * - Peer-to-peer sync state tracking
+ */
+/**
+ * 16-byte unique identifier for a replica.
+ */
+export type SiteId = Uint8Array;
+/**
+ * Generate a new random site ID (UUID v4).
+ */
+export declare function generateSiteId(): SiteId;
+/**
+ * Convert a Uint8Array to base64url encoding (no padding).
+ */
+export declare function toBase64Url(bytes: Uint8Array): string;
+/**
+ * Convert a base64url string to Uint8Array.
+ */
+export declare function fromBase64Url(str: string): Uint8Array;
+/**
+ * Convert site ID to base64url string for serialization.
+ * 16 bytes → 22 characters (no padding).
+ */
+export declare function siteIdToBase64(siteId: SiteId): string;
+/**
+ * Parse site ID from base64url string.
+ */
+export declare function siteIdFromBase64(base64: string): SiteId;
+/**
+ * Compare two site IDs for equality.
+ */
+export declare function siteIdEquals(a: SiteId, b: SiteId): boolean;
+/**
+ * Storage key for site identity.
+ */
+export declare const SITE_ID_KEY = "si:";
+/**
+ * Site identity record stored in the KV store.
+ */
+export interface SiteIdentity {
+    siteId: SiteId;
+    createdAt: number;
+}
+/**
+ * Serialize site identity for storage.
+ */
+export declare function serializeSiteIdentity(identity: SiteIdentity): Uint8Array;
+/**
+ * Deserialize site identity from storage.
+ */
+export declare function deserializeSiteIdentity(buffer: Uint8Array): SiteIdentity;
+//# sourceMappingURL=site.d.ts.map

package/dist/src/clock/site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../../../src/clock/site.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAmBvC;AAKD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAmBrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA2BrD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAM1D;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,QAAQ,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,UAAU,CAQxE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY,CAUxE"}