@evelinka-ai/core 0.1.6 → 0.3.0

package/dist/lib/budgets/prepaid-call.js

@@ -0,0 +1,32 @@
+function nonnegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+export async function executePrepaidCall(call, ledger, dispatch) {
+    if (!call.sessionId ||
+        !call.operationId ||
+        !call.provider ||
+        !call.model ||
+        !call.priceVersion ||
+        !nonnegativeInteger(call.maxChargeMicroUsd) ||
+        call.maxChargeMicroUsd === 0) {
+        throw new Error("PREPAID_INVALID_QUOTE");
+    }
+    const reservation = await ledger.reserve(call);
+    if (reservation.replay || reservation.state !== "reserved") {
+        throw new Error("PREPAID_OPERATION_ALREADY_DISPATCHED_OR_UNAVAILABLE");
+    }
+    const { result, receipt } = await dispatch();
+    if (receipt.costKind !== "actual" ||
+        !nonnegativeInteger(receipt.providerCostMicroUsd) ||
+        ![
+            receipt.usage.inputTokens,
+            receipt.usage.outputTokens,
+            receipt.usage.cacheReadTokens,
+            receipt.usage.cacheWriteTokens,
+        ].every(nonnegativeInteger)) {
+        throw new Error("PREPAID_INVALID_PROVIDER_RECEIPT");
+    }
+    await ledger.settle(call, receipt);
+    return result;
+}
+//# sourceMappingURL=prepaid-call.js.map

package/dist/lib/budgets/prepaid-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepaid-call.js","sourceRoot":"","sources":["../../../src/lib/budgets/prepaid-call.ts"],"names":[],"mappings":"AAgDA,SAAS,kBAAkB,CAAC,KAAa;IACvC,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAiB,EACjB,MAAqB,EAGrB,QAAgE;IAEhE,IACE,CAAC,IAAI,CAAC,SAAS;QACf,CAAC,IAAI,CAAC,WAAW;QACjB,CAAC,IAAI,CAAC,QAAQ;QACd,CAAC,IAAI,CAAC,KAAK;QACX,CAAC,IAAI,CAAC,YAAY;QAClB,CAAC,kBAAkB,CAAC,IAAI,CAAC,iBAAiB,CAAC;QAC3C,IAAI,CAAC,iBAAiB,KAAK,CAAC,EAC5B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAGD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC7C,IACE,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAC7B,CAAC,kBAAkB,CAAC,OAAO,CAAC,oBAAoB,CAAC;QACjD,CAAC;YACC,OAAO,CAAC,KAAK,CAAC,WAAW;YACzB,OAAO,CAAC,KAAK,CAAC,YAAY;YAC1B,OAAO,CAAC,KAAK,CAAC,eAAe;YAC7B,OAAO,CAAC,KAAK,CAAC,gBAAgB;SAC/B,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAC3B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib/budgets/prepaid-response-store.d.ts

@@ -0,0 +1,17 @@
+import type { PrepaidCall, ProviderReceipt } from "./prepaid-call.js";
+export interface CompletedProviderCall {
+    call: PrepaidCall;
+    receipt: ProviderReceipt;
+    body: string;
+    contentType: string;
+}
+export declare class PrepaidResponseStore {
+    private readonly directory;
+    constructor(directory: string);
+    ready(): void;
+    private path;
+    prepare(call: PrepaidCall, requestHash: string): PrepaidCall;
+    read(id: string): CompletedProviderCall | undefined;
+    write(value: CompletedProviderCall): void;
+}
+//# sourceMappingURL=prepaid-response-store.d.ts.map

package/dist/lib/budgets/prepaid-response-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepaid-response-store.d.ts","sourceRoot":"","sources":["../../../src/lib/budgets/prepaid-response-store.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAKD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM;IAC9C,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW;IA+B5D,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAcnD,KAAK,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;CAmB1C"}

package/dist/lib/budgets/prepaid-response-store.js

@@ -0,0 +1,85 @@
+import { accessSync, constants, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+export class PrepaidResponseStore {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    ready() {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        accessSync(this.directory, constants.W_OK);
+    }
+    path(id) {
+        if (!/^[a-f0-9]{64}$/.test(id))
+            throw new Error("PREPAID_INVALID_OPERATION_ID");
+        return join(this.directory, `${id}.json`);
+    }
+    prepare(call, requestHash) {
+        this.ready();
+        const path = `${this.path(call.operationId)}.intent`;
+        if (!/^[a-f0-9]{64}$/.test(requestHash))
+            throw new Error("PREPAID_INVALID_REQUEST_HASH");
+        let fd;
+        try {
+            fd = openSync(path, "wx", 0o600);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const saved = JSON.parse(readFileSync(path, "utf8"));
+            if (saved.call?.operationId !== call.operationId || saved.requestHash !== requestHash)
+                throw new Error("PREPAID_INVOCATION_PAYLOAD_CHANGED");
+            return saved.call;
+        }
+        try {
+            writeFileSync(fd, JSON.stringify({ call, requestHash }));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const directoryFd = openSync(this.directory, "r");
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+        return call;
+    }
+    read(id) {
+        const path = this.path(id);
+        if (!existsSync(path))
+            return undefined;
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (value.call?.operationId !== id ||
+            typeof value.body !== "string" ||
+            value.receipt?.costKind !== "actual" ||
+            typeof value.contentType !== "string") {
+            throw new Error("PREPAID_CORRUPT_RESPONSE");
+        }
+        return value;
+    }
+    write(value) {
+        this.ready();
+        const path = this.path(value.call.operationId);
+        const temporary = `${path}.${process.pid}.tmp`;
+        const fd = openSync(temporary, "w", 0o600);
+        try {
+            writeFileSync(fd, JSON.stringify(value));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+        const directoryFd = openSync(this.directory, "r");
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+    }
+}
+//# sourceMappingURL=prepaid-response-store.js.map

package/dist/lib/budgets/prepaid-response-store.js.map

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

package/dist/lib/coordination/checkpoints.d.ts

@@ -0,0 +1,33 @@
+import { type PgDeps, type QueryPool } from "./pg.js";
+export type CheckpointPool = QueryPool;
+export interface CheckpointDeps extends PgDeps {
+    now?: () => number;
+}
+export declare const CHECKPOINT_TTL_MS: number;
+export type CheckpointRun<K> = K & {
+    head: string;
+    runId: string;
+    scope: string;
+};
+export type Checkpoints<Phase extends string> = Partial<Record<Phase, unknown>>;
+export interface CheckpointsConfig<M extends Record<string, string>, Phases extends readonly string[]> {
+    table: string;
+    key: M;
+    phases: Phases;
+    ttlMs?: number;
+}
+type KeyOf<M extends Record<string, string>> = {
+    [F in keyof M]: number;
+};
+export interface CheckpointStore<K, Phase extends string> {
+    readonly table: string;
+    readonly ttlMs: number;
+    ensureSchema(p: QueryPool): Promise<void>;
+    save(run: CheckpointRun<K>, phase: Phase, payload: unknown, deps?: CheckpointDeps): Promise<boolean>;
+    load(run: CheckpointRun<K>, deps?: CheckpointDeps): Promise<Checkpoints<Phase>>;
+    clear(key: K, deps?: CheckpointDeps): Promise<number>;
+    sweepExpired(ttlMs?: number, deps?: CheckpointDeps): Promise<number>;
+}
+export declare function defineCheckpoints<M extends Record<string, string>, const Phases extends readonly string[]>(config: CheckpointsConfig<M, Phases>): CheckpointStore<KeyOf<M>, Phases[number]>;
+export {};
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/lib/coordination/checkpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.d.ts","sourceRoot":"","sources":["../../../src/lib/coordination/checkpoints.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAuB,KAAK,MAAM,EAAW,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAIpF,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,cAAe,SAAQ,MAAM;IAI5C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAEhD,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IAEd,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,KAAK,SAAS,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhF,MAAM,WAAW,iBAAiB,CAChC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,MAAM,SAAS,SAAS,MAAM,EAAE;IAGhC,KAAK,EAAE,MAAM,CAAC;IAEd,GAAG,EAAE,CAAC,CAAC;IAEP,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAAE,CAAC;AAE1E,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C,IAAI,CACF,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,OAAO,CAAC,CAAC;IAQpB,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAEhF,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtD,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtE;AAED,wBAAgB,iBAAiB,CAC/B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,KAAK,CAAC,MAAM,SAAS,SAAS,MAAM,EAAE,EACtC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAkHjF"}

package/dist/lib/coordination/checkpoints.js

@@ -0,0 +1,105 @@
+import { logger } from "../observability/logger.js";
+import { intervalMs, keyPlan, pgBrick } from "./pg.js";
+const log = logger.child({ module: "checkpoints" });
+export const CHECKPOINT_TTL_MS = 24 * 3_600_000;
+export function defineCheckpoints(config) {
+    const { table } = config;
+    const key = keyPlan(config.key);
+    const ttlMs = config.ttlMs ?? CHECKPOINT_TTL_MS;
+    const kn = key.columns.length;
+    const p = (i) => `$${kn + i}`;
+    const index = `${table}_${key.columns[kn - 1]}_idx`;
+    const pg = pgBrick([
+        `CREATE TABLE IF NOT EXISTS ${table} (
+  ${key.columns[0]} bigint NOT NULL,
+${key.columns
+            .slice(1)
+            .map((c) => `  ${c} integer NOT NULL,\n`)
+            .join("")}  head text NOT NULL,
+  run_id text NOT NULL,
+  phase text NOT NULL,
+  payload jsonb NOT NULL,
+  scope text NOT NULL DEFAULT '',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, phase)
+)`,
+        `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS scope text NOT NULL DEFAULT ''`,
+        `CREATE INDEX IF NOT EXISTS ${index} ON ${table} (${key.list})`,
+    ]);
+    const save = async (run, phase, payload, deps = {}) => {
+        try {
+            const pool = await pg.poolFor(deps);
+            if (!pool)
+                return false;
+            const r = await pool.query(`INSERT INTO ${table} (${key.list}, head, run_id, phase, payload, scope, created_at)
+       VALUES (${key.params()}, ${p(1)}, ${p(2)}, ${p(3)}, ${p(4)}::jsonb, ${p(5)}, now())
+       ON CONFLICT (run_id, phase) DO UPDATE
+         SET payload = EXCLUDED.payload, head = EXCLUDED.head, scope = EXCLUDED.scope,
+             created_at = now()
+       RETURNING run_id`, [
+                ...key.values(run),
+                run.head,
+                run.runId,
+                phase,
+                JSON.stringify(payload ?? null),
+                run.scope,
+            ]);
+            return (r.rowCount ?? 0) > 0;
+        }
+        catch (err) {
+            log.warn({ err: String(err), runId: run.runId, phase }, "checkpoint save failed (phase re-runs)");
+            return false;
+        }
+    };
+    const load = async (run, deps = {}) => {
+        try {
+            const pool = await pg.poolFor(deps);
+            if (!pool)
+                return {};
+            const r = await pool.query(`SELECT phase, payload, run_id FROM ${table}
+       WHERE ${key.where()} AND head = ${p(1)} AND scope = ${p(4)}
+         AND created_at > now() - (${p(2)} || ' milliseconds')::interval
+       ORDER BY (run_id = ${p(3)}) DESC, created_at DESC`, [...key.values(run), run.head, intervalMs(ttlMs), run.runId, run.scope]);
+            const out = {};
+            for (const row of r.rows) {
+                const phase = row.phase;
+                if (!config.phases.includes(phase) || phase in out)
+                    continue;
+                out[phase] = row.payload;
+            }
+            return out;
+        }
+        catch (err) {
+            log.warn({ err: String(err), runId: run.runId }, "checkpoint load failed (full re-run)");
+            return {};
+        }
+    };
+    const clear = async (k, deps = {}) => {
+        try {
+            const pool = await pg.poolFor(deps);
+            if (!pool)
+                return 0;
+            const r = await pool.query(`DELETE FROM ${table} WHERE ${key.where()}`, key.values(k));
+            return r.rowCount ?? 0;
+        }
+        catch (err) {
+            log.warn({ err: String(err), key: k }, "checkpoint clear failed");
+            return 0;
+        }
+    };
+    const sweepExpired = async (ttl = ttlMs, deps = {}) => {
+        try {
+            const pool = await pg.poolFor(deps);
+            if (!pool)
+                return 0;
+            const r = await pool.query(`DELETE FROM ${table} WHERE created_at < now() - ($1 || ' milliseconds')::interval`, [intervalMs(ttl)]);
+            return r.rowCount ?? 0;
+        }
+        catch (err) {
+            log.warn({ err: String(err) }, "checkpoint sweep failed");
+            return 0;
+        }
+    };
+    return { table, ttlMs, ensureSchema: pg.ensureSchema, save, load, clear, sweepExpired };
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/lib/coordination/checkpoints.js.map

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

package/dist/lib/coordination/head-lease.d.ts

@@ -0,0 +1,91 @@
+import { type PgDeps, type QueryPool } from "./pg.js";
+export declare const LEASE_HEARTBEAT_MS = 20000;
+export declare const LEASE_TTL_MS = 75000;
+export declare const LEASE_PROGRESS_STALL_MS: number;
+export declare const SAME_BOOT_REAP_GRACE_MS = 60000;
+export declare const STALLED_LEASE_MS: number;
+export declare const PROCESS_BOOT_ID: `${string}-${string}-${string}-${string}-${string}`;
+export declare function leaseKey(itemKey: string, head: string): string;
+export declare function splitLeaseKey(key: string): {
+    itemKey: string;
+    head: string;
+} | null;
+export type LeasePool = QueryPool;
+export type RunState = "active" | "terminal" | "absent" | "error";
+export interface LeaseDeps extends PgDeps {
+    now?: () => number;
+    bootId?: string;
+    runState?: (lease: {
+        runId: string;
+        sessionId: string | null;
+    }) => Promise<RunState>;
+    runsTable?: string;
+}
+export declare function workflowRunState(p: LeasePool, runId: string, runsTable?: string): Promise<RunState>;
+export declare function workflowRunStates(p: LeasePool, runIds: readonly string[], runsTable?: string): Promise<Map<string, RunState>>;
+export interface LeaseHolder {
+    owner: string;
+    runId: string;
+    sessionId: string | null;
+    bootId: string;
+    phase: string;
+    heartbeatAt: string;
+    progressAt: string;
+}
+export type HolderVerdict = "take" | "refuse";
+export declare function holderVerdict(holder: {
+    runId: string;
+    sessionId: string | null;
+}, p: LeasePool, deps: LeaseDeps, known?: RunState): Promise<{
+    verdict: HolderVerdict;
+    state: RunState | "reservation";
+}>;
+export interface LeaseReservation {
+    held: boolean;
+    owner?: string;
+    holder?: LeaseHolder;
+    release: () => Promise<void>;
+}
+export interface HeadLease {
+    held: boolean;
+    isOwner: () => boolean;
+    progress: (phase: string) => Promise<boolean>;
+    owner?: string;
+    runId?: string;
+    holder?: LeaseHolder;
+    release: () => Promise<void>;
+}
+export interface LeaseRow extends LeaseHolder {
+    key: string;
+    claimedAt: string;
+    reapReason?: "dead" | "stalled";
+}
+export interface ReapResult {
+    reaped: LeaseRow[];
+    deferred: LeaseRow[];
+}
+export declare function isLeaseDead(row: Pick<LeaseRow, "heartbeatAt" | "bootId">, opts: {
+    now: number;
+    bootId: string;
+}): boolean;
+export interface HeadLeaseConfig {
+    table: string;
+    bootId?: string;
+}
+export interface HeadLeaseStore {
+    readonly table: string;
+    ensureSchema(p: QueryPool): Promise<void>;
+    reserve(key: string, deps?: LeaseDeps): Promise<LeaseReservation>;
+    adopt(key: string, meta: {
+        runId: string;
+        sessionId?: string;
+    }, deps?: LeaseDeps): Promise<HeadLease>;
+    liveFor(itemKey: string, deps?: LeaseDeps): Promise<(LeaseHolder & {
+        key: string;
+    }) | null | undefined>;
+    list(deps?: LeaseDeps): Promise<LeaseRow[] | null>;
+    reapDetailed(deps?: LeaseDeps): Promise<ReapResult>;
+    reap(deps?: LeaseDeps): Promise<LeaseRow[]>;
+}
+export declare function defineHeadLease(config: HeadLeaseConfig): HeadLeaseStore;
+//# sourceMappingURL=head-lease.d.ts.map

package/dist/lib/coordination/head-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-lease.d.ts","sourceRoot":"","sources":["../../../src/lib/coordination/head-lease.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAc,KAAK,MAAM,EAAW,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAI3E,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,YAAY,QAAS,CAAC;AACnC,eAAO,MAAM,uBAAuB,QAAc,CAAC;AAGnD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAI9C,eAAO,MAAM,gBAAgB,QAAc,CAAC;AAE5C,eAAO,MAAM,eAAe,qDAAe,CAAC;AAG5C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D;AAGD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAInF;AAED,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC;AAMlC,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,SAAU,SAAQ,MAAM;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAsB,gBAAgB,CACpC,CAAC,EAAE,SAAS,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,SAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAmBD,wBAAsB,iBAAiB,CACrC,CAAC,EAAE,SAAS,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,SAAS,SAAqB,GAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAkDhC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAsBD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAO9C,wBAAsB,aAAa,CACjC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACnD,CAAC,EAAE,SAAS,EACZ,IAAI,EAAE,SAAS,EACf,KAAK,CAAC,EAAE,QAAQ,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CAAA;CAAE,CAAC,CAQtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IAExB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,OAAO,CAAC;IAEvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAElB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IAEnB,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAGD,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,CAAC,EAC7C,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC,OAAO,CAUT;AAED,MAAM,WAAW,eAAe;IAE9B,KAAK,EAAE,MAAM,CAAC;IAEd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAO1C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAMlE,KAAK,CACH,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAC3C,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,SAAS,CAAC,CAAC;IAOtB,OAAO,CACL,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,CAAC,WAAW,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;IAOnD,YAAY,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACpD,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC7C;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,CA4WvE"}