@soulcraft/sdk 1.7.0 → 2.0.1

package/dist/server/handlers/auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module server/handlers/auth
+ * @description Auth namespace handler — session introspection and WebSocket
+ * token generation.
+ *
+ * The auth handler is deliberately thin. Heavy auth logic (login, logout, OAuth
+ * flows, session creation) lives in middleware (`modules/auth/middleware.ts`).
+ * This handler only exposes the two methods that clients need at runtime:
+ * checking who they are (`getSession`) and getting a short-lived WS token.
+ *
+ * Methods:
+ * - `getSession` — Return the authenticated user and status
+ * - `getWsToken` — Generate a capability token for WebSocket connections
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Capability token generator for WebSocket authentication.
+ *
+ * Products inject their own token factory — Workshop uses HMAC-signed tokens
+ * from `@soulcraft/sdk/server`.
+ */
+export interface CapabilityTokenFactory {
+    /**
+     * Create a short-lived capability token.
+     *
+     * @param email - User's email hash for scoping.
+     * @param scope - Workspace or resource scope.
+     * @returns Signed token string.
+     */
+    create(email: string, scope: string): Promise<string>;
+}
+/**
+ * Options for {@link createAuthHandler}.
+ */
+export interface AuthHandlerOptions {
+    /**
+     * Capability token factory for WS token generation.
+     * If not provided, `getWsToken` throws an error.
+     */
+    tokenFactory?: CapabilityTokenFactory;
+    /**
+     * Token TTL in seconds. Default: 300 (5 minutes).
+     */
+    tokenTtlSeconds?: number;
+}
+/**
+ * Creates the `auth` namespace handler.
+ *
+ * @param options - Optional auth handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link AuthNamespace}.
+ */
+export declare function createAuthHandler(options?: AuthHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=auth.d.ts.map

package/dist/server/handlers/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAM/E;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,sBAAsB,CAAA;IAErC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CAoDjF"}

package/dist/server/handlers/auth.js

@@ -0,0 +1,66 @@
+/**
+ * @module server/handlers/auth
+ * @description Auth namespace handler — session introspection and WebSocket
+ * token generation.
+ *
+ * The auth handler is deliberately thin. Heavy auth logic (login, logout, OAuth
+ * flows, session creation) lives in middleware (`modules/auth/middleware.ts`).
+ * This handler only exposes the two methods that clients need at runtime:
+ * checking who they are (`getSession`) and getting a short-lived WS token.
+ *
+ * Methods:
+ * - `getSession` — Return the authenticated user and status
+ * - `getWsToken` — Generate a capability token for WebSocket connections
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `auth` namespace handler.
+ *
+ * @param options - Optional auth handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link AuthNamespace}.
+ */
+export function createAuthHandler(options) {
+    const tokenFactory = options?.tokenFactory;
+    const tokenTtlSeconds = options?.tokenTtlSeconds ?? 300;
+    return {
+        /**
+         * Get the current session user and authentication status.
+         *
+         * The user is already resolved by the namespace router's `authenticate`
+         * callback and passed in the handler context. This method simply returns it.
+         *
+         * @param ctx - Handler context with authenticated user.
+         * @returns User info and authentication flag.
+         */
+        async getSession(ctx) {
+            return {
+                user: {
+                    id: ctx.user.id,
+                    email: ctx.user.email,
+                    name: ctx.user.name,
+                    ...(ctx.user.role != null ? { role: ctx.user.role } : {}),
+                },
+                authenticated: true,
+            };
+        },
+        /**
+         * Get a short-lived WebSocket capability token.
+         *
+         * @param tokenOptions - Token scope options.
+         * @param ctx - Handler context.
+         * @returns Token string and expiration timestamp.
+         */
+        async getWsToken(tokenOptions, ctx) {
+            if (!tokenFactory) {
+                throw new Error('WebSocket tokens are not configured — provide a tokenFactory in handler options');
+            }
+            const scope = tokenOptions?.scope || ctx.workspaceId;
+            const token = await tokenFactory.create(ctx.user.emailHash, scope);
+            const expiresAt = new Date(Date.now() + tokenTtlSeconds * 1000).toISOString();
+            return { token, expiresAt };
+        },
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/server/handlers/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/server/handlers/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyCH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAA;IAC1C,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,GAAG,CAAA;IAEvD,OAAO;QACL;;;;;;;;WAQG;QACH,KAAK,CAAC,UAAU,CAAC,GAAmB;YAIlC,OAAO;gBACL,IAAI,EAAE;oBACJ,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE;oBACf,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;oBACrB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI;oBACnB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC1D;gBACD,aAAa,EAAE,IAAI;aACpB,CAAA;QACH,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,UAAU,CACd,YAA4C,EAC5C,GAAmB;YAEnB,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;YACpG,CAAC;YAED,MAAM,KAAK,GAAG,YAAY,EAAE,KAAK,IAAI,GAAG,CAAC,WAAW,CAAA;YACpD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;YAElE,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;YAE7E,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;QAC7B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/handlers/certification.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module server/handlers/certification
+ * @description Certification namespace handler — issue, verify, and trace
+ * credential lineage using Brainy's graph model.
+ *
+ * Certifications are `Contract` entities linked by `endorses` (certifier → cert),
+ * `attributedTo` (cert → learner), and `dependsOn` (cert → upstream cert)
+ * relationships. This creates a verifiable lineage chain — the medieval guild
+ * model where every credential traces back to the authority that granted it.
+ *
+ * Originally built for Academy (course completion credentials). Now a platform
+ * primitive usable by Workshop, Venue, and kit apps.
+ *
+ * Methods:
+ * - `issue` — Issue a new certification
+ * - `verify` — Verify a certification's validity
+ * - `getWithLineage` — Get a certification with its ancestor chain
+ * - `assess` — Compute assessment score against required competencies
+ * - `list` — List certifications by issuer or recipient
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Creates the `certification` namespace handler.
+ *
+ * All methods operate directly on Brainy entities and relationships.
+ * No external dependencies required — the knowledge graph IS the
+ * certification store.
+ *
+ * @returns A {@link NamespaceProvider} implementing {@link CertificationNamespace}.
+ */
+export declare function createCertificationHandler(): NamespaceProvider;
+//# sourceMappingURL=certification.d.ts.map

package/dist/server/handlers/certification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certification.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/certification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAM/E;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,iBAAiB,CAqQ9D"}

package/dist/server/handlers/certification.js

@@ -0,0 +1,253 @@
+/**
+ * @module server/handlers/certification
+ * @description Certification namespace handler — issue, verify, and trace
+ * credential lineage using Brainy's graph model.
+ *
+ * Certifications are `Contract` entities linked by `endorses` (certifier → cert),
+ * `attributedTo` (cert → learner), and `dependsOn` (cert → upstream cert)
+ * relationships. This creates a verifiable lineage chain — the medieval guild
+ * model where every credential traces back to the authority that granted it.
+ *
+ * Originally built for Academy (course completion credentials). Now a platform
+ * primitive usable by Workshop, Venue, and kit apps.
+ *
+ * Methods:
+ * - `issue` — Issue a new certification
+ * - `verify` — Verify a certification's validity
+ * - `getWithLineage` — Get a certification with its ancestor chain
+ * - `assess` — Compute assessment score against required competencies
+ * - `list` — List certifications by issuer or recipient
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `certification` namespace handler.
+ *
+ * All methods operate directly on Brainy entities and relationships.
+ * No external dependencies required — the knowledge graph IS the
+ * certification store.
+ *
+ * @returns A {@link NamespaceProvider} implementing {@link CertificationNamespace}.
+ */
+export function createCertificationHandler() {
+    return {
+        /**
+         * Issue a new certification.
+         *
+         * Creates a Contract entity with endorses/attributedTo/dependsOn edges.
+         *
+         * @param issueOptions - Certification details.
+         * @param ctx - Handler context with Brainy instance.
+         * @returns The created certification.
+         */
+        async issue(issueOptions, ctx) {
+            const { brain } = ctx;
+            const now = new Date().toISOString();
+            // Create the certification entity
+            const certId = await brain.add({
+                type: 'contract',
+                data: issueOptions.name,
+                metadata: {
+                    name: issueOptions.name,
+                    certType: 'certification',
+                    score: issueOptions.score,
+                    aiIssued: issueOptions.aiIssued ?? false,
+                    issuedAt: now,
+                    issuedBy: ctx.user.id,
+                    issuedTo: issueOptions.learnerId,
+                },
+            });
+            // Create endorses relationship (certifier → cert)
+            await brain.relate({
+                from: ctx.user.id,
+                to: certId,
+                type: 'endorses',
+            }).catch(() => {
+                // User entity may not exist — non-fatal
+            });
+            // Create attributedTo relationship (cert → learner)
+            await brain.relate({
+                from: certId,
+                to: issueOptions.learnerId,
+                type: 'attributedTo',
+            }).catch(() => {
+                // Learner entity may not exist — non-fatal
+            });
+            // Create dependsOn relationship for lineage
+            if (issueOptions.upstreamCertificationId) {
+                await brain.relate({
+                    from: certId,
+                    to: issueOptions.upstreamCertificationId,
+                    type: 'dependsOn',
+                }).catch(() => {
+                    // Upstream cert may not exist — non-fatal
+                });
+            }
+            return {
+                id: certId,
+                name: issueOptions.name,
+                score: issueOptions.score,
+                issuedAt: now,
+                certifierId: ctx.user.id,
+                learnerId: issueOptions.learnerId,
+                lineageDepth: issueOptions.upstreamCertificationId ? 1 : 0,
+            };
+        },
+        /**
+         * Verify a certification's validity.
+         *
+         * @param certificationId - The certification entity ID.
+         * @param ctx - Handler context.
+         * @returns Verification result.
+         */
+        async verify(certificationId, ctx) {
+            const { brain } = ctx;
+            try {
+                const entity = await brain.get(certificationId);
+                if (!entity)
+                    return { valid: false, certification: null };
+                const meta = entity.metadata || {};
+                if (meta.certType !== 'certification') {
+                    return { valid: false, certification: null };
+                }
+                return {
+                    valid: true,
+                    certification: {
+                        id: entity.id,
+                        name: meta.name || entity.data,
+                        score: meta.score ?? 0,
+                        issuedAt: meta.issuedAt || '',
+                        certifierId: meta.issuedBy || '',
+                        learnerId: meta.issuedTo || '',
+                        lineageDepth: 0, // Computed in getWithLineage
+                    },
+                };
+            }
+            catch {
+                return { valid: false, certification: null };
+            }
+        },
+        /**
+         * Get a certification with its full lineage chain.
+         *
+         * @param certificationId - The certification entity ID.
+         * @param ctx - Handler context.
+         * @returns Certification and ancestor chain.
+         */
+        async getWithLineage(certificationId, ctx) {
+            const { brain } = ctx;
+            const entity = await brain.get(certificationId);
+            if (!entity)
+                return { certification: null, lineage: [] };
+            const meta = entity.metadata || {};
+            const cert = {
+                id: entity.id,
+                name: meta.name || entity.data,
+                score: meta.score ?? 0,
+                issuedAt: meta.issuedAt || '',
+                certifierId: meta.issuedBy || '',
+                learnerId: meta.issuedTo || '',
+                lineageDepth: 0,
+            };
+            // Traverse dependsOn chain
+            const lineage = [];
+            let currentId = certificationId;
+            const visited = new Set();
+            const maxDepth = 20; // Prevent infinite loops
+            while (lineage.length < maxDepth) {
+                visited.add(currentId);
+                const outgoing = await brain.getRelations({ from: currentId }) || [];
+                const dependsOn = outgoing.find((r) => r.type.toLowerCase() === 'dependson' || r.type === 'DependsOn');
+                if (!dependsOn || visited.has(dependsOn.to))
+                    break;
+                const upstream = await brain.get(dependsOn.to);
+                if (!upstream)
+                    break;
+                const upMeta = upstream.metadata || {};
+                lineage.push({
+                    id: upstream.id,
+                    name: upMeta.name || upstream.data,
+                    score: upMeta.score ?? 0,
+                    issuedAt: upMeta.issuedAt || '',
+                    certifierId: upMeta.issuedBy || '',
+                    learnerId: upMeta.issuedTo || '',
+                    lineageDepth: lineage.length + 1,
+                });
+                currentId = dependsOn.to;
+            }
+            cert.lineageDepth = lineage.length;
+            return { certification: cert, lineage };
+        },
+        /**
+         * Compute assessment score for a learner against required competencies.
+         *
+         * Score = demonstrated / total required. A competency is "demonstrated"
+         * if there's a `learns` edge from the learner to the competency entity.
+         *
+         * @param assessOptions - Assessment parameters.
+         * @param ctx - Handler context.
+         * @returns Assessment result with score, pass/fail, and gaps.
+         */
+        async assess(assessOptions, ctx) {
+            const { brain } = ctx;
+            const threshold = assessOptions.threshold ?? 0.8;
+            // Get all "learns" edges from the learner
+            const outgoing = await brain.getRelations({ from: assessOptions.learnerId }) || [];
+            const demonstrated = new Set(outgoing
+                .filter((r) => r.type.toLowerCase() === 'learns')
+                .map((r) => r.to));
+            const total = assessOptions.competencyIds.length;
+            const met = assessOptions.competencyIds.filter(id => demonstrated.has(id));
+            const gaps = assessOptions.competencyIds.filter(id => !demonstrated.has(id));
+            const score = total > 0 ? met.length / total : 0;
+            return {
+                score,
+                passed: score >= threshold,
+                totalCompetencies: total,
+                demonstratedCount: met.length,
+                gaps,
+            };
+        },
+        /**
+         * List certifications issued by or to a user.
+         *
+         * @param listOptions - Filter options.
+         * @param ctx - Handler context.
+         * @returns Array of certifications.
+         */
+        async list(listOptions, ctx) {
+            const { brain } = ctx;
+            const limit = listOptions?.limit ?? 50;
+            const results = await brain.find({
+                where: { type: 'contract' },
+                limit: limit * 2, // Over-fetch for filtering
+            });
+            return results
+                .filter((entity) => {
+                const meta = entity.metadata || {};
+                if (meta.certType !== 'certification')
+                    return false;
+                if (listOptions?.issuedBy && meta.issuedBy !== listOptions.issuedBy)
+                    return false;
+                if (listOptions?.issuedTo && meta.issuedTo !== listOptions.issuedTo)
+                    return false;
+                return true;
+            })
+                .slice(0, limit)
+                .map((entity) => {
+                const meta = entity.metadata || {};
+                return {
+                    id: entity.id,
+                    name: meta.name || entity.data,
+                    score: meta.score ?? 0,
+                    issuedAt: meta.issuedAt || '',
+                    certifierId: meta.issuedBy || '',
+                    learnerId: meta.issuedTo || '',
+                    lineageDepth: 0,
+                };
+            });
+        },
+    };
+}
+//# sourceMappingURL=certification.js.map

package/dist/server/handlers/certification.js.map

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

package/dist/server/handlers/chat/conversations.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module server/handlers/chat/conversations
+ * @description Conversation and message CRUD operations using Brainy entities.
+ *
+ * Conversations are stored as `collection` entities with `_aiDataType: 'conversation'`.
+ * Messages are `message` entities linked to conversations via `contains` edges.
+ * Temporal ordering uses `precedes` edges between consecutive messages.
+ *
+ * All operations are universal — Workshop, Venue, Academy, and Pulse share
+ * the same conversation storage model.
+ */
+import type { Brainy } from '@soulcraft/brainy';
+import type { ChatConversation, ChatConversationDetail } from '../../../namespaces.js';
+import type { ChatEventEmitter } from './types.js';
+/**
+ * Create a new conversation entity.
+ *
+ * @param brain - Brainy instance.
+ * @param userId - User who owns the conversation.
+ * @param title - Optional initial title.
+ * @returns The conversation ID.
+ */
+export declare function createConversation(brain: Brainy, userId: string, title?: string): Promise<string>;
+/**
+ * List all conversations for a user.
+ *
+ * @param brain - Brainy instance.
+ * @param userId - User to list conversations for.
+ * @returns Array of conversation summaries sorted by most recent first.
+ */
+export declare function listConversations(brain: Brainy, userId: string): Promise<ChatConversation[]>;
+/**
+ * Get a conversation with its full message history.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to retrieve.
+ * @returns Full conversation with messages, or null if not found.
+ */
+export declare function getConversation(brain: Brainy, conversationId: string): Promise<ChatConversationDetail | null>;
+/**
+ * Delete a conversation and all its messages (soft delete).
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to delete.
+ */
+export declare function deleteConversation(brain: Brainy, conversationId: string): Promise<void>;
+/**
+ * Rename a conversation.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to rename.
+ * @param title - New title.
+ */
+export declare function renameConversation(brain: Brainy, conversationId: string, title: string): Promise<void>;
+/**
+ * Store a message in a conversation.
+ *
+ * Creates the message entity, links it to the conversation via `contains`,
+ * and establishes temporal ordering via `precedes`.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to add the message to.
+ * @param role - Message role ('user' or 'assistant').
+ * @param content - Message text content.
+ * @param events - Optional event emitter for real-time updates.
+ * @returns The message entity ID.
+ */
+export declare function storeMessage(brain: Brainy, conversationId: string, role: 'user' | 'assistant', content: string, events?: ChatEventEmitter): Promise<string>;
+/**
+ * Load conversation history — recent messages in chronological order.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to load.
+ * @param limit - Maximum messages to return (most recent).
+ * @returns Array of role/content pairs.
+ */
+export declare function loadConversationHistory(brain: Brainy, conversationId: string, limit?: number): Promise<Array<{
+    role: string;
+    content: string;
+}>>;
+/**
+ * Auto-title a conversation from the first user message.
+ *
+ * Fire-and-forget — errors are logged but don't propagate.
+ *
+ * @param brain - Brainy instance.
+ * @param conversationId - Conversation to title.
+ * @param message - The first user message.
+ */
+export declare function autoTitleConversation(brain: Brainy, conversationId: string, message: string): Promise<void>;
+//# sourceMappingURL=conversations.d.ts.map

package/dist/server/handlers/chat/conversations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../../../src/server/handlers/chat/conversations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAe,MAAM,wBAAwB,CAAA;AACnG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAalD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiD7B;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA2CxC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CASf;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,GAAG,WAAW,EAC1B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAkFjB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAyBnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAef"}