wotann 0.5.0 → 0.5.39

package/dist/storage/sqlite-node-backend.js

@@ -3,70 +3,70 @@
  *
  * WHAT: A `StorageAdapter` that wraps the `sqlite3` npm package (the
  *   asynchronous, callback-style binding). Used when `better-sqlite3`
- *   fails to load — the canonical case being Termux ARM64, where the
- *   nodejs-lts package ships without the gyp toolchain.
+ *   fails to load — canonical case: Termux ARM64 where the nodejs-lts
+ *   package ships without the gyp toolchain for native compilation.
  *
- * WHY: `sqlite3` ships precompiled binaries for more architectures than
- *   `better-sqlite3` does, including Android ARM64 / ARMv7 / x86_64
- *   under Termux. Performance is lower and the API is async, but the
- *   functional surface is enough to keep WOTANN's memory store
- *   running. Without this fallback, every Termux user would see the
- *   harness crash on first run.
+ * WHY: `sqlite3` ships precompiled binaries for Android ARM64 / ARMv7
+ *   / x86_64 under Termux. Performance is lower than better-sqlite3
+ *   and the native API is async, but the functional surface keeps
+ *   WOTANN's memory store running. Without this fallback, every
+ *   Termux user would see the harness crash on first run.
  *
  * WHERE: Selected by `selectStorageAdapter()` in `src/storage/index.ts`
  *   only after `BetterSqliteAdapter.probe()` reports unavailable.
  *   Threaded through the existing memory store unchanged — callers see
- *   the same `StoragePreparedStatement` interface.
+ *   the same synchronous `StoragePreparedStatement` interface.
  *
- * HOW: We wrap the async `sqlite3.Database` with a synchronous facade
- *   using a deasync technique: every call returns a value computed
- *   from the resolved promise via `Atomics.wait` on a SharedArrayBuffer.
+ * HOW: The `sqlite3` driver is callback-async. WOTANN's
+ *   `StoragePreparedStatement` contract is synchronous (the OMEGA
+ *   layers + FTS5 search code in `src/memory/store.ts` rely on
+ *   blocking semantics). Bridging requires deasync.
  *
- *   PRACTICAL NOTE: Termux Node ships without `Atomics.wait` working
- *   reliably on the main thread, so we DO NOT actually deasync. Instead
- *   this scaffold exposes the synchronous façade as a STUB that throws
- *   `StorageNotSupportedError` with a clear message until the async
- *   port of the memory store lands. This is intentional — silent
- *   blocking-on-async would crash the runtime in subtle ways that are
- *   harder to debug than an honest error at startup.
+ *   We use a Node `worker_threads` + `SharedArrayBuffer` + `Atomics.wait`
+ *   pattern: the worker owns the actual `sqlite3.Database` and handles
+ *   queries asynchronously. The main thread posts a request, then
+ *   blocks on `Atomics.wait` until the worker flips the sync flag and
+ *   stashes the JSON-serialisable result on its message port. Node
+ *   20+ permits `Atomics.wait` on the main thread; engine requirement
+ *   is `>=20`.
  *
- *   The full async port is tracked separately as V9 FT.3.1.4 (refactor
- *   `src/memory/store.ts` to async). For the FT.3 scaffold we ship the
- *   adapter with `available = false` and a doctor-friendly explanation.
+ *   The worker is shipped as an inline JavaScript blob (no extra file
+ *   to deploy). It dynamic-imports `sqlite3` on its own side, so a
+ *   missing module still surfaces via the `loadDriver()` probe before
+ *   any worker is spawned.
  *
- * Honest stub policy: We could fake-up sync semantics with deasync, but
- * deasync hides bugs and makes debugging a nightmare. Better to fail
- * cleanly and force the runtime to evolve toward an async memory store
- * — which is the right thing for Termux anyway, since the OS will
- * suspend background processes that block synchronously on I/O.
+ * Honest stub: if `sqlite3` fails to import, `available` is `false`,
+ *   `unavailableReason` includes the import error, and `open()` throws
+ *   `StorageNotSupportedError`. Never silently swallows errors —
+ *   propagates the worker's error message verbatim into the calling
+ *   thread on every `run`/`all`/`get`.
+ *
+ * Immutability: the adapter exposes no shared mutable state. Each
+ *   `open()` creates a fresh worker + handle. Closed handles refuse
+ *   further calls rather than mutating the database from a stale
+ *   reference.
  */
+import { Worker, receiveMessageOnPort } from "node:worker_threads";
 import { StorageNotSupportedError } from "./storage-adapter.js";
 let driverCache = null;
 let driverLoadError = "";
 /**
- * Lazy-import the `sqlite3` npm package. We do not declare it as a
+ * Lazy-import the `sqlite3` npm package. We do NOT declare it as a
  * runtime dependency of WOTANN — Termux users install it manually via
- * `npm install -g sqlite3` (the `install-termux.sh` script handles
+ * `npm install -g sqlite3` (the install-termux.sh script handles
  * this). Non-Termux users never load this module.
+ *
+ * On import failure we cache the error message so `probe()` can
+ * surface it to the doctor command and the tier-2 selector.
  */
 async function loadDriver() {
     if (driverCache !== null) {
         return driverCache;
     }
     try {
-        // The `sqlite3` package historically ships both a CommonJS and an
-        // ES Module entry. We prefer the verbose API (`.verbose()`) to get
-        // better error messages on schema bootstrap failures.
-        //
-        // The `@ts-expect-error` is load-bearing: `sqlite3` is intentionally
-        // NOT declared in WOTANN's package.json — Termux users install it
-        // separately via `npm install -g sqlite3`. On every other platform
-        // this dynamic import will fail at runtime (which is fine; we cache
-        // the failure and return a "not available" adapter).
         // @ts-expect-error sqlite3 is an optional Termux-only dependency
-        const mod = (await import("sqlite3"));
-        const verbose = mod.default.verbose();
-        driverCache = { Database: verbose.Database };
+        await import("sqlite3");
+        driverCache = true;
         return driverCache;
     }
     catch (err) {
@@ -77,78 +77,235 @@ async function loadDriver() {
     }
 }
 /**
- * Probe sqlite3 availability without forcing the import path on
- * non-Termux platforms.
+ * Test-only hook to reset the driver-cache. Lets the test suite force
+ * a re-probe between assertions without leaking module-global state.
+ * Not part of the public surface; flagged with the conventional
+ * underscore prefix.
+ */
+export function _resetDriverCacheForTests() {
+    driverCache = null;
+    driverLoadError = "";
+}
+/**
+ * Expose the probe for the doctor command + tests. Mirrors
+ * `isBetterSqliteAvailable()`.
  */
 export async function isNodeSqliteAvailable() {
     const state = await loadDriver();
-    return state !== false && state !== null;
+    return state === true;
 }
 /**
- * Prepared-statement façade for the async sqlite3 driver.
+ * Worker source. Lives inline so we ship as a single TS file.
+ *
+ * Protocol (parent -> worker, JSON-serialised over `parentPort`):
+ *   { kind: "open",  path: string }
+ *   { kind: "schema", sql: string }            // schema-bootstrap, no rows
+ *   { kind: "run",   sql: string, params: unknown[] }
+ *   { kind: "all",   sql: string, params: unknown[] }
+ *   { kind: "get",   sql: string, params: unknown[] }
+ *   { kind: "close" }
  *
- * IMPORTANT: This is a HONEST STUB. The real implementation requires
- * an async memory store — the existing `src/memory/store.ts` is
- * synchronous and would block forever on these methods if we naively
- * called the underlying async API.
+ * Replies (worker -> parent):
+ *   { ok: true,  value: unknown }
+ *   { ok: false, error: string }
  *
- * Until the async port lands (V9 FT.3.1.4), every method throws
- * `StorageNotSupportedError` so callers see a clean error at first
- * use rather than a silent hang.
+ * Synchronisation: the parent allocates a `SharedArrayBuffer` whose
+ * first Int32 slot is 0 (busy) before each request. The parent calls
+ * `Atomics.wait(view, 0, 0)`; the worker writes 1 with `Atomics.store`
+ * and `Atomics.notify` once the result is queued on its port. The
+ * parent then `receiveMessageOnPort`s the result synchronously.
+ */
+const WORKER_SOURCE = `
+const { parentPort } = require("node:worker_threads");
+let sqlite3;
+let db;
+
+parentPort.on("message", async (msg) => {
+  const { sab, request } = msg;
+  const view = new Int32Array(sab);
+  let reply;
+  try {
+    if (request.kind === "open") {
+      if (!sqlite3) {
+        sqlite3 = require("sqlite3").verbose();
+      }
+      db = await new Promise((resolve, reject) => {
+        const handle = new sqlite3.Database(request.path, (err) => {
+          if (err) reject(err);
+          else resolve(handle);
+        });
+      });
+      reply = { ok: true, value: null };
+    } else if (request.kind === "schema") {
+      await new Promise((resolve, reject) => {
+        db.exec(request.sql, (err) => {
+          if (err) reject(err);
+          else resolve(undefined);
+        });
+      });
+      reply = { ok: true, value: null };
+    } else if (request.kind === "run") {
+      const result = await new Promise((resolve, reject) => {
+        db.run(request.sql, request.params, function runCb(err) {
+          if (err) reject(err);
+          else resolve({ changes: this.changes, lastInsertRowid: this.lastID });
+        });
+      });
+      reply = { ok: true, value: result };
+    } else if (request.kind === "all") {
+      const rows = await new Promise((resolve, reject) => {
+        db.all(request.sql, request.params, (err, rows) => {
+          if (err) reject(err);
+          else resolve(rows);
+        });
+      });
+      reply = { ok: true, value: rows };
+    } else if (request.kind === "get") {
+      const row = await new Promise((resolve, reject) => {
+        db.get(request.sql, request.params, (err, row) => {
+          if (err) reject(err);
+          else resolve(row === undefined ? null : row);
+        });
+      });
+      reply = { ok: true, value: row };
+    } else if (request.kind === "close") {
+      if (db) {
+        await new Promise((resolve) => {
+          db.close(() => resolve(undefined));
+        });
+        db = undefined;
+      }
+      reply = { ok: true, value: null };
+    } else {
+      reply = { ok: false, error: "unknown request kind: " + String(request.kind) };
+    }
+  } catch (err) {
+    reply = { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+  parentPort.postMessage(reply);
+  Atomics.store(view, 0, 1);
+  Atomics.notify(view, 0);
+});
+`;
+/**
+ * Synchronous round-trip to the worker. Sends a request, blocks the
+ * thread via `Atomics.wait`, drains the reply queue via
+ * `receiveMessageOnPort`. Throws `StorageNotSupportedError` on
+ * worker-reported errors.
+ *
+ * Each call allocates a fresh `SharedArrayBuffer` so prior wait state
+ * cannot bleed between requests. The 30-second wait ceiling protects
+ * against worker hangs — a query that takes longer than that should
+ * never make it through WOTANN's memory store, and surfacing a
+ * timeout is preferable to deadlocking the calling thread.
+ */
+function syncCall(worker, request) {
+    const sab = new SharedArrayBuffer(4);
+    const view = new Int32Array(sab);
+    worker.postMessage({ sab, request });
+    const status = Atomics.wait(view, 0, 0, 30_000);
+    if (status === "timed-out") {
+        throw new StorageNotSupportedError("node-sqlite3", `sqlite3 worker timed out after 30s on ${request.kind} request`);
+    }
+    // Node's runtime accepts a `Worker` here even though the .d.ts
+    // declares only `MessagePort`. The runtime is correct (the worker
+    // owns its parent-facing port internally) so we cast to satisfy
+    // the type-checker without smuggling an unsound `any`.
+    const drained = receiveMessageOnPort(worker);
+    if (!drained) {
+        throw new StorageNotSupportedError("node-sqlite3", "sqlite3 worker did not deliver a reply (deasync bug — please report)");
+    }
+    const reply = drained.message;
+    if (!reply.ok) {
+        throw new StorageNotSupportedError("node-sqlite3", reply.error);
+    }
+    return reply.value;
+}
+/**
+ * Build the prepared-statement façade. Each call hits the worker;
+ * we do not cache compiled statements on the worker side because the
+ * `sqlite3.Database.prepare()` statement lifecycle would need to be
+ * tracked across worker messages — a complexity not worth paying for
+ * in the Termux fallback path. The parent-side SQL string is the
+ * cache key and re-sent on every invocation.
  */
-function buildStubStatement(sql) {
-    const reason = `sqlite3 (async) backend cannot satisfy the synchronous ` +
-        `StoragePreparedStatement contract. Statement: ${sql.slice(0, 64)}…`;
+function buildStatement(worker, sql) {
     return {
         run(...args) {
-            void args;
-            throw new StorageNotSupportedError("node-sqlite3", reason);
+            const value = syncCall(worker, {
+                kind: "run",
+                sql,
+                params: args,
+            });
+            return {
+                changes: value.changes,
+                lastInsertRowid: value.lastInsertRowid,
+            };
         },
         all(...args) {
-            void args;
-            throw new StorageNotSupportedError("node-sqlite3", reason);
+            const rows = syncCall(worker, {
+                kind: "all",
+                sql,
+                params: args,
+            });
+            return rows.map((r) => r ?? {});
         },
         get(...args) {
-            void args;
-            throw new StorageNotSupportedError("node-sqlite3", reason);
+            const row = syncCall(worker, {
+                kind: "get",
+                sql,
+                params: args,
+            });
+            return row === null || row === undefined ? undefined : row;
         },
     };
 }
 /**
- * Wrap a sqlite3 `Database` into a `StorageHandle`. Closing the
- * handle is best-effort — the async close callback is fired and we
- * ignore its result so the synchronous `close()` contract is honoured.
+ * Wrap the worker-backed sqlite3 database into a `StorageHandle`.
+ * Idempotent close. Calls on a closed handle throw rather than
+ * silently no-op, so misuse surfaces immediately.
  */
-function wrapHandle(db) {
-    const d = db;
+function wrapHandle(worker) {
     let closed = false;
     return {
         execSql(sql) {
-            void sql;
-            throw new StorageNotSupportedError("node-sqlite3", "Schema-exec on the async sqlite3 backend is not yet implemented (V9 FT.3.1.4 will port the memory store to async).");
+            if (closed) {
+                throw new StorageNotSupportedError("node-sqlite3", "execSql called on a closed handle");
+            }
+            syncCall(worker, { kind: "schema", sql });
         },
         prepare(sql) {
-            return buildStubStatement(sql);
+            if (closed) {
+                throw new StorageNotSupportedError("node-sqlite3", "prepare called on a closed handle");
+            }
+            return buildStatement(worker, sql);
         },
         close() {
             if (closed) {
                 return;
             }
             closed = true;
-            d.close(() => {
-                // Ignore — best-effort. Real implementation will surface
-                // close errors to telemetry once the async port lands.
-            });
+            try {
+                syncCall(worker, { kind: "close" });
+            }
+            catch {
+                // Best-effort: even if the close-message failed, we still
+                // want to terminate the worker so the process can exit
+                // cleanly. The error is intentionally swallowed here ONLY
+                // because we're already on the destruction path; live ops
+                // never swallow.
+            }
+            finally {
+                void worker.terminate();
+            }
         },
     };
 }
 /**
- * Concrete adapter. Probes the driver lazily and surfaces a clear
- * "not yet implemented" error when callers try to actually use it.
- *
- * This is wired into `selectStorageAdapter()` so the doctor command
- * can report "sqlite3 is installed but the async port isn't ready
- * yet" — which is much better than a silent hang on first read.
+ * Concrete adapter. Probes the driver lazily and, when present,
+ * spawns a fresh worker per `open()` to host the async sqlite3
+ * database. The synchronous façade hides the async hop from callers
+ * via `Atomics.wait` deasync.
  */
 export class NodeSqliteAdapter {
     platform = "node-sqlite3";
@@ -156,36 +313,35 @@ export class NodeSqliteAdapter {
     unavailableReason = "";
     async probe() {
         const state = await loadDriver();
-        if (state === false || state === null) {
+        if (state !== true) {
             this.available = false;
             this.unavailableReason =
                 driverLoadError ||
                     "sqlite3 npm package not installed (Termux users: `pkg install sqlite && npm install -g sqlite3`)";
             return;
         }
-        // Driver loads, but synchronous façade is not implemented.
-        // We mark unavailable so the selector falls through to the JSON
-        // fallback rather than crashing on first use.
-        this.available = false;
-        this.unavailableReason =
-            "sqlite3 driver is installed, but WOTANN's synchronous memory store is not yet ported to async (tracked as V9 FT.3.1.4). Use the JSON fallback or wait for the async memory port.";
+        this.available = true;
+        this.unavailableReason = "";
     }
     async open(path) {
-        void path;
         const state = await loadDriver();
-        if (state === false || state === null) {
+        if (state !== true) {
             throw new StorageNotSupportedError("node-sqlite3", this.unavailableReason || "sqlite3 driver is not available on this platform");
         }
-        // Driver loaded but contract not satisfied — return the stub
-        // handle so callers see honest errors rather than hangs.
-        const Ctor = state.Database;
-        const db = new Ctor(path);
-        return wrapHandle(db);
+        const worker = new Worker(WORKER_SOURCE, { eval: true });
+        try {
+            syncCall(worker, { kind: "open", path });
+        }
+        catch (err) {
+            void worker.terminate();
+            throw err;
+        }
+        return wrapHandle(worker);
     }
 }
 /**
  * Factory. Probes immediately so the selector can read `.available`
- * synchronously after the await.
+ * without an extra await round-trip.
  */
 export async function createNodeSqliteAdapter() {
     const adapter = new NodeSqliteAdapter();

package/dist/storage/sqlite-node-backend.js.map

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

package/dist/testing/webapp-server-lifecycle.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Web-app server lifecycle helper — TypeScript port of the
+ * `with_server.py` pattern from anthropics/skills/webapp-testing.
+ *
+ * Spawns a dev/test server as a subprocess, waits for it to become
+ * available (TCP probe or HTTP GET), yields a structured handle to
+ * the caller, and tears down with SIGTERM → grace period → SIGKILL.
+ *
+ * Honest-stub: all entry points return tagged `{ok, ...}` results;
+ * never throws on caller-controllable failure modes (bad command,
+ * port-never-ready, fn rejection inside withServer).
+ *
+ * Composes node:child_process — does NOT reimplement spawn/kill.
+ */
+export interface ServerLifecycleConfig {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    /** Probes localhost:port for connectability via TCP. */
+    readonly waitForPort?: number;
+    /** Probes URL for HTTP 200. Either this or waitForPort, not both required. */
+    readonly waitForUrl?: string;
+    /** Default 30000. */
+    readonly readyTimeoutMs?: number;
+    /** Default 250. */
+    readonly readyPollMs?: number;
+    /** Default 5000. SIGTERM grace before SIGKILL. */
+    readonly gracefulShutdownMs?: number;
+    /** Default true. Capture stdout/stderr in memory. */
+    readonly captureOutput?: boolean;
+}
+export interface ServerHandle {
+    readonly pid: number;
+    readonly port?: number;
+    readonly stdout: () => string;
+    readonly stderr: () => string;
+    readonly stop: () => Promise<void>;
+    readonly waitExit: () => Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+}
+export type StartServerResult = {
+    readonly ok: true;
+    readonly handle: ServerHandle;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type WithServerResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly stdout?: string;
+    readonly stderr?: string;
+};
+/**
+ * Start a server subprocess and wait until it is ready.
+ *
+ * Returns a tagged result; never throws.
+ */
+export declare function startServer(config: ServerLifecycleConfig): Promise<StartServerResult>;
+/**
+ * Run `fn` with a started server, then guarantee teardown.
+ *
+ * Captures fn's return value on success. On any failure (start, fn
+ * rejection, fn throw), returns ok:false with stdout/stderr for
+ * diagnosis. Teardown happens in `finally` semantics.
+ */
+export declare function withServer<T>(config: ServerLifecycleConfig, fn: (handle: ServerHandle) => Promise<T>): Promise<WithServerResult<T>>;
+//# sourceMappingURL=webapp-server-lifecycle.d.ts.map

package/dist/testing/webapp-server-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webapp-server-lifecycle.d.ts","sourceRoot":"","sources":["../../src/testing/webapp-server-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mBAAmB;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;QAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAUN;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqG3F;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE,qBAAqB,EAC7B,EAAE,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GACvC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAoB9B"}