@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/remote/types.d.ts

@@ -0,0 +1,410 @@
+/**
+ * Remote Substrate — Core Types
+ *
+ * Implements durable identity, handshake tokens,
+ * typed transport messages, and replay configuration.
+ */
+import type { DaemonTransportState } from '../store/domains/daemon.js';
+/** Re-export the shared transport lifecycle state. */
+export type { DaemonTransportState as RemoteTransportState };
+/**
+ * Globally unique, stable identity for a remote substrate session.
+ *
+ * These IDs are stable across reconnects — a new transport connection
+ * to the same remote session reuses the same identifiers.
+ */
+export interface DurableIdentity {
+    /** Globally unique session identifier, stable across reconnects. */
+    readonly sessionId: string;
+    /** Task identifier scoped to the current remote task, stable across reconnects. */
+    readonly taskId: string;
+    /** Agent identifier for this remote agent instance, stable across reconnects. */
+    readonly agentId: string;
+    /** Epoch ms when this identity was first created. */
+    readonly createdAt: number;
+    /** Monotonic generation counter — increments on each identity refresh (not reconnect). */
+    readonly generation: number;
+}
+/**
+ * Handshake token exchanged during reconnect negotiations.
+ *
+ * The token proves continuity with a prior session and carries the
+ * epoch and last acknowledged message offset for replay.
+ */
+export interface HandshakeToken {
+    /** The durable session ID this token represents. */
+    readonly sessionId: string;
+    /** Opaque token string issued by the remote server on initial connect. */
+    readonly token: string;
+    /** Epoch number — increments on each server restart. Server sets this. */
+    readonly epoch: number;
+    /** Epoch ms when this token was issued. */
+    readonly issuedAt: number;
+    /** Epoch ms when this token expires (0 = never). */
+    readonly expiresAt: number;
+}
+/**
+ * Configuration for replaying missed messages after a reconnect.
+ */
+export interface ReplayConfig {
+    /**
+     * The offset (sequence number) of the last acknowledged message.
+     * The server will replay all messages with offset > lastAckedOffset.
+     */
+    readonly lastAckedOffset: number;
+    /** Maximum number of messages to replay (0 = unlimited). */
+    readonly maxReplayCount: number;
+    /** Whether to enable replay on reconnect. */
+    readonly enabled: boolean;
+}
+/** Message class discriminant. */
+export type TransportMessageClass = 'control' | 'data' | 'ack' | 'failure';
+/** Error category for failure classification and retry routing. */
+export type TransportErrorCategory = 'network' | 'timeout' | 'authentication' | 'protocol' | 'server' | 'client' | 'transient' | 'unknown';
+/** Retry/backoff policy per message class or error category. */
+export interface RetryPolicy {
+    /** Maximum retry attempts (0 = no retries). */
+    readonly maxAttempts: number;
+    /** Initial delay in ms before first retry. */
+    readonly initialDelayMs: number;
+    /** Maximum delay in ms between retries. */
+    readonly maxDelayMs: number;
+    /** Backoff multiplier applied to delay on each attempt. */
+    readonly backoffMultiplier: number;
+    /** Jitter fraction 0–1 applied to computed delay to prevent thundering herds. */
+    readonly jitter: number;
+    /** Error categories that trigger retry. */
+    readonly retryOn: readonly TransportErrorCategory[];
+}
+/**
+ * Base fields present on every transport message.
+ */
+export interface TransportMessageBase {
+    /** Message class discriminant. */
+    readonly class: TransportMessageClass;
+    /** Monotonically increasing message offset within a session. */
+    readonly offset: number;
+    /** Durable session ID this message belongs to. */
+    readonly sessionId: string;
+    /** Server epoch when this message was produced. */
+    readonly epoch: number;
+    /** Epoch ms when this message was created. */
+    readonly ts: number;
+    /** Idempotency key — same key on retry means server deduplicates. */
+    readonly idempotencyKey: string;
+}
+/**
+ * Discriminated union of all typed transport messages.
+ * Enforces structural typing over raw string payloads.
+ */
+export type TransportMessage = ControlMessage | DataMessage | AckMessage | FailureMessage;
+/** Forward-reference: control plane message shape. */
+export interface ControlMessage extends TransportMessageBase {
+    readonly class: 'control';
+    readonly controlType: string;
+    readonly payload: Record<string, unknown>;
+}
+/** Forward-reference: data plane message shape. */
+export interface DataMessage extends TransportMessageBase {
+    readonly class: 'data';
+    readonly dataType: string;
+    readonly payload: Record<string, unknown>;
+}
+/** Acknowledgement message. */
+export interface AckMessage extends TransportMessageBase {
+    readonly class: 'ack';
+    /** Offset being acknowledged. */
+    readonly ackedOffset: number;
+}
+/** Failure message. */
+export interface FailureMessage extends TransportMessageBase {
+    readonly class: 'failure';
+    /** Error category for retry routing. */
+    readonly errorCategory: TransportErrorCategory;
+    /** Human-readable error message. */
+    readonly error: string;
+    /** Whether the failure is recoverable (triggers reconnect vs terminal failure). */
+    readonly recoverable: boolean;
+    /** Structured error context. */
+    readonly context?: Record<string, unknown>;
+}
+/** Health status of a remote connection. */
+export type RemoteConnectionHealth = 'healthy' | 'degraded' | 'unreachable';
+/**
+ * A mirrored remote task — subset of RuntimeTask fields synced from remote.
+ */
+export interface RemoteTask {
+    /** Remote task ID (stable across reconnects). */
+    readonly taskId: string;
+    /** Remote agent ID owning this task. */
+    readonly agentId: string;
+    /** Human-readable task title. */
+    readonly title: string;
+    /** Current remote task status. */
+    readonly status: 'queued' | 'running' | 'blocked' | 'completed' | 'failed' | 'cancelled';
+    /** Epoch ms when the remote task was last updated. */
+    readonly updatedAt: number;
+    /** Progress value 0–100 (undefined if not reported). */
+    readonly progress?: number;
+    /** Error message if status === 'failed'. */
+    readonly error?: string;
+}
+/**
+ * Health snapshot from the remote substrate.
+ */
+export interface RemoteHealth {
+    /** Overall health status of the remote substrate. */
+    readonly status: RemoteConnectionHealth;
+    /** Epoch ms of last health update. */
+    readonly updatedAt: number;
+    /** Round-trip latency in ms (undefined if not measured). */
+    readonly latencyMs?: number;
+    /** Remote server version string. */
+    readonly serverVersion?: string;
+    /** Human-readable degradation reason. */
+    readonly degradedReason?: string;
+}
+/**
+ * Full state of a remote substrate connection.
+ */
+export interface RemoteSession {
+    /** Connection ID (local tracking ID, not stable across reconnects). */
+    readonly connectionId: string;
+    /** Durable identity stable across reconnects. */
+    readonly identity: DurableIdentity;
+    /** Remote endpoint URL or address. */
+    readonly endpoint: string;
+    /** Current transport state. */
+    readonly transportState: DaemonTransportState;
+    /** Current handshake token (undefined until first handshake). */
+    readonly handshakeToken?: HandshakeToken;
+    /** Replay configuration. */
+    readonly replayConfig: ReplayConfig;
+    /** Number of reconnect attempts since last successful connect. */
+    readonly reconnectAttempts: number;
+    /** Epoch ms of last successful connection. */
+    readonly lastConnectedAt?: number;
+    /** Last error message. */
+    readonly lastError?: string;
+    /** Remote tasks mirrored into local store. */
+    readonly remoteTasks: ReadonlyMap<string, RemoteTask>;
+    /** Latest remote health snapshot. */
+    readonly health: RemoteHealth;
+    /** Total messages sent this session. */
+    readonly messagesSent: number;
+    /** Total messages received this session. */
+    readonly messagesReceived: number;
+    /** Offset of last acknowledged message. */
+    readonly lastAckedOffset: number;
+}
+export interface RemoteRunnerCapabilityCeiling {
+    readonly allowedTools: readonly string[];
+    readonly capabilityCeilingTools: readonly string[];
+    readonly executionProtocol: 'direct' | 'gather-plan-apply';
+    readonly reviewMode: 'none' | 'wrfc';
+    readonly communicationLane: 'parent-only' | 'parent-and-children' | 'cohort' | 'direct';
+    readonly orchestrationDepth: number;
+    readonly successCriteria: readonly string[];
+    readonly requiredEvidence: readonly string[];
+    readonly writeScope: readonly string[];
+}
+export interface RemoteRunnerContract {
+    readonly id: string;
+    readonly runnerId: string;
+    readonly poolId?: string;
+    readonly taskId?: string;
+    readonly label: string;
+    readonly sourceTransport: 'acp' | 'daemon';
+    readonly trustClass: 'self-hosted-acp' | 'local-daemon';
+    readonly template: string;
+    readonly parentAgentId?: string;
+    readonly orchestrationGraphId?: string;
+    readonly orchestrationNodeId?: string;
+    readonly capabilityCeiling: RemoteRunnerCapabilityCeiling;
+    readonly createdAt: number;
+    readonly lastUpdatedAt: number;
+    readonly transport: {
+        readonly state: DaemonTransportState;
+        readonly connectedAt?: number;
+        readonly messageCount: number;
+        readonly errorCount: number;
+        readonly lastError?: string;
+    };
+}
+export interface RemoteRunnerPool {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly trustClass: RemoteRunnerContract['trustClass'] | 'mixed';
+    readonly preferredTemplate?: string;
+    readonly maxRunners?: number;
+    readonly runnerIds: readonly string[];
+    readonly createdAt: number;
+    readonly lastUpdatedAt: number;
+}
+export interface RemoteRunnerEvidenceSummary {
+    readonly toolCallCount: number;
+    readonly messageCount: number;
+    readonly errorCount: number;
+    readonly transportState: DaemonTransportState;
+    readonly connectedAt?: number;
+    readonly lastError?: string;
+    readonly hasKnowledgeInjections: boolean;
+}
+export interface RemoteExecutionArtifact {
+    readonly id: string;
+    readonly runnerId: string;
+    readonly createdAt: number;
+    readonly runnerContract: RemoteRunnerContract;
+    readonly task: {
+        readonly task: string;
+        readonly status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+        readonly startedAt: number;
+        readonly completedAt?: number;
+        readonly summary: string;
+        readonly fullOutput?: string;
+        readonly error?: string;
+        readonly progress?: string;
+    };
+    readonly evidence: RemoteRunnerEvidenceSummary;
+    readonly knowledgeInjections: readonly {
+        readonly id: string;
+        readonly cls: string;
+        readonly summary: string;
+        readonly reason: string;
+        readonly confidence: number;
+        readonly reviewState: 'fresh' | 'reviewed' | 'stale' | 'contradicted';
+    }[];
+}
+export interface RemoteSessionBundle {
+    readonly version: 1;
+    readonly exportedAt: number;
+    readonly sessionId: string;
+    readonly activeConnectionIds: readonly string[];
+    readonly pools: readonly RemoteRunnerPool[];
+    readonly contracts: readonly RemoteRunnerContract[];
+    readonly artifacts: readonly RemoteExecutionArtifact[];
+}
+/**
+ * A semantic protocol version for the transport wire protocol.
+ *
+ * Versions are compared numerically: major.minor.patch.
+ * A peer with a different major version is always incompatible.
+ * A peer with a lower minor version may require graceful downgrade.
+ */
+export interface ProtocolVersion {
+    /** Major version — breaking changes; different majors cannot interoperate. */
+    readonly major: number;
+    /** Minor version — additive features; lower minor = possible downgrade. */
+    readonly minor: number;
+    /** Patch version — bug fixes only; no capability differences. */
+    readonly patch: number;
+    /** Human-readable version string (e.g. "2.1.0"). */
+    readonly label: string;
+}
+/**
+ * Reason codes for a protocol downgrade.
+ *
+ * When a peer's version is lower than the local version, the negotiation
+ * can proceed at the peer's level. The reason code records why the downgrade
+ * occurred for diagnostics and operator visibility.
+ */
+export type DowngradeReason = 
+/** Peer advertised a lower minor version; downgrading feature set. */
+'peer_minor_older'
+/** Local policy forces downgrade for compatibility with older peers. */
+ | 'policy_forced'
+/** Peer explicitly requested an older protocol level. */
+ | 'peer_requested';
+/**
+ * Negotiated protocol contract agreed upon during handshake.
+ *
+ * Both sides commit to this version for the session lifetime.
+ * Any capability absent at the negotiated version must not be used.
+ */
+export interface NegotiatedProtocol {
+    /** The agreed-upon version both peers will use. */
+    readonly version: ProtocolVersion;
+    /** Whether a downgrade from the local maximum occurred. */
+    readonly downgraded: boolean;
+    /** Reason for the downgrade (undefined when no downgrade). */
+    readonly downgradeReason?: DowngradeReason;
+    /** Version the local side offered (before negotiation). */
+    readonly offeredVersion: ProtocolVersion;
+    /** Version the remote peer advertised. */
+    readonly peerVersion: ProtocolVersion;
+    /** Epoch ms when negotiation completed. */
+    readonly negotiatedAt: number;
+}
+/**
+ * Result of a version compatibility check between local and peer versions.
+ *
+ * The `proceed` flag is the gate: if false, the handshake must be rejected
+ * and `incompatibilityReason` explains why to the operator.
+ */
+export type VersionNegotiationResult = {
+    readonly proceed: true;
+    readonly protocol: NegotiatedProtocol;
+} | {
+    readonly proceed: false;
+    /** Structured reason code for programmatic handling. */
+    readonly incompatibilityCode: 'major_version_mismatch' | 'peer_version_too_old' | 'peer_version_unsupported';
+    /** Human-readable explanation for operator diagnostics. */
+    readonly incompatibilityReason: string;
+    /** The local version that was offered. */
+    readonly offeredVersion: ProtocolVersion;
+    /** The peer version that was received. */
+    readonly peerVersion: ProtocolVersion;
+};
+/**
+ * Compatibility matrix entry defining the min/max peer versions that can
+ * interoperate with a given local version.
+ *
+ * "Supported range" is inclusive. Peers outside this range cannot proceed.
+ * Peers below `minSupported` receive an incompatibility rejection.
+ * Peers above `maxSupported` are treated as downgrade targets (peer is newer).
+ */
+export interface CompatibilityEntry {
+    /** The local version this entry describes. */
+    readonly localVersion: ProtocolVersion;
+    /** Minimum peer minor version accepted (same major required). */
+    readonly minSupportedMinor: number;
+    /** Maximum peer minor version accepted (same major required). */
+    readonly maxSupportedMinor: number;
+    /** Human-readable notes on what changed at each boundary. */
+    readonly notes?: string;
+}
+/**
+ * The full compatibility matrix: an ordered list of compatibility entries,
+ * one per supported local version.
+ *
+ * During handshake, the entry matching the current local version is looked up
+ * and the peer version is validated against its min/max range.
+ */
+export type CompatibilityMatrix = readonly CompatibilityEntry[];
+/**
+ * Configuration for creating a remote substrate instance.
+ */
+export interface RemoteSubstrateConfig {
+    /** Remote endpoint URL. */
+    readonly endpoint: string;
+    /** Initial durable identity (caller supplies stable IDs). */
+    readonly identity: DurableIdentity;
+    /** Replay settings. */
+    readonly replayConfig?: Partial<ReplayConfig>;
+    /** Reconnect policy override. */
+    readonly reconnectPolicy?: Partial<RetryPolicy>;
+    /** Authentication credentials or token factory. */
+    readonly authProvider?: AuthProvider;
+}
+/** Provides authentication tokens for transport handshakes. */
+export interface AuthProvider {
+    /**
+     * Returns a bearer token or auth header value.
+     * Called before each connect and reconnect attempt.
+     */
+    getToken(): Promise<string>;
+    /** Optional revocation — called on terminal failure. */
+    revokeToken?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/runtime/remote/types.d.ts.map

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

package/dist/platform/runtime/remote/types.js

@@ -0,0 +1,7 @@
+/**
+ * Remote Substrate — Core Types
+ *
+ * Implements durable identity, handshake tokens,
+ * typed transport messages, and replay configuration.
+ */
+export {};

package/dist/platform/runtime/retention/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * retention/index.ts
+ *
+ * Public barrel for the snapshot retention and pruning policy subsystem.
+ *
+ * Consumers should import from this barrel rather than from individual modules
+ * to remain insulated from internal refactors.
+ *
+ * @example
+ * ```ts
+ * import { RetentionPolicy, SnapshotPruner } from '../retention/index.js';
+ * import type { RetentionClass, CheckpointRecord, PruneResult } from '../retention/index.js';
+ * ```
+ */
+export { RetentionPolicy, DEFAULT_RETENTION_CONFIG } from './policy.js';
+export { SnapshotPruner } from './pruner.js';
+export type { RetentionClass, RetentionClassConfig, RetentionConfig, CheckpointRecord, PruneOptions, PruneResult, PerClassPruneResult, Pruner, RetentionStats, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/runtime/retention/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/retention/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,MAAM,EACN,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/platform/runtime/retention/index.js

@@ -0,0 +1,16 @@
+/**
+ * retention/index.ts
+ *
+ * Public barrel for the snapshot retention and pruning policy subsystem.
+ *
+ * Consumers should import from this barrel rather than from individual modules
+ * to remain insulated from internal refactors.
+ *
+ * @example
+ * ```ts
+ * import { RetentionPolicy, SnapshotPruner } from '../retention/index.js';
+ * import type { RetentionClass, CheckpointRecord, PruneResult } from '../retention/index.js';
+ * ```
+ */
+export { RetentionPolicy, DEFAULT_RETENTION_CONFIG } from './policy.js';
+export { SnapshotPruner } from './pruner.js';

package/dist/platform/runtime/retention/policy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * policy.ts
+ *
+ * `RetentionPolicy` — tracks registered checkpoints and decides which ones
+ * must be pruned to satisfy the configured retention limits.
+ *
+ * Each retention class (`short`, `standard`, `forensic`) has independent
+ * age, count, and size ceilings. Pruning candidates are determined in the
+ * following order:
+ *
+ *  1. Age limit  — any record older than `maxAgeMs` is a candidate.
+ *  2. Count limit — oldest records beyond `maxCount` are candidates.
+ *  3. Size limit  — oldest records are candidates until total size fits.
+ *
+ * The actual file deletion is delegated to `SnapshotPruner`.
+ */
+import type { CheckpointRecord, Pruner, PruneOptions, PruneResult, RetentionConfig, RetentionStats } from './types.js';
+/**
+ * Default limits applied when no override is provided.
+ *
+ * - `short`    : 1 h  / 5 checkpoints  / 50 MB
+ * - `standard` : 24 h / 20 checkpoints / 200 MB
+ * - `forensic` : 7 d  / 100 checkpoints / 1 GB
+ */
+export declare const DEFAULT_RETENTION_CONFIG: RetentionConfig;
+/**
+ * Manages the lifecycle of checkpoint records by enforcing per-class
+ * retention limits (age, count, size).
+ *
+ * @example
+ * ```ts
+ * const policy = new RetentionPolicy();
+ * policy.register({
+ *   id: 'cpt_01',
+ *   createdAt: Date.now(),
+ *   sizeBytes: 1024,
+ *   retentionClass: 'standard',
+ *   path: '/tmp/checkpoints/cpt_01.json',
+ * });
+ * const result = await policy.prune();
+ * ```
+ */
+export declare class RetentionPolicy {
+    private readonly _config;
+    private readonly _records;
+    private readonly _pruner;
+    private readonly _clock;
+    /**
+     * @param config - Optional partial override for any retention class limits.
+     *                 Unspecified classes fall back to `DEFAULT_RETENTION_CONFIG`.
+     * @param clock  - Optional clock function returning the current time in ms.
+     *                 Defaults to `Date.now`. Inject a fixed value in tests for
+     *                 deterministic time-based assertions.
+     * @param pruner - Optional pruner implementation. Defaults to `new SnapshotPruner()`.
+     *                 Inject a mock in tests to avoid file-system I/O.
+     */
+    constructor(config?: Partial<RetentionConfig>, clock?: () => number, pruner?: Pruner);
+    /**
+     * Register a new checkpoint for retention tracking.
+     *
+     * If a record with the same `id` already exists it is silently replaced,
+     * allowing callers to update metadata (e.g. size after write).
+     *
+     * @param record - The checkpoint record to track.
+     */
+    register(record: CheckpointRecord): void;
+    /**
+     * Unregister a checkpoint record (e.g. after it has been pruned externally).
+     *
+     * @param id - The checkpoint ID to remove from tracking.
+     * @returns `true` if the record was found and removed, `false` otherwise.
+     */
+    unregister(id: string): boolean;
+    /**
+     * Prune checkpoints that exceed retention limits.
+     *
+     * Evaluates each retention class independently and delegates file removal
+     * to `SnapshotPruner`. Successfully deleted records are removed from the
+     * internal tracking map.
+     *
+     * @param options - Optional prune options (e.g. `dryRun: true` to preview
+     *                  what would be deleted without touching the file system).
+     * @returns Aggregated `PruneResult` across all classes.
+     */
+    prune(options?: PruneOptions): Promise<PruneResult>;
+    /**
+     * Return current retention statistics per class.
+     *
+     * Useful for surfacing storage pressure in diagnostics panels.
+     */
+    getRetainedCount(): RetentionStats;
+    /**
+     * Return the current `RetentionConfig` in effect (defaults merged with overrides).
+     *
+     * Returns a deep clone so callers cannot mutate the internal configuration
+     * through nested object references.
+     */
+    getConfig(): RetentionConfig;
+    /**
+     * Collect records that violate any limit for their class.
+     *
+     * Evaluation order: age → count → size.
+     * Records violating multiple limits are included once.
+     */
+    private _collectCandidates;
+    /**
+     * Return all records for a given retention class, sorted oldest-first.
+     */
+    private _getClassRecords;
+    /**
+     * Apply age, count, and size limits to a sorted list of class records.
+     *
+     * @param sorted  - Records sorted oldest-first.
+     * @param config  - Limits for this class.
+     * @returns Records that should be pruned.
+     */
+    private _evaluateClass;
+}
+//# sourceMappingURL=policy.d.ts.map

package/dist/platform/runtime/retention/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/retention/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,WAAW,EAGX,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAC;AAOpB;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAgBtC,CAAC;AAMF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC;;;;;;;;OAQG;gBAED,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,KAAK,GAAE,MAAM,MAAiB,EAC9B,MAAM,CAAC,EAAE,MAAM;IAgCjB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;;;;;;OAUG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAczD;;;;OAIG;IACH,gBAAgB,IAAI,cAAc;IAyBlC;;;;;OAKG;IACH,SAAS,IAAI,eAAe;IAY5B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAqCvB"}