@ifc-lite/collab-server 0.2.0

package/dist/path-locks.js

@@ -0,0 +1,176 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Per-section / per-path write locks (spec §8.2 — open problem #7).
+ *
+ * Granular locks beyond role-based gating: an admin can declare that
+ * specific entity-path prefixes (or relationship/geometry paths) are
+ * temporarily read-only — e.g. "MEP coordination is in review, no
+ * structural changes." The server inspects each incoming Y update,
+ * decodes the affected paths, and rejects writes that touch any
+ * locked prefix.
+ *
+ * The lock policy is path-prefix matching: a lock on
+ * `proj/arch/storey-1/` blocks writes to any entity whose path starts
+ * with that prefix. Locks may also exempt specific principals (e.g.
+ * the locking admin can still edit) via `exemptUserIds` /
+ * `exemptRoles`.
+ *
+ * Implementation note: we don't decode the entire Y update wire
+ * format here — instead, we run the update through a throwaway Y.Doc
+ * to reuse Yjs's parser, then walk the resulting tr.changed map to
+ * harvest paths. That's O(update_size) but only runs on writes from
+ * non-exempt principals.
+ */
+import * as Y from 'yjs';
+import * as decoding from 'lib0/decoding';
+import * as syncProtocol from 'y-protocols/sync';
+export function createPathLockRegistry() {
+    const locks = [];
+    return {
+        list: () => [...locks],
+        add(lock) {
+            locks.push(lock);
+            return lock;
+        },
+        remove(lock) {
+            const idx = locks.indexOf(lock);
+            if (idx < 0)
+                return false;
+            locks.splice(idx, 1);
+            return true;
+        },
+        clear() {
+            locks.length = 0;
+        },
+        matches(path, principal) {
+            for (const lock of locks) {
+                if (!path.startsWith(lock.prefix))
+                    continue;
+                if (lock.exemptUserIds?.has(principal.userId))
+                    continue;
+                if (lock.exemptRoles?.has(principal.role))
+                    continue;
+                return lock;
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Apply `update` to a throwaway Y.Doc and harvest the touched paths
+ * as a list of `<top>/<key>` strings (`entities/wall`, `geometry/g1`,
+ * etc.). Each top-level shared type the runtime knows about is
+ * inspected.
+ */
+export function harvestUpdatePaths(update) {
+    const tmp = new Y.Doc();
+    tmp.getMap('entities');
+    tmp.getMap('relationships');
+    tmp.getMap('geometry');
+    tmp.getMap('meta');
+    const touched = new Set();
+    const onAfter = (tr) => {
+        for (const [type, keys] of tr.changed.entries()) {
+            let node = type;
+            const basePath = [];
+            while (node) {
+                const item = node._item;
+                if (!item) {
+                    // Top-level: find its name.
+                    const name = topLevelKeyOf(node, tmp);
+                    if (name)
+                        basePath.unshift(name);
+                    break;
+                }
+                if (typeof item.parentSub === 'string')
+                    basePath.unshift(item.parentSub);
+                node = item.parent;
+            }
+            if (basePath.length === 0)
+                continue;
+            // Always emit the base path itself …
+            touched.add(basePath.join('/'));
+            // … and every changed key under it (key === null means the
+            // change is on a Y.Array's internal struct list — only the
+            // base path is meaningful).
+            for (const key of keys) {
+                if (key === null)
+                    continue;
+                touched.add([...basePath, key].join('/'));
+            }
+        }
+    };
+    tmp.on('afterTransaction', onAfter);
+    Y.applyUpdate(tmp, update);
+    tmp.off('afterTransaction', onAfter);
+    tmp.destroy();
+    return [...touched];
+}
+function topLevelKeyOf(type, doc) {
+    for (const [name, shared] of doc.share) {
+        if (shared === type)
+            return name;
+    }
+    return null;
+}
+/**
+ * Build a `VerifyMessageFn` that rejects sync-update messages whose
+ * harvested paths intersect a locked prefix (and whose principal
+ * isn't exempt). Pass-through for non-update frames.
+ */
+export function verifyAgainstPathLocks(registry) {
+    return (msg, conn) => {
+        if (msg.byteLength === 0)
+            return { ok: true };
+        // Outer envelope is the y-protocols sync frame: [varint type][...].
+        const decoder = decoding.createDecoder(msg);
+        let outerType;
+        try {
+            outerType = decoding.readVarUint(decoder);
+        }
+        catch {
+            // Malformed envelope: pass through. The frame can't apply anything
+            // to the doc, so room-manager's own readSyncMessage will swallow
+            // it without side effects.
+            return { ok: true };
+        }
+        // Outer 0 = sync; inner 0/1/2 = step1/step2/update.
+        if (outerType !== 0)
+            return { ok: true };
+        let inner;
+        try {
+            inner = decoding.readVarUint(decoder);
+        }
+        catch {
+            return { ok: true };
+        }
+        // Both messageYjsSyncStep2 and messageYjsUpdate carry a Yjs binary
+        // update payload that readSyncMessage applies to the doc as a side
+        // effect — they must both go through path-lock checking. Step1 is
+        // pure read intent and is exempt.
+        const isWriteFrame = inner === syncProtocol.messageYjsUpdate ||
+            inner === syncProtocol.messageYjsSyncStep2;
+        if (!isWriteFrame)
+            return { ok: true };
+        let payload;
+        try {
+            payload = decoding.readVarUint8Array(decoder);
+        }
+        catch {
+            // A write-frame with an unreadable payload is suspicious — fail
+            // closed rather than waving the message through to the doc.
+            return { ok: false, reason: 'malformed-update-payload' };
+        }
+        const paths = harvestUpdatePaths(payload);
+        for (const p of paths) {
+            const hit = registry.matches(p, conn.principal);
+            if (hit) {
+                return { ok: false, reason: `locked:${hit.label ?? hit.prefix}` };
+            }
+        }
+        return { ok: true };
+    };
+}
+//# sourceMappingURL=path-locks.js.map

package/dist/path-locks.js.map

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

package/dist/persistence-redis.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Redis persistence backend (spec §12.2).
+ *
+ * Same trick as `S3Persistence`: implemented against a tiny
+ * `RedisLikeClient` interface so deployers wire up `ioredis`,
+ * `node-redis`, or any compatible client without forcing
+ * `@ifc-lite/collab-server` to take a hard dep.
+ *
+ * Layout per room:
+ *   - key `<prefix><roomId>:snap`   ← compacted state (Buffer)
+ *   - list `<prefix><roomId>:log`   ← rolling log frames (Buffer items)
+ *
+ * `load(roomId)` returns `concat(snap, ...all log items)`. `compact`
+ * sets `:snap` and trims `:log` to empty. `drop` deletes both keys.
+ */
+import type { Persistence } from './persistence.js';
+/**
+ * Minimal Redis-like surface. The two big Node clients (ioredis,
+ * node-redis 4+) both satisfy this when wrapped trivially. Buffers
+ * are returned for binary fidelity.
+ */
+export interface RedisLikeClient {
+    /** Get a binary string value, or `null` if missing. */
+    getBuffer(key: string): Promise<Buffer | null>;
+    /** Set a binary string value (no expiry by default). */
+    set(key: string, value: Buffer): Promise<unknown>;
+    /** RPUSH a buffer onto a list. */
+    rpush(key: string, value: Buffer): Promise<unknown>;
+    /** LRANGE 0 -1 returning all binary items in order. */
+    lrangeBuffer(key: string): Promise<Buffer[]>;
+    /** DEL one or more keys. */
+    del(...keys: string[]): Promise<unknown>;
+    /** LTRIM <key> <start> <stop>. */
+    ltrim(key: string, start: number, stop: number): Promise<unknown>;
+}
+export interface RedisPersistenceOptions {
+    client: RedisLikeClient;
+    /** Optional key prefix, e.g. `'collab:'`. Default `''`. */
+    prefix?: string;
+}
+export declare class RedisPersistence implements Persistence {
+    private readonly client;
+    private readonly prefix;
+    constructor(opts: RedisPersistenceOptions);
+    private snapKey;
+    private logKey;
+    load(roomId: string): Promise<Uint8Array | null>;
+    append(roomId: string, update: Uint8Array): Promise<void>;
+    compact(roomId: string, mergedState: Uint8Array): Promise<void>;
+    drop(roomId: string): Promise<void>;
+}
+//# sourceMappingURL=persistence-redis.d.ts.map

package/dist/persistence-redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-redis.d.ts","sourceRoot":"","sources":["../src/persistence-redis.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,wDAAwD;IACxD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,kCAAkC;IAClC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,uDAAuD;IACvD,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,4BAA4B;IAC5B,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,kCAAkC;IAClC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,EAAE,uBAAuB;IAKzC,OAAO,CAAC,OAAO;IAGf,OAAO,CAAC,MAAM;IAIR,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmBhD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/persistence-redis.js

@@ -0,0 +1,50 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+export class RedisPersistence {
+    client;
+    prefix;
+    constructor(opts) {
+        this.client = opts.client;
+        this.prefix = opts.prefix ?? '';
+    }
+    snapKey(roomId) {
+        return `${this.prefix}${roomId}:snap`;
+    }
+    logKey(roomId) {
+        return `${this.prefix}${roomId}:log`;
+    }
+    async load(roomId) {
+        const [snap, frames] = await Promise.all([
+            this.client.getBuffer(this.snapKey(roomId)),
+            this.client.lrangeBuffer(this.logKey(roomId)),
+        ]);
+        const parts = [];
+        if (snap && snap.byteLength > 0)
+            parts.push(snap);
+        for (const f of frames ?? [])
+            parts.push(f);
+        if (parts.length === 0)
+            return null;
+        const total = parts.reduce((n, p) => n + p.byteLength, 0);
+        const out = new Uint8Array(total);
+        let o = 0;
+        for (const p of parts) {
+            out.set(new Uint8Array(p.buffer, p.byteOffset, p.byteLength), o);
+            o += p.byteLength;
+        }
+        return out;
+    }
+    async append(roomId, update) {
+        await this.client.rpush(this.logKey(roomId), Buffer.from(update));
+    }
+    async compact(roomId, mergedState) {
+        await this.client.set(this.snapKey(roomId), Buffer.from(mergedState));
+        // Truncate the log to empty.
+        await this.client.ltrim(this.logKey(roomId), 1, 0);
+    }
+    async drop(roomId) {
+        await this.client.del(this.snapKey(roomId), this.logKey(roomId));
+    }
+}
+//# sourceMappingURL=persistence-redis.js.map

package/dist/persistence-redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-redis.js","sourceRoot":"","sources":["../src/persistence-redis.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AA8C/D,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAkB;IACxB,MAAM,CAAS;IAEhC,YAAY,IAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;IAClC,CAAC;IAEO,OAAO,CAAC,MAAc;QAC5B,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,MAAM,OAAO,CAAC;IACxC,CAAC;IACO,MAAM,CAAC,MAAc;QAC3B,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,MAAM,MAAM,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SAC9C,CAAC,CAAC;QACH,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClD,KAAK,MAAM,CAAC,IAAI,MAAM,IAAI,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,GAAG,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;QACpB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAkB;QAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,WAAuB;QACnD,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;QACtE,6BAA6B;QAC7B,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,CAAC;CACF"}

package/dist/persistence-s3.d.ts

@@ -0,0 +1,81 @@
+import type { Persistence } from './persistence.js';
+/** Minimum S3 surface we need; AWS SDK satisfies it directly. */
+export interface S3LikeClient {
+    send(command: unknown): Promise<unknown>;
+}
+export interface S3Commands {
+    PutObjectCommand: new (input: PutObjectInput) => unknown;
+    GetObjectCommand: new (input: GetObjectInput) => unknown;
+    DeleteObjectCommand: new (input: {
+        Bucket: string;
+        Key: string;
+    }) => unknown;
+    ListObjectsV2Command: new (input: {
+        Bucket: string;
+        Prefix?: string;
+    }) => unknown;
+    HeadObjectCommand?: new (input: {
+        Bucket: string;
+        Key: string;
+    }) => unknown;
+}
+export interface PutObjectInput {
+    Bucket: string;
+    Key: string;
+    Body: Uint8Array | Buffer;
+    ContentType?: string;
+}
+export interface GetObjectInput {
+    Bucket: string;
+    Key: string;
+}
+export interface S3PersistenceOptions {
+    client: S3LikeClient;
+    commands: S3Commands;
+    bucket: string;
+    /** Optional key prefix, e.g. `'collab/'`. Default `''`. */
+    prefix?: string;
+    /** Frame size cap in bytes per log entry. Default 1 MB. */
+    frameMaxBytes?: number;
+}
+export declare class S3Persistence implements Persistence {
+    private readonly client;
+    private readonly cmds;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly frameMaxBytes;
+    /**
+     * In-process monotonic counter — guarantees same-millisecond appends
+     * sort in submission order. Combined with `randomBytes` it stays
+     * globally unique across processes.
+     */
+    private appendCounter;
+    constructor(opts: S3PersistenceOptions);
+    /**
+     * Map a room id to a safe, *unique* key segment. `encodeURIComponent`
+     * preserves distinct ids (so `a/b` and `a_b` never collide) while keeping
+     * the result safe for S3 keys.
+     */
+    private safeRoom;
+    private snapKey;
+    /**
+     * Per-frame key composed of:
+     *   - a fixed-width unix-ms timestamp (sorts by wall-clock order),
+     *   - an in-process monotonic counter (breaks ties when two appends
+     *     land in the same millisecond — without this, two same-ms
+     *     appends from the same writer could replay out of order),
+     *   - a random suffix (gives cross-process uniqueness when multiple
+     *     server instances serve the same room).
+     *
+     * Lexicographic key ordering = chronological-then-submission ordering,
+     * which is what `load()` relies on.
+     */
+    private logKey;
+    private getObjectBytes;
+    load(roomId: string): Promise<Uint8Array | null>;
+    append(roomId: string, update: Uint8Array): Promise<void>;
+    compact(roomId: string, mergedState: Uint8Array): Promise<void>;
+    drop(roomId: string): Promise<void>;
+    private removeLog;
+}
+//# sourceMappingURL=persistence-s3.d.ts.map

package/dist/persistence-s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-s3.d.ts","sourceRoot":"","sources":["../src/persistence-s3.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,KAAK,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC;IACzD,gBAAgB,EAAE,KAAK,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC;IACzD,mBAAmB,EAAE,KAAK,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IAC7E,oBAAoB,EAAE,KAAK,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IAClF,iBAAiB,CAAC,EAAE,KAAK,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;CAC7E;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAK;gBAEd,IAAI,EAAE,oBAAoB;IAQtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM;YASA,cAAc;IAqBtB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAqBhD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBzD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAQ3B,SAAS;CAaxB"}

package/dist/persistence-s3.js

@@ -0,0 +1,183 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * S3 persistence backend (spec §12.2).
+ *
+ * Implements the `Persistence` interface against any S3-compatible
+ * object store (AWS S3, R2, MinIO, etc.). To keep `@ifc-lite/collab-server`
+ * free of a hard `@aws-sdk/client-s3` dependency, this module accepts
+ * a tiny `S3Client`-shaped interface that the deployer fulfils — either
+ * by passing the real SDK directly (the AWS SDK satisfies the shape) or
+ * by writing a thin shim around their preferred storage client.
+ *
+ * Layout per room:
+ *   - `s3://bucket/<prefix><safeRoomId>.snap`            ← compacted state
+ *   - `s3://bucket/<prefix><safeRoomId>.log/<ulid>.bin`  ← rolling log frames
+ *
+ * Compaction overwrites `.snap` and truncates the log directory.
+ *
+ * Frame keys are ULID-like (sortable timestamp prefix + random suffix), not
+ * monotonic per-process counters, so multiple writers serving the same room
+ * never produce identical keys. They remain lexicographically sortable, which
+ * is what `load()` relies on to replay frames in append order.
+ *
+ * Room IDs are `encodeURIComponent`-escaped rather than replaced with `_`,
+ * so distinct room IDs never collapse to the same storage prefix.
+ */
+import { randomBytes } from 'node:crypto';
+export class S3Persistence {
+    client;
+    cmds;
+    bucket;
+    prefix;
+    frameMaxBytes;
+    /**
+     * In-process monotonic counter — guarantees same-millisecond appends
+     * sort in submission order. Combined with `randomBytes` it stays
+     * globally unique across processes.
+     */
+    appendCounter = 0;
+    constructor(opts) {
+        this.client = opts.client;
+        this.cmds = opts.commands;
+        this.bucket = opts.bucket;
+        this.prefix = opts.prefix ?? '';
+        this.frameMaxBytes = opts.frameMaxBytes ?? 1024 * 1024;
+    }
+    /**
+     * Map a room id to a safe, *unique* key segment. `encodeURIComponent`
+     * preserves distinct ids (so `a/b` and `a_b` never collide) while keeping
+     * the result safe for S3 keys.
+     */
+    safeRoom(roomId) {
+        return encodeURIComponent(roomId);
+    }
+    snapKey(roomId) {
+        return `${this.prefix}${this.safeRoom(roomId)}.snap`;
+    }
+    /**
+     * Per-frame key composed of:
+     *   - a fixed-width unix-ms timestamp (sorts by wall-clock order),
+     *   - an in-process monotonic counter (breaks ties when two appends
+     *     land in the same millisecond — without this, two same-ms
+     *     appends from the same writer could replay out of order),
+     *   - a random suffix (gives cross-process uniqueness when multiple
+     *     server instances serve the same room).
+     *
+     * Lexicographic key ordering = chronological-then-submission ordering,
+     * which is what `load()` relies on.
+     */
+    logKey(roomId) {
+        // 13-digit unix-ms is good through the year 2286; pad to 14 for safety.
+        const ts = Date.now().toString().padStart(14, '0');
+        this.appendCounter = (this.appendCounter + 1) >>> 0;
+        const seq = this.appendCounter.toString(16).padStart(8, '0');
+        const rand = randomBytes(8).toString('hex');
+        return `${this.prefix}${this.safeRoom(roomId)}.log/${ts}-${seq}-${rand}.bin`;
+    }
+    async getObjectBytes(key) {
+        const Get = this.cmds.GetObjectCommand;
+        try {
+            const res = await this.client.send(new Get({ Bucket: this.bucket, Key: key }));
+            const body = res.Body;
+            if (body?.transformToByteArray) {
+                return await body.transformToByteArray();
+            }
+            // Stream-shape body: collect chunks.
+            if (body && typeof body[Symbol.asyncIterator] === 'function') {
+                const chunks = [];
+                for await (const chunk of body)
+                    chunks.push(chunk);
+                return concat(chunks);
+            }
+            return null;
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return null;
+            throw err;
+        }
+    }
+    async load(roomId) {
+        // Snapshot first, then concatenated log frames after it.
+        const snap = await this.getObjectBytes(this.snapKey(roomId));
+        const List = this.cmds.ListObjectsV2Command;
+        const list = (await this.client.send(new List({ Bucket: this.bucket, Prefix: `${this.prefix}${this.safeRoom(roomId)}.log/` })));
+        const keys = (list.Contents ?? [])
+            .map((c) => c.Key)
+            .filter((k) => typeof k === 'string')
+            .sort();
+        const frames = snap ? [snap] : [];
+        for (const key of keys) {
+            const bytes = await this.getObjectBytes(key);
+            if (bytes)
+                frames.push(bytes);
+        }
+        if (frames.length === 0)
+            return null;
+        return concat(frames);
+    }
+    async append(roomId, update) {
+        if (update.byteLength > this.frameMaxBytes) {
+            throw new Error(`@ifc-lite/collab-server: frame ${update.byteLength}B exceeds frameMaxBytes ${this.frameMaxBytes}`);
+        }
+        const Put = this.cmds.PutObjectCommand;
+        await this.client.send(new Put({
+            Bucket: this.bucket,
+            Key: this.logKey(roomId),
+            Body: Buffer.from(update),
+            ContentType: 'application/octet-stream',
+        }));
+    }
+    async compact(roomId, mergedState) {
+        const Put = this.cmds.PutObjectCommand;
+        await this.client.send(new Put({
+            Bucket: this.bucket,
+            Key: this.snapKey(roomId),
+            Body: Buffer.from(mergedState),
+            ContentType: 'application/octet-stream',
+        }));
+        await this.removeLog(roomId);
+    }
+    async drop(roomId) {
+        const Del = this.cmds.DeleteObjectCommand;
+        await Promise.all([
+            this.client.send(new Del({ Bucket: this.bucket, Key: this.snapKey(roomId) })).catch(swallowNotFound),
+            this.removeLog(roomId),
+        ]);
+    }
+    async removeLog(roomId) {
+        const List = this.cmds.ListObjectsV2Command;
+        const Del = this.cmds.DeleteObjectCommand;
+        const list = (await this.client.send(new List({ Bucket: this.bucket, Prefix: `${this.prefix}${this.safeRoom(roomId)}.log/` })));
+        const keys = (list.Contents ?? []).map((c) => c.Key).filter((k) => typeof k === 'string');
+        await Promise.all(keys.map((k) => this.client.send(new Del({ Bucket: this.bucket, Key: k })).catch(swallowNotFound)));
+    }
+}
+function concat(arr) {
+    const total = arr.reduce((n, a) => n + a.byteLength, 0);
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const a of arr) {
+        out.set(a, o);
+        o += a.byteLength;
+    }
+    return out;
+}
+function isNotFound(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.name === 'NoSuchKey' || e.Code === 'NoSuchKey')
+        return true;
+    if (e.$metadata?.httpStatusCode === 404)
+        return true;
+    return false;
+}
+function swallowNotFound(err) {
+    if (isNotFound(err))
+        return;
+    throw err;
+}
+//# sourceMappingURL=persistence-s3.js.map

package/dist/persistence-s3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-s3.js","sourceRoot":"","sources":["../src/persistence-s3.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAsC1C,MAAM,OAAO,aAAa;IACP,MAAM,CAAe;IACrB,IAAI,CAAa;IACjB,MAAM,CAAS;IACf,MAAM,CAAS;IACf,aAAa,CAAS;IACvC;;;;OAIG;IACK,aAAa,GAAG,CAAC,CAAC;IAE1B,YAAY,IAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,GAAG,IAAI,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACK,QAAQ,CAAC,MAAc;QAC7B,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAEO,OAAO,CAAC,MAAc;QAC5B,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;OAWG;IACK,MAAM,CAAC,MAAc;QAC3B,wEAAwE;QACxE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACnD,IAAI,CAAC,aAAa,GAAG,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,IAAI,MAAM,CAAC;IAC/E,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,GAAW;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAC/E,MAAM,IAAI,GAAI,GAAuE,CAAC,IAAI,CAAC;YAC3F,IAAI,IAAI,EAAE,oBAAoB,EAAE,CAAC;gBAC/B,OAAO,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC3C,CAAC;YACD,qCAAqC;YACrC,IAAI,IAAI,IAAI,OAAQ,IAAkC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,EAAE,CAAC;gBAC5F,MAAM,MAAM,GAAiB,EAAE,CAAC;gBAChC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAiC;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAChF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,UAAU,CAAC,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;YACjC,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,yDAAyD;QACzD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAClC,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CACzF,CAAkE,CAAC;QACpE,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;aACjB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;aACjD,IAAI,EAAE,CAAC;QACV,MAAM,MAAM,GAAiB,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAErC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,MAAkB;QAC7C,IAAI,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACb,kCAAkC,MAAM,CAAC,UAAU,2BAA2B,IAAI,CAAC,aAAa,EAAE,CACnG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC;QACvC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACpB,IAAI,GAAG,CAAC;YACN,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;YACzB,WAAW,EAAE,0BAA0B;SACxC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,WAAuB;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC;QACvC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACpB,IAAI,GAAG,CAAC;YACN,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YACzB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC;YAC9B,WAAW,EAAE,0BAA0B;SACxC,CAAC,CACH,CAAC;QACF,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC;QAC1C,MAAM,OAAO,CAAC,GAAG,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;YACpG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SACvB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,MAAc;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC;QAC1C,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAClC,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CACzF,CAA2C,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QACvG,MAAM,OAAO,CAAC,GAAG,CACf,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACb,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAClF,CACF,CAAC;IACJ,CAAC;CACF;AAED,SAAS,MAAM,CAAC,GAAiB;IAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACd,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC9B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,CAAC,GAAG,GAAgF,CAAC;IAC3F,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAClE,IAAI,CAAC,CAAC,SAAS,EAAE,cAAc,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,GAAY;IACnC,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO;IAC5B,MAAM,GAAG,CAAC;AACZ,CAAC"}

package/dist/persistence.d.ts

@@ -0,0 +1,41 @@
+export interface Persistence {
+    /** Load any saved updates for `roomId` and return them as a single merged blob. */
+    load(roomId: string): Promise<Uint8Array | null>;
+    /** Append `update` to `roomId`'s log. */
+    append(roomId: string, update: Uint8Array): Promise<void>;
+    /** Replace the room's log with a freshly compacted state (called periodically). */
+    compact(roomId: string, mergedState: Uint8Array): Promise<void>;
+    /** Hard-delete a room. */
+    drop(roomId: string): Promise<void>;
+}
+export declare class MemoryPersistence implements Persistence {
+    private readonly logs;
+    load(roomId: string): Promise<Uint8Array | null>;
+    append(roomId: string, update: Uint8Array): Promise<void>;
+    compact(roomId: string, mergedState: Uint8Array): Promise<void>;
+    drop(roomId: string): Promise<void>;
+}
+export interface FilePersistenceOptions {
+    /** Root directory for room logs. */
+    dataDir: string;
+}
+/**
+ * Append-only file-per-room persistence.
+ *
+ * Update layout: each `append()` writes one frame `[length:u32][bytes]`
+ * to `<dataDir>/<sanitizedRoomId>.log`. `load()` reads the file and
+ * returns the concatenated payload.
+ *
+ * Compaction rewrites the log atomically by writing to a temp file then
+ * renaming.
+ */
+export declare class FilePersistence implements Persistence {
+    private readonly dataDir;
+    constructor(opts: FilePersistenceOptions);
+    private logPath;
+    load(roomId: string): Promise<Uint8Array | null>;
+    append(roomId: string, update: Uint8Array): Promise<void>;
+    compact(roomId: string, mergedState: Uint8Array): Promise<void>;
+    drop(roomId: string): Promise<void>;
+}
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACjD,yCAAyC;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,mFAAmF;IACnF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,0BAA0B;IAC1B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IAElD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAMhD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C;AAED,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,IAAI,EAAE,sBAAsB;IAKxC,OAAO,CAAC,OAAO;IAKT,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkBhD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM1C"}