@opendatalabs/personal-server-ts-core 1.8.0 → 1.10.0

package/dist/derivatives/inference.js

@@ -0,0 +1,223 @@
+/**
+ * Inference provider adapter for the derivative compute layer.
+ *
+ * One implementation: OpenAI-compatible chat completions over `fetch`, so it
+ * runs unchanged in Node and in the browser (PS-Lite). In production the
+ * base URL is the Vana inference relay, which holds the provider key; the
+ * optional API key header exists for local development against a provider
+ * directly.
+ *
+ * E2EE SEAM: the Phala confidential-inference E2EE v2 protocol encrypts each
+ * `messages[i].content` to the gateway's attested public key and adds the
+ * headers X-E2EE-Version, X-Client-Pub-Key, X-Model-Pub-Key, X-E2EE-Nonce
+ * and X-E2EE-Timestamp; the response content comes back encrypted to the
+ * client key. `InferenceRequestEncryption` below is the hook, implemented
+ * by `createPhalaE2eeEncryption` in ./e2ee. This module only knows the
+ * shape: encrypt the outgoing messages, decrypt the one response field.
+ */
+export const DEFAULT_INFERENCE_BASE_URL = "https://inference.phala.com/v1";
+export const DEFAULT_INFERENCE_MODEL = "z-ai/glm-5.2";
+export const DEFAULT_INFERENCE_TIMEOUT_MS = 120_000;
+export const DEFAULT_INFERENCE_MAX_TOKENS = 2_048;
+export const DEFAULT_INFERENCE_REQUEST_FIELDS = {
+    provider: { aci_verified: true, zdr: true },
+};
+/** Thrown for a non-2xx or malformed provider reply. Carries no prompt text. */
+export class InferenceRequestError extends Error {
+    status;
+    /** OpenAI-style `error.type` of the rejection, when the body had one. */
+    errorType;
+    /**
+     * Explicit retry hint. When undefined the compute layer falls back to the
+     * status: no response, 429 or 5xx are retried.
+     */
+    retryable;
+    constructor(message, status, options = {}) {
+        super(message);
+        this.status = status;
+        this.name = "InferenceRequestError";
+        this.errorType = options.errorType ?? null;
+        this.retryable = options.retryable;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readUsage(value) {
+    if (!isRecord(value))
+        return undefined;
+    const num = (v) => (typeof v === "number" ? v : undefined);
+    const usage = {
+        promptTokens: num(value.prompt_tokens),
+        completionTokens: num(value.completion_tokens),
+        totalTokens: num(value.total_tokens),
+    };
+    return usage;
+}
+function readContent(body) {
+    if (!isRecord(body) || !Array.isArray(body.choices))
+        return null;
+    const first = body.choices[0];
+    if (!isRecord(first) || !isRecord(first.message))
+        return null;
+    const index = typeof first.index === "number" ? first.index : 0;
+    const field = `choices.${index}.message.content`;
+    const id = typeof body.id === "string" ? body.id : "";
+    const content = first.message.content;
+    if (typeof content === "string")
+        return { content, field, id };
+    // Some providers return content parts.
+    if (Array.isArray(content)) {
+        const text = content
+            .map((part) => isRecord(part) && typeof part.text === "string" ? part.text : "")
+            .join("");
+        return { content: text, field, id };
+    }
+    return null;
+}
+/** OpenAI-style `{ error: { type } }` of a rejection; never its message. */
+async function readErrorType(response) {
+    try {
+        const body = await response.json();
+        if (isRecord(body) && isRecord(body.error)) {
+            return typeof body.error.type === "string" ? body.error.type : null;
+        }
+    }
+    catch {
+        // Not JSON: no type to report.
+    }
+    return null;
+}
+export function createOpenAiCompatibleInferenceProvider(options = {}) {
+    const base = (options.baseUrl ?? DEFAULT_INFERENCE_BASE_URL).replace(/\/+$/, "");
+    const defaultModel = options.model ?? DEFAULT_INFERENCE_MODEL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_INFERENCE_TIMEOUT_MS;
+    const doFetch = options.fetch ?? fetch;
+    const requestFields = options.requestFields ?? DEFAULT_INFERENCE_REQUEST_FIELDS;
+    const encryption = options.encryption;
+    /** One send; `rejected` reports a non-2xx so the caller may retry once. */
+    async function send(input) {
+        const headers = new Headers({ "Content-Type": "application/json" });
+        if (options.apiKey) {
+            headers.set("Authorization", `Bearer ${options.apiKey}`);
+        }
+        const model = input.model || defaultModel;
+        let messages = input.messages;
+        let encrypted = null;
+        if (encryption) {
+            encrypted = await encryption.encryptRequest({
+                model,
+                messages,
+                headers,
+            });
+            messages = encrypted.messages;
+        }
+        const body = {
+            ...requestFields,
+            model,
+            messages,
+            max_tokens: input.maxTokens ?? DEFAULT_INFERENCE_MAX_TOKENS,
+        };
+        let response;
+        try {
+            response = await doFetch(`${base}/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            // Transport failure: no status, no body. The message is the error
+            // class name only; it never carries request contents.
+            const name = err instanceof Error ? err.name : "Error";
+            throw new InferenceRequestError(`inference request failed before a response (${name})`, null);
+        }
+        if (!response.ok) {
+            const errorType = await readErrorType(response);
+            const retry = (await encryption?.onRejected?.({
+                status: response.status,
+                errorType,
+                headers: response.headers,
+            })) === true;
+            return {
+                ok: false,
+                retry,
+                error: new InferenceRequestError(`inference request failed with status ${response.status}${errorType ? ` (${errorType})` : ""}`, response.status, { errorType }),
+            };
+        }
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw new InferenceRequestError("inference response was not JSON", response.status);
+        }
+        const choice = readContent(parsed);
+        if (choice === null) {
+            throw new InferenceRequestError("inference response carried no assistant content", response.status);
+        }
+        let content = choice.content;
+        if (encrypted) {
+            // Fail closed: a reply that is not valid ciphertext for this request
+            // is an error, never used as plaintext.
+            content = await encrypted.decryptResponse({
+                content,
+                field: choice.field,
+                id: choice.id,
+                headers: response.headers,
+            });
+        }
+        if (content.trim() === "") {
+            // An empty reply must never become a "ready" derivative.
+            throw new InferenceRequestError("inference response carried no assistant content", response.status);
+        }
+        const receiptId = response.headers.get("x-receipt-id") ?? undefined;
+        const aciIdentity = response.headers.get("x-aci-identity") ?? undefined;
+        return {
+            ok: true,
+            result: {
+                content,
+                usage: readUsage(isRecord(parsed) ? parsed.usage : undefined),
+                ...(receiptId ? { receiptId } : {}),
+                ...(aciIdentity ? { aciIdentity } : {}),
+            },
+        };
+    }
+    return {
+        defaultModel,
+        async chat(input) {
+            const first = await send(input);
+            if (first.ok)
+                return first.result;
+            if (!first.retry)
+                throw first.error;
+            // The encryption asked for one re-send (fresh key, fresh nonce).
+            const second = await send(input);
+            if (second.ok)
+                return second.result;
+            throw second.error;
+        },
+    };
+}
+/** Test double: records calls, answers with a fixed JSON object by default. */
+export function createFakeInferenceProvider(options = {}) {
+    const calls = [];
+    return {
+        defaultModel: options.model ?? "fake-model",
+        calls,
+        async chat(input) {
+            calls.push(input);
+            if (options.respond)
+                return options.respond(input, calls.length - 1);
+            return {
+                content: JSON.stringify({
+                    answer: "fake answer",
+                    evidence: "fake evidence",
+                }),
+                receiptId: "fake-receipt",
+            };
+        },
+    };
+}
+//# sourceMappingURL=inference.js.map

package/dist/derivatives/inference.js.map

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

package/dist/derivatives/prompt.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+import type { InferenceMessage } from "./inference.js";
+export declare const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export declare const DEFAULT_MAX_SOURCE_CHARS = 200000;
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export declare function sortNewestFirst<T>(items: readonly T[]): T[];
+export interface TrimResult {
+    data: unknown;
+    /** Items kept / items present, summed over every array that was trimmed. */
+    kept: number;
+    total: number;
+    /** True when the char cap cut the serialization. */
+    truncated: boolean;
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export declare function trimSourceData(data: unknown, options?: {
+    maxItems?: number;
+    maxChars?: number;
+}): TrimResult;
+export interface PromptSource {
+    scope: string;
+    collectedAt: string;
+    version: number;
+    data: unknown;
+    kept: number;
+    total: number;
+    truncated: boolean;
+}
+export declare const SYSTEM_PROMPT: string;
+/** Assemble the chat messages for one compute. */
+export declare function buildQuestionMessages(input: {
+    question: string;
+    sources: readonly PromptSource[];
+}): InferenceMessage[];
+export interface ParsedAnswer {
+    answer: string;
+    evidence: string | null;
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export declare function parseAnswer(content: string): ParsedAnswer;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/derivatives/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/derivatives/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAyChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAW3D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,UAAU,CA+CZ;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,QAMd,CAAC;AAEb,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAClC,GAAG,gBAAgB,EAAE,CA0BrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAwBzD"}

package/dist/derivatives/prompt.js

@@ -0,0 +1,186 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+export const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export const DEFAULT_MAX_SOURCE_CHARS = 200_000;
+/** Keys a record commonly carries its own timestamp under, in priority order. */
+const TIMESTAMP_KEYS = [
+    "collectedAt",
+    "updatedAt",
+    "updated_at",
+    "update_time",
+    "createdAt",
+    "created_at",
+    "create_time",
+    "timestamp",
+    "time",
+    "date",
+    "publishedAt",
+    "published_at",
+];
+/** Server-stamped envelope keys that are not user data. */
+const RESERVED_KEYS = new Set(["$lineage", "$writtenBy", "$binary"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function timestampOf(item) {
+    if (!isRecord(item))
+        return null;
+    for (const key of TIMESTAMP_KEYS) {
+        const value = item[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            // Seconds vs milliseconds: anything below 1e12 is taken as seconds.
+            return value < 1e12 ? value * 1000 : value;
+        }
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (!Number.isNaN(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export function sortNewestFirst(items) {
+    const indexed = items.map((item, index) => ({
+        item,
+        index,
+        at: timestampOf(item),
+    }));
+    const dated = indexed
+        .filter((entry) => entry.at !== null)
+        .sort((a, b) => b.at - a.at || b.index - a.index);
+    const undated = indexed.filter((entry) => entry.at === null).reverse();
+    return [...dated, ...undated].map((entry) => entry.item);
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export function trimSourceData(data, options = {}) {
+    const maxItems = Math.max(1, options.maxItems ?? DEFAULT_MAX_SOURCE_ITEMS);
+    const maxChars = Math.max(1, options.maxChars ?? DEFAULT_MAX_SOURCE_CHARS);
+    let kept = 0;
+    let total = 0;
+    const trimArray = (items, limit) => {
+        total += items.length;
+        const sorted = sortNewestFirst(items).slice(0, limit);
+        kept += sorted.length;
+        return sorted;
+    };
+    const build = (limit) => {
+        kept = 0;
+        total = 0;
+        if (Array.isArray(data))
+            return trimArray(data, limit);
+        if (isRecord(data)) {
+            const out = {};
+            for (const [key, value] of Object.entries(data)) {
+                if (RESERVED_KEYS.has(key))
+                    continue;
+                out[key] = Array.isArray(value) ? trimArray(value, limit) : value;
+            }
+            return out;
+        }
+        return data;
+    };
+    let limit = maxItems;
+    let result = build(limit);
+    let text = JSON.stringify(result) ?? "null";
+    // Shrink the item budget while the serialization is over the cap. Each
+    // pass at least halves the budget, so this ends in O(log maxItems) steps.
+    while (text.length > maxChars && limit > 1) {
+        limit = Math.max(1, Math.floor(limit / 2));
+        result = build(limit);
+        text = JSON.stringify(result) ?? "null";
+    }
+    if (text.length > maxChars) {
+        return {
+            data: `${text.slice(0, maxChars)}...[truncated]`,
+            kept,
+            total,
+            truncated: true,
+        };
+    }
+    return { data: result, kept, total, truncated: false };
+}
+export const SYSTEM_PROMPT = [
+    "You answer a question about a person using ONLY the user data provided in the message.",
+    "Do not use outside knowledge and do not guess; if the data does not support an answer, say so in the answer.",
+    "Respond with a single JSON object and nothing else, with exactly these fields:",
+    '  "answer": string, the answer to the question, written for the person the data belongs to;',
+    '  "evidence": string, a short summary of which parts of the data support the answer.',
+].join("\n");
+/** Assemble the chat messages for one compute. */
+export function buildQuestionMessages(input) {
+    const sections = input.sources.map((source) => {
+        const note = source.total > source.kept
+            ? ` (newest ${source.kept} of ${source.total} items)`
+            : "";
+        const cut = source.truncated ? " (truncated)" : "";
+        return [
+            `### Scope: ${source.scope}${note}${cut}`,
+            `Collected at: ${source.collectedAt}`,
+            JSON.stringify(source.data),
+        ].join("\n");
+    });
+    const user = [
+        "## Question",
+        input.question,
+        "",
+        "## User data",
+        ...sections,
+        "",
+        "Answer the question as a JSON object with the fields answer and evidence.",
+    ].join("\n");
+    return [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: user },
+    ];
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export function parseAnswer(content) {
+    const candidates = [content.trim()];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(content);
+    if (fenced?.[1])
+        candidates.unshift(fenced[1].trim());
+    const first = content.indexOf("{");
+    const last = content.lastIndexOf("}");
+    if (first !== -1 && last > first) {
+        candidates.push(content.slice(first, last + 1));
+    }
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (isRecord(parsed) && typeof parsed.answer === "string") {
+                return {
+                    answer: parsed.answer,
+                    evidence: typeof parsed.evidence === "string" ? parsed.evidence : null,
+                };
+            }
+        }
+        catch {
+            // try the next framing
+        }
+    }
+    return { answer: content.trim(), evidence: null };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/derivatives/prompt.js.map

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

package/dist/derivatives/registration.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Question registration: input validation, the naming rule (shared with the
+ * lineage write path) and the cycle guard that keeps recompute-on-refresh
+ * bounded.
+ */
+import type { QuestionRegisteredBy, QuestionRegistration, QuestionStore } from "./types.js";
+export declare const MAX_QUESTION_SOURCE_SCOPES = 16;
+export declare const MAX_QUESTION_CHARS = 8000;
+export declare const MAX_MODEL_CHARS = 128;
+/** Unvalidated scope strings echoed in 400 details are cut to this. */
+export declare const MAX_ECHOED_SCOPE_CHARS = 128;
+export interface ParsedQuestionInput {
+    derivedScope: string;
+    sourceScopes: string[];
+    question: string;
+    model: string | null;
+}
+/**
+ * Validate the POST body of a question registration. Throws 400
+ * DERIVATIVE_QUESTION_INVALID on shape errors and 400
+ * LINEAGE_SCOPE_UNDER_SOURCE_PREFIX when the derived scope shares its
+ * first segment with a source (the lineage naming rule, applied up front
+ * so a registration that could never be written is refused here).
+ */
+export declare function parseQuestionInput(body: unknown): ParsedQuestionInput;
+/**
+ * Recompute-on-refresh follows edges source -> derived. A registration whose
+ * derived scope can reach one of its own sources through other
+ * registrations would recompute forever (A from B, B from A). Refuse it.
+ * Returns the offending path (derived scope back to itself) or null.
+ */
+export declare function findDerivationCycle(candidate: Pick<QuestionRegistration, "derivedScope" | "sourceScopes">, existing: readonly Pick<QuestionRegistration, "derivedScope" | "sourceScopes">[]): string[] | null;
+export interface CreateQuestionRegistrationInput {
+    body: unknown;
+    registeredBy: QuestionRegisteredBy;
+    store: QuestionStore;
+    questionId: string;
+    now: () => Date;
+}
+/**
+ * Validate, guard against cycles and persist a registration in `pending`.
+ * The caller has already authorized the write on `derivedScope`.
+ */
+export declare function createQuestionRegistration(input: CreateQuestionRegistrationInput): Promise<QuestionRegistration>;
+/**
+ * Consent check for a builder question: the sources feed a prompt whose
+ * answer the builder reads, so every source scope must be covered by a READ
+ * entry of the builder's grant (bare entries; `write:` entries confer
+ * nothing). Returns the uncovered scopes; empty = all covered. The system
+ * prompt is not a security boundary, this is.
+ */
+export declare function uncoveredSourceScopes(sourceScopes: readonly string[], grantScopes: readonly string[] | undefined): string[];
+//# sourceMappingURL=registration.d.ts.map

package/dist/derivatives/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../src/derivatives/registration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAK1C,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAyBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CA8DrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,cAAc,CAAC,EACtE,QAAQ,EAAE,SAAS,IAAI,CACrB,oBAAoB,EACpB,cAAc,GAAG,cAAc,CAChC,EAAE,GACF,MAAM,EAAE,GAAG,IAAI,CA+BjB;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,oBAAoB,CAAC;IACnC,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,oBAAoB,CAAC,CA2B/B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,MAAM,EAAE,CAOV"}