@metrxbot/sdk 0.1.0 → 0.2.1

package/dist/routing-gate.js

@@ -0,0 +1,118 @@
+/**
+ * Confidence gate for the SDK cascade (spec §5.3): G1 structural validators
+ * (zero-cost floor) + G4 cheap checker call (the primary signal).
+ *
+ * Gate contract: any error or timeout inside the gate means ESCALATE — the
+ * gate fails toward quality, never toward serving an unchecked answer (F5).
+ */
+/** G1 — structural validators. Cheap, high-precision, low-recall. */
+export function runValidators(output, config) {
+    if (!config)
+        return { pass: true };
+    if (config.min_length != null && output.length < config.min_length) {
+        return { pass: false, reason: `g1:min_length(${output.length}<${config.min_length})` };
+    }
+    if (config.max_length != null && output.length > config.max_length) {
+        return { pass: false, reason: `g1:max_length(${output.length}>${config.max_length})` };
+    }
+    if (config.regex != null) {
+        try {
+            if (!new RegExp(config.regex).test(output)) {
+                return { pass: false, reason: 'g1:regex' };
+            }
+        }
+        catch {
+            // A malformed regex in the policy must not throw in the request path
+            // (F3-adjacent) — treat as validator failure → escalate.
+            return { pass: false, reason: 'g1:regex_invalid' };
+        }
+    }
+    if (config.require_json) {
+        let parsed;
+        try {
+            parsed = JSON.parse(output);
+        }
+        catch {
+            return { pass: false, reason: 'g1:json_parse' };
+        }
+        if (config.required_fields?.length) {
+            if (parsed === null || typeof parsed !== 'object') {
+                return { pass: false, reason: 'g1:json_not_object' };
+            }
+            for (const field of config.required_fields) {
+                if (!(field in parsed)) {
+                    return { pass: false, reason: `g1:missing_field(${field})` };
+                }
+            }
+        }
+    }
+    return { pass: true };
+}
+const CHECKER_INSTRUCTIONS = 'You are a strict quality checker. Given a task input and a candidate answer, ' +
+    'judge whether the answer adequately and correctly addresses the task. ' +
+    'Respond with ONLY a JSON object: {"score": <number between 0 and 1>} — ' +
+    'no prose, no code fences.';
+/**
+ * G4 — cheap checker call via the customer-supplied checkerCaller.
+ * Throws on any failure (timeout, unparsable verdict) — the caller escalates.
+ */
+export async function runChecker(opts) {
+    const task = {
+        instructions: CHECKER_INSTRUCTIONS,
+        rubric: opts.rubric ?? null,
+        task_input: safeStringify(opts.input),
+        candidate_answer: opts.output,
+    };
+    const result = await withTimeout(opts.checkerCaller(opts.checkerModel, task, opts.ctx), opts.timeoutMs, 'checker');
+    const score = parseScore(result.output);
+    if (score === null) {
+        throw new Error('checker returned an unparsable verdict');
+    }
+    return score;
+}
+/** Extract {"score": x} from checker output, tolerating stray text. */
+export function parseScore(text) {
+    try {
+        const direct = JSON.parse(text);
+        if (typeof direct?.score === 'number')
+            return clamp01(direct.score);
+    }
+    catch {
+        // fall through to fragment scan
+    }
+    const match = text.match(/"score"\s*:\s*(-?\d+(?:\.\d+)?)/);
+    if (match)
+        return clamp01(Number(match[1]));
+    return null;
+}
+function clamp01(n) {
+    if (isNaN(n))
+        return null;
+    return Math.max(0, Math.min(1, n));
+}
+function safeStringify(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export async function withTimeout(promise, ms, label) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=routing-gate.js.map

package/dist/routing-gate.js.map

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

package/dist/routing-policy-cache.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Policy cache for the SDK cascade router (spec §5.6).
+ *
+ * - One fetch caches the whole org's policy set (GET /api/v1/routing/policies).
+ * - TTL 5 min (matches the server's max-age) with ETag revalidation.
+ * - Stale tolerance ≤ 60 min: a kill-switch flip must propagate; past the
+ *   bound the cache reports "unknown" and every caller falls back to
+ *   pass-through (seam F2).
+ * - Lazy + non-blocking: the first call triggers a background load and
+ *   returns "unknown" — cold start is pass-through, never a blocked request
+ *   (seam F1).
+ *
+ * NEVER throws. All fetch failures degrade to "unknown" → pass-through.
+ */
+export interface RoutingPolicy {
+    id: string;
+    agent_key: string;
+    enabled: boolean;
+    denied: boolean;
+    mode: 'pass_through' | 'shadow_sample' | 'cascade';
+    pool: string;
+    candidate_model: string | null;
+    prod_model: string | null;
+    confidence_threshold: number | null;
+    gate_config: Record<string, unknown>;
+    sample_rate: number;
+    holdout_pct: number;
+    max_extra_latency_ms: number;
+    min_sdk_version: string | null;
+    policy_version: number;
+    experiment_id: string | null;
+}
+export interface PolicyFetchResult {
+    policies: RoutingPolicy[];
+    /** Org-level monotonic version (informational). */
+    version: number;
+    /** The server's ETag header, echoed back OPAQUELY on the next fetch — the
+     * SDK cannot reconstruct it (it embeds the org id, review H1). */
+    etag?: string | null;
+    /** True when the server answered 304 (cache still valid). */
+    notModified?: boolean;
+}
+/** Injectable fetcher — the router wires this to the Metrx API; tests stub it.
+ * `etag` is the OPAQUE value from the previous response's ETag header. */
+export type PolicyFetcher = (etag: string | null) => Promise<PolicyFetchResult>;
+export declare class PolicyCache {
+    private byKey;
+    private etag;
+    private loaded;
+    private loadedAt;
+    private loading;
+    private readonly fetcher;
+    private readonly ttlMs;
+    private readonly staleMaxMs;
+    private readonly now;
+    constructor(opts: {
+        fetcher: PolicyFetcher;
+        ttlMs?: number;
+        staleMaxMs?: number;
+        now?: () => number;
+    });
+    /**
+     * Non-blocking lookup.
+     * - `undefined` → policy state UNKNOWN (never loaded, or stale past the
+     *   bound) — caller must pass through.
+     * - `null` → the org's policies ARE loaded and this agent has no row —
+     *   pass-through by design (no row = not allow-listed).
+     * - a policy row otherwise.
+     */
+    get(agentKey: string): RoutingPolicy | null | undefined;
+    /** Await any in-flight load — for tests and graceful shutdown. */
+    settle(): Promise<void>;
+    private refresh;
+}
+/** Normalization rule shared with policy writes (spec §5.1 M8). */
+export declare function normalizeAgentKey(key: string): string;
+//# sourceMappingURL=routing-policy-cache.d.ts.map

package/dist/routing-policy-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-policy-cache.d.ts","sourceRoot":"","sources":["../src/routing-policy-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,SAAS,CAAC;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB;sEACkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;0EAC0E;AAC1E,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAKhF,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE;QAChB,OAAO,EAAE,aAAa,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;KACpB;IAOD;;;;;;;OAOG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,GAAG,SAAS;IAuBvD,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,OAAO,CAAC,OAAO;CA0BhB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/routing-policy-cache.js

@@ -0,0 +1,96 @@
+/**
+ * Policy cache for the SDK cascade router (spec §5.6).
+ *
+ * - One fetch caches the whole org's policy set (GET /api/v1/routing/policies).
+ * - TTL 5 min (matches the server's max-age) with ETag revalidation.
+ * - Stale tolerance ≤ 60 min: a kill-switch flip must propagate; past the
+ *   bound the cache reports "unknown" and every caller falls back to
+ *   pass-through (seam F2).
+ * - Lazy + non-blocking: the first call triggers a background load and
+ *   returns "unknown" — cold start is pass-through, never a blocked request
+ *   (seam F1).
+ *
+ * NEVER throws. All fetch failures degrade to "unknown" → pass-through.
+ */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_STALE_MAX_MS = 60 * 60 * 1000;
+export class PolicyCache {
+    byKey = new Map();
+    etag = null;
+    loaded = false;
+    loadedAt = 0;
+    loading = null;
+    fetcher;
+    ttlMs;
+    staleMaxMs;
+    now;
+    constructor(opts) {
+        this.fetcher = opts.fetcher;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.staleMaxMs = opts.staleMaxMs ?? DEFAULT_STALE_MAX_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Non-blocking lookup.
+     * - `undefined` → policy state UNKNOWN (never loaded, or stale past the
+     *   bound) — caller must pass through.
+     * - `null` → the org's policies ARE loaded and this agent has no row —
+     *   pass-through by design (no row = not allow-listed).
+     * - a policy row otherwise.
+     */
+    get(agentKey) {
+        if (!this.loaded) {
+            // Cold: kick off the first load, serve pass-through now (F1).
+            this.refresh();
+            return undefined;
+        }
+        const age = this.now() - this.loadedAt;
+        if (age > this.staleMaxMs) {
+            // Too stale to trust — a kill-switch flip may not have propagated (F2).
+            this.refresh();
+            return undefined;
+        }
+        if (age > this.ttlMs) {
+            // Stale-but-tolerable: serve, refresh in the background.
+            this.refresh();
+        }
+        return this.byKey.get(normalizeAgentKey(agentKey)) ?? null;
+    }
+    /** Await any in-flight load — for tests and graceful shutdown. */
+    async settle() {
+        if (this.loading)
+            await this.loading.catch(() => undefined);
+    }
+    refresh() {
+        if (this.loading)
+            return; // single-flight
+        this.loading = this.fetcher(this.etag)
+            .then((result) => {
+            if (result.notModified) {
+                this.loadedAt = this.now();
+                return;
+            }
+            const next = new Map();
+            for (const p of result.policies) {
+                if (p && typeof p.agent_key === 'string') {
+                    next.set(normalizeAgentKey(p.agent_key), p);
+                }
+            }
+            this.byKey = next;
+            this.etag = result.etag ?? null;
+            this.loaded = true;
+            this.loadedAt = this.now();
+        })
+            .catch(() => {
+            // F1: fetch failure never surfaces; state stays as-is (or unknown).
+        })
+            .finally(() => {
+            this.loading = null;
+        });
+    }
+}
+/** Normalization rule shared with policy writes (spec §5.1 M8). */
+export function normalizeAgentKey(key) {
+    return key.trim().toLowerCase();
+}
+//# sourceMappingURL=routing-policy-cache.js.map

package/dist/routing-policy-cache.js.map

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

package/dist/routing.d.ts

@@ -0,0 +1,156 @@
+/**
+ * SDK cascade routing module — `runWithPolicy()` (spec
+ * docs/roi-engine-cascade-sdk-phase1-spec.md §5, Phase 1 S2).
+ *
+ * Bring-your-own-caller: the customer supplies the function that calls their
+ * provider with THEIR keys; this module supplies policy consultation, the
+ * confidence gate, escalation, holdout randomization, and evidence emission.
+ *
+ * THE INVARIANT (throw-parity, §5.7): no code path in runWithPolicy throws an
+ * error that the customer's own `callModel(prodModel)` would not have thrown.
+ * Policy fetch, gate, candidate calls, and every emit fail OPEN; only the
+ * production-model call's own errors propagate.
+ *
+ * Streaming is OUT OF SCOPE for v1 (§5.1 H7): this contract handles complete
+ * responses only — keep streaming call sites on their original path.
+ */
+import type { MetrxbotClient } from './client';
+/** Bump with package.json (atomic-version rule). Server can force pass-through
+ * for known-bad versions via routing_policies.min_sdk_version (F10). */
+export declare const SDK_VERSION = "0.2.1";
+export interface ModelCallResult {
+    output: string;
+    costMicrocents?: number;
+    /** Server-side cost fallback via model_registry pricing when cost is absent. */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    raw?: unknown;
+}
+/**
+ * Call-context handed to the customer's `ModelCaller`/`checkerCaller` on every
+ * provider call (v0.2.1, additive). Lets caller-side instrumentation (a) stamp
+ * `requestId`/`experimentId`/`arm` on the provider call so cascade cost SUMs
+ * join across `llm_events ↔ optimization_decisions ↔ quality`, and (b) detect
+ * the background shadow candidate (`phase === 'shadow_candidate'`) and suppress
+ * it from a cost dashboard.
+ *
+ * `phase` marks which leg of routing is making the call:
+ *   - `primary`          served production call (pass-through, shadow served,
+ *                        cascade control arm)
+ *   - `candidate`        cascade treatment candidate (the cheaper model)
+ *   - `escalation`       cascade treatment fell back to the production model
+ *   - `shadow_candidate` background dual-call in shadow_sample (never served)
+ *   - `checker`          any `checkerCaller` invocation (gate + post-response judging)
+ */
+export interface ModelCallContext {
+    requestId: string;
+    experimentId?: string;
+    arm?: 'control' | 'treatment';
+    phase: 'primary' | 'candidate' | 'escalation' | 'shadow_candidate' | 'checker';
+}
+export interface ModelCaller {
+    /**
+     * `model === undefined` ⇒ "call your own default" — the day-0 pass-through
+     * contract (§5.1 M2). The input is passed through verbatim and is never
+     * serialized to Metrx.
+     *
+     * `ctx` (v0.2.1) is an OPTIONAL third argument — existing two-arg callers
+     * keep working unchanged. It is purely informational: it never changes what
+     * the router serves and passing it introduces no new throw path (§5.7).
+     */
+    (model: string | undefined, input: unknown, ctx?: ModelCallContext): Promise<ModelCallResult>;
+}
+export interface ClientJudge {
+    (args: {
+        input: unknown;
+        output: string;
+        model: string;
+    }): Promise<{
+        score: number;
+        judgeModel: string;
+    }>;
+}
+export interface RunWithPolicyOptions {
+    agentKey: string;
+    /** The customer's own provider call — their client, their keys. */
+    callModel: ModelCaller;
+    /**
+     * Caller for the cross-family checker model. REQUIRED for shadow/cascade
+     * when the checker family is one the primary caller can't reach (e.g. an
+     * all-Anthropic customer with a non-Anthropic checker — §5.3 C3).
+     */
+    checkerCaller?: ModelCaller;
+    input: unknown;
+    /** Optional custom scorer; default = the G4 checker via checkerCaller. */
+    judge?: ClientJudge;
+    requestId?: string;
+}
+export interface RunWithPolicyResult {
+    output: string;
+    /** undefined on no-policy pass-through (the customer's own default ran). */
+    servedModel: string | undefined;
+    escalated: boolean;
+    arm?: 'control' | 'treatment';
+    /** Cascade experiment id — attach to telemetry events (with the arm) so the
+     * contamination guard can exclude routed calls from baselines. */
+    experimentId?: string;
+    requestId: string;
+    /** What the policy said: pass_through | shadow_sample | cascade | disabled. */
+    mode: string;
+}
+export interface RouterConfig {
+    apiKey: string;
+    apiUrl: string;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    random?: () => number;
+    /** Hard local kill switch (F10); also honors METRX_ROUTING_DISABLED=true. */
+    disabled?: boolean;
+    policyTtlMs?: number;
+    policyStaleMaxMs?: number;
+}
+export declare class MetrxRouter {
+    private readonly cfg;
+    private readonly cache;
+    private readonly now;
+    private readonly random;
+    private readonly fetchImpl;
+    private readonly breakers;
+    private readonly background;
+    constructor(cfg: RouterConfig);
+    /** Await all in-flight background work (emits, shadow calls, judging).
+     * For tests and graceful shutdown — never required for correctness. */
+    flush(): Promise<void>;
+    run(opts: RunWithPolicyOptions): Promise<RunWithPolicyResult>;
+    private passThrough;
+    private runShadowSample;
+    private runCascade;
+    private judgeOutput;
+    private emitDecision;
+    private emitPair;
+    private emitQuality;
+    private fireAndForget;
+    /** F8/F9: background work never throws into the request path. */
+    private spawnBackground;
+    private breakerFor;
+    private breakerOpen;
+    private recordCandidateError;
+    private recordEscalation;
+    private makePolicyFetcher;
+}
+export declare function routerFor(client: MetrxbotClient, overrides?: Partial<RouterConfig>): MetrxRouter;
+/**
+ * Run one request under the agent's routing policy. Day 0 (no policy rows):
+ * behaves exactly like `opts.callModel(undefined, opts.input)`.
+ */
+export declare function runWithPolicy(client: MetrxbotClient, opts: RunWithPolicyOptions): Promise<RunWithPolicyResult>;
+/**
+ * Loose semver-ish comparison. Returns true when a < b, false when a >= b,
+ * and `undefined` when either side is unparseable — the caller treats
+ * "unknown" as pass-through (fail toward doing nothing).
+ */
+export declare function semverLt(a: string, b: string): boolean | undefined;
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAS/C;wEACwE;AACxE,eAAO,MAAM,WAAW,UAAU,CAAC;AAYnC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,kBAAkB,GAAG,SAAS,CAAC;CAChF;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/F;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACjE,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,WAAW,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B;sEACkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAUD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;gBAE9C,GAAG,EAAE,YAAY;IAa7B;2EACuE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,GAAG,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAuDrD,WAAW;YAoBX,eAAe;YAqEf,UAAU;YAsNV,WAAW;IAsCzB,OAAO,CAAC,YAAY;IAmCpB,OAAO,CAAC,QAAQ;IA6BhB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,aAAa;IAoBrB,iEAAiE;IACjE,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,iBAAiB;CAsB1B;AAMD,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,WAAW,CAQhG;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAE9B;AA6CD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAWlE"}