@namzu/sdk 38.0.0 → 38.2.1

package/dist/manager/resident/delivery-window.js

@@ -0,0 +1,78 @@
+const minuteMs = 60_000;
+const searchMinutes = 72 * 60;
+/**
+ * @experimental Admit delivery within a daily local-time window, without model
+ * calls. The start is inclusive and the end exclusive; equal boundaries are
+ * rejected. Omit this gate when no time restriction is wanted.
+ *
+ * Future admission searches actual UTC minute boundaries, so nonexistent local
+ * times are skipped and repeated times can open the window twice. The search
+ * is bounded to 72 hours and the Date range; no opening returns nextCheckAt:null.
+ * Historic time zones with second-based offsets may defer up to one extra minute.
+ * This gate does not schedule a timer, authorize a destination or send a message.
+ */
+export function createResidentDeliveryWindow(config) {
+    if (!config ||
+        typeof config.timeZone !== 'string' ||
+        config.timeZone.length === 0 ||
+        config.timeZone !== config.timeZone.trim() ||
+        /^[+-]/.test(config.timeZone) ||
+        !Number.isInteger(config.startMinute) ||
+        config.startMinute < 0 ||
+        config.startMinute > 1439 ||
+        !Number.isInteger(config.endMinute) ||
+        config.endMinute < 0 ||
+        config.endMinute > 1439 ||
+        config.startMinute === config.endMinute) {
+        throw new TypeError('Delivery window requires a named time zone and distinct minutes 0–1439.');
+    }
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: config.timeZone,
+            hour: '2-digit',
+            minute: '2-digit',
+            hourCycle: 'h23',
+        });
+    }
+    catch {
+        throw new TypeError('Delivery window requires a valid named time zone.');
+    }
+    const { startMinute, endMinute } = config;
+    const timeZone = formatter.resolvedOptions().timeZone;
+    const allowed = (at) => {
+        const parts = formatter.formatToParts(at);
+        const hour = Number(parts.find((part) => part.type === 'hour')?.value);
+        const minute = Number(parts.find((part) => part.type === 'minute')?.value);
+        const localMinute = hour * 60 + minute;
+        return startMinute < endMinute
+            ? localMinute >= startMinute && localMinute < endMinute
+            : localMinute >= startMinute || localMinute < endMinute;
+    };
+    return (_message, now) => {
+        if (!Number.isFinite(now) || !Number.isFinite(new Date(now).getTime())) {
+            throw new TypeError('Delivery window requires a finite timestamp within the Date range.');
+        }
+        if (allowed(now))
+            return { allow: true };
+        const firstMinute = (Math.floor(now / minuteMs) + 1) * minuteMs;
+        for (let offset = 0; offset < searchMinutes; offset++) {
+            const candidate = firstMinute + offset * minuteMs;
+            if (!Number.isFinite(new Date(candidate).getTime()))
+                break;
+            if (allowed(candidate)) {
+                return {
+                    allow: false,
+                    nextCheckAt: candidate,
+                    reason: `Outside the allowed daily delivery window in ${timeZone}.`,
+                };
+            }
+        }
+        return {
+            allow: false,
+            nextCheckAt: null,
+            reason: `No allowed delivery minute found within the next 72 hours and Date range in ${timeZone}.`,
+        };
+    };
+}
+//# sourceMappingURL=delivery-window.js.map

package/dist/manager/resident/delivery-window.js.map

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

package/dist/manager/resident/host.d.ts

@@ -0,0 +1,78 @@
+import type { ResidentAgendaStore, ResidentPursuit } from './agenda.js';
+import { type ResidentObservation, type ResidentSelection, type ResidentSelector } from './initiative.js';
+import { type ResidentLearningState } from './learning.js';
+import { type ResidentStep } from './loop.js';
+import { type ResidentMessageInput } from './outbox.js';
+import { type ResidentDecision } from './store.js';
+/** @experimental Host result describes execution, not external-effect rollback. */
+export interface ResidentHostResult {
+    readonly status: 'idle' | 'paused' | 'unresolved' | 'cancelled' | 'limit' | 'contended';
+    readonly stepsSettled: number;
+    readonly nextWakeAt: number | null;
+    readonly selection?: ResidentSelection;
+}
+/** @experimental Explicit authorization to drive a finite number of background steps. */
+export interface ResidentHostRunOptions {
+    readonly signal: AbortSignal;
+    readonly maxSteps: number;
+    /** Maximum single idle wait; with keepAlive, also bounds local agenda polling. */
+    readonly maxIdleMs?: number;
+    /** Keep waiting for useful work within this invocation's finite step cap. Default false. */
+    readonly keepAlive?: boolean;
+}
+/** @experimental Immutable context from the agenda snapshot that authorized this admission. */
+export interface ResidentStepContext {
+    readonly agendaRevision: number;
+    readonly learning?: ResidentLearningState;
+}
+/** @experimental A developer callback may bind a different SDK run for each pursuit. */
+export type ResidentPursuitStep = (pursuit: ResidentPursuit, signal: AbortSignal) => ReturnType<ResidentStep>;
+/** @experimental Context-aware callback; existing two-argument steps remain assignable. */
+export type ResidentContextualStep = (pursuit: ResidentPursuit, signal: AbortSignal, context: ResidentStepContext) => ReturnType<ResidentStep>;
+/** @experimental Inspect actual outcomes and resource receipts independently of model prose. */
+export type ResidentObserver = (pursuit: ResidentPursuit, decision: ResidentDecision, signal: AbortSignal) => Promise<ResidentObservation>;
+/** @experimental Host validates content and destination; null means no communication. */
+export type ResidentMessageFactory = (pursuit: ResidentPursuit, decision: ResidentDecision, signal: AbortSignal) => Promise<ResidentMessageInput | null>;
+/** @experimental Opt-in local selection, observed settlement and atomic outbound intent. */
+export interface ResidentHostOptions {
+    readonly select?: ResidentSelector;
+    readonly observe?: ResidentObserver;
+    readonly prepareMessage?: ResidentMessageFactory;
+    /** Bind approved learning to the exact admission snapshot. Default false. */
+    readonly learning?: boolean;
+}
+/**
+ * @experimental Local driver for one durable agenda. Shared agenda admission
+ * prevents overlapping pursuits across processes. Notifications are local;
+ * opt-in keepAlive also rereads durable state on bounded idle timers.
+ */
+export declare class ResidentHost {
+    private readonly agenda;
+    private readonly step;
+    private controller;
+    private active;
+    private idle;
+    private generation;
+    private controls;
+    private controlsPending;
+    private readonly options;
+    constructor(agenda: ResidentAgendaStore, step: ResidentContextualStep, options?: ResidentHostOptions);
+    /** Interrupt local idle waiting after the host learns of new durable state. */
+    notify(): void;
+    private snapshot;
+    private paused;
+    private control;
+    /**
+     * Signal current work and durably close future admission. Resolving this method
+     * is NOT quiescence: await the run promise before claiming the callback stopped.
+     * An interrupted admitted pursuit remains unresolved until reconciled explicitly.
+     */
+    pause(): Promise<void>;
+    /** Reauthorize future work only after this host's previous invocation drained. */
+    resume(): Promise<void>;
+    /** Persist fresh evidence and interrupt this host's idle timer. */
+    wake(id: string, reason: string): Promise<void>;
+    run(options: ResidentHostRunOptions): Promise<ResidentHostResult>;
+    private drive;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/manager/resident/host.d.ts.map

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

package/dist/manager/resident/host.js

@@ -0,0 +1,252 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { residentObservationSchema, } from './initiative.js';
+import { freezeResidentLearning } from './learning.js';
+import { stepResident } from './loop.js';
+import { residentMessageInputSchema } from './outbox.js';
+import { ResidentConflictError, residentDecisionSchema } from './store.js';
+/**
+ * @experimental Local driver for one durable agenda. Shared agenda admission
+ * prevents overlapping pursuits across processes. Notifications are local;
+ * opt-in keepAlive also rereads durable state on bounded idle timers.
+ */
+export class ResidentHost {
+    agenda;
+    step;
+    controller;
+    active;
+    idle;
+    generation = 0;
+    controls = Promise.resolve();
+    controlsPending = 0;
+    options;
+    constructor(agenda, step, options = {}) {
+        this.agenda = agenda;
+        this.step = step;
+        if (options.learning !== undefined && typeof options.learning !== 'boolean')
+            throw new TypeError('Resident learning must be explicitly enabled with a boolean.');
+        if ((options.select || options.learning) && !agenda.executionAt)
+            throw new TypeError('Resident selection or learning requires atomic executionAt support.');
+        if (options.observe && !agenda.settleObserved)
+            throw new TypeError('Resident observation requires atomic settleObserved support.');
+        if (options.prepareMessage && !agenda.settleWithMessage)
+            throw new TypeError('Resident messages require atomic settleWithMessage support.');
+        this.options = Object.freeze({ ...options });
+    }
+    /** Interrupt local idle waiting after the host learns of new durable state. */
+    notify() {
+        this.generation++;
+        this.idle?.abort();
+    }
+    async snapshot() {
+        const state = await this.agenda.read();
+        if (!state)
+            throw new Error('Create the resident agenda before running the host.');
+        return state;
+    }
+    async paused(value) {
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const state = await this.snapshot();
+            if (state.paused === value)
+                return;
+            try {
+                await this.agenda.setPaused(state, value);
+                return;
+            }
+            catch (error) {
+                if (!(error instanceof ResidentConflictError) || attempt === 7)
+                    throw error;
+            }
+        }
+    }
+    control(update) {
+        this.controlsPending++;
+        const pending = this.controls.then(update);
+        this.controls = pending.catch(() => { });
+        return pending.finally(() => {
+            this.controlsPending--;
+        });
+    }
+    /**
+     * Signal current work and durably close future admission. Resolving this method
+     * is NOT quiescence: await the run promise before claiming the callback stopped.
+     * An interrupted admitted pursuit remains unresolved until reconciled explicitly.
+     */
+    async pause() {
+        this.controller?.abort();
+        this.notify();
+        await this.control(() => this.paused(true));
+    }
+    /** Reauthorize future work only after this host's previous invocation drained. */
+    async resume() {
+        if (this.controlsPending)
+            throw new Error('Wait for pending resident controls before resuming.');
+        if (this.active)
+            throw new Error('Wait for the active resident invocation to drain before resuming.');
+        await this.control(() => this.paused(false));
+        this.notify();
+    }
+    /** Persist fresh evidence and interrupt this host's idle timer. */
+    async wake(id, reason) {
+        const state = await this.snapshot();
+        const pursuit = state.pursuits.find((p) => p.id === id);
+        if (!pursuit)
+            throw new Error('Unknown resident pursuit.');
+        await this.agenda.wake(id, pursuit.state, reason, Date.now());
+        this.notify();
+    }
+    run(options) {
+        if (this.controlsPending)
+            throw new Error('Wait for pending resident controls before running.');
+        if (this.active)
+            throw new Error('A resident host invocation is already active.');
+        const maxIdleMs = options.maxIdleMs ?? 60_000;
+        const keepAlive = options.keepAlive ?? false;
+        if (options.keepAlive !== undefined && typeof options.keepAlive !== 'boolean')
+            throw new TypeError('Resident keepAlive must be explicitly enabled with a boolean.');
+        if (!Number.isSafeInteger(options.maxSteps) ||
+            options.maxSteps < 1 ||
+            !Number.isSafeInteger(maxIdleMs) ||
+            maxIdleMs < 0 ||
+            maxIdleMs > 2_147_483_647 ||
+            (keepAlive && maxIdleMs === 0))
+            throw new TypeError('Invalid resident host limits.');
+        const controller = new AbortController();
+        this.controller = controller;
+        const signal = AbortSignal.any([controller.signal, options.signal]);
+        this.active = this.drive(options.maxSteps, maxIdleMs, keepAlive, signal).finally(() => {
+            this.active = undefined;
+            this.controller = undefined;
+            this.idle = undefined;
+        });
+        return this.active;
+    }
+    async drive(maxSteps, maxIdleMs, keepAlive, signal) {
+        let stepsSettled = 0;
+        try {
+            while (true) {
+                signal.throwIfAborted();
+                const observed = this.generation;
+                const state = await this.snapshot();
+                signal.throwIfAborted();
+                if (state.paused)
+                    return { status: 'paused', stepsSettled, nextWakeAt: null };
+                if (state.pursuits.some((p) => p.state.phase === 'running'))
+                    return { status: 'unresolved', stepsSettled, nextWakeAt: null };
+                const waiting = state.pursuits.filter((p) => p.state.phase === 'waiting' && p.state.wakeAt !== null);
+                const now = Date.now();
+                // Fair, deterministic baseline; this is not model-authored initiative.
+                let due = waiting
+                    .filter((p) => (p.state.wakeAt ?? 0) <= now)
+                    .sort((a, b) => a.state.stepsAdmitted - b.state.stepsAdmitted ||
+                    (a.state.wakeAt ?? 0) - (b.state.wakeAt ?? 0) ||
+                    a.id.localeCompare(b.id))[0];
+                let selection;
+                if (due && this.options.select) {
+                    selection = this.options.select(state, now);
+                    signal.throwIfAborted();
+                    if (selection.agendaRevision !== state.revision)
+                        throw new Error('Resident selector returned a stale agenda revision.');
+                    if (selection.pursuitId === null)
+                        due = undefined;
+                    else {
+                        const selectedId = selection.pursuitId;
+                        due = waiting.find((p) => p.id === selectedId && (p.state.wakeAt ?? 0) <= now);
+                        if (!due)
+                            throw new Error('Resident selector chose an ineligible pursuit.');
+                    }
+                }
+                if (due) {
+                    const selected = due;
+                    const context = Object.freeze({
+                        agendaRevision: state.revision,
+                        ...(this.options.learning && state.learning
+                            ? { learning: freezeResidentLearning(state.learning) }
+                            : {}),
+                    });
+                    const execution = this.options.select || this.options.learning
+                        ? this.agenda.executionAt?.(selected.id, state)
+                        : this.agenda.execution(selected.id);
+                    if (!execution)
+                        throw new Error('Resident executionAt support was removed.');
+                    const observe = this.options.observe;
+                    const prepareMessage = this.options.prepareMessage;
+                    const observedExecution = observe || prepareMessage
+                        ? {
+                            read: () => execution.read(),
+                            claim: (...args) => execution.claim(...args),
+                            settle: async (current, decision, at) => {
+                                const disposition = Object.freeze(residentDecisionSchema.parse(decision));
+                                const observed = await observe?.({ ...selected, state: current }, disposition, signal);
+                                signal.throwIfAborted();
+                                const observation = observe
+                                    ? Object.freeze(residentObservationSchema.parse(observed))
+                                    : undefined;
+                                const prepared = await prepareMessage?.({ ...selected, state: current }, disposition, signal);
+                                signal.throwIfAborted();
+                                const message = prepareMessage && prepared !== null
+                                    ? Object.freeze(residentMessageInputSchema.parse(prepared))
+                                    : null;
+                                if (message !== null) {
+                                    if (!this.agenda.settleWithMessage)
+                                        throw new Error('Resident settleWithMessage support was removed.');
+                                    return this.agenda.settleWithMessage(selected.id, current, disposition, message, at, observation);
+                                }
+                                if (observation) {
+                                    if (!this.agenda.settleObserved)
+                                        throw new Error('Resident settleObserved support was removed.');
+                                    return this.agenda.settleObserved(selected.id, current, disposition, observation, at);
+                                }
+                                return execution.settle(current, disposition, at);
+                            },
+                        }
+                        : execution;
+                    const result = await stepResident(observedExecution, (current, abort) => this.step({ ...selected, state: current }, abort, context), signal);
+                    if (result.status === 'idle')
+                        return {
+                            status: result.reason === 'unresolved' ? 'unresolved' : 'contended',
+                            stepsSettled,
+                            nextWakeAt: null,
+                        };
+                    stepsSettled++;
+                    if (stepsSettled >= maxSteps)
+                        return { status: 'limit', stepsSettled, nextWakeAt: null };
+                    continue;
+                }
+                const scheduled = selection?.pursuitId === null
+                    ? waiting.filter((p) => (p.state.wakeAt ?? 0) > now)
+                    : waiting;
+                const nextWakeAt = scheduled.length === 0 ? null : Math.min(...scheduled.map((p) => p.state.wakeAt ?? now));
+                if (observed !== this.generation)
+                    continue;
+                if (!keepAlive && (nextWakeAt === null || nextWakeAt - now > maxIdleMs))
+                    return { status: 'idle', stepsSettled, nextWakeAt, ...(selection ? { selection } : {}) };
+                const delay = nextWakeAt === null
+                    ? maxIdleMs
+                    : keepAlive
+                        ? Math.min(maxIdleMs, nextWakeAt - now)
+                        : nextWakeAt - now;
+                const idle = new AbortController();
+                this.idle = idle;
+                try {
+                    await sleep(Math.max(1, delay), undefined, {
+                        signal: AbortSignal.any([signal, idle.signal]),
+                    });
+                }
+                catch (error) {
+                    if (!idle.signal.aborted || signal.aborted)
+                        throw error;
+                }
+                finally {
+                    if (this.idle === idle)
+                        this.idle = undefined;
+                }
+            }
+        }
+        catch (error) {
+            if (!signal.aborted)
+                throw error;
+            return { status: 'cancelled', stepsSettled, nextWakeAt: null };
+        }
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/manager/resident/host.js.map

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

package/dist/manager/resident/initiative.d.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import type { ResidentAgendaState } from './agenda.js';
+export declare const residentObservationSchema: z.ZodObject<{
+    evidenceKey: z.ZodString;
+    source: z.ZodString;
+    progress: z.ZodNumber;
+    /** All observations and policy costs use the same host-defined resource unit. */
+    costUnits: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    evidenceKey: string;
+    progress: number;
+    costUnits: number | null;
+}, {
+    source: string;
+    evidenceKey: string;
+    progress: number;
+    costUnits: number | null;
+}>;
+/** @experimental Host-validated outcome and measured resource use, never model self-confidence. */
+export type ResidentObservation = Readonly<z.infer<typeof residentObservationSchema>>;
+export declare const residentFeedbackSchema: z.ZodObject<{
+    bestProgress: z.ZodNumber;
+    hasUnobservedSteps: z.ZodDefault<z.ZodBoolean>;
+    stagnantSteps: z.ZodNumber;
+    observations: z.ZodArray<z.ZodObject<{
+        evidenceKey: z.ZodString;
+        source: z.ZodString;
+        progress: z.ZodNumber;
+        /** All observations and policy costs use the same host-defined resource unit. */
+        costUnits: z.ZodNullable<z.ZodNumber>;
+    } & {
+        gain: z.ZodNumber;
+        step: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }, {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    observations: {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }[];
+    bestProgress: number;
+    hasUnobservedSteps: boolean;
+    stagnantSteps: number;
+}, {
+    observations: {
+        source: string;
+        evidenceKey: string;
+        progress: number;
+        costUnits: number | null;
+        gain: number;
+        step: number;
+    }[];
+    bestProgress: number;
+    stagnantSteps: number;
+    hasUnobservedSteps?: boolean | undefined;
+}>;
+/** @experimental Last eight observations; best progress and stagnation survive eviction. */
+export type ResidentFeedback = Readonly<Omit<z.infer<typeof residentFeedbackSchema>, 'observations'>> & {
+    readonly observations: readonly Readonly<z.infer<typeof residentFeedbackSchema>['observations'][number]>[];
+};
+export declare function observeResidentStep(previous: ResidentFeedback | undefined, input: ResidentObservation, step: number): ResidentFeedback;
+export declare function freezeResidentFeedback(value: ResidentFeedback): ResidentFeedback;
+/** @experimental Policy units are chosen by the host; scores are heuristics, not probabilities. */
+export interface ResidentSelectionConfig {
+    readonly progressValue: number;
+    readonly initialExpectedProgress: number;
+    readonly initialExpectedCost: number;
+    readonly maxStagnantSteps?: number;
+}
+/** @experimental Explainable inputs for a single selection; unknown cost is not zero. */
+export interface ResidentCandidate {
+    readonly pursuitId: string;
+    readonly reason: 'eligible' | 'not-due' | 'missing-observation' | 'stalled' | 'unknown-cost' | 'nonpositive-value';
+    readonly expectedGain: number | null;
+    readonly expectedCost: number | null;
+    readonly score: number | null;
+}
+/** @experimental Choice is bound to the whole agenda revision used to compute it. */
+export interface ResidentSelection {
+    readonly agendaRevision: number;
+    readonly pursuitId: string | null;
+    readonly reason: 'selected' | 'paused' | 'unresolved' | 'no-useful-work';
+    readonly candidates: readonly ResidentCandidate[];
+}
+/** @experimental Pure local selection; perform inference inside budgeted steps, not here. */
+export type ResidentSelector = (agenda: ResidentAgendaState, now: number) => ResidentSelection;
+/**
+ * @experimental Cost-aware continuation with an explicit abstention choice.
+ * This is a measured-progress heuristic, not Bayesian value of computation.
+ * A finite bootstrap allowance permits delayed payoffs but may stop too early.
+ */
+export declare function createResidentSelector(config: ResidentSelectionConfig): ResidentSelector;
+//# sourceMappingURL=initiative.d.ts.map

package/dist/manager/resident/initiative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initiative.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/initiative.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAItD,eAAO,MAAM,yBAAyB;;;;IAIrC,iFAAiF;;;;;;;;;;;;EAEhF,CAAA;AAEF,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC,CAAA;AAErF,eAAO,MAAM,sBAAsB;;;;;;;;QAPlC,iFAAiF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBhF,CAAA;AAEF,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CACtC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,EAAE,cAAc,CAAC,CAC5D,GAAG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CACvC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAC9D,EAAE,CAAA;CACH,CAAA;AAED,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,MAAM,GACV,gBAAgB,CAkBlB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAKhF;AAED,mGAAmG;AACnG,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAClC;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EACZ,UAAU,GACV,SAAS,GACT,qBAAqB,GACrB,SAAS,GACT,cAAc,GACd,mBAAmB,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,gBAAgB,CAAA;IACxE,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACjD;AAED,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,KAAK,iBAAiB,CAAA;AAE9F;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAoFxF"}