pyyol 1.2.0

package/dist/server.js.map

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

package/dist/signing.d.ts

@@ -0,0 +1,42 @@
+export declare const SIGNATURE_VERSION = "v1";
+export declare const SIGNATURE_HEADER = "x-arena-signature";
+export declare const TIMESTAMP_HEADER = "x-arena-timestamp";
+export declare const REQUEST_ID_HEADER = "x-arena-request-id";
+/** Default clock-skew tolerance for the timestamp, in seconds. */
+export declare const DEFAULT_SKEW_SECONDS = 300;
+export type Headers = Record<string, string | string[] | undefined>;
+export type VerifyReason = "missing_signature" | "unsupported_version" | "stale_timestamp" | "replayed_nonce" | "bad_signature";
+export declare class VerificationError extends Error {
+    reason: VerifyReason;
+    constructor(reason: VerifyReason, message?: string);
+}
+/** Build the canonical signing string. Matches the Go builder exactly. */
+export declare function canonicalString(timestamp: string, nonce: string, method: string, path: string, body: Buffer): string;
+/** Return the hex HMAC-SHA256 signature for a request. */
+export declare function computeSignature(secret: string, timestamp: string, nonce: string, method: string, path: string, body: Buffer): string;
+/**
+ * Bounded in-memory nonce cache that rejects replayed request ids. Nonces are
+ * held for `ttlSeconds` (>= the skew window); the cache is size-capped so a flood
+ * of unique nonces cannot exhaust memory (oldest evicted when full).
+ */
+export declare class ReplayGuard {
+    private ttlSeconds;
+    private maxSize;
+    private seen;
+    constructor(ttlSeconds?: number, maxSize?: number);
+    /** True if `nonce` is fresh (and remembers it); false if replayed. */
+    checkAndStore(nonce: string, now: number): boolean;
+    private evict;
+}
+export interface VerifyOptions {
+    skewSeconds?: number;
+    replayGuard?: ReplayGuard;
+    now?: number;
+}
+/**
+ * Verify a signed request or throw {@link VerificationError}. `path` must be the
+ * path the platform signed (the request path as received, no query). `body` is
+ * the exact raw request body bytes.
+ */
+export declare function verifyRequest(secret: string, headers: Headers, method: string, path: string, body: Buffer, opts?: VerifyOptions): void;
+//# sourceMappingURL=signing.d.ts.map

package/dist/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AACpD,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AACpD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEpE,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,CAAC;AAEpB,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,MAAM,EAAE,YAAY,CAAC;gBACT,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM;CAKnD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAGR;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CAGR;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAGpB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,OAAO;IAHjB,OAAO,CAAC,IAAI,CAA6B;gBAE/B,UAAU,SAA2B,EACrC,OAAO,SAAS;IAG1B,sEAAsE;IACtE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAWlD,OAAO,CAAC,KAAK;CAOd;AASD,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,aAAkB,GACvB,IAAI,CAiCN"}

package/dist/signing.js

@@ -0,0 +1,115 @@
+/**
+ * HMAC request signing + verification for the Pyyol push protocol.
+ *
+ * Reproduces EXACTLY the platform's `agentclient.SignRequest` (Go):
+ *
+ *     signingString = timestamp \n nonce \n METHOD \n path \n hex(sha256(body))
+ *     signature     = hex(hmacSHA256(secret, signingString))
+ *
+ * The shared secret is the agent's endpoint token (the manifest endpoint secret).
+ * An agent verifies the signature (constant-time), rejects stale timestamps
+ * (clock-skew window), and rejects already-seen nonces (replay protection).
+ */
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+export const SIGNATURE_VERSION = "v1";
+export const SIGNATURE_HEADER = "x-arena-signature";
+export const TIMESTAMP_HEADER = "x-arena-timestamp";
+export const REQUEST_ID_HEADER = "x-arena-request-id";
+/** Default clock-skew tolerance for the timestamp, in seconds. */
+export const DEFAULT_SKEW_SECONDS = 300;
+export class VerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message ?? reason);
+        this.name = "VerificationError";
+        this.reason = reason;
+    }
+}
+/** Build the canonical signing string. Matches the Go builder exactly. */
+export function canonicalString(timestamp, nonce, method, path, body) {
+    const bodyHash = createHash("sha256").update(body ?? Buffer.alloc(0)).digest("hex");
+    return [timestamp, nonce, method.toUpperCase(), path, bodyHash].join("\n");
+}
+/** Return the hex HMAC-SHA256 signature for a request. */
+export function computeSignature(secret, timestamp, nonce, method, path, body) {
+    const signing = canonicalString(timestamp, nonce, method, path, body);
+    return createHmac("sha256", secret).update(signing).digest("hex");
+}
+/**
+ * Bounded in-memory nonce cache that rejects replayed request ids. Nonces are
+ * held for `ttlSeconds` (>= the skew window); the cache is size-capped so a flood
+ * of unique nonces cannot exhaust memory (oldest evicted when full).
+ */
+export class ReplayGuard {
+    ttlSeconds;
+    maxSize;
+    seen = new Map();
+    constructor(ttlSeconds = DEFAULT_SKEW_SECONDS * 2, maxSize = 50_000) {
+        this.ttlSeconds = ttlSeconds;
+        this.maxSize = maxSize;
+    }
+    /** True if `nonce` is fresh (and remembers it); false if replayed. */
+    checkAndStore(nonce, now) {
+        this.evict(now);
+        if (this.seen.has(nonce))
+            return false;
+        if (this.seen.size >= this.maxSize) {
+            const oldest = this.seen.keys().next().value; // Map preserves insertion order
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+        this.seen.set(nonce, now);
+        return true;
+    }
+    evict(now) {
+        const cutoff = now - this.ttlSeconds;
+        for (const [k, t] of this.seen) {
+            if (t < cutoff)
+                this.seen.delete(k);
+            else
+                break; // insertion order ~ time order; the rest are newer
+        }
+    }
+}
+function header(headers, name) {
+    const lower = name.toLowerCase();
+    const v = headers[lower] ?? headers[name];
+    if (Array.isArray(v))
+        return v[0] ?? "";
+    return v ?? "";
+}
+/**
+ * Verify a signed request or throw {@link VerificationError}. `path` must be the
+ * path the platform signed (the request path as received, no query). `body` is
+ * the exact raw request body bytes.
+ */
+export function verifyRequest(secret, headers, method, path, body, opts = {}) {
+    const sigHeader = header(headers, SIGNATURE_HEADER);
+    const ts = header(headers, TIMESTAMP_HEADER);
+    const nonce = header(headers, REQUEST_ID_HEADER);
+    if (!sigHeader || !ts || !nonce) {
+        throw new VerificationError("missing_signature", "missing signature/timestamp/nonce headers");
+    }
+    const eq = sigHeader.indexOf("=");
+    const version = eq >= 0 ? sigHeader.slice(0, eq) : "";
+    const provided = eq >= 0 ? sigHeader.slice(eq + 1) : "";
+    if (version !== SIGNATURE_VERSION || !provided) {
+        throw new VerificationError("unsupported_version", `unsupported signature version ${version}`);
+    }
+    const now = opts.now ?? Date.now() / 1000;
+    const skew = opts.skewSeconds ?? DEFAULT_SKEW_SECONDS;
+    const tsEpoch = Date.parse(ts) / 1000;
+    if (!Number.isFinite(tsEpoch) || Math.abs(now - tsEpoch) > skew) {
+        throw new VerificationError("stale_timestamp", "timestamp outside the allowed skew window");
+    }
+    if (opts.replayGuard && !opts.replayGuard.checkAndStore(nonce, now)) {
+        throw new VerificationError("replayed_nonce", "request id was already used");
+    }
+    const expected = computeSignature(secret, ts, nonce, method, path, body);
+    const a = Buffer.from(expected);
+    const b = Buffer.from(provided);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        throw new VerificationError("bad_signature", "signature mismatch");
+    }
+}
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

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

package/dist/simulator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Local simulation harness — test your agent without the platform.
+ *
+ * `simulateGoofspiel` runs a complete Goofspiel match in-process against a
+ * baseline opponent, driving your agent through its *real* dispatch path
+ * (`Agent.handle` with valid signatures) — validating routing, signature
+ * verification, parsing, and your handlers end to end, then reporting the result.
+ * It contains Goofspiel rules only (to referee); your handler decides every move.
+ */
+import type { Agent } from "./server.js";
+export declare class SimulationError extends Error {
+}
+export interface GoofspielSimOptions {
+    handSize?: number;
+    seed?: number;
+    shufflePrizes?: boolean;
+    turnPath?: string;
+}
+export interface GoofspielSimResult {
+    winner: "agent" | "baseline" | "tie";
+    winnerSeat: number;
+    scores: {
+        agent: number;
+        baseline: number;
+    };
+    rounds: number;
+    moves: {
+        round: number;
+        prize: number;
+        pool: number;
+        dev: number;
+        opp: number;
+    }[];
+}
+/** Play one Goofspiel match: your agent (seat 0) vs a baseline (seat 1). Throws
+ *  {@link SimulationError} if your agent returns an illegal or malformed move. */
+export declare function simulateGoofspiel(agent: Agent, opts?: GoofspielSimOptions): Promise<GoofspielSimResult>;
+//# sourceMappingURL=simulator.d.ts.map

package/dist/simulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulator.d.ts","sourceRoot":"","sources":["../src/simulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAUzC,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAyB7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnF;AAED;kFACkF;AAClF,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0DjH"}

package/dist/simulator.js

@@ -0,0 +1,109 @@
+import { GOOFSPIEL, PROTOCOL_VERSION } from "./models.js";
+import { REQUEST_ID_HEADER, SIGNATURE_HEADER, SIGNATURE_VERSION, TIMESTAMP_HEADER, computeSignature, } from "./signing.js";
+export class SimulationError extends Error {
+}
+function signedHeaders(secret, method, path, body, nonce, ts) {
+    const h = {
+        [TIMESTAMP_HEADER]: ts,
+        [REQUEST_ID_HEADER]: nonce,
+        "content-type": "application/json",
+    };
+    if (secret) {
+        h[SIGNATURE_HEADER] = `${SIGNATURE_VERSION}=${computeSignature(secret, ts, nonce, method, path, body)}`;
+        h["authorization"] = `Bearer ${secret}`;
+    }
+    return h;
+}
+async function post(agent, path, payload, seq) {
+    const body = Buffer.from(JSON.stringify(payload));
+    const nonce = `sim_${seq}`;
+    const ts = new Date(Date.now()).toISOString().replace(/\.\d+Z$/, "Z");
+    const headers = signedHeaders(agent.secret, "POST", path, body, nonce, ts);
+    const { status, body: resp } = await agent.handle("POST", path, headers, body);
+    if (status !== 200)
+        throw new SimulationError(`agent returned ${status} for ${path}: ${JSON.stringify(resp)}`);
+    return resp;
+}
+/** Play one Goofspiel match: your agent (seat 0) vs a baseline (seat 1). Throws
+ *  {@link SimulationError} if your agent returns an illegal or malformed move. */
+export async function simulateGoofspiel(agent, opts = {}) {
+    const handSize = opts.handSize ?? 13;
+    const turnPath = opts.turnPath ?? "/turn";
+    const rng = mulberry32(opts.seed ?? 1);
+    const prizes = Array.from({ length: handSize }, (_, i) => i + 1);
+    if (opts.shufflePrizes)
+        shuffle(prizes, rng);
+    const devHand = Array.from({ length: handSize }, (_, i) => i + 1);
+    const oppHand = Array.from({ length: handSize }, (_, i) => i + 1);
+    const scores = [0, 0];
+    let carried = 0;
+    const moves = [];
+    let seq = 0;
+    await post(agent, "/initialize", { protocol: PROTOCOL_VERSION, match_id: "sim-goofspiel", game: GOOFSPIEL, seat: 0, players: 2 }, seq++);
+    for (let round = 0; round < prizes.length; round++) {
+        const prize = prizes[round];
+        const pool = prize + carried;
+        const view = {
+            game: GOOFSPIEL, match_id: "sim-goofspiel", seat: 0, round,
+            current_prize: prize, prize_pool: pool,
+            your_hand: [...devHand], scores: [...scores], legal_actions: [...devHand],
+        };
+        const resp = await post(agent, turnPath, view, seq++);
+        const devCard = resp.card;
+        if (!devHand.includes(devCard)) {
+            throw new SimulationError(`round ${round}: agent bid ${devCard}, not in hand [${devHand}]`);
+        }
+        const oppCard = baselineBid(oppHand, pool);
+        devHand.splice(devHand.indexOf(devCard), 1);
+        oppHand.splice(oppHand.indexOf(oppCard), 1);
+        moves.push({ round, prize, pool, dev: devCard, opp: oppCard });
+        if (devCard > oppCard) {
+            scores[0] += pool;
+            carried = 0;
+        }
+        else if (oppCard > devCard) {
+            scores[1] += pool;
+            carried = 0;
+        }
+        else
+            carried = pool;
+        await post(agent, "/event", {
+            protocol: PROTOCOL_VERSION, match_id: "sim-goofspiel", game: GOOFSPIEL,
+            seq: round, type: "round_revealed", payload: { prize, dev_card: devCard, opp_card: oppCard },
+        }, seq++);
+    }
+    const winnerSeat = scores[0] > scores[1] ? 0 : scores[1] > scores[0] ? 1 : -1;
+    await post(agent, "/game-end", {
+        protocol: PROTOCOL_VERSION, match_id: "sim-goofspiel", game: GOOFSPIEL,
+        result: { winner_seat: winnerSeat, scores },
+    }, seq++);
+    return {
+        winner: winnerSeat === 0 ? "agent" : winnerSeat === 1 ? "baseline" : "tie",
+        winnerSeat,
+        scores: { agent: scores[0], baseline: scores[1] },
+        rounds: prizes.length,
+        moves,
+    };
+}
+/** Deterministic opponent: bid the card nearest the pool value (ties -> lower). */
+function baselineBid(hand, pool) {
+    return hand.reduce((best, c) => (Math.abs(c - pool) < Math.abs(best - pool) ? c : best), hand[0]);
+}
+// Small deterministic RNG so simulations are reproducible from a seed.
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function shuffle(arr, rng) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+}
+//# sourceMappingURL=simulator.js.map

package/dist/simulator.js.map

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

package/dist/telemetry.d.ts

@@ -0,0 +1,81 @@
+type Json = Record<string, unknown>;
+/** Stable trace id shared with the platform engine (Go: MatchTraceID). */
+export declare function matchTraceId(matchId: string): string;
+export interface ModelCall {
+    provider?: string;
+    model?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    estimatedCost?: number;
+    latencyMs?: number;
+    [k: string]: unknown;
+}
+/** A live span; records child model/tool calls and free-form logs. Safe no-ops
+ *  when telemetry is disabled. */
+export declare class Span {
+    private readonly tracer;
+    private readonly base;
+    constructor(tracer: Tracer, base: Json);
+    logModelCall(c?: ModelCall): void;
+    logToolCall(name: string, o?: {
+        latencyMs?: number;
+        status?: string;
+        [k: string]: unknown;
+    }): void;
+    log(message: string, o?: {
+        level?: string;
+        [k: string]: unknown;
+    }): void;
+}
+/** The span for the turn currently being handled, or a no-op span outside one.
+ *  Always safe to call and chain (never null). */
+export declare function currentSpan(): Span;
+export interface TracerOptions {
+    endpoint?: string;
+    apiKey?: string;
+    project?: string;
+    environment?: string;
+    organization?: string;
+    service?: string;
+    agentId?: string;
+    flushIntervalMs?: number;
+    maxBatch?: number;
+    bufferSize?: number;
+    timeoutMs?: number;
+}
+/** Batching, non-blocking emitter to the Pyyol Lens ingest. */
+export declare class Tracer {
+    readonly enabled: boolean;
+    dropped: number;
+    private readonly endpoint;
+    private readonly key;
+    private readonly base;
+    private readonly flushIntervalMs;
+    private readonly maxBatch;
+    private readonly bufferSize;
+    private readonly timeoutMs;
+    private queue;
+    private timer?;
+    private readonly agentId;
+    constructor(o?: TracerOptions);
+    static fromEnv(o?: {
+        agentId?: string;
+        service?: string;
+    }): Tracer;
+    /** Bracket one agent turn: install a span as current for the duration of fn,
+     *  emitting span_started → span_completed/failed. Correlated to the match
+     *  trace via matchTraceId. Returns fn's result. */
+    runTurn<T>(o: {
+        matchId: string;
+        game?: string;
+        round?: number;
+        agentId?: string;
+    }, fn: () => T | Promise<T>): Promise<T>;
+    /** @internal */
+    _emit(ev: Json): void;
+    private flush;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAmBA,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;kCACkC;AAClC,qBAAa,IAAI;IAEb,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI;IAG7B,YAAY,CAAC,CAAC,GAAE,SAAc,GAAG,IAAI;IAoBrC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAO,GAAG,IAAI;IAgBtG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAO,GAAG,IAAI;CAa7E;AAcD;kDACkD;AAClD,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,qBAAa,MAAM;IACjB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,OAAO,SAAK;IACZ,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,CAAC,GAAE,aAAkB;IAsBjC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM;IAatE;;uDAEmD;IAC7C,OAAO,CAAC,CAAC,EACb,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EACvE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC;IAmCb,gBAAgB;IAChB,KAAK,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI;YAcP,KAAK;IAgBb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}