@vibesdotdev/runnable 0.0.0-stage → 1.0.0-rc.0

package/dist/docs/runnable.nodes.docs.descriptor.js

@@ -0,0 +1,327 @@
+const nodesMarkdown = `---
+title: Runnable Nodes
+summary: Node types, execution contexts, inputs, outputs, and lifecycle
+tags: [runnable, nodes, execution, lifecycle, types]
+parent: runnable
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runnable Nodes
+
+Nodes are the fundamental execution units within runnable graphs. Each node encapsulates a discrete computation step with well-defined inputs, outputs, and execution semantics.
+
+## Node anatomy
+
+A node definition comprises:
+
+\`\`\`ts
+interface NodeDefinition {
+  id: string;                    // Unique within graph
+  type: string;                  // References runnable/runnable descriptor
+  config: Record<string, unknown>;
+  inputs?: Record<string, string>;  // Maps input name to "nodeId.outputName"
+  outputs?: string[];            // Declared output names
+  metadata?: {
+    name?: string;
+    description?: string;
+    timeout?: number;            // Execution timeout in ms
+    retries?: number;            // Retry count on failure
+  };
+}
+\`\`\`
+
+## Node types
+
+Nodes are typed via the \`runnable/type\` descriptor kind. Common categories:
+
+### Benchmark nodes
+
+Execute performance benchmarks and collect metrics:
+
+\`\`\`ts
+{
+  id: 'benchmark-inference',
+  type: 'benchmark',
+  config: {
+    model: 'claude-sonnet-4-20250514',
+    dataset: 'mmlu-physics',
+    batchSize: 32
+  },
+  outputs: ['latency', 'throughput', 'accuracy']
+}
+\`\`\`
+
+### Training nodes
+
+Run model training with telemetry streaming:
+
+\`\`\`ts
+{
+  id: 'train-encoder',
+  type: 'train',
+  config: {
+    architecture: 'transformer',
+    hiddenSize: 768,
+    layers: 12,
+    epochs: 100,
+    lr: 0.0001,
+    warmupSteps: 1000
+  },
+  outputs: ['model-checkpoint', 'training-loss', 'validation-accuracy']
+}
+\`\`\`
+
+### Test nodes
+
+Execute test suites and collect results:
+
+\`\`\`ts
+{
+  id: 'test-integration',
+  type: 'test',
+  config: {
+    suite: 'integration',
+    parallelism: 4,
+    timeout: 300000
+  },
+  outputs: ['pass-count', 'fail-count', 'flaky-tests']
+}
+\`\`\`
+
+### Parameter sweep nodes
+
+Run hyperparameter sweeps across multiple configurations:
+
+\`\`\`ts
+{
+  id: 'sweep-lr',
+  type: 'sweep',
+  config: {
+    parameter: 'learning_rate',
+    values: [0.0001, 0.001, 0.01, 0.1],
+    metric: 'validation-loss',
+    strategy: 'grid'  // or 'random', 'bayesian'
+  },
+  outputs: ['best-config', 'all-results']
+}
+\`\`\`
+
+## Execution lifecycle
+
+Nodes progress through the following states:
+
+\`\`\`
+pending → validating → preparing → running → completing → done
+                                    ↓
+                              (on error) → failed → (retry) → running
+\`\`\`
+
+### State transitions
+
+1. **pending** — Waiting for upstream dependencies
+2. **validating** — Checking inputs and config
+3. **preparing** — Allocating resources, loading artifacts
+4. **running** — Executing computation
+5. **completing** — Finalizing outputs, flushing telemetry
+6. **done** — Successful completion
+7. **failed** — Irrecoverable error (may retry)
+
+## Context passing
+
+Nodes receive execution context from the graph runner:
+
+\`\`\`ts
+interface NodeExecutionContext {
+  runId: string;
+  nodeId: string;
+  graphId: string;
+  inputs: Record<string, unknown>;  // Resolved from upstream outputs
+  config: Record<string, unknown>;
+  telemetry: {
+    metric: (key: string, value: number, dimensions?: Record<string, string>) => void;
+    log: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: unknown) => void;
+    artifact: (name: string, mimeType: string, data: string) => void;
+  };
+  cancellation: AbortSignal;
+}
+\`\`\`
+
+## Output handling
+
+Node outputs are immutable once emitted. Outputs flow to downstream nodes via the graph's edge definitions:
+
+\`\`\`ts
+interface NodeOutput {
+  nodeId: string;
+  outputName: string;
+  value: unknown;
+  timestamp: number;
+  schema?: Record<string, unknown>;  // Optional JSON schema for validation
+}
+\`\`\`
+
+### Output validation
+
+Outputs can be validated against a schema:
+
+\`\`\`ts
+{
+  id: 'train-model',
+  type: 'train',
+  outputs: ['model', 'metrics'],
+  config: {
+    outputSchema: {
+      model: { type: 'object', properties: { id: { type: 'string' } } },
+      metrics: {
+        type: 'object',
+        properties: {
+          loss: { type: 'number' },
+          accuracy: { type: 'number' }
+        },
+        required: ['loss', 'accuracy']
+      }
+    }
+  }
+}
+\`\`\`
+
+## Error handling
+
+### Retry strategies
+
+\`\`\`ts
+{
+  id: 'flaky-api-call',
+  type: 'api-request',
+  config: {
+    retries: 3,
+    retryDelay: 1000,        // Base delay in ms
+    retryBackoff: 'exponential'  // or 'linear', 'constant'
+  }
+}
+\`\`\`
+
+### Failure isolation
+
+By default, node failures cancel downstream dependents. To isolate failures:
+
+\`\`\`ts
+{
+  id: 'optional-enrichment',
+  type: 'data-enricher',
+  config: {
+    onFailure: 'continue',  // or 'fail', 'retry'
+    fallbackOutput: { enriched: false }
+  }
+}
+\`\`\`
+
+## WRONG patterns
+
+:::card{title="Common mistakes"}
+- ❌ **Circular input references** — \`nodeA.input = nodeB.output\` and \`nodeB.input = nodeA.output\` causes deadlock
+- ❌ **Missing input declarations** — Using undeclared inputs fails at validation time
+- ❌ **Mutable outputs** — Modifying outputs after emission breaks downstream nodes
+- ❌ **Ignoring cancellation** — Long-running nodes should check \`context.cancellation.aborted\`
+- ❌ **Swallowing errors** — Always propagate or explicitly handle errors
+:::
+
+## Example: Multi-stage pipeline
+
+\`\`\`ts
+const pipeline = {
+  id: 'ml-pipeline',
+  nodes: [
+    {
+      id: 'fetch-data',
+      type: 'data-fetcher',
+      config: { source: 's3://bucket/dataset.parquet' },
+      outputs: ['raw-data'],
+      metadata: { timeout: 60000 }
+    },
+    {
+      id: 'validate-data',
+      type: 'data-validator',
+      inputs: { data: 'fetch-data.raw-data' },
+      config: { schema: './schemas/dataset.json' },
+      outputs: ['validated-data']
+    },
+    {
+      id: 'train-model',
+      type: 'train',
+      inputs: { trainingData: 'validate-data.validated-data' },
+      config: { epochs: 50, lr: 0.001 },
+      outputs: ['model', 'training-metrics'],
+      metadata: { retries: 2 }
+    },
+    {
+      id: 'evaluate-model',
+      type: 'evaluate',
+      inputs: { 
+        model: 'train-model.model',
+        testData: 'fetch-data.raw-data'
+      },
+      config: { metrics: ['accuracy', 'precision', 'recall'] },
+      outputs: ['evaluation-results']
+    }
+  ],
+  edges: [
+    { source: { node: 'fetch-data', output: 'raw-data' }, target: { node: 'validate-data', input: 'data' } },
+    { source: { node: 'validate-data', output: 'validated-data' }, target: { node: 'train-model', input: 'trainingData' } },
+    { source: { node: 'train-model', output: 'model' }, target: { node: 'evaluate-model', input: 'model' } },
+    { source: { node: 'fetch-data', output: 'raw-data' }, target: { node: 'evaluate-model', input: 'testData' } }
+  ]
+};
+\`\`\`
+
+## Related
+
+:::card{title="See also"}
+- [\`runnable.graphs\`](runnable.graphs) — Graph definitions, nodes, edges
+- [\`runnable.context\`](runnable.context) — Context passing, state management, caching
+:::
+
+## Code paths
+
+- Node schemas: [\`runnable/src/schemas/descriptors.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/schemas/descriptors.ts)
+- Runner implementation: [\`runnable/src/runner.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/runner.ts)
+- Kind definitions: [\`runnable/src/kinds/runnable.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/kinds/runnable.ts)
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runnable.nodes',
+    title: 'Runnable Nodes',
+    summary: 'Node types, execution contexts, inputs, outputs, and lifecycle',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: nodesMarkdown
+    },
+    parent: 'runnable',
+    order: 2,
+    tags: ['runnable', 'nodes', 'execution', 'lifecycle', 'types'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    man: {
+        name: 'runnable.nodes — execution units within graphs',
+        section: 1,
+        synopsis: 'vibes man runnable.nodes',
+        options: [],
+        examples: [
+            {
+                description: 'Define a training node',
+                command: '{ id: "train", type: "train", config: { epochs: 10 } }'
+            },
+            {
+                description: 'Connect nodes via edges',
+                command: '{ source: { node: "A", output: "result" }, target: { node: "B", input: "data" } }'
+            }
+        ],
+        seeAlso: ['runnable.graphs', 'runnable.context']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=runnable.nodes.docs.descriptor.js.map

package/dist/docs/runnable.nodes.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.nodes.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/runnable.nodes.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkSrB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,gBAAgB;IACpB,KAAK,EAAE,gBAAgB;IACvB,OAAO,EAAE,gEAAgE;IACzE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,aAAa;KACrB;IACD,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;IACb,GAAG,EAAE;QACJ,IAAI,EAAE,gDAAgD;QACtD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,0BAA0B;QACpC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,wBAAwB;gBACrC,OAAO,EAAE,wDAAwD;aACjE;YACD;gBACC,WAAW,EAAE,yBAAyB;gBACtC,OAAO,EAAE,mFAAmF;aAC5F;SACD;QACD,OAAO,EAAE,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;KAChD;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/event-broker.d.ts

@@ -0,0 +1,54 @@
+import * as z from 'zod/v4';
+import type { KindContext, RuntimeDescriptor, RuntimeRef } from '@vibesdotdev/kernel';
+import type { RuntimeKindDescriptorRecord } from '@vibesdotdev/kernel/schemas/kind';
+import type { RunnableChangePurpose } from './change-source.ts';
+export declare const RUNNABLE_EVENT_BROKER_ID = "runnable-events";
+export declare const RUNNABLE_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const runnableEventBrokerDescriptor: {
+    readonly id: "runnable-events";
+    readonly kind: "runnable/event-broker";
+    readonly description: "Runtime-local authenticated Runnable event and state stream.";
+};
+export declare const runnableEventBrokerKind: RuntimeKindDescriptorRecord;
+export declare const RunnableBrokerEventSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type RunnableBrokerEvent = z.infer<typeof RunnableBrokerEventSchema>;
+export interface RunnableEventBroker {
+    subscribe(changed: () => void, purpose?: 'catalog' | 'native'): () => void;
+    notify(purpose?: RunnableChangePurpose): void;
+    createStream(userId: string | null): Response;
+    broadcast(event: RunnableBrokerEvent, runId?: string): void;
+    broadcastSnapshot(): void;
+    setRunOwner(runId: string, userId: string | null): void;
+    clearRunOwner(runId: string): void;
+    getRunOwner(runId: string): string | null | undefined;
+    clientCount(): number;
+    dispose(): void;
+}
+export declare class RuntimeLocalRunnableEventBroker implements RunnableEventBroker {
+    readonly descriptor: RuntimeDescriptor;
+    private readonly subscribers;
+    private readonly clients;
+    private readonly runOwners;
+    private readonly stateHost;
+    private stopHeartbeat;
+    private readonly runtime;
+    constructor(descriptor: RuntimeDescriptor, context: KindContext);
+    createStream(userId: string | null): Response;
+    broadcast(event: RunnableBrokerEvent, runId?: string): void;
+    broadcastSnapshot(): void;
+    setRunOwner(runId: string, userId: string | null): void;
+    clearRunOwner(runId: string): void;
+    getRunOwner(runId: string): string | null | undefined;
+    clientCount(): number;
+    subscribe(changed: () => void, purpose?: 'catalog' | 'native'): () => void;
+    notify(purpose?: RunnableChangePurpose): void;
+    dispose(): void;
+    private canReceive;
+    private scopeSnapshot;
+    private snapshot;
+    private ensureHeartbeat;
+    private stopHeartbeatWhenIdle;
+}
+export declare function resolveRunnableEventBroker(runtime: RuntimeRef): Promise<RunnableEventBroker>;
+export default RuntimeLocalRunnableEventBroker;
+//# sourceMappingURL=event-broker.d.ts.map

package/dist/event-broker.d.ts.map

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

package/dist/event-broker.js

@@ -0,0 +1,157 @@
+import * as z from 'zod/v4';
+import { settleNow as settleSync } from '@vibesdotdev/kernel';
+import { RunnableEventBrokerDescriptorSchema } from "./schemas/descriptors.js";
+import { RUNNABLE_STATE_HOST_CONTEXT_ID } from "./host.js";
+export const RUNNABLE_EVENT_BROKER_ID = 'runnable-events';
+export const RUNNABLE_HEARTBEAT_INTERVAL_MS = 15_000;
+export const runnableEventBrokerDescriptor = {
+    id: RUNNABLE_EVENT_BROKER_ID,
+    kind: 'runnable/event-broker',
+    description: 'Runtime-local authenticated Runnable event and state stream.'
+};
+export const runnableEventBrokerKind = {
+    id: 'runnable/event-broker',
+    descriptorSchema: RunnableEventBrokerDescriptorSchema,
+    contexts: [RUNNABLE_STATE_HOST_CONTEXT_ID]
+};
+export const RunnableBrokerEventSchema = z.record(z.string(), z.unknown());
+function brokerEvent(value) {
+    return RunnableBrokerEventSchema.parse(value);
+}
+function frame(eventType, data) {
+    return new TextEncoder().encode(`event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+export class RuntimeLocalRunnableEventBroker {
+    descriptor;
+    subscribers = new Map();
+    clients = new Set();
+    runOwners = new Map();
+    stateHost;
+    stopHeartbeat = null;
+    runtime;
+    constructor(descriptor, context) {
+        this.descriptor = descriptor;
+        // SAFETY: RUNNABLE_STATE_HOST_CONTEXT_ID is declared in kind contexts and guaranteed by runtime
+        this.stateHost = context[RUNNABLE_STATE_HOST_CONTEXT_ID];
+        this.runtime = context.runtime;
+    }
+    createStream(userId) {
+        this.ensureHeartbeat();
+        let client;
+        const stream = new ReadableStream({
+            start: (controller) => {
+                client = { controller, userId };
+                this.clients.add(client);
+                const outcome = settleSync(() => controller.enqueue(frame('state', brokerEvent(this.scopeSnapshot(this.snapshot(), userId)))));
+                if (!outcome.ok) {
+                    this.clients.delete(client);
+                }
+            },
+            cancel: () => {
+                this.clients.delete(client);
+                this.stopHeartbeatWhenIdle();
+            }
+        });
+        return new Response(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive'
+            }
+        });
+    }
+    broadcast(event, runId) {
+        this.notify();
+        const payload = brokerEvent(runId === undefined ? event : { ...event, run_id: runId });
+        const encoded = frame(String(event.type ?? 'event'), payload);
+        const ownerId = runId ? this.runOwners.get(runId) : undefined;
+        for (const client of this.clients) {
+            if (!this.canReceive(client.userId, ownerId))
+                continue;
+            const outcome = settleSync(() => client.controller.enqueue(encoded));
+            if (!outcome.ok)
+                this.clients.delete(client);
+        }
+        this.stopHeartbeatWhenIdle();
+    }
+    broadcastSnapshot() {
+        this.notify();
+        if (this.clients.size === 0)
+            return;
+        const snapshot = this.snapshot();
+        for (const client of this.clients) {
+            const outcome = settleSync(() => client.controller.enqueue(frame('state', brokerEvent(this.scopeSnapshot(snapshot, client.userId)))));
+            if (!outcome.ok)
+                this.clients.delete(client);
+        }
+        this.stopHeartbeatWhenIdle();
+    }
+    setRunOwner(runId, userId) { this.runOwners.set(runId, userId); }
+    clearRunOwner(runId) { this.runOwners.delete(runId); }
+    getRunOwner(runId) { return this.runOwners.get(runId); }
+    clientCount() { return this.clients.size; }
+    subscribe(changed, purpose = 'native') {
+        this.subscribers.set(changed, purpose);
+        return () => { this.subscribers.delete(changed); };
+    }
+    notify(purpose = 'catalog') {
+        for (const [changed, projection] of this.subscribers) {
+            if (purpose === 'telemetry' && projection === 'catalog')
+                continue;
+            const delivered = settleSync(changed);
+            if (!delivered.ok)
+                this.runtime.diagnostics.error('Runnable change notification failed', {
+                    scope: 'runnable:events', plugin: 'runnable', error: delivered.cause
+                });
+        }
+    }
+    dispose() {
+        this.stopHeartbeat?.();
+        this.stopHeartbeat = null;
+        this.clients.clear();
+        this.runOwners.clear();
+        this.subscribers.clear();
+    }
+    canReceive(userId, ownerId) {
+        return !!userId && !!ownerId && userId === ownerId;
+    }
+    scopeSnapshot(snapshot, userId) {
+        if (!userId)
+            return { activeRuns: [], runCount: 0 };
+        const activeRuns = snapshot.activeRuns.filter((run) => this.runOwners.get(run.id) === userId);
+        return { activeRuns, runCount: activeRuns.length };
+    }
+    snapshot() {
+        const activeRuns = this.stateHost.state.getAllRuns().map((run) => run.state);
+        return { activeRuns, runCount: activeRuns.length };
+    }
+    ensureHeartbeat() {
+        if (this.stopHeartbeat)
+            return;
+        // A finite host starts no autonomous background work (`interval` refuses it); it serves no long-lived stream.
+        if (this.runtime.scope.lifecycle === 'finite')
+            return;
+        // Runtime-owned tick: ends with the runtime, or earlier when the last client leaves.
+        this.stopHeartbeat = this.runtime.lifecycle.interval(() => {
+            const encoded = new TextEncoder().encode(':heartbeat\n\n');
+            for (const client of this.clients) {
+                const outcome = settleSync(() => client.controller.enqueue(encoded));
+                if (!outcome.ok)
+                    this.clients.delete(client);
+            }
+            this.stopHeartbeatWhenIdle();
+        }, RUNNABLE_HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeatWhenIdle() {
+        if (this.clients.size > 0 || !this.stopHeartbeat)
+            return;
+        this.stopHeartbeat();
+        this.stopHeartbeat = null;
+    }
+}
+export async function resolveRunnableEventBroker(runtime) {
+    return runtime.query('runnable/event-broker')
+        .withId(RUNNABLE_EVENT_BROKER_ID).resolve();
+}
+export default RuntimeLocalRunnableEventBroker;
+//# sourceMappingURL=event-broker.js.map

package/dist/event-broker.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import type { IngestMappingContext } from './schemas/contracts.ts';
+import { type GenericWrite } from './schemas/writes.ts';
+import { type RunnableEvent } from './schemas/events.ts';
+export * from './schemas/events.ts';
+export * from './schemas/writes.ts';
+/** Old occurrences remain evidence; their lifecycle patches cannot control a newer native admission. */
+export declare function runnableEventAppliesLifecycle(event: {
+    execution_generation?: number;
+    execution_attempt?: number;
+}, metadata: import('@vibesdotdev/kernel/schemas/json').JsonObject): boolean;
+export declare function coreEventToWrites(event: RunnableEvent, ts: number): GenericWrite[];
+/** Read the selected owner's mapping once; one canonical row preserves each actual extension event. */
+export declare function projectRunnableEvent(runtime: RuntimeRef, input: RunnableEvent, context: IngestMappingContext, runnableType?: string): Promise<GenericWrite[]>;
+export { mergeRunEventMetadata } from './records/authority.ts';
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAqB,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,KAAK,EAAgB,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAsB,KAAK,YAAY,EAAuE,MAAM,qBAAqB,CAAC;AAEjJ,OAAO,EAGU,KAAK,aAAa,EAClC,MAAM,qBAAqB,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AAEpC,wGAAwG;AACxG,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAAE,OAAO,kCAAkC,EAAE,UAAU,GAAG,OAAO,CAU5L;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAwFlF;AAED,uGAAuG;AACvG,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,oBAAoB,EAC7B,YAAY,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAmBzB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}