@massa-ai/core 1.2.1

package/dist/services/checkpoint/checkpoint-store-pg.js

@@ -0,0 +1,476 @@
+/**
+ * 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 { CheckpointType, logger, } from "@massa-ai/shared";
+import { getPrismaClient } from "../query/prisma-client.js";
+import { getProjectIdentityAliasResolver } from "../project-identity/alias-resolver.js";
+import { Prisma } from "../../generated/prisma/index.js";
+import { assertSchemaSupported } from "../structural/schema-version.js";
+/**
+ * Schema-ahead guard for checkpoint state. The `task_checkpoints.state_schema_version`
+ * column is written on every save; the read path (rowToCheckpoint) now refuses
+ * rows written by NEWER code so an unreadable checkpoint never loads silently.
+ *
+ * Kept as a numeric-typed semver-shaped constant: the column is an integer today
+ * (always `1`), but the guard accepts the same `major.minor.patch` compare the
+ * structural guard uses, so a future bump to e.g. `2` or a migrated `"2.0.0"`
+ * string both fail loud against this running binary. Older / equal / null
+ * versions pass through unchanged.
+ */
+const SUPPORTED_CHECKPOINT_STATE_SCHEMA_VERSION = "1.0.0";
+function toNum(v) {
+    if (v == null)
+        return null;
+    return typeof v === "bigint" ? Number(v) : v;
+}
+/** Compress state JSON the same way the PostgreSQL store does (Bun.deflateSync). */
+function compressState(state) {
+    const json = JSON.stringify(state);
+    return Buffer.from(Bun.deflateSync(Buffer.from(json, "utf-8")));
+}
+/** Decompress state bytes the same way the PostgreSQL store does (Bun.inflateSync). */
+function decompressState(data) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const inflated = Bun.inflateSync(new Uint8Array(buf));
+    return JSON.parse(Buffer.from(inflated).toString("utf-8"));
+}
+export class PgCheckpointStore {
+    prisma;
+    /** In-memory mirror: the sync read path. Hydrated from PG on first use. */
+    mirror = new Map();
+    hydrated = false;
+    hydrating = null;
+    /**
+     * 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).
+     */
+    hydrateFailedAt = 0;
+    static HYDRATE_RETRY_MS = 30_000;
+    /** Per-id serialized write chain so commits land in call order. */
+    inflight = new Map();
+    getClient() {
+        if (!this.prisma)
+            this.prisma = getPrismaClient();
+        return this.prisma;
+    }
+    /**
+     * 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.
+     */
+    ensureHydrated() {
+        if (this.hydrated)
+            return Promise.resolve();
+        if (this.hydrating)
+            return this.hydrating;
+        // Rate-limit retries: if the last hydration attempt failed recently,
+        // skip the full SELECT and let the op proceed against the in-memory mirror.
+        // Without this, a persistent PG error turns every op into a full-table
+        // retry storm (hydrated stays false forever → ensureHydrated re-fires).
+        if (this.hydrateFailedAt > 0 &&
+            Date.now() - this.hydrateFailedAt < PgCheckpointStore.HYDRATE_RETRY_MS) {
+            return Promise.resolve();
+        }
+        this.hydrating = (async () => {
+            try {
+                const prisma = this.getClient();
+                const rows = await prisma.$queryRaw `
+          SELECT * FROM task_checkpoints
+        `;
+                const next = new Map();
+                const dbIds = new Set();
+                for (const row of rows) {
+                    dbIds.add(row.id);
+                    next.set(row.id, this.rowToCheckpoint(row));
+                }
+                // Re-apply any in-flight save whose row isn't in the DB snapshot yet.
+                for (const [id, existing] of this.mirror) {
+                    if (!dbIds.has(id))
+                        next.set(id, existing);
+                }
+                this.mirror = next;
+                this.hydrated = true;
+                this.hydrateFailedAt = 0;
+                logger.info("PgCheckpointStore hydrated", {
+                    rows: this.mirror.size,
+                });
+            }
+            catch (e) {
+                this.hydrateFailedAt = Date.now();
+                logger.warn("PgCheckpointStore hydrate failed (best-effort)", {
+                    error: e.message,
+                });
+            }
+            finally {
+                this.hydrating = null;
+            }
+        })();
+        return this.hydrating;
+    }
+    rowToCheckpoint(row) {
+        const state = decompressState(row.state);
+        // Schema-ahead guard: a state_schema_version strictly newer than the code's
+        // supported version means the row was written by newer code and the state
+        // payload may not deserialize/interpret correctly. Fail loud instead of
+        // silently loading a drifted checkpoint. Older / equal / null / legacy
+        // integer stamps (the current `1`) pass through — only strictly-newer throws.
+        const storedSchemaVersion = toNum(row.state_schema_version);
+        if (storedSchemaVersion != null) {
+            const storedVersionString = String(storedSchemaVersion);
+            // Normalize a bare integer like "1" to "1.0.0" so the semver guard can
+            // compare it; non-numeric / malformed strings fall through to the helper
+            // (which treats non-semver as unknown and does NOT throw).
+            const normalized = /^\d+$/u.test(storedVersionString)
+                ? `${storedVersionString}.0.0`
+                : storedVersionString;
+            assertSchemaSupported("checkpoint", normalized, SUPPORTED_CHECKPOINT_STATE_SCHEMA_VERSION);
+        }
+        return {
+            id: row.id,
+            taskId: row.task_id,
+            taskDescription: row.task_description ?? undefined,
+            agentId: row.agent_id ?? undefined,
+            projectId: row.project_id ?? undefined,
+            state,
+            memoryIds: row.memory_ids ? JSON.parse(row.memory_ids) : [],
+            fileChanges: row.file_changes ? JSON.parse(row.file_changes) : [],
+            checkpointType: row.checkpoint_type,
+            parentCheckpointId: row.parent_checkpoint_id ?? undefined,
+            createdAt: toNum(row.created_at) ?? Date.now(),
+            expiresAt: toNum(row.expires_at) ?? undefined,
+        };
+    }
+    // ── Create ───────────────────────────────────────────────────────────────
+    createCheckpoint(state, options = {}) {
+        const { agentId, projectId, checkpointType = CheckpointType.MANUAL, memoryIds = [], fileChanges = [], parentCheckpointId, ttlMs = 7 * 24 * 60 * 60 * 1000, // 7 days
+         } = options;
+        const id = `ckpt_${checkpointType}_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+        const now = Date.now();
+        const expiresAt = now + ttlMs;
+        const checkpoint = {
+            id,
+            taskId: state.taskId,
+            taskDescription: state.description,
+            agentId,
+            projectId,
+            state,
+            memoryIds,
+            fileChanges,
+            checkpointType,
+            parentCheckpointId,
+            createdAt: now,
+            expiresAt,
+        };
+        // Mirror update is synchronous so a subsequent sync read sees the value.
+        this.mirror.set(id, checkpoint);
+        void this.ensureHydrated();
+        // Fire-and-forget persist (best-effort).
+        this.chainWrite(id, async () => {
+            const prisma = this.getClient();
+            // Resolve canonical project id at the persist seam (spec req 3). The
+            // sync mirror keeps the caller's id; the durable row uses the target.
+            const canonicalProjectId = projectId
+                ? await getProjectIdentityAliasResolver().resolve(projectId)
+                : projectId;
+            const compressed = compressState(state);
+            await prisma.$executeRaw `
+        INSERT INTO task_checkpoints (
+          id, task_id, task_description, agent_id, project_id,
+          state, state_schema_version,
+          memory_ids, file_changes,
+          checkpoint_type, parent_checkpoint_id,
+          created_at, expires_at
+        ) VALUES (
+          ${id},
+          ${state.taskId},
+          ${state.description ?? null},
+          ${agentId ?? null},
+          ${canonicalProjectId ?? null},
+          ${compressed},
+          1,
+          ${JSON.stringify(memoryIds)},
+          ${JSON.stringify(fileChanges)},
+          ${checkpointType},
+          ${parentCheckpointId ?? null},
+          ${now}::bigint,
+          ${expiresAt}::bigint
+        )
+        ON CONFLICT (id) DO UPDATE SET
+          task_id = EXCLUDED.task_id,
+          task_description = EXCLUDED.task_description,
+          agent_id = EXCLUDED.agent_id,
+          project_id = EXCLUDED.project_id,
+          state = EXCLUDED.state,
+          state_schema_version = EXCLUDED.state_schema_version,
+          memory_ids = EXCLUDED.memory_ids,
+          file_changes = EXCLUDED.file_changes,
+          checkpoint_type = EXCLUDED.checkpoint_type,
+          parent_checkpoint_id = EXCLUDED.parent_checkpoint_id,
+          created_at = EXCLUDED.created_at,
+          expires_at = EXCLUDED.expires_at
+      `;
+        });
+        logger.info("Checkpoint created (PG)", {
+            id,
+            taskId: state.taskId,
+            type: checkpointType,
+            compressedBytes: compressState(state).byteLength,
+        });
+        return checkpoint;
+    }
+    // ── Read ─────────────────────────────────────────────────────────────────
+    getCheckpoint(checkpointId) {
+        void this.ensureHydrated();
+        return this.mirror.get(checkpointId) ?? null;
+    }
+    listCheckpoints(options = {}) {
+        void this.ensureHydrated();
+        return this.applyFilters(this.mirror.values(), options);
+    }
+    listCheckpointsMetadata(options = {}) {
+        void this.ensureHydrated();
+        const filtered = this.applyFilters(this.mirror.values(), options);
+        return filtered.map((c) => this.checkpointToMetadata(c));
+    }
+    getCheckpointState(checkpointId) {
+        void this.ensureHydrated();
+        const ckpt = this.mirror.get(checkpointId);
+        return ckpt ? ckpt.state : null;
+    }
+    getLatestCheckpoint(taskId) {
+        void this.ensureHydrated();
+        const now = Date.now();
+        let latest = null;
+        for (const ckpt of this.mirror.values()) {
+            if (ckpt.taskId === taskId &&
+                (ckpt.expiresAt == null || ckpt.expiresAt > now)) {
+                if (!latest || ckpt.createdAt > latest.createdAt) {
+                    latest = ckpt;
+                }
+            }
+        }
+        return latest;
+    }
+    // ── Delete / Cleanup ─────────────────────────────────────────────────────
+    deleteCheckpoint(checkpointId) {
+        const existed = this.mirror.has(checkpointId);
+        this.mirror.delete(checkpointId);
+        void this.ensureHydrated();
+        this.chainWrite(checkpointId, async () => {
+            const prisma = this.getClient();
+            await prisma.$executeRaw `
+        DELETE FROM task_checkpoints WHERE id = ${checkpointId}
+      `;
+        });
+        // Best-effort: report whether the mirror had it (durable delete is async).
+        return existed;
+    }
+    purgeExpired() {
+        const now = Date.now();
+        let count = 0;
+        const toRemove = [];
+        for (const ckpt of this.mirror.values()) {
+            if (ckpt.expiresAt != null && ckpt.expiresAt < now) {
+                toRemove.push(ckpt.id);
+                count++;
+            }
+        }
+        for (const id of toRemove)
+            this.mirror.delete(id);
+        if (count > 0) {
+            this.chainWrite("__purge__", async () => {
+                const prisma = this.getClient();
+                await prisma.$executeRaw `
+          DELETE FROM task_checkpoints
+          WHERE expires_at IS NOT NULL AND expires_at < ${now}::bigint
+        `;
+            });
+            logger.info("Expired checkpoints purged (PG)", { count });
+        }
+        return count;
+    }
+    // ── Backend-aware memory existence ───────────────────────────────────────
+    /**
+     * 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.
+     */
+    async countExistingMemoryIds(memoryIds) {
+        if (memoryIds.length === 0)
+            return [];
+        void this.ensureHydrated();
+        const BATCH_SIZE = 1000;
+        const existing = [];
+        try {
+            const prisma = this.getClient();
+            for (let i = 0; i < memoryIds.length; i += BATCH_SIZE) {
+                const batch = memoryIds.slice(i, i + BATCH_SIZE);
+                const rows = await prisma.$queryRaw `
+          SELECT id FROM memories WHERE id IN (${Prisma.join(batch)})
+        `;
+                for (const row of rows)
+                    existing.push(row.id);
+            }
+            return existing;
+        }
+        catch (e) {
+            // Query failed (memories table missing, connection error, ...) —
+            // best-effort: assume all referenced memories exist so a restore is never
+            // blocked by an unrelated query error. Mirrors the PostgreSQL store's catch.
+            logger.warn("countExistingMemoryIds failed (best-effort: assuming all exist)", {
+                error: e.message,
+            });
+            return memoryIds;
+        }
+    }
+    // ── Stats ────────────────────────────────────────────────────────────────
+    getStats() {
+        void this.ensureHydrated();
+        const checkpoints = Array.from(this.mirror.values());
+        const byType = {};
+        let totalSizeBytes = 0;
+        let oldest;
+        for (const c of checkpoints) {
+            byType[c.checkpointType] = (byType[c.checkpointType] ?? 0) + 1;
+            totalSizeBytes += compressState(c.state).byteLength;
+            if (oldest == null || c.createdAt < oldest)
+                oldest = c.createdAt;
+        }
+        return {
+            totalCheckpoints: checkpoints.length,
+            byType,
+            totalSizeBytes,
+            oldestCheckpointAge: oldest != null ? Date.now() - oldest : undefined,
+        };
+    }
+    // ── Readiness ────────────────────────────────────────────────────────────
+    /**
+     * 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() {
+        return this.ensureHydrated();
+    }
+    close() {
+        // Fire-and-forget writes may still be in-flight; they settle against the
+        // shared prisma pool. Nothing to close here (the pool is owned by
+        // getPrismaClient() / disconnectPrisma()).
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    /** Apply the list filters + ordering + limit/offset to a checkpoint iterable. */
+    applyFilters(iter, options) {
+        const { taskId, projectId, checkpointType, includeExpired = false, limit = 20, offset = 0, } = options;
+        const now = Date.now();
+        const out = [];
+        for (const c of iter) {
+            if (taskId && c.taskId !== taskId)
+                continue;
+            if (projectId && c.projectId !== projectId)
+                continue;
+            if (checkpointType && c.checkpointType !== checkpointType)
+                continue;
+            if (!includeExpired && c.expiresAt != null && c.expiresAt <= now)
+                continue;
+            out.push(c);
+        }
+        out.sort((a, b) => b.createdAt - a.createdAt);
+        return out.slice(offset, offset + limit);
+    }
+    checkpointToMetadata(c) {
+        return {
+            id: c.id,
+            taskId: c.taskId,
+            taskDescription: c.taskDescription,
+            agentId: c.agentId,
+            projectId: c.projectId,
+            checkpointType: c.checkpointType,
+            parentCheckpointId: c.parentCheckpointId,
+            createdAt: c.createdAt,
+            expiresAt: c.expiresAt,
+            compressedSizeBytes: compressState(c.state).byteLength,
+            memoryCount: c.memoryIds.length,
+            fileChangeCount: c.fileChanges.length,
+        };
+    }
+    /**
+     * Chain a write onto any in-flight write for the same key so commits land in
+     * call order. Different keys stay concurrent. Mirrors PgSynapseSessionStore.
+     */
+    chainWrite(key, fn) {
+        const prev = this.inflight.get(key) ?? Promise.resolve();
+        const next = prev.then(fn).catch((e) => {
+            logger.warn("PgCheckpointStore write failed (best-effort)", {
+                key,
+                error: e.message,
+            });
+        });
+        this.inflight.set(key, next);
+        // Drop settled entries so the map does not grow.
+        void next.then(() => {
+            if (this.inflight.get(key) === next)
+                this.inflight.delete(key);
+        });
+    }
+    /** Test helper: await in-flight writes. Not for production use. */
+    async __drain() {
+        // Snapshot the pending set ONCE. Re-reading `this.inflight` in a loop would
+        // re-await writes that a concurrent caller repopulated during the drain,
+        // risking a hang under load. We only owe the caller that the writes
+        // in-flight at drain-start have settled.
+        const pending = Array.from(this.inflight.values());
+        if (pending.length > 0)
+            await Promise.allSettled(pending);
+        // A short settle delay covers any write queued during the drain.
+        await new Promise((r) => setTimeout(r, 10));
+    }
+    /** Test helper: force hydration to complete before reading the mirror. */
+    async __hydrate() {
+        await this.ensureHydrated();
+    }
+}
+//# sourceMappingURL=checkpoint-store-pg.js.map

package/dist/services/checkpoint/checkpoint-store-pg.js.map

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

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

@@ -0,0 +1,100 @@
+/**
+ * ICheckpointStore — storage contract for task/INDEX state checkpoints.
+ *
+ * Structural gap #16: checkpoints were PostgreSQL-only (raw legacy local database inside
+ * CheckpointManager). This interface decouples the storage backend from the
+ * CheckpointManager domain facade so a Postgres deployment can persist
+ * checkpoints in the same backend as the rest of the data plane (one-backend
+ * rule, mirroring getMemoryRepository / getScheduledJobStore / getSessionStore).
+ *
+ * Mostly SYNCHRONOUS: create_checkpoint / list_checkpoints + AutoCheckpointer
+ * call these methods without await (create/list stay sync, matching the
+ * PostgreSQL store). `restoreCheckpoint` + `countExistingMemoryIds` ARE async
+ * (Promise-returning) so the PG backend can run a real `SELECT id FROM
+ * memories WHERE id IN (...)` memory-existence check on the restore path
+ * (was a no-op under PG). The single production restore caller
+ * (restore_checkpoint tool handler) already awaits. The PG store otherwise
+ * honors the sync discipline with an in-memory mirror hydrated from PG on
+ * first use + write-through fire-and-forget persists — the same discipline as
+ * PgSynapseSessionStore / PgScheduledJobStore. Callers that must observe
+ * persisted rows immediately after a process restart await `ensureReady()`
+ * before reading (sync backends resolve immediately).
+ */
+import type { TaskCheckpoint, TaskState, CheckpointType } from "@massa-ai/shared";
+export interface CheckpointMetadata {
+    id: string;
+    taskId: string;
+    taskDescription?: string;
+    agentId?: string;
+    projectId?: string;
+    checkpointType: CheckpointType;
+    parentCheckpointId?: string;
+    createdAt: number;
+    expiresAt?: number;
+    compressedSizeBytes: number;
+    memoryCount: number;
+    fileChangeCount: number;
+}
+export interface ListCheckpointsOptions {
+    taskId?: string;
+    projectId?: string;
+    checkpointType?: CheckpointType;
+    includeExpired?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateCheckpointOptions {
+    agentId?: string;
+    projectId?: string;
+    checkpointType?: CheckpointType;
+    memoryIds?: string[];
+    fileChanges?: string[];
+    parentCheckpointId?: string;
+    /** TTL in milliseconds (default: 7 days). */
+    ttlMs?: number;
+}
+export interface CheckpointStats {
+    totalCheckpoints: number;
+    byType: Record<string, number>;
+    totalSizeBytes: number;
+    oldestCheckpointAge?: number;
+}
+export interface ICheckpointStore {
+    /** Create + persist a checkpoint; returns the created checkpoint. */
+    createCheckpoint(state: TaskState, options?: CreateCheckpointOptions): TaskCheckpoint;
+    /** Get a checkpoint by ID (with deserialized state). */
+    getCheckpoint(checkpointId: string): TaskCheckpoint | null;
+    /** List checkpoints (with deserialized state). */
+    listCheckpoints(options?: ListCheckpointsOptions): TaskCheckpoint[];
+    /** List checkpoint metadata without deserializing state (lazy deserialization). */
+    listCheckpointsMetadata(options?: ListCheckpointsOptions): CheckpointMetadata[];
+    /** Get just the deserialized state for a checkpoint (lazy deserialization). */
+    getCheckpointState(checkpointId: string): TaskState | null;
+    /** Get the latest non-expired checkpoint for a task. */
+    getLatestCheckpoint(taskId: string): TaskCheckpoint | null;
+    /** Delete a checkpoint by ID; returns true if a row was removed. */
+    deleteCheckpoint(checkpointId: string): boolean;
+    /** Purge expired checkpoints; returns the count removed. */
+    purgeExpired(): number;
+    /** Aggregate stats. */
+    getStats(): CheckpointStats;
+    /**
+     * Count how many of the given memory ids still exist. Used by the restore
+     * integrity check (valid vs missing referenced memories). Backends that cannot
+     * reach the memories table return all ids as existing (best-effort — never
+     * blocks a restore). Returns a Promise so the PG backend can run a real
+     * `SELECT id FROM memories WHERE id IN (...)` via prisma; the PostgreSQL backend
+     * resolves immediately (it wraps its synchronous result in Promise.resolve).
+     */
+    countExistingMemoryIds(memoryIds: string[]): Promise<string[]>;
+    /**
+     * Await backend readiness before a read (hydration race fix, #16/#18).
+     * Sync backends (PostgreSQL) resolve immediately. The PG backend awaits its
+     * mirror hydration so the first read after a process restart observes
+     * persisted rows.
+     */
+    ensureReady(): Promise<void>;
+    /** Release resources (PostgreSQL closes the DB handle; PG flushes writes). */
+    close(): void;
+}
+//# sourceMappingURL=checkpoint-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../../src/services/checkpoint/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,cAAc,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,gBAAgB,CACd,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,cAAc,CAAC;IAElB,wDAAwD;IACxD,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAE3D,kDAAkD;IAClD,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,cAAc,EAAE,CAAC;IAEpE,mFAAmF;IACnF,uBAAuB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,EAAE,CAAC;IAEhF,+EAA+E;IAC/E,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAE3D,wDAAwD;IACxD,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAE3D,oEAAoE;IACpE,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAEhD,4DAA4D;IAC5D,YAAY,IAAI,MAAM,CAAC;IAEvB,uBAAuB;IACvB,QAAQ,IAAI,eAAe,CAAC;IAE5B;;;;;;;OAOG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE/D;;;;;OAKG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAAC;CACf"}

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

@@ -0,0 +1,24 @@
+/**
+ * ICheckpointStore — storage contract for task/INDEX state checkpoints.
+ *
+ * Structural gap #16: checkpoints were PostgreSQL-only (raw legacy local database inside
+ * CheckpointManager). This interface decouples the storage backend from the
+ * CheckpointManager domain facade so a Postgres deployment can persist
+ * checkpoints in the same backend as the rest of the data plane (one-backend
+ * rule, mirroring getMemoryRepository / getScheduledJobStore / getSessionStore).
+ *
+ * Mostly SYNCHRONOUS: create_checkpoint / list_checkpoints + AutoCheckpointer
+ * call these methods without await (create/list stay sync, matching the
+ * PostgreSQL store). `restoreCheckpoint` + `countExistingMemoryIds` ARE async
+ * (Promise-returning) so the PG backend can run a real `SELECT id FROM
+ * memories WHERE id IN (...)` memory-existence check on the restore path
+ * (was a no-op under PG). The single production restore caller
+ * (restore_checkpoint tool handler) already awaits. The PG store otherwise
+ * honors the sync discipline with an in-memory mirror hydrated from PG on
+ * first use + write-through fire-and-forget persists — the same discipline as
+ * PgSynapseSessionStore / PgScheduledJobStore. Callers that must observe
+ * persisted rows immediately after a process restart await `ensureReady()`
+ * before reading (sync backends resolve immediately).
+ */
+export {};
+//# sourceMappingURL=checkpoint-store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.js","sourceRoot":"","sources":["../../../src/services/checkpoint/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/services/checkpoint/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checkpoint services barrel exports.
+ *
+ * State checkpointing for long-running agent tasks.
+ */
+export { CheckpointManager } from "./checkpoint-manager.js";
+export { AutoCheckpointer } from "./auto-checkpointer.js";
+export type { AutoCheckpointerOptions, CheckpointTrigger } from "./auto-checkpointer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/checkpoint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/services/checkpoint/index.js

@@ -0,0 +1,8 @@
+/**
+ * Checkpoint services barrel exports.
+ *
+ * State checkpointing for long-running agent tasks.
+ */
+export { CheckpointManager } from "./checkpoint-manager.js";
+export { AutoCheckpointer } from "./auto-checkpointer.js";
+//# sourceMappingURL=index.js.map

package/dist/services/checkpoint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}