@sponsio/sdk 0.1.0-alpha.3 → 0.2.0-alpha.4

package/dist/core/formula.d.ts

@@ -4,7 +4,7 @@
  * Direct port of sponsio/formulas/formula.py.
  * Three families: Propositional, Temporal (LTL), Arithmetic.
  */
-export type Formula = Atom | Not | And | Or | Implies | G | F | X | U | Le | Lt | Ge | Gt | Eq | Var | Const;
+export type Formula = Atom | Not | And | Or | Implies | G | F | X | U | Le | Lt | Ge | Gt | Eq | Var | Const | ArgValue | CtxValue | UnaryFn | ArgLength;
 export declare class Atom {
     readonly predicate: string;
     readonly args: readonly string[];
@@ -68,36 +68,95 @@ export declare class Const {
     readonly kind: "Const";
     constructor(value: number);
 }
-export type ArithExpr = Var | Const;
+/**
+ * Read ``args[field]`` from the current event when it is a call to ``tool``.
+ *
+ * Returns ``undefined`` ("missing" signal) when the current event is a
+ * call to a different tool, or not a tool call, or args[field] absent.
+ * Pair with ``Implies(called(tool), ...)`` to scope the rule cleanly.
+ */
+export declare class ArgValue {
+    readonly tool: string;
+    readonly field: string;
+    readonly kind: "ArgValue";
+    constructor(tool: string, field: string);
+}
+/**
+ * Read a fact pushed via ``guard.observeContext({ key: value })``.
+ *
+ * Returns ``undefined`` when the key has never been pushed for this trace.
+ */
+export declare class CtxValue {
+    readonly key: string;
+    readonly kind: "CtxValue";
+    constructor(key: string);
+}
+/**
+ * Apply a JavaScript callable to another Term's value.
+ *
+ * Common cases:
+ *   new UnaryFn(s => String(s).toLowerCase(),
+ *               new ArgValue("send_email", "subject"))
+ *
+ * If the inner Term resolves to undefined, UnaryFn also returns undefined.
+ * If the callable throws, UnaryFn returns undefined rather than crashing.
+ *
+ * The ``name`` field is for debug repr only.
+ */
+export declare class UnaryFn {
+    readonly fn: (v: unknown) => unknown;
+    readonly arg: Term;
+    readonly name: string;
+    readonly kind: "UnaryFn";
+    constructor(fn: (v: unknown) => unknown, arg: Term, name?: string);
+}
+/**
+ * Convenience: ``args[field].length`` for the current event.
+ *
+ * Equivalent to ``new UnaryFn(v => (v as { length: number }).length,
+ * new ArgValue(tool, field))`` but exposed as its own class for clean
+ * repr and faster eval. Returns ``undefined`` when missing or not a
+ * .length-bearing value.
+ */
+export declare class ArgLength {
+    readonly tool: string;
+    readonly field: string;
+    readonly kind: "ArgLength";
+    constructor(tool: string, field: string);
+}
+/** A Term is anything that resolves to a value at evaluation time. */
+export type Term = Var | Const | ArgValue | CtxValue | UnaryFn | ArgLength;
+/** Backward-compatible alias. */
+export type ArithExpr = Term;
 export declare class Le {
-    readonly left: ArithExpr;
-    readonly right: ArithExpr;
+    readonly left: Term;
+    readonly right: Term;
     readonly kind: "Le";
-    constructor(left: ArithExpr, right: ArithExpr);
+    constructor(left: Term, right: Term);
 }
 export declare class Lt {
-    readonly left: ArithExpr;
-    readonly right: ArithExpr;
+    readonly left: Term;
+    readonly right: Term;
     readonly kind: "Lt";
-    constructor(left: ArithExpr, right: ArithExpr);
+    constructor(left: Term, right: Term);
 }
 export declare class Ge {
-    readonly left: ArithExpr;
-    readonly right: ArithExpr;
+    readonly left: Term;
+    readonly right: Term;
     readonly kind: "Ge";
-    constructor(left: ArithExpr, right: ArithExpr);
+    constructor(left: Term, right: Term);
 }
 export declare class Gt {
-    readonly left: ArithExpr;
-    readonly right: ArithExpr;
+    readonly left: Term;
+    readonly right: Term;
     readonly kind: "Gt";
-    constructor(left: ArithExpr, right: ArithExpr);
+    constructor(left: Term, right: Term);
 }
 export declare class Eq {
-    readonly left: ArithExpr;
-    readonly right: ArithExpr;
+    readonly left: Term;
+    readonly right: Term;
     readonly kind: "Eq";
-    constructor(left: ArithExpr, right: ArithExpr);
+    constructor(left: Term, right: Term);
 }
 export declare function predKey(predicate: string, ...args: string[]): string;
 //# sourceMappingURL=formula.d.ts.map

package/dist/core/formula.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../../src/core/formula.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../../src/core/formula.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,MAAM,MAAM,OAAO,GACf,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,GAAG,OAAO,GAC/B,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GACb,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GACtB,GAAG,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAI5D,qBAAa,IAAI;IAGb,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE;IAHlC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAErB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,SAAS,MAAM,EAAO;IAGvC,GAAG,IAAI,MAAM;CAGd;AAED,qBAAa,GAAG;IAEF,QAAQ,CAAC,KAAK,EAAE,OAAO;IADnC,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;gBACV,KAAK,EAAE,OAAO;CACpC;AAED,qBAAa,GAAG;IAEF,QAAQ,CAAC,IAAI,EAAE,OAAO;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO;IAD3D,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;gBACV,IAAI,EAAE,OAAO,EAAW,KAAK,EAAE,OAAO;CAC5D;AAED,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,OAAO;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO;IAD3D,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,OAAO,EAAW,KAAK,EAAE,OAAO;CAC5D;AAED,qBAAa,OAAO;IAEN,QAAQ,CAAC,IAAI,EAAE,OAAO;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO;IAD3D,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;gBACd,IAAI,EAAE,OAAO,EAAW,KAAK,EAAE,OAAO;CAC5D;AAID,qBAAa,CAAC;IAEA,QAAQ,CAAC,KAAK,EAAE,OAAO;IADnC,QAAQ,CAAC,IAAI,EAAG,GAAG,CAAU;gBACR,KAAK,EAAE,OAAO;CACpC;AAED,qBAAa,CAAC;IAEA,QAAQ,CAAC,KAAK,EAAE,OAAO;IADnC,QAAQ,CAAC,IAAI,EAAG,GAAG,CAAU;gBACR,KAAK,EAAE,OAAO;CACpC;AAED,qBAAa,CAAC;IAEA,QAAQ,CAAC,KAAK,EAAE,OAAO;IADnC,QAAQ,CAAC,IAAI,EAAG,GAAG,CAAU;gBACR,KAAK,EAAE,OAAO;CACpC;AAED,qBAAa,CAAC;IAEA,QAAQ,CAAC,IAAI,EAAE,OAAO;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO;IAD3D,QAAQ,CAAC,IAAI,EAAG,GAAG,CAAU;gBACR,IAAI,EAAE,OAAO,EAAW,KAAK,EAAE,OAAO;CAC5D;AAkBD,qBAAa,GAAG;IAGF,QAAQ,CAAC,IAAI,EAAE,MAAM;IAFjC,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;gBACZ,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE;IAGpD,GAAG,IAAI,MAAM;CAMd;AAED,qBAAa,KAAK;IAEJ,QAAQ,CAAC,KAAK,EAAE,MAAM;IADlC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;gBACZ,KAAK,EAAE,MAAM;CACnC;AAED;;;;;;GAMG;AACH,qBAAa,QAAQ;IAEP,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM;IADzD,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBACf,IAAI,EAAE,MAAM,EAAW,KAAK,EAAE,MAAM;CAC1D;AAED;;;;GAIG;AACH,qBAAa,QAAQ;IAEP,QAAQ,CAAC,GAAG,EAAE,MAAM;IADhC,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBACf,GAAG,EAAE,MAAM;CACjC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,OAAO;IAGhB,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO;IACpC,QAAQ,CAAC,GAAG,EAAE,IAAI;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAJvB,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAU;gBAExB,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,EAC3B,GAAG,EAAE,IAAI,EACT,IAAI,GAAE,MAAa;CAE/B;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;IAER,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM;IADzD,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;gBAChB,IAAI,EAAE,MAAM,EAAW,KAAK,EAAE,MAAM;CAC1D;AAED,sEAAsE;AACtE,MAAM,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3E,iCAAiC;AACjC,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC;AAE7B,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI;IADrD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,IAAI,EAAW,KAAK,EAAE,IAAI;CACtD;AAED,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI;IADrD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,IAAI,EAAW,KAAK,EAAE,IAAI;CACtD;AAED,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI;IADrD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,IAAI,EAAW,KAAK,EAAE,IAAI;CACtD;AAED,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI;IADrD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,IAAI,EAAW,KAAK,EAAE,IAAI;CACtD;AAED,qBAAa,EAAE;IAED,QAAQ,CAAC,IAAI,EAAE,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI;IADrD,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;gBACT,IAAI,EAAE,IAAI,EAAW,KAAK,EAAE,IAAI;CACtD;AAaD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAGpE"}

package/dist/core/formula.js

@@ -82,7 +82,21 @@ export class U {
         this.right = right;
     }
 }
-// --- Arithmetic ---
+// --- Arithmetic / Term abstraction ---
+//
+// Comparison nodes (Eq, Le, Lt, Ge, Gt) accept any ``Term`` on either
+// side. A Term is anything that knows how to evaluate(state) -> value;
+// the evaluator dispatches on `kind`. This lets contract authors
+// compose runtime-bound values (``new ArgValue("issue_refund",
+// "amount")``) against constants (``new Const(50)``) or against other
+// runtime values (``new CtxValue("approved_amount")``) in the same
+// comparison.
+//
+// Returning ``undefined`` from evaluation is the canonical "missing"
+// signal: comparison evaluation treats either operand being missing as
+// false (the comparison cannot decide). Wrap fragile comparisons in
+// ``Implies(scopePredicate, comparison)`` to suppress them where the
+// relevant arg is not applicable.
 export class Var {
     name;
     kind = "Var";
@@ -105,6 +119,74 @@ export class Const {
         this.value = value;
     }
 }
+/**
+ * Read ``args[field]`` from the current event when it is a call to ``tool``.
+ *
+ * Returns ``undefined`` ("missing" signal) when the current event is a
+ * call to a different tool, or not a tool call, or args[field] absent.
+ * Pair with ``Implies(called(tool), ...)`` to scope the rule cleanly.
+ */
+export class ArgValue {
+    tool;
+    field;
+    kind = "ArgValue";
+    constructor(tool, field) {
+        this.tool = tool;
+        this.field = field;
+    }
+}
+/**
+ * Read a fact pushed via ``guard.observeContext({ key: value })``.
+ *
+ * Returns ``undefined`` when the key has never been pushed for this trace.
+ */
+export class CtxValue {
+    key;
+    kind = "CtxValue";
+    constructor(key) {
+        this.key = key;
+    }
+}
+/**
+ * Apply a JavaScript callable to another Term's value.
+ *
+ * Common cases:
+ *   new UnaryFn(s => String(s).toLowerCase(),
+ *               new ArgValue("send_email", "subject"))
+ *
+ * If the inner Term resolves to undefined, UnaryFn also returns undefined.
+ * If the callable throws, UnaryFn returns undefined rather than crashing.
+ *
+ * The ``name`` field is for debug repr only.
+ */
+export class UnaryFn {
+    fn;
+    arg;
+    name;
+    kind = "UnaryFn";
+    constructor(fn, arg, name = "fn") {
+        this.fn = fn;
+        this.arg = arg;
+        this.name = name;
+    }
+}
+/**
+ * Convenience: ``args[field].length`` for the current event.
+ *
+ * Equivalent to ``new UnaryFn(v => (v as { length: number }).length,
+ * new ArgValue(tool, field))`` but exposed as its own class for clean
+ * repr and faster eval. Returns ``undefined`` when missing or not a
+ * .length-bearing value.
+ */
+export class ArgLength {
+    tool;
+    field;
+    kind = "ArgLength";
+    constructor(tool, field) {
+        this.tool = tool;
+        this.field = field;
+    }
+}
 export class Le {
     left;
     right;

package/dist/core/formula.js.map

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

package/dist/core/grounding.d.ts

@@ -1,5 +1,5 @@
 /**
- * Grounding: convert tool-call events into per-timestep predicate valuations.
+ * Grounding: convert events into per-timestep predicate valuations.
  *
  * Port of sponsio/tracer/grounding.py (Det-relevant atoms).
  *
@@ -16,11 +16,28 @@
  *   arg_paths_within(tool, *prefixes)  — all paths in args within prefix set
  *   token_count(type)                  — cumulative tokens (from event.args.tokens)
  *   delegation_depth                   — depth of agent-to-agent delegation
+ *   ctx(key, value)                    — external fact pushed via observe_context
+ *   ctx_matches(key, pattern)          — current ctx[key] matches regex
+ *   llm_said(pattern)                  — llm_response content matches regex
+ *   response_words / response_chars    — response length on llm_response
+ *   time_since(predicate_key)          — event-clock delta since predicate last True
  */
 import type { Formula } from "./formula.js";
+/**
+ * Public event shape consumed by the grounding kernel. ``tool`` is
+ * required for the dominant ``tool_call`` path; the optional fields
+ * cover ``llm_response`` (response-length / regex content checks) and
+ * ``context_update`` (external-fact ``ctx`` atoms).
+ */
 export interface ToolEvent {
     tool: string;
     args?: Record<string, unknown>;
+    /** ``"tool_call"`` (default) | ``"llm_response"`` | ``"context_update"`` | ``"delegation"``. */
+    event_type?: string;
+    /** Free-form text — only consumed for ``llm_response`` events (regex matching, length). */
+    content?: string;
+    /** Optional event timestamp; if omitted, the grounding state's monotonic clock advances by 1. */
+    ts?: number;
 }
 export interface GroundingState {
     callCounts: Record<string, number>;
@@ -29,6 +46,28 @@ export interface GroundingState {
     consecutiveCounts: Record<string, number>;
     tokenCounts: Record<string, number>;
     delegationDepth: number;
+    /**
+     * External facts pushed by the integration via ``observeContext``.
+     * Persists across events; re-emitted as ``ctx(k, v)`` atoms each
+     * timestep so ``G(called(x) → ctx(k, v))`` fires as expected.
+     */
+    currentCtx: Record<string, string>;
+    /**
+     * Event clock — advances by 1 per event when no explicit ``ts`` is
+     * supplied. Used as the numerator for ``time_since(key)`` and
+     * accessible to formulas via ``Var("now")``.
+     */
+    now: number;
+    /**
+     * Per-predicate-key timestamp of the most recent False→True
+     * transition. Re-emissions of a sustained predicate (forward-
+     * propagated ``flow``/``contains``, ``ctx`` atoms held in scope)
+     * do NOT refresh this — that's what makes ``time_since(approval)``
+     * measure "since granted" rather than "since last re-emit".
+     */
+    lastTs: Record<string, number>;
+    /** Predicates that were True at the previous event (post-emission). */
+    trueAtPrev: Set<string>;
 }
 export declare function newGroundingState(): GroundingState;
 /**
@@ -37,7 +76,15 @@ export declare function newGroundingState(): GroundingState;
  */
 export declare function collectContentAtoms(formulas: Formula[]): Record<string, Set<string>>;
 /**
- * Ground a single tool-call event into a predicate valuation dict.
+ * Ground a single event into a predicate valuation dict.
+ *
+ * Routes by ``event.event_type``:
+ *   - ``tool_call`` (default) — emits the full tool-call atom set
+ *   - ``llm_response`` — emits ``llm_said(pattern)`` + length atoms
+ *   - ``context_update`` — merges ``event.args`` into ``state.currentCtx``
+ *
+ * Ctx atoms (``ctx(k, v)``), accumulator snapshots, and ``time_since``
+ * fire on every event regardless of type (matching Python parity).
  */
-export declare function groundEvent(event: ToolEvent, state: GroundingState, contentAtoms?: Record<string, Set<string>>): Record<string, boolean | number>;
+export declare function groundEvent(event: ToolEvent, state: GroundingState, contentAtoms?: Record<string, Set<string>>): Record<string, unknown>;
 //# sourceMappingURL=grounding.d.ts.map

package/dist/core/grounding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/core/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AAE9E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CASlD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAgC7B;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,cAAc,EACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CA6MlC"}
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/core/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,uEAAuE;IACvE,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAalD;AAmCD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA0B7B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,cAAc,EACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6UzB"}