@trillboards/edge-core 0.2.2 → 0.2.3

package/dist/StatusServer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * StatusServer — HTTP server exposing device status, health, and Prometheus metrics.
+ *
+ * Runs inside the EdgeAgent process on a configurable port (default 9090).
+ * Uses ONLY Node.js built-in `http` module — zero external dependencies.
+ *
+ * Endpoints:
+ *   GET /status  — Full JSON status snapshot
+ *   GET /health  — Simple health probe (200 OK / 503 degraded)
+ *   GET /metrics — Prometheus-format text metrics
+ */
+export interface StatusServerOptions {
+    /** HTTP listen port. Default: 9090 */
+    port?: number;
+    /** HTTP listen host. Default: '0.0.0.0' */
+    host?: string;
+}
+export interface StatusData {
+    /** Device fingerprint */
+    fingerprint: string;
+    /** Assigned screen ID, or null if unassigned */
+    screenId: string | null;
+    /** Capability tier (1-4) */
+    tier: number;
+    /** Platform string, e.g. 'linux x64' */
+    platform: string;
+    /** Seconds since agent start (computed on read) */
+    uptime: number;
+    /** SDK version string */
+    sdkVersion: string;
+    /** Health snapshot from SubsystemHealthRegistry.toHeartbeatPayload() */
+    subsystemHealth: Record<string, unknown>;
+    /** Current sensing mode, e.g. 'edge_onnx', 'cloud', 'proxy_only' */
+    sensingMode: string;
+    /** Current detected face count */
+    currentFaceCount: number;
+    /** Average attention score (0-1) */
+    avgAttention: number;
+    /** Weighted VAS score (0-1) */
+    avgVAS: number;
+    /** Evidence grade, e.g. 'FACE_BACKED' */
+    evidenceGrade: string;
+    /** Number of signals currently buffered */
+    signalBufferCount: number;
+    /** Maximum buffer capacity */
+    signalBufferCapacity: number;
+    /** Whether the Socket.io connection is live */
+    socketConnected: boolean;
+    /** Epoch ms of last signal emit */
+    lastSignalTimestamp: number;
+    /** Total RSS memory usage in MB */
+    memoryUsageMb: number;
+    /** V8 heap used in MB */
+    heapUsedMb: number;
+    /** List of loaded model names, e.g. ['blazeFace', 'yamnet'] */
+    modelsLoaded: string[];
+    /** ONNX execution provider, e.g. 'cpu', 'openvino' */
+    executionProvider: string;
+    /** Whether federated learning is enabled */
+    federatedEnabled: boolean;
+    /** Epoch ms of last gradient upload */
+    lastGradientUpload: number;
+}
+export declare class StatusServer {
+    private server;
+    private statusData;
+    private startTime;
+    private port;
+    private host;
+    constructor(options?: StatusServerOptions);
+    /**
+     * Merge partial updates into the status snapshot.
+     * Call this from EdgeAgent whenever subsystem state changes.
+     */
+    updateStatus(partial: Partial<StatusData>): void;
+    /**
+     * Start the HTTP server. Resolves once the server is listening.
+     * If the port is already in use, logs a warning and resolves without starting.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server gracefully. Resolves once all connections are closed.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current status snapshot with computed fields (uptime, memory).
+     * Also used by the status CLI command via the /status HTTP endpoint.
+     */
+    getStatus(): StatusData & {
+        uptime: number;
+        memoryUsageMb: number;
+        heapUsedMb: number;
+    };
+    private handleRequest;
+    private handleStatus;
+    private handleHealth;
+    private handleMetrics;
+}
+//# sourceMappingURL=StatusServer.d.ts.map

package/dist/StatusServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatusServer.d.ts","sourceRoot":"","sources":["../src/StatusServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IAGzB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAInB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIzC,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IAItB,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAI7B,+CAA+C;IAC/C,eAAe,EAAE,OAAO,CAAC;IACzB,mCAAmC;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAI5B,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAInB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAI1B,4CAA4C;IAC5C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AA2BD,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,OAAO,CAAC,EAAE,mBAAmB;IAOzC;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAIhD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;;OAGG;IACH,SAAS,IAAI,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAcvF,OAAO,CAAC,aAAa;IAgCrB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,aAAa;CAyDtB"}

package/dist/StatusServer.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * StatusServer — HTTP server exposing device status, health, and Prometheus metrics.
+ *
+ * Runs inside the EdgeAgent process on a configurable port (default 9090).
+ * Uses ONLY Node.js built-in `http` module — zero external dependencies.
+ *
+ * Endpoints:
+ *   GET /status  — Full JSON status snapshot
+ *   GET /health  — Simple health probe (200 OK / 503 degraded)
+ *   GET /metrics — Prometheus-format text metrics
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatusServer = void 0;
+const http = __importStar(require("http"));
+const os = __importStar(require("os"));
+const DEFAULT_STATUS = {
+    fingerprint: '',
+    screenId: null,
+    tier: 0,
+    platform: `${os.platform()} ${os.arch()}`,
+    uptime: 0,
+    sdkVersion: '0.2.2',
+    subsystemHealth: {},
+    sensingMode: 'unknown',
+    currentFaceCount: 0,
+    avgAttention: 0,
+    avgVAS: 0,
+    evidenceGrade: 'EMPTY',
+    signalBufferCount: 0,
+    signalBufferCapacity: 8640,
+    socketConnected: false,
+    lastSignalTimestamp: 0,
+    memoryUsageMb: 0,
+    heapUsedMb: 0,
+    modelsLoaded: [],
+    executionProvider: 'cpu',
+    federatedEnabled: false,
+    lastGradientUpload: 0,
+};
+class StatusServer {
+    constructor(options) {
+        this.server = null;
+        this.port = options?.port ?? 9090;
+        this.host = options?.host ?? '0.0.0.0';
+        this.startTime = Date.now();
+        this.statusData = { ...DEFAULT_STATUS };
+    }
+    /**
+     * Merge partial updates into the status snapshot.
+     * Call this from EdgeAgent whenever subsystem state changes.
+     */
+    updateStatus(partial) {
+        Object.assign(this.statusData, partial);
+    }
+    /**
+     * Start the HTTP server. Resolves once the server is listening.
+     * If the port is already in use, logs a warning and resolves without starting.
+     */
+    async start() {
+        if (this.server)
+            return;
+        const server = http.createServer((req, res) => {
+            this.handleRequest(req, res);
+        });
+        return new Promise((resolve) => {
+            server.once('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    console.warn(`[StatusServer] Port ${this.port} is already in use — status server not started`);
+                    this.server = null;
+                    resolve();
+                }
+                else {
+                    console.warn(`[StatusServer] Failed to start: ${err.message}`);
+                    this.server = null;
+                    resolve();
+                }
+            });
+            server.listen(this.port, this.host, () => {
+                this.server = server;
+                console.log(`[StatusServer] Listening on http://${this.host}:${this.port}`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the HTTP server gracefully. Resolves once all connections are closed.
+     */
+    async stop() {
+        if (!this.server)
+            return;
+        return new Promise((resolve) => {
+            this.server.close(() => {
+                this.server = null;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Get the current status snapshot with computed fields (uptime, memory).
+     * Also used by the status CLI command via the /status HTTP endpoint.
+     */
+    getStatus() {
+        const mem = process.memoryUsage();
+        const uptimeSeconds = Math.floor((Date.now() - this.startTime) / 1000);
+        return {
+            ...this.statusData,
+            uptime: uptimeSeconds,
+            memoryUsageMb: parseFloat((mem.rss / (1024 * 1024)).toFixed(1)),
+            heapUsedMb: parseFloat((mem.heapUsed / (1024 * 1024)).toFixed(1)),
+        };
+    }
+    // ---- Private request handler ----
+    handleRequest(req, res) {
+        // CORS headers for local dev tooling
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Parse URL path (strip query string)
+        const urlPath = (req.url || '/').split('?')[0];
+        switch (urlPath) {
+            case '/status':
+                this.handleStatus(res);
+                break;
+            case '/health':
+                this.handleHealth(res);
+                break;
+            case '/metrics':
+                this.handleMetrics(res);
+                break;
+            default:
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Not Found', path: urlPath }));
+                break;
+        }
+    }
+    handleStatus(res) {
+        const status = this.getStatus();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(status));
+    }
+    handleHealth(res) {
+        const status = this.getStatus();
+        const failedSubsystems = [];
+        for (const [name, info] of Object.entries(status.subsystemHealth)) {
+            const sub = info;
+            if (sub.stale === true || isErrorStatus(sub.status)) {
+                failedSubsystems.push(name);
+            }
+        }
+        if (failedSubsystems.length > 0) {
+            res.writeHead(503, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'degraded', failed: failedSubsystems }));
+        }
+        else {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+        }
+    }
+    handleMetrics(res) {
+        const status = this.getStatus();
+        const lines = [
+            '# HELP trillboards_face_count Current detected face count',
+            '# TYPE trillboards_face_count gauge',
+            `trillboards_face_count ${status.currentFaceCount}`,
+            '',
+            '# HELP trillboards_attention_score Average attention score',
+            '# TYPE trillboards_attention_score gauge',
+            `trillboards_attention_score ${status.avgAttention}`,
+            '',
+            '# HELP trillboards_vas_score Weighted VAS score',
+            '# TYPE trillboards_vas_score gauge',
+            `trillboards_vas_score ${status.avgVAS}`,
+            '',
+            '# HELP trillboards_signal_buffer_count Buffered signals waiting to send',
+            '# TYPE trillboards_signal_buffer_count gauge',
+            `trillboards_signal_buffer_count ${status.signalBufferCount}`,
+            '',
+            '# HELP trillboards_uptime_seconds Agent uptime in seconds',
+            '# TYPE trillboards_uptime_seconds gauge',
+            `trillboards_uptime_seconds ${status.uptime}`,
+            '',
+            '# HELP trillboards_heap_used_mb V8 heap used in MB',
+            '# TYPE trillboards_heap_used_mb gauge',
+            `trillboards_heap_used_mb ${status.heapUsedMb}`,
+            '',
+            '# HELP trillboards_memory_rss_mb Process RSS memory in MB',
+            '# TYPE trillboards_memory_rss_mb gauge',
+            `trillboards_memory_rss_mb ${status.memoryUsageMb}`,
+            '',
+            '# HELP trillboards_signal_buffer_capacity Maximum signal buffer capacity',
+            '# TYPE trillboards_signal_buffer_capacity gauge',
+            `trillboards_signal_buffer_capacity ${status.signalBufferCapacity}`,
+            '',
+            '# HELP trillboards_socket_connected Socket.io connection status (1=connected, 0=disconnected)',
+            '# TYPE trillboards_socket_connected gauge',
+            `trillboards_socket_connected ${status.socketConnected ? 1 : 0}`,
+            '',
+            '# HELP trillboards_federated_enabled Federated learning enabled (1=yes, 0=no)',
+            '# TYPE trillboards_federated_enabled gauge',
+            `trillboards_federated_enabled ${status.federatedEnabled ? 1 : 0}`,
+            '',
+            '# HELP trillboards_tier Device capability tier',
+            '# TYPE trillboards_tier gauge',
+            `trillboards_tier ${status.tier}`,
+            '',
+            '# HELP trillboards_models_loaded_count Number of loaded ML models',
+            '# TYPE trillboards_models_loaded_count gauge',
+            `trillboards_models_loaded_count ${status.modelsLoaded.length}`,
+            '',
+        ];
+        res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8' });
+        res.end(lines.join('\n'));
+    }
+}
+exports.StatusServer = StatusServer;
+/**
+ * Check if a subsystem status string represents an error condition.
+ * Matches the ERROR_STATUSES set in SubsystemHealthRegistry.
+ */
+function isErrorStatus(status) {
+    const errorStatuses = new Set([
+        'DISCONNECTED',
+        'STUCK',
+        'CRASHED',
+        'PERMISSION_DENIED',
+        'ERROR',
+        'CRITICAL',
+        'OFFLINE',
+        'HIGH',
+    ]);
+    return errorStatuses.has(status);
+}
+//# sourceMappingURL=StatusServer.js.map

package/dist/StatusServer.js.map

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

package/dist/ZKAudienceProver.d.ts

@@ -0,0 +1,137 @@
+/**
+ * ZKAudienceProver — Zero-Knowledge proof system for audience measurement.
+ *
+ * Proves that aggregate audience metrics are consistent with individual
+ * observations WITHOUT revealing individual observation data.
+ *
+ * Since snarkjs is a heavy dependency and may not be available on all edge
+ * devices, this implementation uses a commitment-based approach with
+ * Pedersen-like commitments using standard crypto (SHA-256 + HMAC), providing
+ * a practical ZK-adjacent proof system that can be upgraded to full ZK-SNARKs
+ * when snarkjs is available.
+ *
+ * Proof generation (on device):
+ *   1. Commit to each observation via HMAC-SHA256(secretSeed, observation)
+ *   2. Build a Merkle tree from all commitments (root proves the set)
+ *   3. Compute aggregate hash: SHA256(aggregate + rangeProofNonce)
+ *   4. Bind range constraints via rangeProofNonce derived from secret + aggregate
+ *   5. Chain all commitments into a single observationCommitment hash
+ *
+ * Verification (server-side, no device secret needed):
+ *   1. Verify aggregateHash matches SHA256(aggregate + rangeProofNonce)
+ *   2. Verify leafCount matches claimed faceCount
+ *   3. Verify range constraints (attention in [0,1], faceCount >= 0, etc.)
+ *   4. Verify proof version and timestamp are reasonable
+ *   5. Individual observations remain private (cannot be recovered)
+ *
+ * Zero external dependencies — uses Node.js built-in crypto module only.
+ */
+export interface AudienceObservation {
+    faceId: number;
+    attention: number;
+    age: number;
+    gender: 'male' | 'female' | null;
+    dwellMs: number;
+    timestamp: number;
+}
+export interface AudienceAggregate {
+    faceCount: number;
+    avgAttention: number;
+    maleCount: number;
+    femaleCount: number;
+    avgAge: number;
+    totalDwellMs: number;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface AudienceProof {
+    /** SHA-256 of all individual observation commitment hashes chained together. */
+    observationCommitment: string;
+    /** SHA-256 of the aggregate values bound with rangeProofNonce. */
+    aggregateHash: string;
+    /** Random nonce derived from secret + aggregate for range proof binding. */
+    rangeProofNonce: string;
+    /** Root of the Merkle tree built from individual observation commitments. */
+    merkleRoot: string;
+    /** Number of leaves (observations) in the Merkle tree. */
+    leafCount: number;
+    /** Proof scheme version identifier. */
+    proofVersion: string;
+    /** Timestamp when the proof was generated. */
+    generatedAt: number;
+    /** Device fingerprint that produced this proof. */
+    deviceFingerprint: string;
+}
+export interface VerificationResult {
+    valid: boolean;
+    checks: {
+        /** Whether the aggregateHash matches re-computed SHA256(aggregate + nonce). */
+        aggregateConsistency: boolean;
+        /** Whether the observationCommitment is structurally valid (non-empty hex). */
+        commitmentIntegrity: boolean;
+        /** Whether aggregate values are in expected ranges. */
+        rangeValidity: boolean;
+        /** Whether the merkleRoot is consistent with the claimed leafCount. */
+        merkleIntegrity: boolean;
+    };
+    verifiedAt: number;
+}
+export declare class ZKAudienceProver {
+    private readonly deviceFingerprint;
+    private readonly secretSeed;
+    /**
+     * @param deviceFingerprint - Unique identifier for the device producing proofs.
+     * @param secretSeed - Device-specific secret for commitment generation.
+     *   If not provided, a cryptographically random 32-byte seed is generated.
+     */
+    constructor(deviceFingerprint: string, secretSeed?: string);
+    /**
+     * Generate a ZK proof that the aggregate is consistent with individual
+     * observations without revealing the individual data.
+     *
+     * Algorithm:
+     * 1. Commit to each observation: HMAC-SHA256(secretSeed, serialize(obs_i))
+     * 2. Build a Merkle tree from all commitments; root proves the set.
+     * 3. Derive rangeProofNonce from secretSeed + aggregate fields (binds
+     *    range constraints to the proof without revealing the secret).
+     * 4. Compute aggregateHash = SHA256(serialize(aggregate) + rangeProofNonce).
+     * 5. Chain all commitments into observationCommitment =
+     *    SHA256(commitment_0 + commitment_1 + ... + commitment_n).
+     *
+     * @param observations - Individual face observations in the window.
+     * @param aggregate - Pre-computed aggregate of those observations.
+     * @returns AudienceProof that can be verified server-side.
+     */
+    prove(observations: AudienceObservation[], aggregate: AudienceAggregate): Promise<AudienceProof>;
+    /**
+     * Server-side verification of an audience proof.
+     *
+     * Since the server does not have the device secret, it cannot reconstruct
+     * individual observation commitments. However, it CAN verify:
+     *   1. aggregateHash matches SHA256(serialize(aggregate) + rangeProofNonce)
+     *   2. leafCount matches aggregate.faceCount
+     *   3. All aggregate values are in expected ranges
+     *   4. Proof metadata (version, timestamp) are reasonable
+     *   5. merkleRoot and observationCommitment are structurally valid
+     *
+     * Individual observations remain private (the point of ZK).
+     *
+     * @param aggregate - The claimed aggregate values.
+     * @param proof - The proof generated by a device.
+     * @returns VerificationResult with per-check breakdown.
+     */
+    static verify(aggregate: AudienceAggregate, proof: AudienceProof): Promise<VerificationResult>;
+    /**
+     * Compute an AudienceAggregate from a set of individual observations.
+     *
+     * This is a utility for consistency: the device calls this to build the
+     * aggregate, then passes both observations and aggregate to prove().
+     *
+     * @param observations - Individual face observations.
+     * @param windowStart - Start of the aggregation window (epoch ms).
+     * @param windowEnd - End of the aggregation window (epoch ms).
+     * @returns AudienceAggregate computed from the observations.
+     */
+    static computeAggregate(observations: AudienceObservation[], windowStart: number, windowEnd: number): AudienceAggregate;
+}
+//# sourceMappingURL=ZKAudienceProver.d.ts.map

package/dist/ZKAudienceProver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZKAudienceProver.d.ts","sourceRoot":"","sources":["../src/ZKAudienceProver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE;QACN,+EAA+E;QAC/E,oBAAoB,EAAE,OAAO,CAAC;QAC9B,+EAA+E;QAC/E,mBAAmB,EAAE,OAAO,CAAC;QAC7B,uDAAuD;QACvD,aAAa,EAAE,OAAO,CAAC;QACvB,uEAAuE;QACvE,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;CACpB;AAyGD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;OAIG;gBACS,iBAAiB,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAK1D;;;;;;;;;;;;;;;;OAgBG;IACG,KAAK,CACT,YAAY,EAAE,mBAAmB,EAAE,EACnC,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAAC,aAAa,CAAC;IA8CzB;;;;;;;;;;;;;;;;OAgBG;WACU,MAAM,CACjB,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,kBAAkB,CAAC;IA6E9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CACrB,YAAY,EAAE,mBAAmB,EAAE,EACnC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,iBAAiB;CA6CrB"}