@f0rbit/corpus 0.1.5 → 0.1.6

package/dist/observations/storage.d.ts.map

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

package/dist/observations/storage.js

@@ -0,0 +1,137 @@
+/**
+ * @module ObservationsStorage
+ * @description Raw storage interface and row conversion utilities for observations.
+ */
+import { ok } from '../types';
+/**
+ * Extract common fields from an observation row (everything except content).
+ * Used internally by row_to_observation and row_to_meta.
+ */
+function row_to_base(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        source: {
+            store_id: row.source_store_id,
+            version: row.source_version,
+            ...(row.source_path && { path: row.source_path }),
+            ...(row.source_span_start && row.source_span_end && {
+                span: {
+                    start: parseInt(row.source_span_start, 10),
+                    end: parseInt(row.source_span_end, 10)
+                }
+            })
+        },
+        ...(row.confidence !== null && { confidence: row.confidence }),
+        ...(row.observed_at && { observed_at: new Date(row.observed_at) }),
+        created_at: new Date(row.created_at),
+        ...(row.derived_from && { derived_from: JSON.parse(row.derived_from) })
+    };
+}
+/**
+ * Convert a storage row to an Observation (includes content).
+ */
+export function row_to_observation(row) {
+    return {
+        ...row_to_base(row),
+        content: JSON.parse(row.content)
+    };
+}
+/**
+ * Convert a storage row to ObservationMeta (excludes content).
+ */
+export function row_to_meta(row) {
+    return row_to_base(row);
+}
+/**
+ * Create an ObservationRow from put options.
+ */
+export function create_observation_row(id, type_name, source, content, opts) {
+    const now = new Date();
+    return {
+        id,
+        type: type_name,
+        source_store_id: source.store_id,
+        source_version: source.version,
+        source_path: source.path ?? null,
+        source_span_start: source.span?.start?.toString() ?? null,
+        source_span_end: source.span?.end?.toString() ?? null,
+        content: JSON.stringify(content),
+        confidence: opts.confidence ?? null,
+        observed_at: opts.observed_at?.toISOString() ?? null,
+        created_at: now.toISOString(),
+        derived_from: opts.derived_from ? JSON.stringify(opts.derived_from) : null
+    };
+}
+/**
+ * Filter and sort observation rows based on query options.
+ * Used by in-memory storage implementations (memory backend, file backend).
+ */
+export function filter_observation_rows(rows, opts = {}) {
+    let filtered = rows;
+    if (opts.type) {
+        const types = Array.isArray(opts.type) ? opts.type : [opts.type];
+        filtered = filtered.filter(r => types.includes(r.type));
+    }
+    if (opts.source_store_id) {
+        filtered = filtered.filter(r => r.source_store_id === opts.source_store_id);
+    }
+    if (opts.source_version) {
+        filtered = filtered.filter(r => r.source_version === opts.source_version);
+    }
+    if (opts.source_prefix) {
+        filtered = filtered.filter(r => r.source_version.startsWith(opts.source_prefix));
+    }
+    if (opts.created_after) {
+        filtered = filtered.filter(r => r.created_at > opts.created_after);
+    }
+    if (opts.created_before) {
+        filtered = filtered.filter(r => r.created_at < opts.created_before);
+    }
+    if (opts.observed_after) {
+        filtered = filtered.filter(r => r.observed_at && r.observed_at > opts.observed_after);
+    }
+    if (opts.observed_before) {
+        filtered = filtered.filter(r => r.observed_at && r.observed_at < opts.observed_before);
+    }
+    filtered.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    if (opts.limit) {
+        filtered = filtered.slice(0, opts.limit);
+    }
+    return filtered;
+}
+/**
+ * Create an ObservationsStorage from simple CRUD operations.
+ * Used by memory and file backends.
+ */
+export function create_observations_storage(crud) {
+    return {
+        async put_row(row) {
+            await crud.add_one(row);
+            return ok(row);
+        },
+        async get_row(id) {
+            const row = await crud.get_one(id);
+            return ok(row);
+        },
+        async *query_rows(opts = {}) {
+            const rows = filter_observation_rows(await crud.get_all(), opts);
+            for (const row of rows) {
+                yield row;
+            }
+        },
+        async delete_row(id) {
+            const deleted = await crud.remove_one(id);
+            return ok(deleted);
+        },
+        async delete_by_source(store_id, version, path) {
+            const rows = await crud.get_all();
+            const toKeep = rows.filter(r => !(r.source_store_id === store_id &&
+                r.source_version === version &&
+                (path === undefined || r.source_path === path)));
+            const deleted = rows.length - toKeep.length;
+            await crud.set_all(toKeep);
+            return ok(deleted);
+        }
+    };
+}

package/dist/observations/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @module ObservationTypes
+ * @description Type definitions for the observations feature.
+ */
+import type { ZodType } from 'zod';
+/**
+ * Universal address to versioned content within a corpus store.
+ *
+ * A SnapshotPointer identifies a specific location within a versioned snapshot:
+ * - `store_id` + `version` - Required: which snapshot
+ * - `path` - Optional: JSONPath expression to a specific element
+ * - `span` - Optional: character range within text content
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * // Point to entire snapshot
+ * const pointer: SnapshotPointer = {
+ *   store_id: 'hansard',
+ *   version: 'AZJx4vM'
+ * }
+ *
+ * // Point to specific speech within a transcript
+ * const speechPointer: SnapshotPointer = {
+ *   store_id: 'hansard',
+ *   version: 'AZJx4vM',
+ *   path: '$.content[0].speeches[2]'
+ * }
+ *
+ * // Point to text range within content
+ * const rangePointer: SnapshotPointer = {
+ *   store_id: 'hansard',
+ *   version: 'AZJx4vM',
+ *   path: '$.content[0].speeches[2].text',
+ *   span: { start: 100, end: 250 }
+ * }
+ * ```
+ */
+export type SnapshotPointer = {
+    store_id: string;
+    version: string;
+    path?: string;
+    span?: {
+        start: number;
+        end: number;
+    };
+};
+/**
+ * Definition for a typed observation schema.
+ *
+ * Created by `define_observation_type()` and passed to `observations.put()`.
+ * The schema validates observation content and provides type inference.
+ *
+ * @category Types
+ * @group Observation Types
+ */
+export type ObservationTypeDef<T> = {
+    readonly name: string;
+    readonly schema: ZodType<T>;
+};
+/**
+ * A stored observation record linking structured facts to versioned content.
+ *
+ * Observations are typed facts extracted from or computed about content:
+ * - `source` - Points to the content this observation is about
+ * - `content` - The typed observation data (validated by schema)
+ * - `confidence` - Optional confidence score (0.0 to 1.0)
+ * - `observed_at` - When the observation was made (vs when stored)
+ * - `derived_from` - Optional provenance chain for computed observations
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * const observation: Observation<EntityMention> = {
+ *   id: 'obs_abc123',
+ *   type: 'entity_mention',
+ *   source: { store_id: 'hansard', version: 'AZJx4vM', path: '$.speeches[0]' },
+ *   content: { entity: 'Climate Change', entity_type: 'topic' },
+ *   confidence: 0.95,
+ *   observed_at: new Date('2024-01-15'),
+ *   created_at: new Date(),
+ *   derived_from: [{ store_id: 'hansard', version: 'AZJx4vM' }]
+ * }
+ * ```
+ */
+export type Observation<T = unknown> = {
+    id: string;
+    type: string;
+    source: SnapshotPointer;
+    content: T;
+    confidence?: number;
+    observed_at?: Date;
+    created_at: Date;
+    derived_from?: SnapshotPointer[];
+};
+/**
+ * Observation metadata without content payload.
+ *
+ * Used for efficient listing operations where only metadata is needed.
+ *
+ * @category Types
+ * @group Observation Types
+ */
+export type ObservationMeta = Omit<Observation<never>, 'content'>;
+/**
+ * Query options for filtering observations.
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * // Find recent entity mentions from a specific store
+ * const opts: ObservationQueryOpts = {
+ *   type: 'entity_mention',
+ *   source_store: 'hansard',
+ *   after: new Date('2024-01-01'),
+ *   limit: 100
+ * }
+ *
+ * // Find all observations for a specific version
+ * const versionOpts: ObservationQueryOpts = {
+ *   source_store: 'hansard',
+ *   source_version: 'AZJx4vM',
+ *   include_stale: true
+ * }
+ * ```
+ */
+export type ObservationQueryOpts = {
+    type?: string | string[];
+    source_store?: string;
+    source_version?: string;
+    source_prefix?: string;
+    after?: Date;
+    before?: Date;
+    created_after?: Date;
+    created_before?: Date;
+    include_stale?: boolean;
+    limit?: number;
+    cursor?: string;
+};
+/**
+ * Options for creating a new observation.
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * const opts: ObservationPutOpts<EntityMention> = {
+ *   source: { store_id: 'hansard', version: 'AZJx4vM', path: '$.speeches[0]' },
+ *   content: { entity: 'Climate Change', entity_type: 'topic' },
+ *   confidence: 0.95,
+ *   observed_at: new Date(),
+ *   derived_from: [{ store_id: 'raw_text', version: 'xyz789' }]
+ * }
+ * ```
+ */
+export type ObservationPutOpts<T> = {
+    source: SnapshotPointer;
+    content: T;
+    confidence?: number;
+    observed_at?: Date;
+    derived_from?: SnapshotPointer[];
+};
+/**
+ * Defines a typed observation schema.
+ *
+ * Creates an ObservationTypeDef that provides:
+ * - Runtime validation via Zod schema
+ * - Compile-time type inference for content
+ * - Named type for querying and filtering
+ *
+ * @category Core
+ * @group Observation Helpers
+ * @param name - Unique identifier for this observation type
+ * @param schema - Zod schema for validating observation content
+ * @returns An ObservationTypeDef to pass to `observations.put()`
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const EntityMentionSchema = z.object({
+ *   entity: z.string(),
+ *   entity_type: z.enum(['person', 'organization', 'topic', 'location']),
+ *   context: z.string().optional()
+ * })
+ *
+ * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
+ *
+ * // Type-safe usage
+ * await corpus.observations.put(entity_mention, {
+ *   source: { store_id: 'hansard', version: 'abc123' },
+ *   content: { entity: 'Parliament', entity_type: 'organization' }
+ * })
+ * ```
+ */
+export declare function define_observation_type<T>(name: string, schema: ZodType<T>): ObservationTypeDef<T>;
+/**
+ * Utility type to extract the content type from an ObservationTypeDef.
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
+ *
+ * type EntityMention = InferObservationContent<typeof entity_mention>
+ * // => { entity: string; entity_type: 'person' | 'organization' | ... }
+ * ```
+ */
+export type InferObservationContent<T> = T extends ObservationTypeDef<infer C> ? C : never;
+//# sourceMappingURL=types.d.ts.map

package/dist/observations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../observations/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;CACF,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,UAAU,EAAE,IAAI,CAAA;IAChB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,cAAc,CAAC,EAAE,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA"}

package/dist/observations/types.js

@@ -0,0 +1,40 @@
+/**
+ * @module ObservationTypes
+ * @description Type definitions for the observations feature.
+ */
+/**
+ * Defines a typed observation schema.
+ *
+ * Creates an ObservationTypeDef that provides:
+ * - Runtime validation via Zod schema
+ * - Compile-time type inference for content
+ * - Named type for querying and filtering
+ *
+ * @category Core
+ * @group Observation Helpers
+ * @param name - Unique identifier for this observation type
+ * @param schema - Zod schema for validating observation content
+ * @returns An ObservationTypeDef to pass to `observations.put()`
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const EntityMentionSchema = z.object({
+ *   entity: z.string(),
+ *   entity_type: z.enum(['person', 'organization', 'topic', 'location']),
+ *   context: z.string().optional()
+ * })
+ *
+ * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
+ *
+ * // Type-safe usage
+ * await corpus.observations.put(entity_mention, {
+ *   source: { store_id: 'hansard', version: 'abc123' },
+ *   content: { entity: 'Parliament', entity_type: 'organization' }
+ * })
+ * ```
+ */
+export function define_observation_type(name, schema) {
+    return { name, schema };
+}

package/dist/observations/utils.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @module ObservationUtils
+ * @description Utility functions for working with SnapshotPointers and observations.
+ */
+import type { SnapshotPointer } from './types';
+import type { Result, CorpusError } from '../types';
+/**
+ * Creates a SnapshotPointer to a location in a snapshot.
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param store_id - The store identifier
+ * @param version - The snapshot version
+ * @param path - Optional JSONPath expression to a specific element
+ * @param span - Optional character range within text content
+ * @returns A SnapshotPointer instance
+ *
+ * @example
+ * ```ts
+ * // Point to entire snapshot
+ * const pointer = create_pointer('hansard', 'AZJx4vM')
+ *
+ * // Point to specific element
+ * const element = create_pointer('hansard', 'AZJx4vM', '$.speeches[0]')
+ *
+ * // Point to text range
+ * const range = create_pointer('hansard', 'AZJx4vM', '$.speeches[0].text', { start: 100, end: 250 })
+ * ```
+ */
+export declare function create_pointer(store_id: string, version: string, path?: string, span?: {
+    start: number;
+    end: number;
+}): SnapshotPointer;
+/**
+ * Converts a SnapshotPointer to a stable string key for Map storage.
+ *
+ * Format: `store_id:version[:path][:start-end]`
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param pointer - The pointer to convert
+ * @returns A string key suitable for use as a Map key
+ *
+ * @example
+ * ```ts
+ * const key = pointer_to_key({ store_id: 'hansard', version: 'abc' })
+ * // => 'hansard:abc'
+ *
+ * const pathKey = pointer_to_key({ store_id: 'hansard', version: 'abc', path: '$.foo' })
+ * // => 'hansard:abc:$.foo'
+ *
+ * const spanKey = pointer_to_key({ store_id: 'hansard', version: 'abc', span: { start: 0, end: 10 } })
+ * // => 'hansard:abc:0-10'
+ * ```
+ */
+export declare function pointer_to_key(pointer: SnapshotPointer): string;
+/**
+ * Parses a pointer key back to a SnapshotPointer.
+ *
+ * Note: This is a best-effort parse - complex paths containing colons may not round-trip perfectly.
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param key - The string key to parse
+ * @returns A SnapshotPointer or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * const pointer = key_to_pointer('hansard:abc:$.foo:0-10')
+ * // => { store_id: 'hansard', version: 'abc', path: '$.foo', span: { start: 0, end: 10 } }
+ *
+ * const simple = key_to_pointer('hansard:abc')
+ * // => { store_id: 'hansard', version: 'abc' }
+ *
+ * const invalid = key_to_pointer('invalid')
+ * // => null
+ * ```
+ */
+export declare function key_to_pointer(key: string): SnapshotPointer | null;
+/**
+ * Resolves a JSONPath expression against a value.
+ *
+ * Supports simple dot notation with array indices:
+ * - `$` or empty string - Returns the root value
+ * - `$.foo` - Property access
+ * - `$.foo.bar` - Nested property access
+ * - `$.foo[0]` - Array index access
+ * - `$.foo[0].bar` - Combined access
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param value - The value to resolve against
+ * @param path - The JSONPath expression
+ * @returns Result containing the resolved value or an error
+ *
+ * @example
+ * ```ts
+ * const data = { speeches: [{ text: 'Hello', speaker: 'Alice' }] }
+ *
+ * const result = resolve_path(data, '$.speeches[0].text')
+ * if (result.ok) console.log(result.value) // 'Hello'
+ *
+ * const root = resolve_path(data, '$')
+ * if (root.ok) console.log(root.value) // { speeches: [...] }
+ * ```
+ */
+export declare function resolve_path<T = unknown>(value: unknown, path: string): Result<T, CorpusError>;
+/**
+ * Applies a span (character range) to a string value.
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param value - The string to slice
+ * @param span - The character range to extract
+ * @returns Result containing the substring or an error for invalid spans
+ *
+ * @example
+ * ```ts
+ * const result = apply_span('Hello, world!', { start: 0, end: 5 })
+ * if (result.ok) console.log(result.value) // 'Hello'
+ *
+ * const invalid = apply_span('Hi', { start: 0, end: 10 })
+ * if (!invalid.ok) console.log(invalid.error.kind) // 'validation_error'
+ * ```
+ */
+export declare function apply_span(value: string, span: {
+    start: number;
+    end: number;
+}): Result<string, CorpusError>;
+/**
+ * Generates a unique observation ID.
+ *
+ * Format: `obs_{timestamp}_{random}` where timestamp is base36-encoded
+ * and random is 8 characters of base36.
+ *
+ * @category Utilities
+ * @group Observation Utilities
+ * @returns A unique observation ID string
+ *
+ * @example
+ * ```ts
+ * const id = generate_observation_id()
+ * // => 'obs_lq9x2k_a7b3c2d1'
+ * ```
+ */
+export declare function generate_observation_id(): string;
+/**
+ * Checks if two SnapshotPointers reference the same location.
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param a - First pointer
+ * @param b - Second pointer
+ * @returns True if pointers reference the same location
+ *
+ * @example
+ * ```ts
+ * const p1 = create_pointer('hansard', 'abc', '$.foo')
+ * const p2 = create_pointer('hansard', 'abc', '$.foo')
+ * const p3 = create_pointer('hansard', 'xyz', '$.foo')
+ *
+ * pointers_equal(p1, p2) // true
+ * pointers_equal(p1, p3) // false
+ * ```
+ */
+export declare function pointers_equal(a: SnapshotPointer, b: SnapshotPointer): boolean;
+/**
+ * Creates a pointer to the same snapshot without path or span.
+ *
+ * @category Utilities
+ * @group Pointer Utilities
+ * @param pointer - The source pointer
+ * @returns A pointer to just the snapshot (store_id + version)
+ *
+ * @example
+ * ```ts
+ * const detailed = create_pointer('hansard', 'abc', '$.speeches[0]', { start: 0, end: 100 })
+ * const snapshot = pointer_to_snapshot(detailed)
+ * // => { store_id: 'hansard', version: 'abc' }
+ * ```
+ */
+export declare function pointer_to_snapshot(pointer: SnapshotPointer): SnapshotPointer;
+//# sourceMappingURL=utils.d.ts.map

package/dist/observations/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../observations/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAGnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpC,eAAe,CAKjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAwBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,WAAW,CAAC,CAsC9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAS3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAIhD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,OAAO,CAO9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAE7E"}