@yydb/light-db 0.0.18 → 0.1.2

package/dist/shared/micro.js

@@ -0,0 +1,194 @@
+/**
+ * Host micro registry and definition helpers for `@yydb/light-db`.
+ *
+ * Mirrors the Node-side `@yydb/yydb` micro contract but speaks to the WASM
+ * session's JSON bridge (`registerMicroJson` / `callScalarJson`) instead of
+ * the N-API layer. No binary wire protocol is encoded here — Rust owns that.
+ */
+/** Map a VOS descriptor onto its wire tag. Throws for unsupported kinds. */
+export function udfWireKind(descriptor) {
+    switch (descriptor.kind) {
+        case 'i64':
+            return 'i64';
+        case 'bool':
+            return 'bool';
+        case 'utf8':
+            return 'text';
+        default:
+            throw new Error(`unsupported micro type descriptor: ${descriptor.kind}`);
+    }
+}
+let nextHostId = 1;
+/**
+ * Per-session registry for JS functions behind opaque host handles.
+ *
+ * WASM keeps `hostId + functionId + handleVersion`, never the closure. The
+ * WASM session's `setMicroHostInvoker` should call
+ * {@link MicroSessionRegistry.invokeFromWire} to route host calls back into
+ * author code.
+ */
+export class MicroSessionRegistry {
+    hostId;
+    nextFunctionId = 1;
+    byKey = new Map();
+    byFunctionId = new Map();
+    constructor(hostId = nextHostId++) {
+        this.hostId = hostId;
+    }
+    /** Installs a defined micro into this session registry. */
+    register(definition) {
+        const key = logicalKey(definition.name, definition.version);
+        if (this.byKey.has(key)) {
+            throw new Error(`micro already registered: ${definition.name}@${definition.version}`);
+        }
+        const functionId = String(this.nextFunctionId++);
+        const handle = {
+            name: definition.name,
+            version: definition.version,
+            functionId,
+            hostId: this.hostId,
+            implementationVersion: 1,
+        };
+        const entry = { handle, definition: definition };
+        this.byKey.set(key, entry);
+        this.byFunctionId.set(functionId, entry);
+        return handle;
+    }
+    /** Returns a registered micro by opaque host handle. */
+    resolve(handle) {
+        if (handle.hostId !== this.hostId) {
+            return undefined;
+        }
+        return this.byFunctionId.get(handle.functionId)?.definition;
+    }
+    /** Invokes a registered micro from a wire `MicroHostInvoke` payload. */
+    invokeFromWire(payload) {
+        const handle = {
+            hostId: payload.hostId,
+            functionId: payload.functionId,
+            implementationVersion: payload.handleVersion,
+            name: '',
+            version: 0,
+        };
+        const definition = this.resolve(handle);
+        if (!definition) {
+            throw new Error(`micro not found: ${payload.functionId}`);
+        }
+        const args = definition.args.map((descriptor, index) => wireToBoundary(descriptor, payload.args[index]));
+        return boundaryToWire(definition.returns, this.invokeScalar(handle, args));
+    }
+    /** Direct scalar invocation (host adapter entry point). */
+    invokeScalar(handle, args) {
+        const definition = this.resolve(handle);
+        if (!definition) {
+            throw new Error(`micro not found: ${handle.functionId}`);
+        }
+        if (definition.mode !== 'scalar') {
+            throw new Error(`micro ${definition.name} is not scalar mode`);
+        }
+        if (args.length !== definition.args.length) {
+            throw new Error(`micro ${definition.name} arity mismatch: expected ${definition.args.length}, got ${args.length}`);
+        }
+        definition.args.forEach((descriptor, index) => {
+            validateValue(descriptor, args[index], `micro ${definition.name} arg ${index}`);
+        });
+        const result = definition.fn(...args);
+        validateValue(definition.returns, result, `micro ${definition.name} return`);
+        return result;
+    }
+    /** Lists logical names currently registered in this session. */
+    list() {
+        return [...this.byKey.values()].map((entry) => entry.definition.name).sort();
+    }
+}
+/** Build a session-local micro definition without registering it. */
+export function defineMicro(input) {
+    if (!input.name.trim()) {
+        throw new Error('micro name must not be empty');
+    }
+    if (!Number.isInteger(input.version) || input.version <= 0) {
+        throw new Error('micro version must be a positive integer');
+    }
+    if (input.effect !== 'pure') {
+        throw new Error('TS micro effect must be pure in Phase 1');
+    }
+    if (!input.deterministic) {
+        throw new Error('TS micro must be deterministic in Phase 1');
+    }
+    if (typeof input.fn !== 'function') {
+        throw new Error('micro fn must be a function');
+    }
+    input.args.forEach((descriptor, index) => {
+        assertSupportedDescriptor(descriptor, `micro ${input.name} arg ${index}`);
+    });
+    assertSupportedDescriptor(input.returns, `micro ${input.name} return`);
+    return {
+        name: input.name,
+        version: input.version,
+        args: input.args,
+        returns: input.returns,
+        effect: input.effect,
+        deterministic: input.deterministic,
+        mode: input.mode ?? 'scalar',
+        placement: 'host',
+        fn: input.fn,
+    };
+}
+/** Stable 32-byte fingerprint for a logical micro name and version. */
+export function microFingerprint(name, version) {
+    const bytes = new Uint8Array(32);
+    const seed = `${name}@${version}`;
+    for (let index = 0; index < bytes.byteLength; index += 1) {
+        bytes[index] = seed.charCodeAt(index % seed.length) & 0xff;
+    }
+    return bytes;
+}
+function logicalKey(name, version) {
+    return `${name}@${version}`;
+}
+function assertSupportedDescriptor(descriptor, label) {
+    try {
+        udfWireKind(descriptor);
+    }
+    catch {
+        throw new Error(`${label} uses a descriptor outside the Phase-1 micro subset`);
+    }
+}
+/** Validate a boundary value against a descriptor. */
+function validateValue(descriptor, value, label) {
+    switch (udfWireKind(descriptor)) {
+        case 'i64':
+            if (typeof value !== 'bigint') {
+                throw new Error(`${label} expects VOS \`i64\` (a bigint)`);
+            }
+            break;
+        case 'bool':
+            if (typeof value !== 'boolean') {
+                throw new Error(`${label} expects VOS \`bool\``);
+            }
+            break;
+        case 'text':
+            if (typeof value !== 'string') {
+                throw new Error(`${label} expects VOS \`utf8\` (a string)`);
+            }
+            break;
+    }
+}
+/** Convert a wire value (number for i64, string, bool, null) to a boundary value. */
+function wireToBoundary(descriptor, value) {
+    if (udfWireKind(descriptor) === 'i64' && typeof value === 'number' && Number.isSafeInteger(value)) {
+        return BigInt(value);
+    }
+    return value;
+}
+/** Boundary value → wire subset; i64 must still fit a JS number. */
+function boundaryToWire(descriptor, value) {
+    if (udfWireKind(descriptor) === 'i64' && typeof value === 'bigint') {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+            throw new Error(`micro return i64 ${value} does not fit the wire number path`);
+        }
+        return Number(value);
+    }
+    return value;
+}
+//# sourceMappingURL=micro.js.map

package/dist/shared/micro.js.map

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

package/dist/shared/udf-types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Host micro (UDF) boundary types — browser WASM product subset.
+ *
+ * Descriptors come straight from `@voml/vos`: `v.i64()`, `v.bool()`, `v.utf8()`.
+ * `@yydb/light-db` keeps no scalar descriptor algebra of its own — it simply
+ * re-exports the VOS descriptors the Phase-1 UDF boundary accepts.
+ *
+ * `null` is not a descriptor; it is a value carried by the wire subset.
+ * This module is types-only and can be stripped at compile time.
+ */
+import type { Infer, TypeDescriptor } from '@voml/vos';
+/** Phase-1 scalar kinds on the YY wire micro path, aligned with `yydb-udf`. */
+export type UdfScalarKind = 'i64' | 'bool' | 'text' | 'null';
+/**
+ * VOS descriptors accepted at the Phase-1 host micro boundary.
+ *
+ * Non-scalar descriptors (`v.optional(…)`, `v.list(…)`, `v.utf16()`, …) are
+ * rejected before they reach the wire.
+ */
+export type UdfScalarDescriptor = TypeDescriptor<'i64', bigint> | TypeDescriptor<'bool', boolean> | TypeDescriptor<'utf8', string>;
+/** Maps a descriptor tuple to positional boundary value types. */
+export type InferUdfArgs<T extends readonly UdfScalarDescriptor[]> = {
+    [K in keyof T]: Infer<T[K]>;
+};
+/** Maps a return descriptor to its boundary value type. */
+export type InferUdfReturn<T extends UdfScalarDescriptor> = Infer<T>;
+/** Session micro effect surface (Phase 1: pure only). */
+export type MicroEffect = 'pure';
+/** Invocation mode — scalar for Phase 1, batch reserved for future. */
+export type MicroInvocationMode = 'scalar' | 'batch';
+//# sourceMappingURL=udf-types.d.ts.map

package/dist/shared/udf-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"udf-types.d.ts","sourceRoot":"","sources":["../../src/shared/udf-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GACzB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErC,kEAAkE;AAClE,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,mBAAmB,EAAE,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9B,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,mBAAmB,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;AAErE,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,uEAAuE;AACvE,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,OAAO,CAAC"}

package/dist/shared/udf-types.js

@@ -0,0 +1,12 @@
+/**
+ * Host micro (UDF) boundary types — browser WASM product subset.
+ *
+ * Descriptors come straight from `@voml/vos`: `v.i64()`, `v.bool()`, `v.utf8()`.
+ * `@yydb/light-db` keeps no scalar descriptor algebra of its own — it simply
+ * re-exports the VOS descriptors the Phase-1 UDF boundary accepts.
+ *
+ * `null` is not a descriptor; it is a value carried by the wire subset.
+ * This module is types-only and can be stripped at compile time.
+ */
+export {};
+//# sourceMappingURL=udf-types.js.map

package/dist/shared/udf-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"udf-types.js","sourceRoot":"","sources":["../../src/shared/udf-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yydb/light-db",
-  "version": "0.0.18",
-  "description": "Light DB — browser-native YYDB database written in pure TypeScript",
+  "version": "0.1.2",
+  "description": "Light DB — browser-native YYDB database backed by Rust WASM (yydb-unknown-wasm32)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -9,9 +9,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx tests/index.ts",
-    "test:browser": "tsx tests/browser/run.ts"
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "yydb",
@@ -43,7 +41,7 @@
     "typescript": "^5.3.0"
   },
   "dependencies": {
-    "@voml/vos": "^0.0.1",
-    "@yydb/yydb-unknown-wasm32": "0.0.18"
+    "@voml/vos": "^0.0.5",
+    "@yydb/yydb-unknown-wasm32": "0.1.2"
   }
 }

package/readme.md

@@ -1,98 +1,91 @@
 # `@yydb/light-db`
 
-**Light DB** is the browser edition of YYDB: a database written in pure TypeScript that stores `.yydb`-style
-snapshots, WAL records and checkpoints in browser storage. It has no Node built-ins, no N-API bindings and no WASM in
-its runtime path.
+**Light DB** is the browser-native edition of YYDB. A thin TypeScript facade over
+`@yydb/yydb-unknown-wasm32`, which ships the Rust semantic core compiled to
+WebAssembly — same engine as the Node-side `@yydb/yydb`, same OPFS persistence,
+same VOS schema validation, same transaction and UDF semantics.
+
+> No Node built-ins. No filesystem paths. No second semantic implementation.
+> One package, one implementation: WASM-backed `Database`.
 
 ## Product relationship
 
 | Package | Role |
 |---------|------|
-| `@yydb/yydb` | Node product: native Rust engine, N-API, local `.yydb` / `.yydx` files and CLI |
-| `@yydb/light-db` | Browser product: pure TypeScript, OPFS / IndexedDB storage, Web APIs, same author surface |
-| `@yydb/yydb-client` | Remote wire client for a running `yydb serve` |
-
-## Status
-
-Light DB is a migration of the original `LightDB.ts` engine, rebuilt around a browser-native architecture. The package
-ships as a pre-1.0 release of the browser product, so the author surface may still change between patch releases.
-
-Current coverage:
-
-- `pnpm test` runs the Node-side runner over codec, adapter and database logic (29 cases).
-- `pnpm test:browser` runs the conformance suite in an installed Chrome (16 cases): OPFS persistence across reopen, WAL
-  recovery, checkpoint truncation, corruption detection, single-writer exclusion, transaction rollback and commit,
-  schema and close notifications, and two-tab lease and broadcast behaviour.
+| `@yydb/yydb` | Node product: native Rust engine, N-API, local `.yydb` / `.yydx` files, CLI |
+| `@yydb/light-db` | **This package** — browser product: WASM core over OPFS, same author surface |
+| `@yydb/yydb-client` | Remote wire client for a running `yydb serve` (TCP or WebSocket) |
 
 ## Usage
 
 ```ts
-import { LightDbError, openLightDatabase } from '@yydb/light-db';
+import { Database } from '@yydb/light-db';
 
-const db = await openLightDatabase('app');
+const db = await Database.open('app');
 
-await db.ensureSchema('// @yydb-schema-version: 1\nkv users');
-await db.put('user:1', new TextEncoder().encode('Ada'));
+// Schema — either raw source or @voml/vos descriptors
+await db.ensureSchema('table Setting { @@id: uuid, key: utf8 }');
+// or: await db.ensureSchema(v.table('Setting', { key: v.text() }));
 
+await db.put('user:1', new TextEncoder().encode('Ada'));
 const value = await db.get('user:1');
-await db.checkpoint();
+
+// VOS read / write
+const users = await db.query('User.all().take(10).collect()');
+await db.execute('INSERT User { @@id: uuid(), name: "Ada" }');
+
+// Transactions
+await db.transaction(async (tx) => {
+    await tx.put('user:2', new TextEncoder().encode('Grace'));
+    await tx.put('user:3', new TextEncoder().encode('Eve'));
+});
+
 await db.close();
 ```
 
-Public data types are browser-native: keys and values use `Uint8Array`, databases are addressed by name rather than by
-file path, and every lifecycle call is asynchronous.
-
 ## Author surface
 
 ```ts
-const db: LightDatabase = await openLightDatabase('app', options);
-
-await db.schema();
-await db.ensureSchema(document);
-await db.get(key);
-await db.put(key, value);
-await db.delete(key);
-await db.begin();
-await db.commit();
-await db.rollback();
-await db.checkpoint();
-db.stats();
-await db.close();
-```
+await db.serverVersion();            // engine version string
+await db.info();                      // session diagnostics
 
-`schema()` returns the persisted schema version and document. The document is the single source of truth: a second
-`ensureSchema` call must pass the identical document, otherwise it fails with `yydb.schema.conflict`. Keys starting with
-`__yydb__/` are reserved for the database.
+await db.getSchema();                 // { version, document } | null
+await db.ensureSchema(document);      // publish schema
+await db.migrateSchema(source, { renames: [...] });
 
-## Storage backends
+await db.get(key);                    // Uint8Array | null
+await db.put(key, value);             // value: Uint8Array | string
+await db.delete(key);                 // void
+await db.scan({ prefix, after, limit });
 
-| Adapter | Use |
-|---------|-----|
-| `OpfsStorageAdapterFactory` | Default. Origin Private File System, positional reads and writes, atomic snapshot publication |
-| `IndexedDbStorageAdapterFactory` | Compatibility backend for hosts without OPFS |
-| `MemoryStorageBackend` | Tests and throwaway sessions |
+await db.batch([{ key, value }, ...]);
+await db.compareExchange(key, expected, replacement);
 
-`StorageAdapter` is the only platform boundary. Transactions, recovery and checkpoint semantics live in `core`, so
-backends implement files, not database behaviour.
+await db.begin(); await db.commit(); await db.rollback();
+await db.transaction(async (tx) => { ... });
 
-## Concurrency
+await db.query(source);               // VOS read pipeline → typed rows[]
+await db.execute(source);             // VOS write program
 
-A writer holds a session-scoped `Web Locks` lease. A second tab that opens the same database fails with
-`yydb.lease.unavailable` and `retryable: true` instead of silently writing alongside the first one. When a lock manager
-is missing the call fails the same way; it never degrades to multiple writers.
+await db.registerMicro(body);         // host UDF wire-format registration
+await db.callScalar(body);            // host UDF invocation
+await db.setMicroHostInvoker(fn);     // JS → Rust UDF bridge
 
-`BroadcastChannel` carries `commit`, `schema` and `close` events so other same-origin contexts can discard stale views
-and retry after the lease is released. `listenDatabaseEvents(name, handler)` subscribes without opening the database.
+await db.checkpoint();                // fold WAL into main file
+await db.close();
+```
+
+Data types are browser-native: keys are strings, values are `Uint8Array`,
+databases are addressed by name (no file paths), and every lifecycle call is
+`async`.
 
 ## Layout
 
 | Path | Role |
 |------|------|
-| `src/api/` | Public database, transaction, schema and shared types |
-| `src/core/` | Records, WAL, checkpoint, recovery, writer lease and broadcast |
-| `src/storage/` | `StorageAdapter` plus OPFS, IndexedDB and memory backends |
-| `src/codec/` | Page, snapshot and WAL record encoding over `Uint8Array` |
-| `src/errors/` | Stable `yydb.*` error codes |
+| `src/api/wasm-database.ts` | Main {@link Database} facade over WASM sessions |
+| `src/api/types.ts` | Public type contract (SchemaVersion, ScanRow, LightDatabase, …) |
+| `src/errors/` | Stable `yydb.*` error codes and envelope parsing |
 
 ## Errors
 
@@ -107,4 +100,8 @@ and retry after the lease is released. `listenDatabaseEvents(name, handler)` sub
 | `yydb.lease.unavailable` | Writer lease is held elsewhere or Web Locks is missing (retryable) |
 | `yydb.quota.exceeded` | Browser storage quota is exhausted |
 
-[YYDB overview](https://github.com/yy-database/yydb.rs)
+## See also
+
+- [YYDB overview](https://github.com/yy-database/yydb)
+- [@yydb/yydb-unknown-wasm32](https://github.com/yy-database/yydb/tree/dev/projects/packages/yydb-unknown-wasm32) — the Rust semantic core
+- [Project structure](https://github.com/yy-database/yydb/tree/dev/projects/packages/homepage/documentation/zh-hans)

package/dist/api/database.d.ts

@@ -1,101 +0,0 @@
-/**
- * Schema 版本与文档。
- *
- * 共享类型：纯 TS {@link Database} 与 WASM {@link WasmDatabase} 都使用同一版本模型。
- */
-export interface SchemaVersion {
-    version: number;
-    document: string;
-}
-/** One row from a scan. */
-export interface ScanRow {
-    key: string;
-    value: Uint8Array;
-}
-/** Options for scan. */
-export interface ScanOptions {
-    prefix?: string;
-    after?: string | null;
-    limit?: number;
-}
-/** One batch change. */
-export interface BatchChange {
-    key: string;
-    value: Uint8Array | string | null;
-}
-/** Options for migrateSchema. */
-export interface MigrateOptions {
-    renames?: ReadonlyArray<{
-        fromType: string;
-        toType: string;
-    } | {
-        type: string;
-        fromField: string;
-        toField: string;
-    }>;
-}
-/** 打开浏览器 WASM 数据库的选项。 */
-export interface OpenOptions {
-    /** 使用内存 session（测试专用；默认使用 OPFS 持久 session）。 */
-    memory?: boolean;
-}
-import type { CheckpointResult, StorageEngineStats } from '../core/engine.js';
-import type { LightDatabase, LightDatabaseOptions } from './types.js';
-/**
- * 浏览器可用的纯 TS 数据库实现。
- *
- * 与 Node 侧 `@yydb/yydb` 的 {@link Database} 同构：宿主靠 import 来源区分：
- *
- * ```ts
- * import { Database } from '@yydb/yydb';       // Node 原生
- * import { Database } from '@yydb/light-db';   // 浏览器纯 TS（本文件）
- * ```
- *
- * 完全不依赖 WASM；OPFS 持久化、WAL 恢复、检查点、事务都在 TypeScript 内完成。
- *
- * 默认后端是 `OpfsStorageAdapterFactory`；通过 `options.storage` 可以显式指定。
- */
-export declare class Database implements LightDatabase {
-    /** 数据库名 */
-    readonly name: string;
-    private readonly engine;
-    private readonly transaction;
-    private constructor();
-    /**
-     * 打开数据库
-     * @param name 数据库名
-     * @param options 打开选项
-     */
-    static open(name: string, options?: LightDatabaseOptions): Promise<Database>;
-    /** 读取已持久化的 schema */
-    schema(): Promise<SchemaVersion | null>;
-    /**
-     * 声明 schema 文档
-     *
-     * 文档是唯一真相：首次写入后，重复调用必须传入完全相同的文档。
-     */
-    ensureSchema(document: string): Promise<void>;
-    /** 读取键 */
-    get(key: string): Promise<Uint8Array | null>;
-    /** 写入键 */
-    put(key: string, value: Uint8Array): Promise<void>;
-    /** 删除键 */
-    delete(key: string): Promise<boolean>;
-    /** 开始事务 */
-    begin(): Promise<void>;
-    /** 提交事务 */
-    commit(): Promise<void>;
-    /** 回滚事务 */
-    rollback(): Promise<void>;
-    /** 执行检查点 */
-    checkpoint(): Promise<CheckpointResult>;
-    /** 统计信息 */
-    stats(): StorageEngineStats;
-    /** 关闭数据库 */
-    close(): Promise<void>;
-    /**
-     * 校验用户键
-     */
-    private assertUserKey;
-}
-//# sourceMappingURL=database.d.ts.map

package/dist/api/database.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/api/database.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,2BAA2B;AAC3B,MAAM,WAAW,OAAO;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,CAAC;CACrB;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,aAAa,CACjB;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACpC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CACzD,CAAC;CACL;AAED,yBAAyB;AACzB,MAAM,WAAW,WAAW;IACxB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAOD,OAAO,KAAK,EAAE,gBAAgB,EAAwB,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMpG,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAKtE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,YAAW,aAAa;IAC1C,WAAW;IACX,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C,OAAO;IAMP;;;;OAIG;WACiB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmB7F,qBAAqB;IACR,MAAM,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAKpD;;;;OAIG;IACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D,UAAU;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIzD,UAAU;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D,UAAU;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD,WAAW;IACE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,WAAW;IACE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC,WAAW;IACE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,YAAY;IACC,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIpD,WAAW;IACJ,KAAK,IAAI,kBAAkB;IAIlC,YAAY;IACC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC;;OAEG;IACH,OAAO,CAAC,aAAa;CAWxB"}