@ibgib/core-gib 0.1.9 → 0.1.10

package/dist/sync/sync-constants.mjs

@@ -0,0 +1,16 @@
+export const SYNC_ATOM = "sync";
+/**
+ * Protocol version string for V1.
+ */
+export const SYNC_PROTOCOL_V1 = "sync 1.0.0";
+export const SYNC_STAGE_INIT = "init";
+export const SYNC_STAGE_REQUEST = "request";
+export const SYNC_STAGE_DELTA = "delta";
+export const SYNC_STAGE_COMMIT = "commit";
+export const SyncStage = {
+    init: SYNC_STAGE_INIT,
+    request: SYNC_STAGE_REQUEST,
+    delta: SYNC_STAGE_DELTA,
+    commit: SYNC_STAGE_COMMIT,
+};
+//# sourceMappingURL=sync-constants.mjs.map

package/dist/sync/sync-constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-constants.mjs","sourceRoot":"","sources":["../../src/sync/sync-constants.mts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAC5C,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAQ1C,MAAM,CAAC,MAAM,SAAS,GAAG;IACrB,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,iBAAiB;CACnB,CAAC"}

package/dist/sync/sync-helpers.d.mts

@@ -0,0 +1,15 @@
+import { Ib } from "@ibgib/ts-gib/dist/types.mjs";
+import { SyncData_V1, SyncIbInfo_V1 } from "./sync-types.mjs";
+/**
+ * Constructs the standard 'ib' string for a Sync frame.
+ */
+export declare function getSyncIb({ data, }: {
+    data: SyncData_V1;
+}): Promise<Ib>;
+/**
+ * Parses a standard Sync 'ib' string.
+ */
+export declare function parseSyncIb({ ib, }: {
+    ib: Ib;
+}): Promise<SyncIbInfo_V1>;
+//# sourceMappingURL=sync-helpers.d.mts.map

package/dist/sync/sync-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-helpers.d.mts","sourceRoot":"","sources":["../../src/sync/sync-helpers.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,8BAA8B,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK9D;;GAEG;AACH,wBAAsB,SAAS,CAAC,EAC5B,IAAI,GACP,EAAE;IACC,IAAI,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,EAAE,CAAC,CAgBd;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,EAC9B,EAAE,GACL,EAAE;IACC,EAAE,EAAE,EAAE,CAAC;CACV,GAAG,OAAO,CAAC,aAAa,CAAC,CAkBzB"}

package/dist/sync/sync-helpers.mjs

@@ -0,0 +1,46 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { SYNC_ATOM } from "./sync-constants.mjs";
+const GLOBAL_LOG_A_LOT = false; // Todo: import from core constants if needed
+const logalot = GLOBAL_LOG_A_LOT;
+/**
+ * Constructs the standard 'ib' string for a Sync frame.
+ */
+export async function getSyncIb({ data, }) {
+    const lc = `[${getSyncIb.name}]`;
+    try {
+        // sync uuid stage
+        // e.g. "sync 1234-5678 init"
+        const ib = [
+            SYNC_ATOM,
+            data.uuid,
+            data.stage
+        ].join(' ');
+        return ib;
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Parses a standard Sync 'ib' string.
+ */
+export async function parseSyncIb({ ib, }) {
+    const lc = `[${parseSyncIb.name}]`;
+    try {
+        const parts = ib.split(' ');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid sync ib. Expected 3 parts [atom uuid stage]. Got ${parts.length}. (E: 7c8d9...)`);
+        }
+        const [atom, uuid, stage] = parts;
+        if (atom !== SYNC_ATOM) {
+            throw new Error(`Invalid sync ib. Expected atom '${SYNC_ATOM}', got '${atom}'. (E: 8f9e1...)`);
+        }
+        return { atom, uuid, stage: stage };
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+//# sourceMappingURL=sync-helpers.mjs.map

package/dist/sync/sync-helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-helpers.mjs","sourceRoot":"","sources":["../../src/sync/sync-helpers.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAElF,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,MAAM,gBAAgB,GAAG,KAAK,CAAC,CAAC,6CAA6C;AAC7E,MAAM,OAAO,GAAG,gBAAgB,CAAC;AAEjC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAC5B,IAAI,GAGP;IACG,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC;IACjC,IAAI,CAAC;QACD,kBAAkB;QAClB,6BAA6B;QAC7B,MAAM,EAAE,GAAG;YACP,SAAS;YACT,IAAI,CAAC,IAAI;YACT,IAAI,CAAC,KAAK;SACb,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEZ,OAAO,EAAE,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAC9B,EAAE,GAGL;IACG,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,IAAI,GAAG,CAAC;IACnC,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,4DAA4D,KAAK,CAAC,MAAM,iBAAiB,CAAC,CAAC;QAC/G,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QAElC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,mCAAmC,SAAS,WAAW,IAAI,kBAAkB,CAAC,CAAC;QACnG,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAY,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC"}

package/dist/sync/sync-local-spaces.respec.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sync-local-spaces.respec.d.mts.map

package/dist/sync/sync-local-spaces.respec.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-local-spaces.respec.d.mts","sourceRoot":"","sources":["../../src/sync/sync-local-spaces.respec.mts"],"names":[],"mappings":""}

package/dist/sync/sync-local-spaces.respec.mjs

@@ -0,0 +1,159 @@
+import { rm } from 'node:fs/promises';
+import { default as pathUtils } from 'path';
+import { respecfully, lastOfAll } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+import { IBGIB_ENCODING } from '../witness/space/filesystem-space/filesystem-constants.mjs';
+import { NodeFilesystemSpace_V1 } from '../witness/space/filesystem-space/node-filesystem-space/node-filesystem-space-v1.mjs';
+import { getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+const logalot = true;
+const lc = `[sync-local-spaces.respec]`;
+// Helper to create a temp space
+const createTempSpace = async ({ baseDir, name }) => {
+    const uuid = await getUUID();
+    const initialData = {
+        version: '1',
+        classname: NodeFilesystemSpace_V1.name,
+        uuid,
+        name,
+        description: `Temp space for ${name}`,
+        baseDir,
+        baseSubPath: 'ibgib', // keep short to avoid long path issues
+        spaceSubPath: name,
+        ibgibsSubPath: 'ibgibs',
+        metaSubPath: 'meta',
+        binSubPath: 'bin',
+        dnaSubPath: 'dna',
+        encoding: IBGIB_ENCODING,
+        mitigateLongPaths: true,
+        // other defaults
+        catchAllErrors: false,
+        trace: false,
+    };
+    // mimic constructor logic if needed, or just new it up
+    const space = new NodeFilesystemSpace_V1(initialData);
+    // Explicitly initialize if needed (based on findings, constructor calls super which calls initialize? 
+    // Actually source had it commented out in ctor. Let's call it via a witness "put" which should verify initialization)
+    return space;
+};
+// class MockKeystoneService implements KeystoneService_V1 {
+//     async getIdentity(): Promise<KeystoneIbGib_V1> {
+//         // Return a dummy identity
+//         const res = await Factory_V1.firstGen({
+//             ib: 'identity',
+//             data: { uuid: await getUUID() },
+//             dna: true,
+//         });
+//         return res.newIbGib as KeystoneIbGib_V1;
+//     }
+//     // Implement other methods as no-ops or simple mocks
+//     async sign(ibGib: any): Promise<any> { return ibGib; }
+//     async verify(ibGib: any): Promise<boolean> { return true; }
+//     // Add other required properties/methods of KeystoneService_V1 if any (checking interface might be needed)
+//     // Assuming for now these are the core ones used by Coordinator.
+//     // If strict interface, might need more.
+// }
+await respecfully(sir, `Sync Local Spaces`, async () => {
+    const TEST_ROOT = pathUtils.join(process.cwd(), 'tmp_sync_test_' + await getUUID());
+    lastOfAll(sir, async () => {
+        if (!logalot) {
+            await rm(TEST_ROOT, { recursive: true, force: true });
+        }
+        else {
+            console.log(`${lc} Leaving TEST_ROOT for inspection: ${TEST_ROOT}`);
+        }
+    });
+    await respecfully(sir, `Basic Push Sync (Source -> Dest)`, async () => {
+        // // 1. Setup Spaces
+        // const srcDir = pathUtils.join(TEST_ROOT, 'source');
+        // const destDir = pathUtils.join(TEST_ROOT, 'dest');
+        // const sourceSpace = await createTempSpace({ baseDir: srcDir, name: 'source' });
+        // const destSpace = await createTempSpace({ baseDir: destDir, name: 'dest' });
+        // // 2. Seed Source Data
+        // // 2.1 Create a "Stone" (Primitive-like or just immutable data)
+        // const stoneRes = await Factory_V1.firstGen({
+        //     ib: 'stone_data',
+        //     data: { some: 'data', timestamp: getTimestampInTicks() },
+        //     dna: false,
+        // });
+        // const stone = stoneRes.newIbGib;
+        // const stoneAddr = getIbGibAddr({ ibGib: stone });
+        // // 2.2 Create a "Living" Timeline (Root -> Child)
+        // const rootRes = await Factory_V1.firstGen({
+        //     ib: 'timeline_root',
+        //     data: { type: 'root' },
+        //     dna: true,
+        // });
+        // const root = rootRes.newIbGib;
+        // const rootAddr = getIbGibAddr({ ibGib: root });
+        // const childRes = await mut8({
+        //     type: 'fork',
+        //     src: root,
+        //     dna: true,
+        //     data: { type: 'child', n: 1 }
+        // });
+        // const child = childRes.newIbGib;
+        // const childAddr = getIbGibAddr({ ibGib: child });
+        // // Put into Source
+        // await putInSpace({
+        //     space: sourceSpace,
+        //     ibGibs: [stone, root, child]
+        // });
+        // // 3. Setup Sync Coordinator
+        // const mockKeystone = new MockKeystoneService() as unknown as KeystoneService_V1;
+        // const identity = await mockKeystone.getIdentity();
+        // const coordinator = new SyncSagaCoordinator(mockKeystone);
+        // // Define domain (roots to sync)
+        // const domainIbGibs = [root]; // We only explicitly track the "Living" root. Stone is standalone? 
+        // // Actually for the test let's explicitly include both or rely on dependency graph.
+        // // If 'stone' is not related to 'root', it won't be picked up unless we add it to domain.
+        // // Let's Rel8 the stone to the child to test dependency traversal.
+        // const childWithRelRes = await rel8({
+        //     src: child,
+        //     rel8nsToAddByAddr: { 'linked_stone': [stoneAddr] },
+        //     dna: true,
+        // });
+        // const childWithRel = childWithRelRes.newIbGib;
+        // const childWithRelAddr = getIbGibAddr({ ibGib: childWithRel });
+        // // Update Source with linked child
+        // await putInSpace({
+        //     space: sourceSpace,
+        //     ibGibs: [childWithRel]
+        // });
+        // // 4. Run Sync
+        // const syncRes = await coordinator.sync({
+        //     source: sourceSpace,
+        //     dest: destSpace,
+        //     domainIbGibs: [childWithRel], // Sync starting from the tip
+        //     identity
+        // });
+        // // 5. Verify Dest
+        // // Check Stone
+        // const getStone = await getFromSpace({
+        //     space: destSpace,
+        //     addr: stoneAddr
+        // });
+        // if (!getStone.success || !getStone.ibGibs?.[0]) {
+        //     throw new Error(`Dest failed to get Stone: ${stoneAddr}`);
+        // }
+        // console.log(`${lc} Verified Stone synced.`);
+        // // Check ChildWithRel (Tip)
+        // const getChild = await getFromSpace({
+        //     space: destSpace,
+        //     addr: childWithRelAddr
+        // });
+        // if (!getChild.success || !getChild.ibGibs?.[0]) {
+        //     throw new Error(`Dest failed to get ChildWithRel: ${childWithRelAddr}`);
+        // }
+        // console.log(`${lc} Verified Timeline Tip synced.`);
+        // // Check Root (Dependency)
+        // const getRoot = await getFromSpace({
+        //     space: destSpace,
+        //     addr: rootAddr
+        // });
+        // if (!getRoot.success || !getRoot.ibGibs?.[0]) {
+        //     throw new Error(`Dest failed to get Root: ${rootAddr}`);
+        // }
+        // console.log(`${lc} Verified Root synced.`);
+    });
+});
+//# sourceMappingURL=sync-local-spaces.respec.mjs.map

package/dist/sync/sync-local-spaces.respec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-local-spaces.respec.mjs","sourceRoot":"","sources":["../../src/sync/sync-local-spaces.respec.mts"],"names":[],"mappings":"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"}

package/dist/sync/sync-saga-coordinator.d.mts

@@ -0,0 +1,118 @@
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
+import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
+import { KeystoneService_V1 } from "../keystone/keystone-service-v1.mjs";
+import { SyncIbGib_V1 } from "./sync-types.mjs";
+export interface SyncOptions {
+    /**
+     * The space containing the data we want to send.
+     */
+    source: IbGibSpaceAny;
+    /**
+     * The space receiving the data.
+     */
+    dest: IbGibSpaceAny;
+    /**
+     * The identity authorizing this sync.
+     */
+    identity: KeystoneIbGib_V1;
+    /**
+     * The secret for the identity (to sign the commit).
+     */
+    identitySecret: string;
+}
+/**
+ * Orchestrates the synchronization process between two spaces (Source and Destination).
+ *
+ * ## Architecture: Dependency Graph Synchronization
+ *
+ * Instead of a naive file-by-file sync or a holistic "Space" sync, this coordinator operates
+ * on a **Dependency Graph** derived from specific "Domain Roots" (e.g., a specific tag,
+ * folder, or application root).
+ *
+ * ### Workflow Pipeline
+ *
+ * 1.  **Graph Generation**:
+ *     *   Generates a `FlatIbGibGraph` using `getDependencyGraph({ live: true })` starting
+ *         from the provided `domainIbGibs`.
+ *     *   This ensures we capture the *latest* reachable state of all relevant timelines.
+ *
+ * 2.  **Classification (`splitPerTjpAndOrDna`)**:
+ *     *   **Stones**: Immutable, non-living ibGibs (no TJP/DNA). Trivial to sync (copy if missing).
+ *     *   **Living**: Evolving timelines (TJP + DNA). Complex to sync (require ordering & merging).
+ *
+ * 3.  **Timeline Ordering (`getTimelinesGroupedByTjp`)**:
+ *     *   Living ibGibs are grouped into timelines.
+ *     *   A "Timeline Dependency Graph" is built. Use Case: If a Comment Timeline refers to a
+ *         Post Timeline, the Post Timeline must be synced *before* the Comment Timeline to
+ *         ensure referential integrity at the destination.
+ *     *   **Topological Sort** determines the execution order. Circular dependencies are
+ *         treated as siblings.
+ *
+ * 4.  **Saga Execution ("Smart Coordinator, Dumb Space")**:
+ *     *   The Coordinator (running on the Client/Source) drives the entire process via a
+ *         "Pull-Merge-Push" strategy to resolve conflicts.
+ *
+ *     *   **Phase 1: Knowledge Exchange (Init)**
+ *         *   Generates a "Knowledge Vector" (Map<Tjp, LatestAddr>) of the Source's graph.
+ *         *   Sends `SyncStage.Init` to Dest.
+ *         *   Dest responds with its own Knowledge Vector for overlapping timelines.
+ *
+ *     *   **Phase 2: Gap Analysis & Conflict Resolution**
+ *         *   Coordinator compares Source vs. Dest knowledge.
+ *         *   **Fast-Forward**: Source is strictly ahead of Dest. Mark new frames for PUSH.
+ *         *   **Fast-Backward**: Dest is strictly ahead of Source. Mark frames for PULL (to update Local).
+ *         *   **Conflict/Divergence**: Both have new frames from a common ancestor.
+ *             *   **LOCK**: `lockSpace({ scope: tjpGib })` on Dest to prevent race conditions.
+ *             *   **PULL**: Download conflicting branch from Dest.
+ *             *   **MERGE**: Execute merge logic locally (creating a new merge frame `A_merge`).
+ *             *   **PUSH**: Mark `A_merge` (and dependencies) for PUSH.
+ *             *   **UNLOCK**: Release Dest lock.
+ *
+ *     *   **Phase 3: Batch Streaming (Delta)**
+ *         *   **Stones**: Batch `putInSpace` all missing "Stone" ibGibs first.
+ *         *   **Timelines**: Batch `putInSpace` Living Timelines in topological order.
+ *         *   *Note*: The `SyncFrame` (Init/Delta/Commit) tracks protocol state, but data transfer
+ *             happens via standard `putInSpace`.
+ *
+ *     *   **Phase 4: Commit**
+ *         *   Update Local Index (register new latests).
+ *         *   Send `SyncStage.Commit` to Dest to finalize session.
+ */
+export declare class SyncSagaCoordinator {
+    protected keystone: KeystoneService_V1;
+    protected lc: string;
+    constructor(keystone: KeystoneService_V1);
+    /**
+     * Executes a synchronization saga.
+     *
+     * @param opts.source The local space (Client) driving the sync.
+     * @param opts.dest The remote space (Server/Other Peer) to sync with.
+     * @param opts.identity The Keystone Identity performing the sync.
+     * @param opts.domainIbGibs The root ibGibs that define the scope of the sync (the "Dependency Graph").
+     * @param opts.identitySecret Optional secret if needed (usually handled by `keystone` service).
+     */
+    sync({ source, dest, identity, domainIbGibs, identitySecret }: {
+        source: IbGibSpaceAny;
+        dest: IbGibSpaceAny;
+        identity: KeystoneIbGib_V1;
+        domainIbGibs: IbGib_V1[];
+        identitySecret?: string;
+    }): Promise<void>;
+    protected createSyncFrame({ uuid, stage, payload, identity }: {
+        uuid: string;
+        stage: any;
+        payload: any;
+        identity: KeystoneIbGib_V1;
+    }): Promise<SyncIbGib_V1>;
+    protected getLatestAddrsFromSpace({ space, tjpAddrs, }: {
+        space: IbGibSpaceAny;
+        tjpAddrs: string[];
+    }): Promise<{
+        [tjpAddr: string]: string;
+    }>;
+    protected sortTimelinesTopologically(timelines: {
+        [tjp: string]: IbGib_V1[];
+    }): string[];
+}
+//# sourceMappingURL=sync-saga-coordinator.d.mts.map

package/dist/sync/sync-saga-coordinator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-saga-coordinator.d.mts","sourceRoot":"","sources":["../../src/sync/sync-saga-coordinator.mts"],"names":[],"mappings":"AASA,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAI3D,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,OAAO,EACU,YAAY,EAC5B,MAAM,kBAAkB,CAAC;AAM1B,MAAM,WAAW,WAAW;IACxB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBAAa,mBAAmB;IAIxB,SAAS,CAAC,QAAQ,EAAE,kBAAkB;IAH1C,SAAS,CAAC,EAAE,EAAE,MAAM,CAAmC;gBAGzC,QAAQ,EAAE,kBAAkB;IAG1C;;;;;;;;OAQG;IACG,IAAI,CAAC,EACP,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,cAAc,EACjB,EAAE;QACC,MAAM,EAAE,aAAa,CAAC;QACtB,IAAI,EAAE,aAAa,CAAC;QACpB,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,YAAY,EAAE,QAAQ,EAAE,CAAC;QACzB,cAAc,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;cAoMD,eAAe,CAAC,EAC5B,IAAI,EACJ,KAAK,EACL,OAAO,EACP,QAAQ,EACX,EAAE;QACC,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,GAAG,CAAC;QACX,OAAO,EAAE,GAAG,CAAC;QACb,QAAQ,EAAE,gBAAgB,CAAA;KAC7B,GAAG,OAAO,CAAC,YAAY,CAAC;cAoCT,uBAAuB,CAAC,EACpC,KAAK,EACL,QAAQ,GACX,EAAE;QACC,KAAK,EAAE,aAAa,CAAC;QACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACtB,GAAG,OAAO,CAAC;QAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAmC1C,SAAS,CAAC,0BAA0B,CAAC,SAAS,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAA;KAAE,GAAG,MAAM,EAAE;CA8D3F"}