@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/derivatives/scheduler.js

@@ -0,0 +1,331 @@
+/**
+ * Recompute scheduler: marks registrations stale when one of their source
+ * scopes changes and runs the compute when someone actually asks for the
+ * answer, one in flight per question. Timers and the clock are injectable
+ * so tests drive it deterministically.
+ *
+ * Compute is just-in-time, not preemptive. A source refresh only marks the
+ * answer stale; the recompute happens on the next authorized demand (a read
+ * of the derived scope, the reader-facing status route, or an explicit
+ * `POST /questions/:id/recompute`). Otherwise the inference bill would
+ * scale with how often the owner's sources refresh rather than with how
+ * often anyone reads the answer.
+ */
+import { computeDataPointId } from "../sync/data-point-id.js";
+const DEFAULT_RETRY_DELAYS_MS = [60_000, 300_000, 1_800_000];
+/**
+ * Structural check on the compute callback's resolved value: retry is only
+ * for a failed outcome whose stored class is the one transient kind. A
+ * callback that resolves anything else (older wiring, tests) never retries.
+ */
+/**
+ * A compute skipped because the runtime is unavailable (PS-Lite with the
+ * hosting tab inactive). During a retry chain this must not end the chain:
+ * nothing else would ever reschedule a failed question.
+ */
+function isRuntimeSkipOutcome(outcome) {
+    if (typeof outcome !== "object" || outcome === null)
+        return false;
+    const shaped = outcome;
+    return shaped.status === "skipped" && shaped.reason === "runtime-unavailable";
+}
+function isTransientFailureOutcome(outcome) {
+    if (typeof outcome !== "object" || outcome === null)
+        return false;
+    const shaped = outcome;
+    return (shaped.status === "failed" &&
+        shaped.registration?.errorCode === "inference_unavailable");
+}
+const defaultTimers = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export function createRecomputeScheduler(options) {
+    const debounceMs = options.debounceMs ?? 5_000;
+    const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    const timers = options.timers ?? defaultTimers;
+    const now = options.now ?? (() => new Date());
+    const states = new Map();
+    const pending = new Set();
+    let stopped = false;
+    // Distinguishes the first start() (which must reschedule) from a
+    // redundant one while already running (which must not).
+    let started = false;
+    function track(promise) {
+        pending.add(promise);
+        const done = () => pending.delete(promise);
+        promise.then(done, done);
+        return promise;
+    }
+    function warn(payload, message) {
+        options.logger?.warn?.(payload, message);
+    }
+    function stateFor(questionId) {
+        let state = states.get(questionId);
+        if (!state) {
+            state = {
+                timer: null,
+                running: null,
+                rerun: false,
+                retryAttempts: 0,
+                retryAtMs: null,
+                retryScheduled: false,
+                retryRunning: false,
+                sourceChangedDuringRun: false,
+            };
+            states.set(questionId, state);
+        }
+        return state;
+    }
+    function run(questionId) {
+        if (stopped)
+            return;
+        const state = stateFor(questionId);
+        if (state.running) {
+            // One in flight per question; a change during the run means the
+            // result is already stale, so run once more when it finishes.
+            state.rerun = true;
+            return;
+        }
+        state.running = track(Promise.resolve()
+            .then(() => options.compute(questionId))
+            .then((outcome) => outcome, (err) => {
+            warn({
+                questionId,
+                error: err instanceof Error ? err.name : String(err),
+            }, "Derivative compute threw");
+            return undefined;
+        })
+            .then(async (outcome) => {
+            state.running = null;
+            state.retryAtMs = null;
+            state.retryRunning = false;
+            // Consumed here whichever branch wins: a rerun and a retry both
+            // recompute from current data, so only the branch that schedules
+            // nothing has to put the question back to `stale`.
+            const sourceChangedDuringRun = state.sourceChangedDuringRun;
+            state.sourceChangedDuringRun = false;
+            const retryable = isTransientFailureOutcome(outcome) ||
+                // A runtime-unavailable skip DURING a chain consumes an attempt
+                // instead of ending the chain; on a fresh compute it keeps the
+                // pre-retry behavior (pending/stale, reswept by start()).
+                (isRuntimeSkipOutcome(outcome) && state.retryAttempts > 0);
+            if (state.rerun) {
+                // A source changed during the run: that supersedes any retry.
+                state.rerun = false;
+                state.retryAttempts = 0;
+                await markStale(questionId);
+                schedule(questionId, 0);
+            }
+            else if (retryable &&
+                // A pending timer means a source change or explicit recompute
+                // arrived during the run and already scheduled a fresher run;
+                // replacing its 5s debounce with a 60s retry would delay the
+                // recompute of data this compute never saw.
+                state.timer === null &&
+                // After stop() nothing may be scheduled; without this a compute
+                // that settles late would record a retryAtMs no timer backs.
+                !stopped &&
+                state.retryAttempts < retryDelaysMs.length) {
+                const delayMs = retryDelaysMs[state.retryAttempts];
+                state.retryAttempts += 1;
+                state.retryAtMs = now().getTime() + delayMs;
+                schedule(questionId, delayMs);
+                state.retryScheduled = true;
+            }
+            else {
+                state.retryAttempts = 0;
+                if (sourceChangedDuringRun) {
+                    // Fresh data landed while this compute was reading, so the
+                    // answer it just wrote is already behind. Say so — and
+                    // schedule nothing: the next reader triggers the recompute.
+                    await markStale(questionId);
+                }
+                if (!states.get(questionId)?.timer) {
+                    states.delete(questionId);
+                }
+            }
+        }));
+    }
+    function schedule(questionId, delayMs) {
+        if (stopped)
+            return;
+        const state = stateFor(questionId);
+        if (state.timer !== null)
+            timers.clearTimeout(state.timer);
+        state.timer = timers.setTimeout(() => {
+            state.timer = null;
+            // Whatever this timer was (debounce or retry), any promised retry is
+            // now being consumed: a past retryAtMs would pin the status route's
+            // retryAfterSeconds at 0 for the whole in-flight compute. A firing
+            // RETRY timer hands over to retryRunning so the in-flight window is
+            // still distinguishable from a terminal failure.
+            state.retryAtMs = null;
+            state.retryRunning = state.retryScheduled;
+            state.retryScheduled = false;
+            run(questionId);
+        }, delayMs);
+    }
+    /**
+     * Run this question because someone asked for its answer. Idempotent by
+     * design: a compute already in flight or already timed is the compute the
+     * demand wants, so concurrent readers collapse into one run. A pending
+     * RETRY timer is the exception — its backoff is a fallback for nobody
+     * asking, and a reader is asking now — so demand pulls it forward,
+     * keeping the attempt count (an exhausting chain stays bounded).
+     */
+    function scheduleDemand(questionId) {
+        const state = stateFor(questionId);
+        if (state.running !== null)
+            return;
+        if (state.timer !== null && !state.retryScheduled)
+            return;
+        schedule(questionId, 0);
+        state.retryScheduled = false;
+    }
+    async function markStale(questionId) {
+        const registration = await options.store.get(questionId);
+        if (!registration)
+            return;
+        if (registration.status === "ready" || registration.status === "failed") {
+            await options.store.update(questionId, {
+                status: "stale",
+                // The reader contract says errorCode is null unless failed; a stale
+                // question is a recompute in progress, not a terminal failure.
+                errorCode: null,
+                updatedAt: now().toISOString(),
+            });
+        }
+    }
+    function resetRetry(questionId) {
+        const state = states.get(questionId);
+        if (!state)
+            return;
+        state.retryAttempts = 0;
+        state.retryAtMs = null;
+        state.retryScheduled = false;
+    }
+    return {
+        nextRetryAt(questionId) {
+            const retryAtMs = states.get(questionId)?.retryAtMs;
+            return retryAtMs == null ? null : new Date(retryAtMs).toISOString();
+        },
+        retryInFlight(questionId) {
+            return states.get(questionId)?.retryRunning ?? false;
+        },
+        markSourceChanged(scope, opts) {
+            if (stopped)
+                return;
+            const lineage = new Set((opts?.lineageSources ?? []).map((id) => id.toLowerCase()));
+            void track((async () => {
+                const affected = await options.store.list({ sourceScope: scope });
+                for (const registration of affected) {
+                    if (registration.recompute === "snapshot") {
+                        // A snapshot question computes at registration and on an
+                        // explicit recompute only; source changes never touch it.
+                        continue;
+                    }
+                    if (options.serverOwner &&
+                        lineage.has(computeDataPointId(options.serverOwner, registration.derivedScope))) {
+                        // The new version descends from this question's own output.
+                        continue;
+                    }
+                    // A change lands on a question whose compute is in flight: that
+                    // compute never saw the new data, so its result must not settle
+                    // as `ready`. Read the flag before and after the store write —
+                    // the run can finish inside that await.
+                    const state = states.get(registration.questionId);
+                    const runningBefore = state?.running != null;
+                    await markStale(registration.questionId);
+                    if (state && (runningBefore || state.running !== null)) {
+                        state.sourceChangedDuringRun = true;
+                    }
+                    // Nothing is scheduled: the recompute is owed, not started. Any
+                    // retry timer the question already carries stays as it is; the
+                    // retry recomputes from current data anyway.
+                }
+            })().catch((err) => warn({ scope, error: err instanceof Error ? err.name : String(err) }, "Could not mark derivative questions stale")));
+        },
+        markDemand(derivedScope) {
+            if (stopped)
+                return;
+            void track((async () => {
+                const affected = await options.store.list({ derivedScope });
+                for (const registration of affected) {
+                    if (registration.recompute === "snapshot") {
+                        // A snapshot answers from the version it computed at
+                        // registration; only an explicit recompute replaces it.
+                        continue;
+                    }
+                    if (registration.status !== "stale" &&
+                        registration.status !== "pending") {
+                        // `ready` has nothing to compute, and `failed` belongs to its
+                        // backoff chain or to an explicit recompute: a reader polling
+                        // a question that keeps failing must not spend an inference
+                        // call per poll.
+                        continue;
+                    }
+                    scheduleDemand(registration.questionId);
+                }
+            })().catch((err) => warn({
+                derivedScope,
+                error: err instanceof Error ? err.name : String(err),
+            }, "Could not schedule derivative questions on demand")));
+        },
+        requestRecompute(questionId, opts) {
+            if (stopped)
+                return;
+            void track(markStale(questionId)
+                .catch((err) => warn({
+                questionId,
+                error: err instanceof Error ? err.name : String(err),
+            }, "Could not mark derivative question stale"))
+                .then(() => {
+                resetRetry(questionId);
+                schedule(questionId, opts?.immediate ? 0 : debounceMs);
+            }));
+        },
+        async whenIdle() {
+            // Waits for store lookups and in-flight computes. Real timers are
+            // polled too; injected timers are the caller's to fire.
+            const waitForTimers = !options.timers;
+            for (;;) {
+                while (pending.size > 0) {
+                    await Promise.allSettled([...pending]);
+                }
+                const busy = [...states.values()].some((state) => state.running !== null || (waitForTimers && state.timer !== null));
+                if (!busy)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        },
+        stop() {
+            stopped = true;
+            for (const state of states.values()) {
+                if (state.timer !== null)
+                    timers.clearTimeout(state.timer);
+                state.timer = null;
+                state.retryAttempts = 0;
+                state.retryAtMs = null;
+                state.retryScheduled = false;
+            }
+        },
+        start() {
+            if (started && !stopped)
+                return;
+            started = true;
+            stopped = false;
+            void track((async () => {
+                for (const registration of await options.store.list()) {
+                    // Only never-answered questions. A `stale` one has a previous
+                    // version to serve and is recomputed on demand, so a restart
+                    // costs nothing.
+                    if (registration.status === "pending") {
+                        schedule(registration.questionId, 0);
+                    }
+                }
+            })().catch((err) => warn({ error: err instanceof Error ? err.name : String(err) }, "Could not reschedule derivative questions")));
+        },
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/derivatives/scheduler.js.map

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

package/dist/derivatives/store.d.ts

@@ -0,0 +1,14 @@
+import type { QuestionRegistration, QuestionStore, QuestionStoreListFilter } from "./types.js";
+export declare function matchesQuestionFilter(registration: QuestionRegistration, filter: QuestionStoreListFilter | undefined): boolean;
+/** Oldest first, the order every store lists in. */
+export declare function sortQuestions(registrations: QuestionRegistration[]): QuestionRegistration[];
+/**
+ * Map-backed store. The PS-Lite store wraps it with persistence; tests use
+ * it as is.
+ */
+export declare function createInMemoryQuestionStore(options?: {
+    /** Called after every mutation with the full current list. */
+    onChange?: (registrations: QuestionRegistration[]) => Promise<void>;
+    initial?: QuestionRegistration[];
+}): QuestionStore;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/derivatives/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EAEpB,aAAa,EACb,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAapB,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,oBAAoB,EAClC,MAAM,EAAE,uBAAuB,GAAG,SAAS,GAC1C,OAAO,CAkBT;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAC3B,aAAa,EAAE,oBAAoB,EAAE,GACpC,oBAAoB,EAAE,CAMxB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE;IACP,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,oBAAoB,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC7B,GACL,aAAa,CA4Cf"}

package/dist/derivatives/store.js

@@ -0,0 +1,79 @@
+import { cloneAnswerShape } from "./answer-shape.js";
+function clone(registration) {
+    return {
+        ...registration,
+        // Registrations persisted before the field existed load as null.
+        errorCode: registration.errorCode ?? null,
+        answerShape: cloneAnswerShape(registration.answerShape ?? null),
+        sourceScopes: [...registration.sourceScopes],
+        registeredBy: { ...registration.registeredBy },
+    };
+}
+export function matchesQuestionFilter(registration, filter) {
+    if (!filter)
+        return true;
+    if (filter.derivedScope && registration.derivedScope !== filter.derivedScope)
+        return false;
+    if (filter.sourceScope &&
+        !registration.sourceScopes.includes(filter.sourceScope))
+        return false;
+    if (filter.builder) {
+        const by = registration.registeredBy;
+        if (by.kind !== "builder" ||
+            by.builder.toLowerCase() !== filter.builder.toLowerCase())
+            return false;
+    }
+    return true;
+}
+/** Oldest first, the order every store lists in. */
+export function sortQuestions(registrations) {
+    return [...registrations].sort((a, b) => a.createdAt.localeCompare(b.createdAt) ||
+        a.questionId.localeCompare(b.questionId));
+}
+/**
+ * Map-backed store. The PS-Lite store wraps it with persistence; tests use
+ * it as is.
+ */
+export function createInMemoryQuestionStore(options = {}) {
+    const byId = new Map();
+    for (const registration of options.initial ?? []) {
+        byId.set(registration.questionId, clone(registration));
+    }
+    async function changed() {
+        if (!options.onChange)
+            return;
+        await options.onChange(sortQuestions([...byId.values()]).map(clone));
+    }
+    return {
+        async list(filter) {
+            return sortQuestions([...byId.values()].filter((registration) => matchesQuestionFilter(registration, filter))).map(clone);
+        },
+        async get(questionId) {
+            const registration = byId.get(questionId);
+            return registration ? clone(registration) : null;
+        },
+        async insert(registration) {
+            if (byId.has(registration.questionId)) {
+                throw new Error(`Question ${registration.questionId} is already registered`);
+            }
+            byId.set(registration.questionId, clone(registration));
+            await changed();
+        },
+        async update(questionId, patch) {
+            const current = byId.get(questionId);
+            if (!current)
+                return null;
+            const next = { ...current, ...patch };
+            byId.set(questionId, next);
+            await changed();
+            return clone(next);
+        },
+        async delete(questionId) {
+            const existed = byId.delete(questionId);
+            if (existed)
+                await changed();
+            return existed;
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/derivatives/store.js.map

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

package/dist/derivatives/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Derivative compute layer: a builder registers a QUESTION over the owner's
+ * source scopes; the Personal Server answers it locally with an inference
+ * provider and writes the answer as an ordinary derivative record (lineage
+ * = the source data points) into the derived scope. See
+ * docs/derivative-data-api.md, "Compute (question to derivative)".
+ */
+import { type AnswerShape } from "./answer-shape.js";
+export type QuestionStatus = "pending" | "ready" | "failed" | "stale";
+/**
+ * When the answer recomputes: "on-change" (the default) goes stale on every
+ * source change and recomputes on the next authorized demand for the answer;
+ * "snapshot" computes at registration and afterwards only on an explicit
+ * POST /questions/:id/recompute. Two values, and only these two: the SDK
+ * validates the field against them, so the meaning of "on-change" moves
+ * rather than the vocabulary.
+ */
+export type QuestionRecompute = "snapshot" | "on-change";
+/**
+ * Closed vocabulary for the machine-readable failure class. Deliberately
+ * coarse: it is served to readers of the derived scope through the status
+ * route, so it must never carry a scope name, the question or provider
+ * detail. `inference_unavailable` is the one transient class (the scheduler
+ * retries it); everything else stays failed until a source change or an
+ * explicit recompute.
+ */
+export type QuestionErrorCode = "inference_unavailable" | "source_missing" | "grant_invalid" | "internal";
+/** Who registered the question; a builder is bound to the write grant. */
+export type QuestionRegisteredBy = {
+    kind: "owner";
+} | {
+    kind: "builder";
+    builder: `0x${string}`;
+    grantId: string;
+};
+export interface QuestionRegistration {
+    questionId: string;
+    derivedScope: string;
+    sourceScopes: string[];
+    /** The prompt template text (the builder's question). */
+    question: string;
+    /** Model override; null = the provider's default. */
+    model: string | null;
+    /**
+     * The declared shape of the answer, enforced at compute time; null = the
+     * free-text answer (the original behavior).
+     */
+    answerShape: AnswerShape | null;
+    recompute: QuestionRecompute;
+    registeredBy: QuestionRegisteredBy;
+    status: QuestionStatus;
+    /** Short failure reason (never the prompt or the data). Null unless failed. */
+    error: string | null;
+    /** Machine-readable failure class; null unless failed. */
+    errorCode: QuestionErrorCode | null;
+    createdAt: string;
+    updatedAt: string;
+    lastComputedAt: string | null;
+    /** Local index version of the derived record the last compute wrote. */
+    derivedVersion: number | null;
+    derivedCollectedAt: string | null;
+}
+export type QuestionRegistrationPatch = Partial<Pick<QuestionRegistration, "status" | "error" | "errorCode" | "updatedAt" | "lastComputedAt" | "derivedVersion" | "derivedCollectedAt">>;
+export interface QuestionStoreListFilter {
+    derivedScope?: string;
+    sourceScope?: string;
+    builder?: `0x${string}`;
+}
+/**
+ * Persistence for question registrations. Small and local: registrations
+ * never sync (the replica that holds them computes them). Implementations:
+ * sqlite (server), a state-store backed map (PS-Lite), in-memory (tests).
+ */
+export interface QuestionStore {
+    list(filter?: QuestionStoreListFilter): Promise<QuestionRegistration[]>;
+    get(questionId: string): Promise<QuestionRegistration | null>;
+    insert(registration: QuestionRegistration): Promise<void>;
+    /** Returns the updated row, or null when the id is unknown. */
+    update(questionId: string, patch: QuestionRegistrationPatch): Promise<QuestionRegistration | null>;
+    delete(questionId: string): Promise<boolean>;
+}
+/** Public JSON shape of a registration (GET / list / POST responses). */
+export interface QuestionRegistrationView {
+    questionId: string;
+    derivedScope: string;
+    sourceScopes: string[];
+    question: string;
+    model: string | null;
+    answerShape: AnswerShape | null;
+    recompute: QuestionRecompute;
+    registeredBy: QuestionRegisteredBy;
+    status: QuestionStatus;
+    error: string | null;
+    errorCode: QuestionErrorCode | null;
+    createdAt: string;
+    updatedAt: string;
+    lastComputedAt: string | null;
+    derivedVersion: number | null;
+    derivedCollectedAt: string | null;
+}
+export declare function questionRegistrationView(registration: QuestionRegistration): QuestionRegistrationView;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/derivatives/types.js

@@ -0,0 +1,29 @@
+/**
+ * Derivative compute layer: a builder registers a QUESTION over the owner's
+ * source scopes; the Personal Server answers it locally with an inference
+ * provider and writes the answer as an ordinary derivative record (lineage
+ * = the source data points) into the derived scope. See
+ * docs/derivative-data-api.md, "Compute (question to derivative)".
+ */
+import { cloneAnswerShape } from "./answer-shape.js";
+export function questionRegistrationView(registration) {
+    return {
+        questionId: registration.questionId,
+        derivedScope: registration.derivedScope,
+        sourceScopes: [...registration.sourceScopes],
+        question: registration.question,
+        model: registration.model,
+        answerShape: cloneAnswerShape(registration.answerShape),
+        recompute: registration.recompute,
+        registeredBy: registration.registeredBy,
+        status: registration.status,
+        error: registration.error,
+        errorCode: registration.errorCode,
+        createdAt: registration.createdAt,
+        updatedAt: registration.updatedAt,
+        lastComputedAt: registration.lastComputedAt,
+        derivedVersion: registration.derivedVersion,
+        derivedCollectedAt: registration.derivedCollectedAt,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/derivatives/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/derivatives/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAoB,MAAM,mBAAmB,CAAC;AAkHvE,MAAM,UAAU,wBAAwB,CACtC,YAAkC;IAElC,OAAO;QACL,UAAU,EAAE,YAAY,CAAC,UAAU;QACnC,YAAY,EAAE,YAAY,CAAC,YAAY;QACvC,YAAY,EAAE,CAAC,GAAG,YAAY,CAAC,YAAY,CAAC;QAC5C,QAAQ,EAAE,YAAY,CAAC,QAAQ;QAC/B,KAAK,EAAE,YAAY,CAAC,KAAK;QACzB,WAAW,EAAE,gBAAgB,CAAC,YAAY,CAAC,WAAW,CAAC;QACvD,SAAS,EAAE,YAAY,CAAC,SAAS;QACjC,YAAY,EAAE,YAAY,CAAC,YAAY;QACvC,MAAM,EAAE,YAAY,CAAC,MAAM;QAC3B,KAAK,EAAE,YAAY,CAAC,KAAK;QACzB,SAAS,EAAE,YAAY,CAAC,SAAS;QACjC,SAAS,EAAE,YAAY,CAAC,SAAS;QACjC,SAAS,EAAE,YAAY,CAAC,SAAS;QACjC,cAAc,EAAE,YAAY,CAAC,cAAc;QAC3C,cAAc,EAAE,YAAY,CAAC,cAAc;QAC3C,kBAAkB,EAAE,YAAY,CAAC,kBAAkB;KACpD,CAAC;AACJ,CAAC"}