@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/dist/sync/delta-client.js

@@ -0,0 +1,201 @@
+const OPAQUE = /^[A-Za-z0-9._~-]{1,512}$/;
+export class DeltaGapError extends Error {
+    constructor(message = "realtime delta: DELTA_GAP; cursor was not advanced") {
+        super(message);
+        this.name = "DeltaGapError";
+    }
+}
+export class CursorRetiredError extends Error {
+    constructor(message = "realtime delta: CURSOR_RETIRED; cursor was not advanced") {
+        super(message);
+        this.name = "CursorRetiredError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`realtime delta: ${label} must be a non-empty string`);
+    return value;
+}
+function opaque(value, label) {
+    const result = nonEmpty(value, label);
+    if (!OPAQUE.test(result))
+        throw new Error(`realtime delta: ${label} is not opaque`);
+    return result;
+}
+function exactKeys(record, keys, label) {
+    if (Object.keys(record).some((key) => !keys.includes(key)))
+        throw new Error(`realtime delta: ${label} contains an unknown field`);
+}
+function parseDelta(value) {
+    if (!isRecord(value))
+        throw new Error("realtime delta: delta record is not an object");
+    exactKeys(value, ["deltaId", "canonicalPath", "operation", "versionId", "source"], "delta record");
+    const operation = value.operation;
+    if (operation !== "upsert" && operation !== "delete")
+        throw new Error("realtime delta: delta operation is invalid");
+    const versionId = value.versionId;
+    if (versionId !== null && typeof versionId !== "string") {
+        throw new Error("realtime delta: delta metadata is invalid");
+    }
+    const source = parseSource(value.source);
+    if (operation === "upsert" && (versionId === null || source === null))
+        throw new Error("realtime delta: upsert lacks immutable content metadata");
+    if (operation === "delete" && (versionId !== null || source !== null))
+        throw new Error("realtime delta: delete carries content metadata");
+    const canonicalPath = nonEmpty(value.canonicalPath, "canonicalPath");
+    if (canonicalPath.includes("\\") || canonicalPath.startsWith("/") || canonicalPath.startsWith(".hq-control/") || canonicalPath.endsWith("/") || canonicalPath.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new Error("realtime delta: canonicalPath is invalid");
+    }
+    return { deltaId: opaque(value.deltaId, "deltaId"), canonicalPath, operation, versionId, source };
+}
+function parseSource(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        throw new Error("realtime delta: source metadata is invalid");
+    exactKeys(value, ["kind", "mode"], "source metadata");
+    if ((value.kind !== "regular" && value.kind !== "symlink") || typeof value.mode !== "number" || !Number.isSafeInteger(value.mode) || value.mode < 0 || value.mode > 0o7777) {
+        throw new Error("realtime delta: source metadata is invalid");
+    }
+    return { kind: value.kind, mode: value.mode };
+}
+function parsePage(value) {
+    if (!isRecord(value))
+        throw new Error("realtime delta: page response is not an object");
+    exactKeys(value, ["untilCursor", "nextPageToken", "deltas"], "page response");
+    if (!Array.isArray(value.deltas))
+        throw new Error("realtime delta: page deltas is not an array");
+    if (value.nextPageToken !== null && (typeof value.nextPageToken !== "string" || value.nextPageToken.length === 0))
+        throw new Error("realtime delta: nextPageToken is invalid");
+    const deltas = value.deltas.map(parseDelta);
+    if (new Set(deltas.map((delta) => delta.deltaId)).size !== deltas.length)
+        throw new Error("realtime delta: page repeats a delta ID");
+    return { untilCursor: nonEmpty(value.untilCursor, "untilCursor"), nextPageToken: value.nextPageToken, deltas };
+}
+function errorCode(text) {
+    try {
+        const value = JSON.parse(text);
+        return isRecord(value) && typeof value.code === "string" ? value.code : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The V2 reader has no LIST capability or dependency.  Its callback is
+ * awaited before another page is requested, so a future durable applier can
+ * make every page's effects and cursor durable before the next page arrives.
+ */
+export class DeltaClient {
+    apiUrl;
+    fetchImpl;
+    now;
+    timeoutMs;
+    constructor(options) {
+        if (!options.apiUrl.trim())
+            throw new Error("realtime delta: apiUrl is required");
+        this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.now = options.now ?? Date.now;
+        this.timeoutMs = options.authorizationTimeoutMs ?? 15_000;
+        if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs < 1)
+            throw new Error("realtime delta: authorizationTimeoutMs must be positive");
+    }
+    async drain(request, consume) {
+        this.assertRequest(request);
+        let pageToken = null;
+        let ceiling = null;
+        let pages = 0;
+        let deltas = 0;
+        const seenTokens = new Set();
+        const seenDeltaIds = new Set();
+        do {
+            this.assertLease(request.authorization);
+            const page = await this.getPage(request, pageToken);
+            if (ceiling !== null && page.untilCursor !== ceiling)
+                throw new Error("realtime delta: page token changed the immutable ceiling");
+            ceiling ??= page.untilCursor;
+            for (const delta of page.deltas) {
+                if (seenDeltaIds.has(delta.deltaId))
+                    throw new Error("realtime delta: delta ID repeats across the drain");
+                seenDeltaIds.add(delta.deltaId);
+            }
+            await consume(page);
+            pages++;
+            deltas += page.deltas.length;
+            pageToken = page.nextPageToken;
+            if (pageToken !== null) {
+                if (seenTokens.has(pageToken))
+                    throw new Error("realtime delta: page token loop detected");
+                seenTokens.add(pageToken);
+            }
+        } while (pageToken !== null);
+        return { untilCursor: ceiling, pages, deltas };
+    }
+    assertRequest(request) {
+        this.assertLease(request.authorization);
+        nonEmpty(request.scopeHandle, "scopeHandle");
+        nonEmpty(request.scopeRevision, "scopeRevision");
+        nonEmpty(request.cursor, "cursor");
+        if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 1_000)
+            throw new Error("realtime delta: limit must be an integer from 1 through 1000");
+    }
+    async getPage(request, pageToken) {
+        const query = pageToken === null
+            ? new URLSearchParams({ scopeHandle: request.scopeHandle, scopeRevision: request.scopeRevision, cursor: request.cursor, limit: String(request.limit) })
+            : new URLSearchParams({ pageToken });
+        const { response, text } = await this.request(request.authorization, `/v2/sync/delta?${query.toString()}`);
+        if (!response.ok) {
+            const code = errorCode(text);
+            if (response.status === 416 && code === "DELTA_GAP")
+                throw new DeltaGapError();
+            if (response.status === 410 && code === "CURSOR_RETIRED")
+                throw new CursorRetiredError();
+            throw new Error(`realtime delta: request failed (${response.status}): ${text.slice(0, 300)}`);
+        }
+        try {
+            return parsePage(JSON.parse(text));
+        }
+        catch (error) {
+            throw new Error(`realtime delta: page response is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    assertLease(authorization) {
+        const expiry = Date.parse(authorization.lease.expiresAt);
+        if (!Number.isFinite(expiry) || expiry <= this.now())
+            throw new Error("realtime delta: lease expired before guarded I/O");
+    }
+    async request(authorization, path) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${nonEmpty(authorization.bearer, "bearer")}`,
+                    Accept: "application/json",
+                    "X-HQ-Sync-Contract": "2",
+                    "X-HQ-Device-ID": nonEmpty(authorization.deviceId, "deviceId"),
+                    "X-HQ-Cloud-Version": nonEmpty(authorization.capabilityVector.hqCloud, "hqCloud version"),
+                    "X-HQ-Desktop-Version": nonEmpty(authorization.capabilityVector.hqDesktop, "hqDesktop version"),
+                    "X-HQ-Sync-Lease": nonEmpty(authorization.lease.lease, "lease"),
+                },
+                signal: controller.signal,
+            });
+            const text = await response.text().catch((error) => {
+                throw new Error(`realtime delta: response unreadable: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            return { response, text };
+        }
+        catch (error) {
+            throw new Error(`realtime delta: request failed without cursor advancement: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+//# sourceMappingURL=delta-client.js.map

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

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

package/dist/sync/delta-client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=delta-client.test.d.ts.map

package/dist/sync/delta-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta-client.test.d.ts","sourceRoot":"","sources":["../../src/sync/delta-client.test.ts"],"names":[],"mappings":""}

package/dist/sync/delta-client.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from "vitest";
+import { DeltaClient, DeltaGapError, CursorRetiredError } from "./delta-client.js";
+const auth = {
+    bearer: "bearer",
+    deviceId: "device_a",
+    capabilityVector: { hqCloud: "6.15.0", hqDesktop: "1.0.0", protocol: 2, journal: 3, durableApply: 0 },
+    lease: { lease: "lease_a", issuedAt: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-01T00:01:00.000Z", authorizationEpoch: "epoch_a" },
+};
+function response(status, value) {
+    return { ok: status >= 200 && status < 300, status, headers: { get: () => null }, body: null, text: async () => JSON.stringify(value) };
+}
+function client(fetchImpl) {
+    return new DeltaClient({ apiUrl: "https://sync.example/", fetchImpl, now: () => Date.parse("2026-01-01T00:00:00.000Z") });
+}
+function request() {
+    return { authorization: auth, scopeHandle: "scope_a", scopeRevision: "revision_a", cursor: "cursor_100", limit: 10 };
+}
+const upsert = { deltaId: "delta_101", canonicalPath: "notes/a.md", operation: "upsert", versionId: "V101", source: { kind: "regular", mode: 0o644 } };
+describe("DeltaClient", () => {
+    it("keeps the first immutable ceiling while C161 arrives after a page token is minted", async () => {
+        const fetchImpl = vi.fn().mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: "page_2", deltas: [upsert] }))
+            .mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: null, deltas: [] }));
+        const consumed = [];
+        await expect(client(fetchImpl).drain(request(), async (page) => { consumed.push(page.untilCursor); })).resolves.toEqual({ untilCursor: "cursor_160", pages: 2, deltas: 1 });
+        expect(consumed).toEqual(["cursor_160", "cursor_160"]);
+        expect(fetchImpl.mock.calls.map(([url]) => url)).toEqual([
+            "https://sync.example/v2/sync/delta?scopeHandle=scope_a&scopeRevision=revision_a&cursor=cursor_100&limit=10",
+            "https://sync.example/v2/sync/delta?pageToken=page_2",
+        ]);
+        expect(fetchImpl.mock.calls[1]?.[0]).not.toContain("cursor=");
+    });
+    it("follows an empty hidden page instead of treating it as end-of-drain", async () => {
+        const fetchImpl = vi.fn().mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: "hidden_2", deltas: [] }))
+            .mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: null, deltas: [upsert] }));
+        const consume = vi.fn(async () => undefined);
+        await expect(client(fetchImpl).drain(request(), consume)).resolves.toEqual({ untilCursor: "cursor_160", pages: 2, deltas: 1 });
+        expect(consume).toHaveBeenCalledTimes(2);
+        expect(fetchImpl).toHaveBeenCalledTimes(2);
+    });
+    it("fails closed without invoking the consumer on a gap or retired epoch", async () => {
+        for (const [status, code, error] of [[416, "DELTA_GAP", DeltaGapError], [410, "CURSOR_RETIRED", CursorRetiredError]]) {
+            const fetchImpl = vi.fn().mockResolvedValue(response(status, { code }));
+            const consume = vi.fn(async () => undefined);
+            await expect(client(fetchImpl).drain(request(), consume)).rejects.toBeInstanceOf(error);
+            expect(consume).not.toHaveBeenCalled();
+            expect(fetchImpl).toHaveBeenCalledTimes(1);
+        }
+    });
+    it("rejects a token response that tries to change the fixed ceiling before applying it", async () => {
+        const fetchImpl = vi.fn().mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: "page_2", deltas: [] }))
+            .mockResolvedValueOnce(response(200, { untilCursor: "cursor_161", nextPageToken: null, deltas: [upsert] }));
+        const consume = vi.fn(async () => undefined);
+        await expect(client(fetchImpl).drain(request(), consume)).rejects.toThrow(/immutable ceiling/);
+        expect(consume).toHaveBeenCalledTimes(1);
+    });
+    it("revalidates its lease before a continuation and never sends an expired page token", async () => {
+        let now = Date.parse("2026-01-01T00:00:00.000Z");
+        const fetchImpl = vi.fn().mockResolvedValue(response(200, { untilCursor: "cursor_160", nextPageToken: "page_2", deltas: [] }));
+        const delta = new DeltaClient({ apiUrl: "https://sync.example", fetchImpl, now: () => now });
+        await expect(delta.drain(request(), async () => { now = Date.parse(auth.lease.expiresAt); })).rejects.toThrow(/lease expired/);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+    });
+    it("preserves non-empty opaque cursor and page-token bytes through URL encoding", async () => {
+        const fetchImpl = vi.fn().mockResolvedValueOnce(response(200, { untilCursor: "cursor/+==", nextPageToken: "page/+==", deltas: [] }))
+            .mockResolvedValueOnce(response(200, { untilCursor: "cursor/+==", nextPageToken: null, deltas: [] }));
+        await client(fetchImpl).drain({ ...request(), cursor: "cursor/+==" }, async () => undefined);
+        expect(fetchImpl.mock.calls.map(([url]) => url)).toEqual([
+            "https://sync.example/v2/sync/delta?scopeHandle=scope_a&scopeRevision=revision_a&cursor=cursor%2F%2B%3D%3D&limit=10",
+            "https://sync.example/v2/sync/delta?pageToken=page%2F%2B%3D%3D",
+        ]);
+    });
+    it("carries source kind and POSIX mode to the durable applier", async () => {
+        const symlinkUpsert = { ...upsert, source: { kind: "symlink", mode: 0o777 } };
+        const fetchImpl = vi.fn().mockResolvedValue(response(200, { untilCursor: "cursor_160", nextPageToken: null, deltas: [symlinkUpsert] }));
+        const consume = vi.fn(async () => undefined);
+        await expect(client(fetchImpl).drain(request(), consume)).resolves.toEqual({ untilCursor: "cursor_160", pages: 1, deltas: 1 });
+        expect(consume).toHaveBeenCalledWith(expect.objectContaining({ deltas: [expect.objectContaining({ source: { kind: "symlink", mode: 0o777 } })] }));
+    });
+    it("rejects duplicate deltas across pages before applying the repeat", async () => {
+        const fetchImpl = vi.fn().mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: "page_2", deltas: [upsert] }))
+            .mockResolvedValueOnce(response(200, { untilCursor: "cursor_160", nextPageToken: null, deltas: [upsert] }));
+        const consume = vi.fn(async () => undefined);
+        await expect(client(fetchImpl).drain(request(), consume)).rejects.toThrow(/repeats across the drain/);
+        expect(consume).toHaveBeenCalledTimes(1);
+    });
+    it("has no LIST surface: all requests are V2 delta control-plane GETs", async () => {
+        const fetchImpl = vi.fn().mockResolvedValue(response(200, { untilCursor: "cursor_160", nextPageToken: null, deltas: [] }));
+        await client(fetchImpl).drain(request(), async () => undefined);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+        for (const [url, init] of fetchImpl.mock.calls) {
+            expect(url).toContain("/v2/sync/delta?");
+            expect(url).not.toMatch(/list|s3|bucket/i);
+            expect(init?.method).toBe("GET");
+        }
+    });
+});
+//# sourceMappingURL=delta-client.test.js.map

package/dist/sync/delta-client.test.js.map

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

package/dist/sync/durable-apply.d.ts

@@ -0,0 +1,76 @@
+import type { DeltaPage, DeltaRecord } from "./delta-client.js";
+type ApplyKind = "regular" | "symlink" | "delete";
+export interface DurableApplyContent {
+    kind: "regular" | "symlink";
+    /** Exact bytes returned by the authorized delta content descriptor. */
+    bytes: Buffer;
+    /** SHA-256 hexadecimal digest authenticated by that descriptor. */
+    sha256: string;
+}
+export interface DurableApplyIntent {
+    deltaId: string;
+    canonicalPath: string;
+    operation: ApplyKind;
+    versionId: string | null;
+    sha256: string | null;
+    mode: number | null;
+    symlinkTarget: string | null;
+    stageName: string | null;
+}
+export interface DurableAppliedPath {
+    deltaId: string;
+    operation: ApplyKind;
+    versionId: string | null;
+    sha256: string | null;
+}
+export interface DurableApplyState {
+    intents: Record<string, DurableApplyIntent>;
+    paths: Record<string, DurableAppliedPath>;
+    cursor: string | null;
+}
+export interface DurableApplyOptions {
+    /** Filesystem root for one authorized scope projection. */
+    rootDir: string;
+    /** Root used by the WAL v3 state store. */
+    stateRootDir: string;
+    scopeId: string;
+    initialCursor?: string | null;
+    /** Test-only crash seam, called after each durable boundary. */
+    afterStep?: (step: DurableApplyStep) => void;
+}
+export type DurableApplyStep = "stage-hashed" | "stage-fdatasynced" | "stage-parent-fsynced" | "intent-durable" | "filesystem-applied" | "parent-fsynced" | "path-durable" | "cursor-durable";
+export declare class DurableApplyError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class DurableApplyRecoveryError extends DurableApplyError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A page is the cursor unit. All path records are durable before its opaque
+ * fixed-H cursor is appended. The caller must serialize calls per scope.
+ */
+export declare class DurableApplyEngine {
+    private readonly rootDir;
+    private readonly afterStep;
+    private readonly store;
+    constructor(options: DurableApplyOptions);
+    getState(): DurableApplyState;
+    /** Finish every prior filesystem intent, but never invent a page cursor. */
+    recover(): void;
+    /**
+     * Fetching is deliberately outside this module: only the authorized
+     * deltaId-to-exact-version transport can provide bytes. Deletes never ask
+     * for content.
+     */
+    applyPage(page: Pick<DeltaPage, "untilCursor" | "nextPageToken" | "deltas">, fetchContent: (delta: DeltaRecord) => Promise<DurableApplyContent>): Promise<void>;
+    private beginUpsert;
+    private beginDelete;
+    private recoverIntent;
+    private applyIntentFilesystem;
+    private finishIntent;
+    private targetPath;
+    private step;
+    private sweepUnreferencedStages;
+}
+export {};
+//# sourceMappingURL=durable-apply.d.ts.map

package/dist/sync/durable-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-apply.d.ts","sourceRoot":"","sources":["../../src/sync/durable-apply.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOhE,KAAK,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC1C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,mBAAmB,GACnB,sBAAsB,GACtB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,CAAC;AAErB,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;gBAClD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,OAAO,EAAE,mBAAmB;IAexC,QAAQ,IAAI,iBAAiB;IAI7B,4EAA4E;IAC5E,OAAO,IAAI,IAAI;IAIf;;;;OAIG;IACG,SAAS,CACb,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,eAAe,GAAG,QAAQ,CAAC,EACjE,YAAY,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,mBAAmB,CAAC,GACjE,OAAO,CAAC,IAAI,CAAC;IAsBhB,OAAO,CAAC,WAAW;IAwCnB,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,qBAAqB;IAwB7B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,uBAAuB;CAQhC"}