@massa-ai/core 1.2.1

package/dist/services/checkpoint/auto-checkpointer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Auto Checkpointer
+ *
+ * Tracks operation count and automatically creates checkpoints
+ * at configurable intervals, on errors, or on milestones.
+ *
+ * Agents call `recordOperation()` after each significant action.
+ * The checkpointer decides when to snapshot based on:
+ * - Operation count threshold (default: every 10 ops)
+ * - Error events (immediate checkpoint on failure)
+ * - Milestone markers (explicit "save now" signal)
+ *
+ * This is a thin coordination layer over CheckpointManager.
+ */
+import { TaskState, TaskCheckpoint } from "@massa-ai/shared";
+export type CheckpointTrigger = "operation" | "error" | "milestone";
+export interface AutoCheckpointerOptions {
+    /** Create checkpoint every N operations (default: 10) */
+    operationInterval?: number;
+    /** Agent ID for labeling checkpoints */
+    agentId?: string;
+    /** Project ID for labeling checkpoints */
+    projectId?: string;
+    /** TTL for auto-checkpoints in ms (default: 3 days) */
+    autoTtlMs?: number;
+    /** TTL for milestone checkpoints in ms (default: 14 days) */
+    milestoneTtlMs?: number;
+}
+export declare class AutoCheckpointer {
+    private operationCount;
+    private lastCheckpointId;
+    private checkpointManager;
+    private options;
+    private static instance;
+    static getInstance(options?: AutoCheckpointerOptions): AutoCheckpointer;
+    constructor(options?: AutoCheckpointerOptions);
+    /**
+     * Record an operation and maybe create a checkpoint.
+     *
+     * Call this from tools (store_memory, search_memories, etc.)
+     * after each significant action.
+     *
+     * @returns The checkpoint if one was created, null otherwise.
+     */
+    recordOperation(state: TaskState, trigger?: CheckpointTrigger): TaskCheckpoint | null;
+    /**
+     * Force-create a milestone checkpoint.
+     */
+    markMilestone(state: TaskState): TaskCheckpoint;
+    /**
+     * Force-create an error checkpoint.
+     */
+    markError(state: TaskState, error: Error): TaskCheckpoint;
+    /**
+     * Get the ID of the last created checkpoint.
+     */
+    getLastCheckpointId(): string | null;
+    /**
+     * Get current operation count since last checkpoint.
+     */
+    getOperationCount(): number;
+    /**
+     * Reset the operation counter (called after manual checkpoint).
+     */
+    resetCounter(): void;
+    private createCheckpoint;
+    close(): void;
+}
+//# sourceMappingURL=auto-checkpointer.d.ts.map

package/dist/services/checkpoint/auto-checkpointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-checkpointer.d.ts","sourceRoot":"","sources":["../../../src/services/checkpoint/auto-checkpointer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,SAAS,EACT,cAAc,EAIf,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAUD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IAExD,MAAM,CAAC,WAAW,CAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,gBAAgB;gBAOP,OAAO,CAAC,EAAE,uBAAuB;IAK7C;;;;;;;OAOG;IACH,eAAe,CACb,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,iBAA+B,GACvC,cAAc,GAAG,IAAI;IAcxB;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc;IAI/C;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,cAAc;IAoBzD;;OAEG;IACH,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAIpC;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;OAEG;IACH,YAAY,IAAI,IAAI;IAMpB,OAAO,CAAC,gBAAgB;IAgDxB,KAAK,IAAI,IAAI;CAGd"}

package/dist/services/checkpoint/auto-checkpointer.js

@@ -0,0 +1,143 @@
+/**
+ * Auto Checkpointer
+ *
+ * Tracks operation count and automatically creates checkpoints
+ * at configurable intervals, on errors, or on milestones.
+ *
+ * Agents call `recordOperation()` after each significant action.
+ * The checkpointer decides when to snapshot based on:
+ * - Operation count threshold (default: every 10 ops)
+ * - Error events (immediate checkpoint on failure)
+ * - Milestone markers (explicit "save now" signal)
+ *
+ * This is a thin coordination layer over CheckpointManager.
+ */
+import { CheckpointType, logger, } from "@massa-ai/shared";
+import { CheckpointManager } from "./checkpoint-manager.js";
+const DEFAULT_OPTIONS = {
+    operationInterval: 10,
+    agentId: "",
+    projectId: "",
+    autoTtlMs: 3 * 24 * 60 * 60 * 1000, // 3 days
+    milestoneTtlMs: 14 * 24 * 60 * 60 * 1000, // 14 days
+};
+export class AutoCheckpointer {
+    operationCount = 0;
+    lastCheckpointId = null;
+    checkpointManager;
+    options;
+    static instance = null;
+    static getInstance(options) {
+        if (!AutoCheckpointer.instance) {
+            AutoCheckpointer.instance = new AutoCheckpointer(options);
+        }
+        return AutoCheckpointer.instance;
+    }
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        this.checkpointManager = CheckpointManager.getInstance();
+    }
+    /**
+     * Record an operation and maybe create a checkpoint.
+     *
+     * Call this from tools (store_memory, search_memories, etc.)
+     * after each significant action.
+     *
+     * @returns The checkpoint if one was created, null otherwise.
+     */
+    recordOperation(state, trigger = "operation") {
+        this.operationCount++;
+        const shouldCheckpoint = trigger === "milestone" ||
+            trigger === "error" ||
+            (trigger === "operation" &&
+                this.operationCount >= this.options.operationInterval);
+        if (!shouldCheckpoint)
+            return null;
+        return this.createCheckpoint(state, trigger);
+    }
+    /**
+     * Force-create a milestone checkpoint.
+     */
+    markMilestone(state) {
+        return this.createCheckpoint(state, "milestone");
+    }
+    /**
+     * Force-create an error checkpoint.
+     */
+    markError(state, error) {
+        // Record the error in state context
+        const updatedState = {
+            ...state,
+            context: {
+                ...state.context,
+                errors: [
+                    ...state.context.errors,
+                    {
+                        message: error.message,
+                        timestamp: Date.now(),
+                        step: state.progress.currentStep,
+                    },
+                ],
+            },
+        };
+        return this.createCheckpoint(updatedState, "error");
+    }
+    /**
+     * Get the ID of the last created checkpoint.
+     */
+    getLastCheckpointId() {
+        return this.lastCheckpointId;
+    }
+    /**
+     * Get current operation count since last checkpoint.
+     */
+    getOperationCount() {
+        return this.operationCount;
+    }
+    /**
+     * Reset the operation counter (called after manual checkpoint).
+     */
+    resetCounter() {
+        this.operationCount = 0;
+    }
+    // ── Private ──────────────────────────────────────────────
+    createCheckpoint(state, trigger) {
+        this.operationCount = 0;
+        const checkpointType = trigger === "milestone"
+            ? CheckpointType.MILESTONE
+            : trigger === "error"
+                ? CheckpointType.MANUAL // errors get manual type for longer TTL
+                : CheckpointType.AUTO;
+        const ttlMs = checkpointType === CheckpointType.AUTO
+            ? this.options.autoTtlMs
+            : this.options.milestoneTtlMs;
+        // Update state's checkpoint metadata
+        const finalState = {
+            ...state,
+            lastCheckpointAt: Date.now(),
+            checkpointCount: state.checkpointCount + 1,
+        };
+        const checkpoint = this.checkpointManager.createCheckpoint(finalState, {
+            agentId: this.options.agentId || undefined,
+            projectId: this.options.projectId || undefined,
+            checkpointType,
+            memoryIds: state.context.decisions,
+            fileChanges: state.context.filesModified,
+            parentCheckpointId: this.lastCheckpointId ?? undefined,
+            ttlMs,
+        });
+        this.lastCheckpointId = checkpoint.id;
+        logger.info("AutoCheckpointer: checkpoint created", {
+            checkpointId: checkpoint.id,
+            trigger,
+            type: checkpointType,
+            taskId: state.taskId,
+            operationsSinceLastCheckpoint: this.operationCount,
+        });
+        return checkpoint;
+    }
+    close() {
+        AutoCheckpointer.instance = null;
+    }
+}
+//# sourceMappingURL=auto-checkpointer.js.map

package/dist/services/checkpoint/auto-checkpointer.js.map

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

package/dist/services/checkpoint/checkpoint-manager.d.ts

@@ -0,0 +1,9 @@
+import { PgCheckpointStore } from "./checkpoint-store-pg.js";
+import type { RestoreResult } from "@massa-ai/shared";
+export type { CheckpointMetadata } from "./checkpoint-store.js";
+export declare class CheckpointManager extends PgCheckpointStore {
+    private static instance;
+    static getInstance(): CheckpointManager;
+    restoreCheckpoint(checkpointId: string): Promise<RestoreResult | null>;
+}
+//# sourceMappingURL=checkpoint-manager.d.ts.map

package/dist/services/checkpoint/checkpoint-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.d.ts","sourceRoot":"","sources":["../../../src/services/checkpoint/checkpoint-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,qBAAa,iBAAkB,SAAQ,iBAAiB;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IACzD,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAIjC,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;CAa7E"}

package/dist/services/checkpoint/checkpoint-manager.js

@@ -0,0 +1,25 @@
+/** Backend-neutral checkpoint facade backed exclusively by PostgreSQL. */
+import { requirePostgresDatabaseUrl } from "@massa-ai/shared/config";
+import { PgCheckpointStore } from "./checkpoint-store-pg.js";
+export class CheckpointManager extends PgCheckpointStore {
+    static instance = null;
+    static getInstance() {
+        requirePostgresDatabaseUrl();
+        return this.instance ??= new CheckpointManager();
+    }
+    async restoreCheckpoint(checkpointId) {
+        const checkpoint = this.getCheckpoint(checkpointId);
+        if (!checkpoint)
+            return null;
+        const existing = new Set(await this.countExistingMemoryIds(checkpoint.memoryIds));
+        const validMemoryIds = checkpoint.memoryIds.filter((id) => existing.has(id));
+        const missingMemoryIds = checkpoint.memoryIds.filter((id) => !existing.has(id));
+        const fileConflicts = [];
+        const restoreInstructions = [
+            `Restore checkpoint ${checkpoint.id} for task ${checkpoint.taskId}.`,
+            missingMemoryIds.length ? `Missing memories: ${missingMemoryIds.join(", ")}.` : "All referenced memories are available.",
+        ].join("\n");
+        return { checkpoint, validMemoryIds, missingMemoryIds, fileConflicts, restoreInstructions };
+    }
+}
+//# sourceMappingURL=checkpoint-manager.js.map

package/dist/services/checkpoint/checkpoint-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.js","sourceRoot":"","sources":["../../../src/services/checkpoint/checkpoint-manager.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IAC9C,MAAM,CAAC,QAAQ,GAA6B,IAAI,CAAC;IACzD,MAAM,CAAC,WAAW;QAChB,0BAA0B,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,QAAQ,KAAK,IAAI,iBAAiB,EAAE,CAAC;IACnD,CAAC;IACD,KAAK,CAAC,iBAAiB,CAAC,YAAoB;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QACpD,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QAClF,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,gBAAgB,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAChF,MAAM,aAAa,GAAa,EAAE,CAAC;QACnC,MAAM,mBAAmB,GAAG;YAC1B,sBAAsB,UAAU,CAAC,EAAE,aAAa,UAAU,CAAC,MAAM,GAAG;YACpE,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,wCAAwC;SACzH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC;IAC9F,CAAC"}

package/dist/services/checkpoint/checkpoint-store-pg.d.ts

@@ -0,0 +1,107 @@
+/**
+ * PgCheckpointStore — PostgreSQL parity for the checkpoint store.
+ *
+ * Structural gap #16: checkpoints were PostgreSQL-only (raw legacy local database inside
+ * CheckpointManager). This store provides PG parity so a Postgres deployment
+ * persists task/INDEX execution state in the same backend as the rest of the
+ * data plane (one-backend rule).
+ *
+ * Mirrors PgSynapseSessionStore / PgScheduledJobStore's discipline: the
+ * ICheckpointStore contract is MOSTLY SYNCHRONOUS (create/list + AutoCheckpointer
+ * call them with no await, matching the PostgreSQL store and legacy local database API);
+ * `restoreCheckpoint` + `countExistingMemoryIds` are async so this store can
+ * run a real `SELECT id FROM memories WHERE id IN (...)` on the restore path
+ * (the single production restore caller already awaits). PG is inherently
+ * async, so this store:
+ *   - Writes fire-and-forget (best-effort, logged on failure — matching the
+ *     PostgreSQL store's try/catch best-effort semantics).
+ *   - Reads are served from an in-memory mirror hydrated from PG on first use
+ *     (async) and kept in sync by every create/delete. The mirror is the hot
+ *     read path within a process; PG is the durability + cross-process recovery
+ *     layer (a new process hydrates its mirror from the persisted rows, so a
+ *     checkpoint created before a restart is visible after it once hydration
+ *     settles).
+ *
+ * Uses raw SQL ($executeRaw / $queryRaw) via the shared prisma client — the
+ * same pattern as PgSynapseSessionStore and MemoryRepositoryPg — to avoid the
+ * Prisma 7.7.0 + adapter-pg isObjectEnumValue incompatibility. Reuses
+ * getPrismaClient() (no second pool).
+ *
+ * Schema parity: task_checkpoints (see Prisma model Checkpoint and PG migration
+ * 20260710160000_add_task_checkpoints_pg). State is stored compressed with the
+ * SAME algorithm as the PostgreSQL store (Bun.deflateSync on the JSON) so a row
+ * round-trips byte-for-byte; decompression uses Bun.inflateSync. Note: the PG
+ * store keeps a deserialized in-memory mirror (TaskCheckpoint objects), so the
+ * compressed bytes only matter for parity with any future direct-SQL consumer.
+ */
+import { TaskCheckpoint, TaskState } from "@massa-ai/shared";
+import type { ICheckpointStore, CheckpointMetadata, ListCheckpointsOptions, CreateCheckpointOptions, CheckpointStats } from "./checkpoint-store.js";
+export declare class PgCheckpointStore implements ICheckpointStore {
+    private prisma;
+    /** In-memory mirror: the sync read path. Hydrated from PG on first use. */
+    private mirror;
+    private hydrated;
+    private hydrating;
+    /**
+     * Epoch (ms) of the last failed hydration attempt. Rate-limits retries so a
+     * persistent PG error does not turn every op into a full `SELECT *` retry
+     * storm (hydrated stays false forever → ensureHydrated re-fires every call).
+     */
+    private hydrateFailedAt;
+    private static readonly HYDRATE_RETRY_MS;
+    /** Per-id serialized write chain so commits land in call order. */
+    private inflight;
+    private getClient;
+    /**
+     * Best-effort hydrate the mirror from PG. Resolves (never rejects) — failures
+     * log a warn and leave the mirror empty; the manager can still create
+     * checkpoints in-memory and persist them once PG is reachable.
+     */
+    private ensureHydrated;
+    private rowToCheckpoint;
+    createCheckpoint(state: TaskState, options?: CreateCheckpointOptions): TaskCheckpoint;
+    getCheckpoint(checkpointId: string): TaskCheckpoint | null;
+    listCheckpoints(options?: ListCheckpointsOptions): TaskCheckpoint[];
+    listCheckpointsMetadata(options?: ListCheckpointsOptions): CheckpointMetadata[];
+    getCheckpointState(checkpointId: string): TaskState | null;
+    getLatestCheckpoint(taskId: string): TaskCheckpoint | null;
+    deleteCheckpoint(checkpointId: string): boolean;
+    purgeExpired(): number;
+    /**
+     * Real PG check: `SELECT id FROM memories WHERE id IN (...)` via prisma, so
+     * the restore integrity check reports genuinely missing referenced memories
+     * (was a no-op that returned the input unchanged — silently permissive). The
+     * id list is chunked (BATCH_SIZE per query) to stay under PG's parameter /
+     * packet limits for large checkpoints. On any failure the method falls back to
+     * returning the full input (best-effort, mirroring the PostgreSQL store's
+     * try/catch) so a restore is never blocked by an unrelated query error.
+     *
+     * Now async: `restoreCheckpoint` was made `Promise<RestoreResult|null>`
+     * (pre-mortem SF4 confirmed exactly one production caller, already-async tool
+     * handler, Promise-based MCP/tools-api contract), so the PG store can finally
+     * await prisma here.
+     */
+    countExistingMemoryIds(memoryIds: string[]): Promise<string[]>;
+    getStats(): CheckpointStats;
+    /**
+     * Await mirror hydration before a read (hydration race fix, #16).
+     * The very first read after a process restart returns empty until hydration
+     * settles (typically <100ms). Callers that must observe persisted rows
+     * immediately after restart await this before reading.
+     */
+    ensureReady(): Promise<void>;
+    close(): void;
+    /** Apply the list filters + ordering + limit/offset to a checkpoint iterable. */
+    private applyFilters;
+    private checkpointToMetadata;
+    /**
+     * Chain a write onto any in-flight write for the same key so commits land in
+     * call order. Different keys stay concurrent. Mirrors PgSynapseSessionStore.
+     */
+    private chainWrite;
+    /** Test helper: await in-flight writes. Not for production use. */
+    __drain(): Promise<void>;
+    /** Test helper: force hydration to complete before reading the mirror. */
+    __hydrate(): Promise<void>;
+}
+//# sourceMappingURL=checkpoint-store-pg.d.ts.map

package/dist/services/checkpoint/checkpoint-store-pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store-pg.d.ts","sourceRoot":"","sources":["../../../src/services/checkpoint/checkpoint-store-pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,cAAc,EACd,SAAS,EAGV,MAAM,kBAAkB,CAAC;AAK1B,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAyD/B,qBAAa,iBAAkB,YAAW,gBAAgB;IACxD,OAAO,CAAC,MAAM,CAAgB;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAA8B;IAC/C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAClD,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAyC;IAEzD,OAAO,CAAC,SAAS;IAKjB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA+CtB,OAAO,CAAC,eAAe;IAwCvB,gBAAgB,CACd,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,uBAA4B,GACpC,cAAc;IA6FjB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAK1D,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,EAAE;IAKvE,uBAAuB,CACrB,OAAO,GAAE,sBAA2B,GACnC,kBAAkB,EAAE;IAMvB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAM1D,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAmB1D,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAc/C,YAAY,IAAI,MAAM;IA2BtB;;;;;;;;;;;;;OAaG;IACG,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA4BpE,QAAQ,IAAI,eAAe;IAqB3B;;;;;OAKG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,KAAK,IAAI,IAAI;IAQb,iFAAiF;IACjF,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,oBAAoB;IAiB5B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAelB,mEAAmE;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,0EAA0E;IACpE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}