@fabric-harness/sdk 1.13.0 → 2.0.0

package/dist/conversation-stream.js

@@ -0,0 +1,159 @@
+export class ConversationStreamStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ConversationStreamStoreError';
+        this.code = code;
+    }
+}
+export const CONVERSATION_STREAM_DEFAULT_READ_LIMIT = 100;
+export const CONVERSATION_STREAM_MAX_READ_LIMIT = 1000;
+export function clampReadLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit) || limit <= 0) {
+        return CONVERSATION_STREAM_DEFAULT_READ_LIMIT;
+    }
+    return Math.min(Math.floor(limit), CONVERSATION_STREAM_MAX_READ_LIMIT);
+}
+export function formatStreamOffset(offset) {
+    return String(offset);
+}
+export function parseStreamOffset(offset) {
+    if (offset === undefined || offset === '')
+        return 0;
+    const parsed = Number.parseInt(offset, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return parsed;
+}
+/** Stream path for a session's conversation projection. */
+export function conversationStreamPath(storeSessionId) {
+    return `conversations/${storeSessionId}`;
+}
+/**
+ * Process-local listener registry shared by store implementations —
+ * registration, unsubscribe-and-prune, and error-swallowing notify.
+ */
+export class StreamListenerRegistry {
+    listeners = new Map();
+    subscribe(path, listener) {
+        let set = this.listeners.get(path);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(path, set);
+        }
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0)
+                this.listeners.delete(path);
+        };
+    }
+    notify(path) {
+        for (const listener of this.listeners.get(path) ?? []) {
+            try {
+                listener();
+            }
+            catch {
+                // Listener failures never affect the writer.
+            }
+        }
+    }
+}
+/** In-memory conversation stream store (dev / `runtime: 'stateless'` / tests). */
+export class InMemoryConversationStreamStore {
+    streams = new Map();
+    registry = new StreamListenerRegistry();
+    async createStream(path, identity) {
+        if (!this.streams.has(path)) {
+            this.streams.set(path, {
+                identity,
+                batches: [],
+                nextOffset: 0,
+                producerId: null,
+                producerEpoch: 0,
+                nextProducerSequence: 0,
+            });
+        }
+    }
+    async acquireProducer(path, producerId) {
+        const stream = this.requireStream(path);
+        stream.producerId = producerId;
+        stream.producerEpoch += 1;
+        stream.nextProducerSequence = 0;
+        return {
+            producerId,
+            producerEpoch: stream.producerEpoch,
+            nextProducerSequence: stream.nextProducerSequence,
+            offset: formatStreamOffset(stream.nextOffset),
+        };
+    }
+    async append(input) {
+        const stream = this.requireStream(input.path);
+        if (input.producerId !== stream.producerId || input.producerEpoch !== stream.producerEpoch) {
+            throw new ConversationStreamStoreError('PRODUCER_FENCED', `Producer ${input.producerId}@${input.producerEpoch} is fenced; current is ${stream.producerId ?? 'none'}@${stream.producerEpoch}.`);
+        }
+        // Idempotent redelivery: identical coordinates return the committed offset.
+        const existing = stream.batches.find((batch) => batch.producerId === input.producerId &&
+            batch.producerEpoch === input.producerEpoch &&
+            batch.producerSequence === input.producerSequence);
+        if (existing)
+            return { offset: formatStreamOffset(existing.seq) };
+        if (input.producerSequence !== stream.nextProducerSequence) {
+            throw new ConversationStreamStoreError('SEQUENCE_CONFLICT', `Producer sequence ${input.producerSequence} does not match expected ${stream.nextProducerSequence}.`);
+        }
+        const seq = stream.nextOffset;
+        stream.batches.push({
+            seq,
+            producerId: input.producerId,
+            producerEpoch: input.producerEpoch,
+            producerSequence: input.producerSequence,
+            records: input.records.map((record) => structuredClone(record)),
+        });
+        stream.nextOffset = seq + 1;
+        stream.nextProducerSequence = input.producerSequence + 1;
+        this.registry.notify(input.path);
+        return { offset: formatStreamOffset(seq) };
+    }
+    async read(path, options) {
+        const stream = this.requireStream(path);
+        const from = parseStreamOffset(options?.offset);
+        const limit = clampReadLimit(options?.limit);
+        const selected = stream.batches.filter((batch) => batch.seq >= from).slice(0, limit);
+        const last = selected[selected.length - 1];
+        const nextOffset = last ? last.seq + 1 : from;
+        return {
+            batches: selected.map((batch) => ({
+                offset: formatStreamOffset(batch.seq),
+                records: batch.records.map((record) => structuredClone(record)),
+            })),
+            nextOffset: formatStreamOffset(nextOffset),
+            upToDate: nextOffset >= stream.nextOffset,
+        };
+    }
+    async getMeta(path) {
+        const stream = this.streams.get(path);
+        if (!stream)
+            return null;
+        return {
+            identity: stream.identity,
+            nextOffset: formatStreamOffset(stream.nextOffset),
+            producerId: stream.producerId,
+            producerEpoch: stream.producerEpoch,
+            nextProducerSequence: stream.nextProducerSequence,
+        };
+    }
+    async delete(path) {
+        this.streams.delete(path);
+    }
+    subscribe(path, listener) {
+        return this.registry.subscribe(path, listener);
+    }
+    requireStream(path) {
+        const stream = this.streams.get(path);
+        if (!stream) {
+            throw new ConversationStreamStoreError('STREAM_NOT_FOUND', `Conversation stream not found: ${path}`);
+        }
+        return stream;
+    }
+}
+//# sourceMappingURL=conversation-stream.js.map

package/dist/conversation-stream.js.map

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

package/dist/cost-budget.d.ts

@@ -94,6 +94,21 @@ export interface CostLimit {
      *   and pause until approved. Re-throw on denial.
      */
     onExceed?: 'throw' | 'approve';
+    /**
+     * Whether the scope is tracked incrementally in-process or read from an
+     * external source. Defaults to `'incremental'`.
+     */
+    scopeSource?: 'incremental' | 'external';
+    /**
+     * External source for actual (non-estimated) spend. When provided, the
+     * budget tracker can query real-time cost data from the provider.
+     */
+    actualSource?: ActualCostSource;
+    /**
+     * TTL for caching actual cost lookups (milliseconds). When omitted, the
+     * actual source's default or per-query option is used.
+     */
+    actualsCacheTtlMs?: number;
 }
 export interface CostLimitContext {
     scope: 'call' | 'session' | 'cross-process';
@@ -101,6 +116,85 @@ export interface CostLimitContext {
     limitUsd: number;
     /** External scope key, populated for `scope: 'cross-process'`. */
     scopeKey?: string;
+    /** ISO timestamp when actual cost data was last fetched from the provider. */
+    actualsFetchedAt?: string;
+    /** TTL (in ms) for the cached actual cost data used in this observation. */
+    cacheTtlMs?: number;
+}
+/**
+ * Attribution dimensions for a single cost observation. All fields are
+ * optional so callers can tag as much or as little metadata as they have.
+ */
+export interface CostAttribution {
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+    model?: string;
+    provider?: string;
+    sessionId?: string;
+    turnId?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Query filters for retrieving aggregated cost attribution rows.
+ */
+export interface AttributionQuery {
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+    model?: string;
+    provider?: string;
+    /** ISO date string (inclusive). */
+    startDate?: string;
+    /** ISO date string (inclusive). */
+    endDate?: string;
+    /** Dimensions to group by. Defaults to all if omitted. */
+    groupBy?: Array<keyof CostAttribution>;
+}
+/**
+ * A single row of aggregated cost attribution data.
+ */
+export interface CostAttributionRow {
+    agentId?: string;
+    userId?: string;
+    tenantId?: string;
+    model?: string;
+    provider?: string;
+    /** Period identifier, e.g. `day:2026-06-23`. */
+    period: string;
+    /** Estimated cost from the static price table. */
+    estimatedUsd: number;
+    /** Actual cost from the provider's billing API. */
+    actualUsd: number;
+    /** Actual DBU (Databricks Unit) spend, if applicable. */
+    actualDbus: number;
+    /** Difference between estimated and actual cost. */
+    deltaUsd: number;
+    /** Number of calls in this aggregation. */
+    calls: number;
+}
+/**
+ * External source for actual (non-estimated) spend. Implementations can
+ * query provider billing APIs, Databricks usage tables, or other real-time
+ * cost data.
+ */
+export interface ActualCostSource {
+    /**
+     * Fetch the actual USD spend for a scope, optionally filtered by
+     * attribution dimensions.
+     */
+    getUsd(scopeKey: string, attribution?: CostAttribution, options?: {
+        cacheTtlMs?: number;
+    }): Promise<{
+        usd: number;
+        dbus?: number;
+        actualsFetchedAt?: string;
+        cacheTtlMs?: number;
+    }>;
+    /**
+     * Query aggregated cost attribution rows for reporting or debugging.
+     */
+    queryAttribution(filters: AttributionQuery): Promise<CostAttributionRow[]>;
 }
 export declare class CostLimitExceededError extends FabricError {
     readonly context: CostLimitContext;
@@ -112,7 +206,11 @@ export declare class CostLimitExceededError extends FabricError {
 export declare class CostBudgetTracker {
     private readonly limit;
     private sessionTotalUsd;
+    private pendingScopeViolation;
+    private defaultStore;
     constructor(limit: CostLimit | undefined);
+    /** How `perScope` is enforced: `'incremental'` (estimate counter) or `'external'` (actual-cost source). */
+    get scopeSource(): 'incremental' | 'external';
     /** Has any budget configured. */
     enabled(): boolean;
     /**
@@ -125,8 +223,15 @@ export declare class CostBudgetTracker {
      * Cross-process scope check. Returns a violation when the scope's running
      * total exceeds `perScope` after incrementing by `callUsd`. No-op when
      * `perScope`/`scopeKey` are not configured.
+     *
+     * For `scopeSource === 'incremental'` (default), increments the store and
+     * compares. For `scopeSource === 'external'`, queries `actualSource` instead.
      */
-    observeScopeAsync(callUsd: number): Promise<CostLimitContext | undefined>;
+    observeScopeAsync(callUsd: number, attribution?: CostAttribution): Promise<CostLimitContext | undefined>;
+    /** Store a pending scope violation for asynchronous reconciliation. */
+    setPendingScopeViolation(violation: CostLimitContext): void;
+    /** Take and clear the pending scope violation, if any. */
+    takePendingScopeViolation(): CostLimitContext | undefined;
     /** Total spend so far this session. */
     total(): number;
     onExceed(): 'throw' | 'approve';

package/dist/cost-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost-budget.d.ts","sourceRoot":"","sources":["../src/cost-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,2CAA2C;IAC3C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,yDAAyD;IACzD,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,SAAS,CAuBX;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,4CAA4C;IAC5C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,IAAI,eAAe,CAezD;AAED,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,sBAAuB,SAAQ,WAAW;aACzB,OAAO,EAAE,gBAAgB;gBAAzB,OAAO,EAAE,gBAAgB;CAQtD;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,eAAe,CAAK;gBAEC,KAAK,EAAE,SAAS,GAAG,SAAS;IAEzD,iCAAiC;IACjC,OAAO,IAAI,OAAO;IAMlB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAYtD;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAU/E,uCAAuC;IACvC,KAAK,IAAI,MAAM;IAIf,QAAQ,IAAI,OAAO,GAAG,SAAS;CAGhC"}
+{"version":3,"file":"cost-budget.d.ts","sourceRoot":"","sources":["../src/cost-budget.ts"],"names":[],"mappings":"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"}

package/dist/cost-budget.js

@@ -86,9 +86,15 @@ export class CostLimitExceededError extends FabricError {
 export class CostBudgetTracker {
     limit;
     sessionTotalUsd = 0;
+    pendingScopeViolation;
+    defaultStore;
     constructor(limit) {
         this.limit = limit;
     }
+    /** How `perScope` is enforced: `'incremental'` (estimate counter) or `'external'` (actual-cost source). */
+    get scopeSource() {
+        return this.limit?.scopeSource ?? 'incremental';
+    }
     /** Has any budget configured. */
     enabled() {
         return Boolean(this.limit && (this.limit.perCall !== undefined || this.limit.perSession !== undefined || this.limit.perScope !== undefined));
@@ -114,17 +120,57 @@ export class CostBudgetTracker {
      * Cross-process scope check. Returns a violation when the scope's running
      * total exceeds `perScope` after incrementing by `callUsd`. No-op when
      * `perScope`/`scopeKey` are not configured.
+     *
+     * For `scopeSource === 'incremental'` (default), increments the store and
+     * compares. For `scopeSource === 'external'`, queries `actualSource` instead.
      */
-    async observeScopeAsync(callUsd) {
+    async observeScopeAsync(callUsd, attribution) {
         if (!this.limit?.perScope || !this.limit.scopeKey || callUsd <= 0)
             return undefined;
-        const store = this.limit.store ?? inMemoryCostBudgetStore();
+        const scopeSource = this.limit.scopeSource ?? 'incremental';
+        if (scopeSource === 'external') {
+            if (!this.limit.actualSource)
+                return undefined;
+            const opts = {};
+            if (this.limit.actualsCacheTtlMs !== undefined)
+                opts.cacheTtlMs = this.limit.actualsCacheTtlMs;
+            const result = await this.limit.actualSource.getUsd(this.limit.scopeKey, attribution, opts);
+            if (result.usd > this.limit.perScope) {
+                const ctx = {
+                    scope: 'cross-process',
+                    observedUsd: result.usd,
+                    limitUsd: this.limit.perScope,
+                    scopeKey: this.limit.scopeKey,
+                };
+                if (result.actualsFetchedAt)
+                    ctx.actualsFetchedAt = result.actualsFetchedAt;
+                if (result.cacheTtlMs !== undefined)
+                    ctx.cacheTtlMs = result.cacheTtlMs;
+                return ctx;
+            }
+            return undefined;
+        }
+        // incremental (default) — reuse a single default store instance per tracker
+        if (!this.defaultStore) {
+            this.defaultStore = this.limit.store ?? inMemoryCostBudgetStore();
+        }
+        const store = this.defaultStore;
         const total = await store.incrementUsd(this.limit.scopeKey, callUsd);
         if (total > this.limit.perScope) {
             return { scope: 'cross-process', observedUsd: total, limitUsd: this.limit.perScope, scopeKey: this.limit.scopeKey };
         }
         return undefined;
     }
+    /** Store a pending scope violation for asynchronous reconciliation. */
+    setPendingScopeViolation(violation) {
+        this.pendingScopeViolation = violation;
+    }
+    /** Take and clear the pending scope violation, if any. */
+    takePendingScopeViolation() {
+        const v = this.pendingScopeViolation;
+        this.pendingScopeViolation = undefined;
+        return v;
+    }
     /** Total spend so far this session. */
     total() {
         return this.sessionTotalUsd;

package/dist/cost-budget.js.map

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

package/dist/delivered-message.d.ts

@@ -0,0 +1,90 @@
+import type { SignalEntryData } from './types.js';
+/**
+ * DeliveredMessage — the single unified input shape for everything that
+ * enters a persistent agent's session: direct HTTP prompts, dispatch,
+ * channels/webhooks, Databricks events, SDK clients, and tests.
+ *
+ * `kind: 'user'` is a direct user talking to the assistant (1:1 chat
+ * surface), optionally carrying attachments.
+ *
+ * `kind: 'signal'` models everything beyond that direct exchange — a Slack
+ * thread or a Lakeflow job event is activity the agent observes, not the
+ * assistant's own user speaking. Sender identity and structured metadata go
+ * in `attributes`; the message itself in `body`. Signals render into model
+ * context as an XML envelope (`<tagName ...attributes>body</tagName>`).
+ *
+ * `body` (not `text`/`content`) is named for headroom — a future revision may
+ * accept a real JSON value and stringify internally without a field rename.
+ */
+export type DeliveredMessage = {
+    kind: 'user';
+    body: string;
+    attachments?: DeliveredAttachment[];
+} | {
+    kind: 'signal';
+    /** Caller-defined event/signal type, e.g. `'slack.message'` or `'databricks.job_run'`. */
+    type: string;
+    body: string;
+    attributes?: Record<string, string>;
+    tagName?: string;
+};
+/**
+ * One attachment on a `kind: 'user'` message. Today the only supported
+ * attachment is an image, carried either inline (`data`, base64) or as a
+ * durable content-addressed reference (`ref`) once an attachment store is
+ * configured — admission materializes inline bytes into refs. An attachment
+ * must carry `data` or `ref` (or both, transiently during materialization).
+ */
+export interface DeliveredAttachment {
+    type: 'image';
+    /** Base64-encoded bytes (inline form). */
+    data?: string;
+    mimeType: string;
+    /** Uploader-provided display name; not part of byte identity. */
+    filename?: string;
+    /** Durable content-addressed reference (materialized form). */
+    ref?: DeliveredAttachmentRef;
+}
+/** Durable reference to attachment bytes in an attachment store. */
+export interface DeliveredAttachmentRef {
+    /** Attachment id assigned at materialization. */
+    id: string;
+    /** Lowercase hex SHA-256 of the bytes — the content address. */
+    digest: string;
+    sizeBytes: number;
+}
+/** Maximum accepted base64 length for a single inline attachment. */
+export declare const MAX_ATTACHMENT_DATA_LENGTH: number;
+/** Thrown by {@link parseDeliveredMessage} on malformed input. */
+export declare class InvalidDeliveredMessageError extends Error {
+    readonly code = "INVALID_DELIVERED_MESSAGE";
+    constructor(reason: string);
+}
+/**
+ * Validate a raw value as a {@link DeliveredMessage}. Shared by dispatch
+ * admission and the direct HTTP route so every transport produces the same
+ * structured error on bad input.
+ */
+export declare function parseDeliveredMessage(value: unknown): DeliveredMessage;
+/** True when a raw value already looks like a {@link DeliveredMessage} (has a valid `kind`). */
+export declare function isDeliveredMessageShape(value: unknown): boolean;
+/**
+ * Normalize legacy inputs into a {@link DeliveredMessage}:
+ * - a string → a user message with that body
+ * - a value with a `kind` discriminator → validated as a DeliveredMessage
+ * - any other JSON value → a user message with the JSON-stringified body
+ *   (matching the historical dispatch rendering, so behavior is unchanged
+ *   for pre-DeliveredMessage callers)
+ */
+export declare function normalizeDeliveredMessage(input: unknown): DeliveredMessage;
+/**
+ * Render a delivered message to the prompt text form. User messages pass
+ * their body through verbatim; signals render as their XML envelope via the
+ * shared {@link renderSignalMessage} machinery.
+ */
+export declare function renderDeliveredMessage(message: DeliveredMessage): string;
+/** Map a signal-kind message onto the persisted `signal` entry's data shape. */
+export declare function deliveredSignalToEntryData(message: Extract<DeliveredMessage, {
+    kind: 'signal';
+}>): SignalEntryData;
+//# sourceMappingURL=delivered-message.d.ts.map

package/dist/delivered-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivered-message.d.ts","sourceRoot":"","sources":["../src/delivered-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACnE;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,sBAAsB,CAAC;CAC9B;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAU3D,kEAAkE;AAClE,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,+BAA+B;gBAChC,MAAM,EAAE,MAAM;CAI3B;AAUD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAiDtE;AAkDD,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAI1E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAGxE;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GACrD,eAAe,CAOjB"}