things-api 0.17.0 → 0.19.0

package/dist/deputy/bridge-worker.js

@@ -0,0 +1,79 @@
+/**
+ * Worker half of the synchronous deputy bridge (see bridge.ts). Owns the
+ * long-lived socket to the deputy and services one request at a time: the main
+ * thread posts a request on the message port and blocks in Atomics.wait; this
+ * worker performs the socket round-trip, posts the response back, and bumps the
+ * shared counter to wake the main thread.
+ */
+import { connect } from "node:net";
+import { workerData } from "node:worker_threads";
+const { socketPath, sab, port } = workerData;
+const flag = new Int32Array(sab);
+let socket = null;
+let buffer = "";
+let pendingLine = null;
+let pendingError = null;
+function resetSocket(err) {
+    socket = null;
+    buffer = "";
+    const reject = pendingError;
+    pendingLine = null;
+    pendingError = null;
+    reject?.(err);
+}
+function ensureSocket() {
+    if (socket !== null)
+        return Promise.resolve(socket);
+    return new Promise((resolve, reject) => {
+        const sock = connect(socketPath);
+        sock.setEncoding("utf8");
+        sock.once("connect", () => {
+            socket = sock;
+            resolve(sock);
+        });
+        sock.on("data", (chunk) => {
+            buffer += chunk;
+            const nl = buffer.indexOf("\n");
+            if (nl < 0)
+                return;
+            const line = buffer.slice(0, nl);
+            buffer = buffer.slice(nl + 1);
+            const deliver = pendingLine;
+            pendingLine = null;
+            pendingError = null;
+            deliver?.(line);
+        });
+        sock.on("error", (err) => {
+            if (socket === null)
+                reject(err);
+            resetSocket(err);
+        });
+        sock.on("close", () => {
+            resetSocket(new Error("deputy closed the connection"));
+        });
+    });
+}
+async function roundTrip(request) {
+    const sock = await ensureSocket();
+    const line = await new Promise((resolve, reject) => {
+        pendingLine = resolve;
+        pendingError = reject;
+        sock.write(`${JSON.stringify(request)}\n`);
+    });
+    return JSON.parse(line);
+}
+port.on("message", ({ bridgeId, request }) => {
+    void roundTrip(request)
+        .then((response) => ({ bridgeId, response: response }))
+        .catch((err) => ({
+        bridgeId,
+        error: err instanceof Error ? err.message : String(err),
+    }))
+        .then((envelope) => {
+        port.postMessage(envelope);
+        Atomics.add(flag, 0, 1);
+        Atomics.notify(flag, 0);
+    });
+});
+port.start();
+//# sourceMappingURL=bridge-worker.js.map

package/dist/deputy/bridge-worker.js.map

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

package/dist/deputy/bridge.d.ts

@@ -0,0 +1,14 @@
+export declare class DeputySyncBridge {
+    private readonly worker;
+    private readonly flag;
+    private readonly port;
+    private seq;
+    constructor(socketPath: string);
+    /**
+     * Send one request and block until its response (or the deadline). Late
+     * responses from a previously timed-out request are drained and discarded by
+     * the id match, so one timeout never poisons the next call.
+     */
+    request(payload: Record<string, unknown>, timeoutMs: number): Record<string, unknown>;
+    close(): void;
+}

package/dist/deputy/bridge.js

@@ -0,0 +1,70 @@
+/**
+ * Synchronous bridge to the deputy for callers that cannot await — the
+ * DatabaseSync-shaped read facade and the sync consent probes. A dedicated
+ * worker thread owns the socket; the main thread posts a request, blocks in
+ * Atomics.wait on a shared counter, then drains the port with
+ * receiveMessageOnPort. One request is in flight at a time by construction
+ * (the main thread is blocked while it waits).
+ *
+ * The bridge must NOT be used for long-running osascript drives — blocking the
+ * event loop would suspend the drive watchdog and signal handlers. Async
+ * dispatch rides client.ts instead.
+ */
+import { MessageChannel, receiveMessageOnPort, Worker, } from "node:worker_threads";
+import { DeputyRequestError } from "./protocol.js";
+export class DeputySyncBridge {
+    worker;
+    flag;
+    port;
+    seq = 0;
+    constructor(socketPath) {
+        const sab = new SharedArrayBuffer(4);
+        this.flag = new Int32Array(sab);
+        const channel = new MessageChannel();
+        this.port = channel.port1;
+        // Live TS source runs the .ts twin; the published build runs the emitted
+        // .js next to this module (same trick as src/cli/version.ts).
+        const ext = import.meta.url.endsWith(".ts") ? "ts" : "js";
+        this.worker = new Worker(new URL(`./bridge-worker.${ext}`, import.meta.url), {
+            workerData: { socketPath, sab, port: channel.port2 },
+            transferList: [channel.port2],
+        });
+        // The bridge must never keep the CLI process alive on its own.
+        this.worker.unref();
+    }
+    /**
+     * Send one request and block until its response (or the deadline). Late
+     * responses from a previously timed-out request are drained and discarded by
+     * the id match, so one timeout never poisons the next call.
+     */
+    request(payload, timeoutMs) {
+        const id = `s${++this.seq}`;
+        let seen = Atomics.load(this.flag, 0);
+        // oxlint-disable-next-line require-post-message-target-origin -- worker_threads port, no targetOrigin
+        this.port.postMessage({ bridgeId: id, request: payload });
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            let received = receiveMessageOnPort(this.port);
+            while (received !== undefined) {
+                const message = received.message;
+                if (message.bridgeId === id) {
+                    if (message.error !== undefined) {
+                        throw new DeputyRequestError("bridge-io", message.error);
+                    }
+                    return message.response ?? {};
+                }
+                received = receiveMessageOnPort(this.port);
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new DeputyRequestError("bridge-timeout", `the deputy did not answer within ${timeoutMs}ms`);
+            }
+            Atomics.wait(this.flag, 0, seen, remaining);
+            seen = Atomics.load(this.flag, 0);
+        }
+    }
+    close() {
+        void this.worker.terminate();
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/deputy/bridge.js.map

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

package/dist/deputy/client.d.ts

@@ -0,0 +1,19 @@
+export declare class DeputyAsyncClient {
+    private socket;
+    private buffer;
+    private seq;
+    private readonly pending;
+    private readonly socketPath;
+    constructor(socketPath: string);
+    private ensureSocket;
+    private onData;
+    private failAll;
+    /**
+     * Send one request; resolves with the raw response object (protocol errors
+     * included — the caller inspects `ok`). Rejects only on transport failure or
+     * client-side deadline (`timeoutMs` should exceed any deputy-side timeout so
+     * the deputy's own honest answer wins).
+     */
+    request(payload: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>>;
+    close(): void;
+}

package/dist/deputy/client.js

@@ -0,0 +1,104 @@
+/**
+ * Async deputy client for event-loop-friendly callers: the applescript vector
+ * and the ui vector's step runner. Long osascript drives ride this client so
+ * timers (drive watchdog) and signal handlers keep running; synchronous
+ * callers ride bridge.ts instead. One shared socket, requests matched by id.
+ */
+import { connect } from "node:net";
+import { DeputyRequestError } from "./protocol.js";
+export class DeputyAsyncClient {
+    socket = null;
+    buffer = "";
+    seq = 0;
+    pending = new Map();
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    ensureSocket() {
+        if (this.socket !== null)
+            return Promise.resolve(this.socket);
+        return new Promise((resolve, reject) => {
+            const sock = connect(this.socketPath);
+            sock.setEncoding("utf8");
+            sock.once("connect", () => {
+                this.socket = sock;
+                // An idle deputy connection must never keep the CLI process alive.
+                sock.unref();
+                resolve(sock);
+            });
+            sock.on("data", (chunk) => this.onData(chunk));
+            sock.on("error", (err) => {
+                if (this.socket === null)
+                    reject(err);
+                this.failAll(err);
+            });
+            sock.on("close", () => this.failAll(new Error("deputy closed the connection")));
+        });
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        for (;;) {
+            const nl = this.buffer.indexOf("\n");
+            if (nl < 0)
+                return;
+            const line = this.buffer.slice(0, nl);
+            this.buffer = this.buffer.slice(nl + 1);
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const id = typeof parsed["id"] === "string" ? parsed["id"] : null;
+            const entry = id !== null ? this.pending.get(id) : undefined;
+            if (id === null || entry === undefined)
+                continue;
+            this.pending.delete(id);
+            clearTimeout(entry.timer);
+            entry.resolve(parsed);
+        }
+    }
+    failAll(err) {
+        this.socket = null;
+        this.buffer = "";
+        const waiting = [...this.pending.values()];
+        this.pending.clear();
+        for (const entry of waiting) {
+            clearTimeout(entry.timer);
+            entry.reject(err);
+        }
+    }
+    /**
+     * Send one request; resolves with the raw response object (protocol errors
+     * included — the caller inspects `ok`). Rejects only on transport failure or
+     * client-side deadline (`timeoutMs` should exceed any deputy-side timeout so
+     * the deputy's own honest answer wins).
+     */
+    async request(payload, timeoutMs) {
+        const sock = await this.ensureSocket();
+        const id = `a${++this.seq}`;
+        // Wake the socket handle while a request is in flight (see unref above).
+        sock.ref();
+        try {
+            return await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new DeputyRequestError("client-timeout", `the deputy did not answer within ${timeoutMs}ms`));
+                }, timeoutMs);
+                this.pending.set(id, { resolve, reject, timer });
+                sock.write(`${JSON.stringify({ ...payload, id })}\n`);
+            });
+        }
+        finally {
+            if (this.pending.size === 0)
+                sock.unref();
+        }
+    }
+    close() {
+        this.socket?.destroy();
+        this.socket = null;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/deputy/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/deputy/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAe,MAAM,UAAU,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAQnD,MAAM,OAAO,iBAAiB;IACpB,MAAM,GAAkB,IAAI,CAAC;IAC7B,MAAM,GAAG,EAAE,CAAC;IACZ,GAAG,GAAG,CAAC,CAAC;IACC,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IACrC,UAAU,CAAS;IAEpC,YAAY,UAAkB;QAC5B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAEO,YAAY;QAClB,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;gBACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;gBACnB,mEAAmE;gBACnE,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;gBAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;oBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;gBACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAa;QAC1B,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;QACrB,SAAS,CAAC;YACR,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,EAAE,GAAG,CAAC;gBAAE,OAAO;YACnB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACxC,IAAI,MAA+B,CAAC;YACpC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;YACvD,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,MAAM,EAAE,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAClE,MAAM,KAAK,GAAG,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC7D,IAAI,EAAE,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YACjD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACxB,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,OAAO,CAAC,GAAU;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CACX,OAAgC,EAChC,SAAiB;QAEjB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,yEAAyE;QACzE,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,OAAO,CAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACpE,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACxB,MAAM,CACJ,IAAI,kBAAkB,CACpB,gBAAgB,EAChB,oCAAoC,SAAS,IAAI,CAClD,CACF,CAAC;gBACJ,CAAC,EAAE,SAAS,CAAC,CAAC;gBACd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;gBACjD,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YACxD,CAAC,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;CACF"}

package/dist/deputy/db-facade.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A DatabaseSync-shaped READ facade over the deputy's `sql` verb. The read
+ * layer types against node:sqlite's DatabaseSync and only ever prepares
+ * SELECT/PRAGMA statements consumed via `.all()` / `.get()`; this facade
+ * implements exactly that surface synchronously (through the bridge) and
+ * throws a teaching error on anything else — never a silent no-op. WAL
+ * freshness is preserved: the deputy holds one read-only connection outside
+ * any transaction, so every statement sees a fresh snapshot exactly like a
+ * local connection (docs/design/architecture.md §0).
+ */
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * Build the facade. The cast is confined to this one construction site: the
+ * object structurally implements the read subset, a Proxy turns any other
+ * member access into a teaching error, and symbol probes (inspect, iterators)
+ * stay undefined so logging never explodes.
+ */
+export declare function createDeputyDbFacade(env?: NodeJS.ProcessEnv): DatabaseSync;

package/dist/deputy/db-facade.js

@@ -0,0 +1,71 @@
+import { reviveRow } from "./protocol.js";
+import { fileSyncRequest } from "./routing.js";
+const SQL_TIMEOUT_MS = 15_000;
+function normalizeParams(params, sql) {
+    return params.map((param, index) => {
+        if (param === null || typeof param === "string" || typeof param === "number")
+            return param;
+        if (typeof param === "bigint") {
+            if (param > BigInt(Number.MAX_SAFE_INTEGER) || param < BigInt(Number.MIN_SAFE_INTEGER)) {
+                throw new TypeError(`deputy sql: bigint parameter ${index} exceeds JSON-safe range`);
+            }
+            return Number(param);
+        }
+        throw new TypeError(`deputy sql: unsupported ${typeof param} parameter at index ${index} for: ${sql.slice(0, 80)}`);
+    });
+}
+function queryRows(sql, params, env) {
+    // Rides the granted reader when present, else the deputy (routing.ts).
+    const res = fileSyncRequest({ verb: "sql", sql, params: normalizeParams(params, sql) }, SQL_TIMEOUT_MS, env);
+    return res["rows"].map(reviveRow);
+}
+function unsupported(member) {
+    return () => {
+        throw new Error(`DatabaseSync.${member} is not available on a deputy-routed connection — the deputy brokers read-only prepare/all/get only. Disable the helpers (THINGS_API_HELPERS=false) for local access.`);
+    };
+}
+/**
+ * Build the facade. The cast is confined to this one construction site: the
+ * object structurally implements the read subset, a Proxy turns any other
+ * member access into a teaching error, and symbol probes (inspect, iterators)
+ * stay undefined so logging never explodes.
+ */
+export function createDeputyDbFacade(env = process.env) {
+    const base = {
+        prepare(sql) {
+            const statement = {
+                all(...params) {
+                    return queryRows(sql, params, env);
+                },
+                get(...params) {
+                    return queryRows(sql, params, env)[0];
+                },
+                run: unsupported("prepare(...).run (writes never touch the database directly)"),
+                iterate: unsupported("prepare(...).iterate"),
+                expandedSQL: sql,
+                sourceSQL: sql,
+            };
+            return new Proxy(statement, {
+                get(target, prop, receiver) {
+                    if (typeof prop === "symbol" || prop in target)
+                        return Reflect.get(target, prop, receiver);
+                    return unsupported(`prepare(...).${String(prop)}`)();
+                },
+            });
+        },
+        exec: unsupported("exec"),
+        close() {
+            // The bridge outlives individual connections; nothing to release here.
+        },
+        isOpen: true,
+        isTransaction: false,
+    };
+    return new Proxy(base, {
+        get(target, prop, receiver) {
+            if (typeof prop === "symbol" || prop in target)
+                return Reflect.get(target, prop, receiver);
+            return unsupported(String(prop))();
+        },
+    });
+}
+//# sourceMappingURL=db-facade.js.map

package/dist/deputy/db-facade.js.map

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

package/dist/deputy/files.d.ts

@@ -0,0 +1 @@
+export declare function readContainerFileSync(path: string): Buffer;

package/dist/deputy/files.js

@@ -0,0 +1,16 @@
+/**
+ * Container-scoped file reads (Things prefs plists for sync-health and URL-
+ * scheme availability). The group container is TCC-protected like the
+ * database, so in deputy mode these reads ride the deputy's `read-file` verb —
+ * which the deputy confines to the container subtree. Direct mode is a plain
+ * readFileSync, byte-identical to the pre-deputy behavior.
+ */
+import { readFileSync } from "node:fs";
+import { deputyFilesActive, fileSyncRequest } from "./routing.js";
+export function readContainerFileSync(path) {
+    if (!deputyFilesActive())
+        return readFileSync(path);
+    const res = fileSyncRequest({ verb: "read-file", path }, 10_000);
+    return Buffer.from(res["b64"], "base64");
+}
+//# sourceMappingURL=files.js.map

package/dist/deputy/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/deputy/files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,eAAe,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IACjE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAW,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC"}