@raviolelabs/engram-mcp 0.2.0

package/dist/sync/apply.js

@@ -0,0 +1,277 @@
+/**
+ * Conflict Resolution Rules (Phase 3 Ops Log):
+ *
+ * 1. ADD_MEMORY collision (same memory_id from two devices simultaneously):
+ *    → content_hash dedup: if content is identical, skip the incoming op (natural dedup).
+ *    → if content differs (truly concurrent inserts), BOTH are kept (different memory_id
+ *      since ID = ULID generated independently). No conflict.
+ *
+ * 2. UPDATE_PROPERTIES concurrent edits:
+ *    → Last-writer-wins per SCALAR field (by Lamport timestamp).
+ *    → ARRAY fields (tags, related_ids, wikilinks): UNION semantics — both sets merged.
+ *    → Result: no data loss, arrays only grow.
+ *
+ * 3. DELETE vs concurrent UPDATE:
+ *    → Within 5-minute grace period: higher Lamport timestamp wins.
+ *      (Update with higher ts → memory survives; delete with higher ts → memory gone.)
+ *    → After grace period: delete wins unconditionally.
+ *
+ * 4. Re-ADD of a tombstoned memory_id:
+ *    → If grace period not yet elapsed: treat as resurrection (insertWithoutLog).
+ *    → After grace period: blocked (tombstone finalized).
+ *
+ * 5. ADD_RELATION:
+ *    → Pure union: idempotent insert into related_ids.
+ */
+// src/sync/apply.ts
+import { createLogger } from '../logger.js';
+import { decryptPayload } from './ops-log.js';
+import { verifySignature, opCanonicalBytes } from './ed25519.js';
+import { AddMemoryPayloadSchema, UpdatePropertiesPayloadSchema, DeleteMemoryPayloadSchema, } from './types.js';
+const log = createLogger('sync:apply');
+/** Last-writer-wins merge for flat properties. Arrays are union-merged. */
+export function lwwMergeProperties(current, incoming, currentLamport, incomingLamport) {
+    if (incomingLamport < currentLamport) {
+        // Incoming is older — only merge arrays (union), scalar fields from current win
+        const result = { ...current };
+        for (const [key, val] of Object.entries(incoming)) {
+            if (Array.isArray(val) && Array.isArray(current[key])) {
+                result[key] = [...new Set([...current[key], ...val])];
+            }
+            // Scalar: current wins (incomingLamport is older)
+        }
+        return result;
+    }
+    // Incoming is newer — incoming scalar wins; arrays union
+    const result = { ...incoming };
+    for (const [key, val] of Object.entries(current)) {
+        if (Array.isArray(val) && Array.isArray(incoming[key])) {
+            result[key] = [...new Set([...val, ...incoming[key]])];
+        }
+        // Scalars already set from incoming spread above
+    }
+    return result;
+}
+/** Resolve delete vs concurrent update. */
+export function resolveDeleteVsUpdate(tombstone, incomingLamport, deleteLamport) {
+    if (!tombstone)
+        return 'apply_update'; // no tombstone — normal update
+    if (Date.now() < tombstone.grace_until) {
+        // Within grace period — higher lamport wins
+        return incomingLamport > deleteLamport ? 'apply_update' : 'defer';
+    }
+    // Grace period expired — delete wins
+    return 'apply_delete';
+}
+export class ReplayApplier {
+    db;
+    store;
+    masterKey;
+    constructor(db, store, masterKey) {
+        this.db = db;
+        this.store = store;
+        this.masterKey = masterKey;
+    }
+    /**
+     * Apply a single WireOp received from cloud or catch-up.
+     * Skips ops that originated from this device (already applied locally).
+     * Idempotent: re-applying the same op_id is a no-op.
+     */
+    async applyOp(op, localDeviceId) {
+        // 0. Skip own ops
+        if (op.device_id === localDeviceId) {
+            log.debug('skip own op', { op_id: op.op_id });
+            return;
+        }
+        // 1. Idempotency check
+        const existing = this.db
+            .prepare(`SELECT applied FROM ops_log WHERE op_id = ?`)
+            .get(op.op_id);
+        if (existing?.applied === 1) {
+            log.debug('op already applied', { op_id: op.op_id });
+            return;
+        }
+        // 2. Verify signature
+        const canonical = opCanonicalBytes({
+            op_id: op.op_id,
+            device_id: op.device_id,
+            lamport_ts: op.lamport_ts,
+            op_type: op.op_type,
+            memory_id: op.memory_id,
+            payload_enc: op.payload_enc,
+            nonce: op.nonce,
+        });
+        if (!verifySignature(canonical, op.sig, op.device_id)) {
+            log.warn('invalid signature — op rejected', {
+                op_id: op.op_id,
+                device: op.device_id.slice(0, 8),
+            });
+            return;
+        }
+        // 3. Decrypt payload
+        let payload;
+        try {
+            const enc = Buffer.from(op.payload_enc, 'base64');
+            const nonce = Buffer.from(op.nonce, 'base64');
+            const plain = decryptPayload(enc, nonce, this.masterKey);
+            payload = JSON.parse(plain.toString('utf8'));
+        }
+        catch (err) {
+            log.warn('failed to decrypt op payload', { op_id: op.op_id, err });
+            return;
+        }
+        // 4. Store op in local ops_log (so we track it)
+        const alreadyStored = this.db
+            .prepare(`SELECT op_id FROM ops_log WHERE op_id = ?`)
+            .get(op.op_id);
+        if (!alreadyStored) {
+            this.db
+                .prepare(`INSERT INTO ops_log
+             (op_id, device_id, lamport_ts, op_type, memory_id,
+              payload_enc, nonce, sig, sent_at, applied, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
+                .run(op.op_id, op.device_id, op.lamport_ts, op.op_type, op.memory_id, Buffer.from(op.payload_enc, 'base64'), Buffer.from(op.nonce, 'base64'), Buffer.from(op.sig, 'hex'), Date.now(), // sent_at — already sent (received from cloud)
+            op.created_at);
+        }
+        // 5. Dispatch by op_type
+        try {
+            switch (op.op_type) {
+                case 'add_memory':
+                    await this.#applyAddMemory(op, payload);
+                    break;
+                case 'update_properties':
+                    await this.#applyUpdateProperties(op, payload);
+                    break;
+                case 'delete_memory':
+                    await this.#applyDeleteMemory(op, payload);
+                    break;
+                case 'add_relation':
+                    await this.#applyAddRelation(op, payload);
+                    break;
+                default:
+                    log.warn('unknown op_type', { op_id: op.op_id, op_type: op.op_type });
+            }
+        }
+        catch (err) {
+            log.error('failed to apply op', { op_id: op.op_id, err });
+            return;
+        }
+        // 6. Mark applied
+        this.db.prepare(`UPDATE ops_log SET applied = 1 WHERE op_id = ?`).run(op.op_id);
+        log.debug('op applied', {
+            op_id: op.op_id,
+            op_type: op.op_type,
+            memory_id: op.memory_id,
+        });
+    }
+    async #applyAddMemory(op, payload) {
+        const { item } = AddMemoryPayloadSchema.parse(payload);
+        const memoryItem = item;
+        // Dedup by content_hash
+        const dup = this.db
+            .prepare(`SELECT id FROM memories WHERE content_hash = ?`)
+            .get(memoryItem.content_hash);
+        if (dup) {
+            log.debug('add_memory dedup by content_hash', {
+                op_id: op.op_id,
+                hash: memoryItem.content_hash,
+            });
+            return;
+        }
+        // Check tombstone — if deleted and grace expired, skip
+        const tomb = this.db
+            .prepare(`SELECT deleted_at, grace_until FROM tombstones WHERE memory_id = ?`)
+            .get(memoryItem.id);
+        if (tomb && Date.now() >= tomb.grace_until) {
+            log.debug('add_memory blocked by finalized tombstone', { memory_id: memoryItem.id });
+            return;
+        }
+        // Disable ops logging for the derived write (avoid double-logging)
+        await this.store.insertWithoutLog(memoryItem);
+    }
+    async #applyUpdateProperties(op, payload) {
+        const { memory_id, delta } = UpdatePropertiesPayloadSchema.parse(payload);
+        // Check tombstone
+        const tomb = this.db
+            .prepare(`SELECT deleted_at, grace_until FROM tombstones WHERE memory_id = ?`)
+            .get(memory_id);
+        // Find existing item for LWW merge
+        const existingRow = this.db
+            .prepare(`SELECT properties_json FROM memories WHERE id = ?`)
+            .get(memory_id);
+        if (!existingRow) {
+            log.debug('update_properties: memory not found locally yet', { memory_id });
+            return; // Will be applied once add_memory arrives
+        }
+        // LWW merge
+        const current = JSON.parse(existingRow.properties_json);
+        const lastUpdateLamport = this.db
+            .prepare(`SELECT MAX(lamport_ts) as m FROM ops_log
+           WHERE memory_id = ? AND op_type = 'update_properties' AND applied = 1`)
+            .get(memory_id).m ?? 0;
+        const verdict = tomb
+            ? resolveDeleteVsUpdate(tomb, op.lamport_ts, tomb.deleted_at)
+            : 'apply_update';
+        if (verdict !== 'apply_update') {
+            log.debug('update_properties blocked by tombstone resolution', { memory_id, verdict });
+            return;
+        }
+        const merged = lwwMergeProperties(current, delta, lastUpdateLamport, op.lamport_ts);
+        this.db
+            .prepare(`UPDATE memories SET properties_json = ? WHERE id = ?`)
+            .run(JSON.stringify(merged), memory_id);
+    }
+    async #applyDeleteMemory(op, payload) {
+        const { memory_id } = DeleteMemoryPayloadSchema.parse(payload);
+        const now = Date.now();
+        const GRACE_MS = 5 * 60 * 1000;
+        // Upsert tombstone
+        this.db
+            .prepare(`INSERT OR REPLACE INTO tombstones (memory_id, deleted_at, op_id, grace_until, finalized)
+         VALUES (?, ?, ?, ?, 0)`)
+            .run(memory_id, now, op.op_id, now + GRACE_MS);
+        // Immediate SQLite delete
+        this.db.prepare(`DELETE FROM memories WHERE id = ?`).run(memory_id);
+        this.db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(memory_id);
+        // LanceDB: delete now if available (grace-period LanceDB deferred cleanup handled by finalizeTombstones)
+        await this.store.deleteVectorIfExists(memory_id);
+        log.debug('delete_memory tombstone inserted', { memory_id, grace_until: now + GRACE_MS });
+    }
+    async #applyAddRelation(_op, payload) {
+        const { from_id, to_id } = payload;
+        // Add to_id to from_id's related_ids if not present
+        const row = this.db
+            .prepare(`SELECT related_ids_json FROM memories WHERE id = ?`)
+            .get(from_id);
+        if (!row)
+            return;
+        const ids = JSON.parse(row.related_ids_json ?? '[]');
+        if (!ids.includes(to_id)) {
+            ids.push(to_id);
+            this.db
+                .prepare(`UPDATE memories SET related_ids_json = ? WHERE id = ?`)
+                .run(JSON.stringify(ids), from_id);
+        }
+    }
+}
+/**
+ * Finalize tombstones whose grace period has elapsed.
+ * Deletes from LanceDB and marks the tombstone as finalized.
+ * Called from a local cron (every 10 minutes).
+ */
+export async function finalizeTombstones(db, store) {
+    const now = Date.now();
+    const expired = db
+        .prepare(`SELECT memory_id FROM tombstones
+       WHERE finalized = 0 AND grace_until < ?`)
+        .all(now);
+    for (const { memory_id } of expired) {
+        await store.deleteVectorIfExists(memory_id);
+        db.prepare(`UPDATE tombstones SET finalized = 1 WHERE memory_id = ?`).run(memory_id);
+        log.debug('tombstone finalized', { memory_id });
+    }
+    if (expired.length > 0) {
+        log.info('finalized tombstones', { count: expired.length });
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/sync/apply.js.map

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

package/dist/sync/channel-client.d.ts

@@ -0,0 +1,27 @@
+import type { OpsLogger } from './ops-log.js';
+import type { ReplayApplier } from './apply.js';
+export interface ChannelClientConfig {
+    cloudBaseUrl: string;
+    jwtToken: string;
+    deviceId: string;
+    opsLogger: OpsLogger;
+    applier: ReplayApplier;
+    localDeviceId: string;
+}
+export declare class ChannelClient {
+    #private;
+    private cfg;
+    private ws;
+    private reconnectMs;
+    private stopped;
+    private pingTimer;
+    private pushTimer;
+    constructor(cfg: ChannelClientConfig);
+    /** Start the channel — connect + schedule periodic push of pending ops. */
+    start(): void;
+    /** Gracefully stop the channel. */
+    stop(): void;
+    /** Trigger an immediate push of pending ops (call after a local write). */
+    pushNow(): Promise<void>;
+}
+//# sourceMappingURL=channel-client.d.ts.map

package/dist/sync/channel-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-client.d.ts","sourceRoot":"","sources":["../../src/sync/channel-client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAUhD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAa;;IACxB,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA+C;gBAEpD,GAAG,EAAE,mBAAmB;IAIpC,2EAA2E;IAC3E,KAAK,IAAI,IAAI;IASb,mCAAmC;IACnC,IAAI,IAAI,IAAI;IAiBZ,2EAA2E;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkH/B"}

package/dist/sync/channel-client.js

@@ -0,0 +1,154 @@
+// src/sync/channel-client.ts
+import WebSocket from 'ws';
+import { createLogger } from '../logger.js';
+import { WireOpSchema } from './types.js';
+const log = createLogger('sync:channel-client');
+const RECONNECT_BASE_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+const PING_INTERVAL_MS = 30_000;
+export class ChannelClient {
+    cfg;
+    ws = null;
+    reconnectMs = RECONNECT_BASE_MS;
+    stopped = false;
+    pingTimer = null;
+    pushTimer = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Start the channel — connect + schedule periodic push of pending ops. */
+    start() {
+        this.stopped = false;
+        this.#connect();
+        // Push pending ops every 10 seconds even if WS is offline (will retry on reconnect)
+        this.pushTimer = setInterval(() => {
+            this.#pushPending().catch(() => { });
+        }, 10_000);
+    }
+    /** Gracefully stop the channel. */
+    stop() {
+        this.stopped = true;
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        if (this.pushTimer) {
+            clearInterval(this.pushTimer);
+            this.pushTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close(1000, 'client stop');
+            this.ws = null;
+        }
+        log.info('channel client stopped');
+    }
+    /** Trigger an immediate push of pending ops (call after a local write). */
+    async pushNow() {
+        await this.#pushPending();
+    }
+    #connect() {
+        if (this.stopped)
+            return;
+        const url = new URL(`${this.cfg.cloudBaseUrl}/sync/ws`);
+        url.searchParams.set('device_id', this.cfg.deviceId);
+        log.info('connecting to sync channel', { url: url.toString() });
+        const ws = new WebSocket(url.toString(), {
+            headers: { Authorization: `Bearer ${this.cfg.jwtToken}` },
+        });
+        this.ws = ws;
+        ws.on('open', () => {
+            log.info('sync channel connected');
+            this.reconnectMs = RECONNECT_BASE_MS;
+            this.#pushPending().catch(() => { });
+            this.pingTimer = setInterval(() => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(JSON.stringify({ type: 'ping' }));
+                }
+            }, PING_INTERVAL_MS);
+        });
+        ws.on('message', (data) => {
+            this.#onMessage(data.toString()).catch((err) => {
+                log.warn('error handling incoming message', { err });
+            });
+        });
+        ws.on('close', () => {
+            log.info('sync channel closed, scheduling reconnect', { nextMs: this.reconnectMs });
+            if (this.pingTimer) {
+                clearInterval(this.pingTimer);
+                this.pingTimer = null;
+            }
+            this.ws = null;
+            if (!this.stopped) {
+                setTimeout(() => this.#connect(), this.reconnectMs);
+                this.reconnectMs = Math.min(this.reconnectMs * 2, RECONNECT_MAX_MS);
+            }
+        });
+        ws.on('error', (err) => {
+            log.warn('sync channel WS error', { err: err.message });
+            // 'close' event fires after error — reconnect handled there
+        });
+    }
+    async #onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            log.warn('received non-JSON message', { raw });
+            return;
+        }
+        if (msg.type === 'incoming_ops' && Array.isArray(msg.ops)) {
+            log.debug('received incoming ops', { count: msg.ops.length });
+            for (const rawOp of msg.ops) {
+                try {
+                    const op = WireOpSchema.parse(rawOp);
+                    await this.cfg.applier.applyOp(op, this.cfg.localDeviceId);
+                }
+                catch (err) {
+                    log.warn('failed to parse/apply incoming op', { err });
+                }
+            }
+        }
+        // 'pong' is informational — no action needed
+    }
+    async #pushPending() {
+        const pending = this.cfg.opsLogger.listPending();
+        if (pending.length === 0)
+            return;
+        // Prefer WS when connected — lower latency and no extra round-trip.
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            log.debug('pushing pending ops via WS', { count: pending.length });
+            this.ws.send(JSON.stringify({ type: 'push_ops', ops: pending }));
+            this.cfg.opsLogger.markSent(pending.map((op) => op.op_id));
+            return;
+        }
+        // WS is offline — fall back to HTTP POST /sync/ops so ops are not silently lost.
+        log.debug('WS offline, pushing pending ops via HTTP POST', { count: pending.length });
+        try {
+            const res = await fetch(`${this.cfg.cloudBaseUrl}/sync/ops`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.cfg.jwtToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    ops: pending,
+                    device_id: this.cfg.deviceId,
+                    last_lamport: pending[pending.length - 1]?.lamport_ts ?? 0,
+                }),
+            });
+            if (res.ok) {
+                this.cfg.opsLogger.markSent(pending.map((op) => op.op_id));
+                const result = (await res.json());
+                log.info('HTTP POST flush accepted', result);
+            }
+            else {
+                log.warn('HTTP POST flush failed', { status: res.status });
+            }
+        }
+        catch (err) {
+            log.warn('HTTP POST flush error', { err: err.message });
+        }
+    }
+}
+//# sourceMappingURL=channel-client.js.map

package/dist/sync/channel-client.js.map

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

package/dist/sync/cloud-saves.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cloud Saves — nightly encrypted snapshot of SQLite DB.
+ *
+ * Flow:
+ *   1. Checkpoint SQLite WAL and copy the DB file to a temp location.
+ *   2. Get the current Lamport timestamp from ops_log.
+ *   3. Encrypt the DB bytes with libsodium secretstream (master key).
+ *   4. PUT /saves/snapshot → engram-cloud (sends body).
+ *   5. Record snapshot in local snapshot_log table.
+ *   6. GC local temp files.
+ *
+ * Bootstrap (new PC):
+ *   1. GET /saves/snapshot → list available snapshots.
+ *   2. Download latest snapshot.
+ *   3. Decrypt → restore SQLite.
+ *   4. Fetch and replay ops_log deltas > snapshot lamport_ts (Plan N protocol).
+ */
+export declare function initCloudSaves(params: {
+    masterKey: Buffer;
+    jwt: string;
+    cloudBaseUrl?: string;
+}): void;
+export declare function clearCloudSaves(): void;
+/** Schedule the nightly snapshot at 03:00 local time. */
+export declare function scheduleNightlySnapshot(): NodeJS.Timeout;
+/**
+ * Take a snapshot now. Can be called manually (e.g., from a dashboard button).
+ */
+export declare function takeSnapshot(): Promise<{
+    id: string;
+    sizeBytes: number;
+}>;
+/**
+ * Bootstrap a new PC from the latest cloud snapshot.
+ * Decrypts the snapshot and restores the SQLite DB in-place.
+ * After this, the caller should replay ops_log deltas > lamportTs from the cloud relay.
+ */
+export declare function bootstrapFromSnapshot(params: {
+    masterKey: Buffer;
+    jwt: string;
+    dataDir: string;
+    cloudBaseUrl?: string;
+}): Promise<{
+    lamportTs: number;
+    sizeBytes: number;
+} | null>;
+export declare function encryptBuffer(plain: Buffer, key: Buffer): Promise<Buffer>;
+export declare function decryptBuffer(encrypted: Buffer, key: Buffer): Promise<Buffer>;
+//# sourceMappingURL=cloud-saves.d.ts.map

package/dist/sync/cloud-saves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-saves.d.ts","sourceRoot":"","sources":["../../src/sync/cloud-saves.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG;AAiBH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,IAAI,CAKP;AAED,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,OAAO,CA0BxD;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA6D/E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAkD3D;AAMD,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB/E;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBnF"}