@massa-ai/core 1.2.1

package/dist/services/synapse/session/session-registry.js

@@ -0,0 +1,241 @@
+/**
+ * SessionRegistry — in-memory store of agent sessions.
+ *
+ * Kept deliberately simple: a Map keyed by sessionId with lazy TTL eviction.
+ * Persistence is out of scope; sessions are by definition ephemeral context
+ * windows for an agent working on a task right now.
+ */
+import { WorkingMemoryBuffer, } from "../buffer/working-memory-buffer.js";
+import { logger } from "@massa-ai/shared";
+const TOKEN_RE = /[a-z0-9_]{2,}/g;
+function tokenize(text) {
+    const tokens = new Set();
+    for (const match of text.toLowerCase().matchAll(TOKEN_RE)) {
+        tokens.add(match[0]);
+    }
+    return tokens;
+}
+const DEFAULT_ACCESS_HISTORY_LIMIT = 1000;
+export class SessionRegistry {
+    sessions = new Map();
+    defaultTtlMs;
+    store;
+    constructor(defaultTtlMs = 3_600_000, store) {
+        this.defaultTtlMs = defaultTtlMs;
+        this.store = store;
+    }
+    create(input, now = Date.now()) {
+        if (this.sessions.has(input.sessionId)) {
+            throw new Error(`Session already exists: ${input.sessionId}`);
+        }
+        const ttl = input.ttlMs ?? this.defaultTtlMs;
+        const session = {
+            sessionId: input.sessionId,
+            ttlMs: ttl,
+            agentId: input.agentId,
+            workspaceId: input.workspaceId,
+            taskContext: input.taskContext,
+            taskTokens: input.taskContext ? tokenize(input.taskContext) : undefined,
+            taskEmbedding: input.taskEmbedding,
+            createdAt: now,
+            expiresAt: now + ttl,
+            accessHistory: new Map(),
+            accessHistoryLimit: input.accessHistoryMaxEntries ?? DEFAULT_ACCESS_HISTORY_LIMIT,
+            buffer: input.bufferConfig ? new WorkingMemoryBuffer(input.bufferConfig) : undefined,
+        };
+        this.sessions.set(session.sessionId, session);
+        // Phase 1: write-through (best-effort).
+        try {
+            this.store?.save(session);
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store save failed:", { error: error.message });
+        }
+        return session;
+    }
+    /**
+     * Await backend readiness before a read (hydration race fix, #18).
+     *
+     * Sync backends (PostgreSQL, Memory) resolve immediately. The PG backend awaits
+     * its in-memory mirror hydration so a session resume immediately after a
+     * process restart observes PG-persisted sessions. Call this before the first
+     * `get()` of a resume flow; the sync `get()` used by the modulation pipeline
+     * stays synchronous.
+     */
+    async ensureReady() {
+        try {
+            await this.store?.ensureReady();
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store ensureReady failed:", { error: error.message });
+        }
+    }
+    /**
+     * Async resume path: await backend hydration, then return the session via the
+     * sync `get()`. Use this for session-resume entry points (REST/MCP) where a
+     * caller must observe a persisted session immediately after a process
+     * restart. The hot-path `process()` pipeline continues to use the sync
+     * `get()`. Project search uses this path before session-aware modulation.
+     */
+    async getAsync(sessionId, now = Date.now()) {
+        await this.ensureReady();
+        return this.get(sessionId, now);
+    }
+    /**
+     * Retrieve a live session. IMP-10: an active `get()` slides the TTL
+     * forward so a session in use does not silently expire mid-task.
+     * The slide is bounded to defaultTtlMs from `now` — accessing a session
+     * never extends it beyond what a fresh `create()` would give.
+     *
+     * NOTE: this is the sync hot path. For backends with an async-warmed read
+     * mirror (PG), the very first call after a process restart may return null
+     * until hydration settles (<100ms). Resume entry points should use
+     * `getAsync()` / `ensureReady()` first.
+     */
+    get(sessionId, now = Date.now()) {
+        let session = this.sessions.get(sessionId);
+        // Phase 1: lazy-load on a hot-cache miss.
+        if (!session && this.store) {
+            try {
+                const loaded = this.store.load(sessionId);
+                if (loaded) {
+                    // Respect TTL on load; an expired persisted session is discarded.
+                    if (loaded.expiresAt <= now) {
+                        this.store.delete(sessionId);
+                        return null;
+                    }
+                    this.sessions.set(sessionId, loaded);
+                    session = loaded;
+                }
+            }
+            catch (error) {
+                logger.warn("[SessionRegistry] store load failed:", { error: error.message });
+            }
+        }
+        if (!session)
+            return null;
+        if (session.expiresAt <= now) {
+            this.sessions.delete(sessionId);
+            try {
+                this.store?.delete(sessionId);
+            }
+            catch (error) {
+                logger.warn("[SessionRegistry] store delete (expired) failed:", { error: error.message });
+            }
+            return null;
+        }
+        const refreshed = now + (session.ttlMs ?? this.defaultTtlMs);
+        if (refreshed > session.expiresAt) {
+            session.expiresAt = refreshed;
+        }
+        return session;
+    }
+    /**
+     * Update the task context for an existing session and refresh its TTL.
+     */
+    updateTaskContext(sessionId, taskContext, taskEmbedding, now = Date.now()) {
+        const session = this.get(sessionId, now);
+        if (!session)
+            return null;
+        session.taskContext = taskContext;
+        session.taskTokens = tokenize(taskContext);
+        if (taskEmbedding)
+            session.taskEmbedding = taskEmbedding;
+        session.expiresAt = now + (session.ttlMs ?? this.defaultTtlMs);
+        try {
+            this.store?.save(session);
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store save (updateTaskContext) failed:", { error: error.message });
+        }
+        return session;
+    }
+    /**
+     * Record that the agent accessed a memory inside this session.
+     * Used by agent-affinity scoring.
+     *
+     * IMP-11: the Map is bounded by `accessHistoryLimit`. Re-recording an
+     * existing key refreshes its recency (delete-then-set), keeping the LRU
+     * intuition exact even with the small overhead.
+     */
+    recordAccess(sessionId, memoryId, now = Date.now()) {
+        const session = this.get(sessionId, now);
+        if (!session)
+            return;
+        const history = session.accessHistory;
+        let nextCount = 1;
+        if (history.has(memoryId)) {
+            const current = history.get(memoryId);
+            nextCount = current + 1;
+            history.delete(memoryId);
+            history.set(memoryId, nextCount);
+        }
+        else {
+            history.set(memoryId, 1);
+        }
+        while (history.size > session.accessHistoryLimit) {
+            const oldest = history.keys().next().value;
+            if (oldest === undefined)
+                break;
+            history.delete(oldest);
+        }
+        // Phase 1: write-through the access touch (best-effort, LRU recency).
+        try {
+            this.store?.recordAccess(sessionId, memoryId, nextCount);
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store recordAccess failed:", { error: error.message });
+        }
+    }
+    delete(sessionId) {
+        const removed = this.sessions.delete(sessionId);
+        try {
+            this.store?.delete(sessionId);
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store delete failed:", { error: error.message });
+        }
+        return removed;
+    }
+    /** Evict expired sessions. Called opportunistically. */
+    evictExpired(now = Date.now()) {
+        let evicted = 0;
+        for (const [id, session] of this.sessions) {
+            if (session.expiresAt <= now) {
+                this.sessions.delete(id);
+                evicted++;
+            }
+        }
+        return evicted;
+    }
+    size() {
+        return this.sessions.size;
+    }
+    /** Test hook. */
+    clear() {
+        this.sessions.clear();
+    }
+}
+let registry = null;
+export function getSessionRegistry() {
+    if (!registry) {
+        // Phase 1: wire the durable PostgreSQL store with an ephemeral fallback.
+        let store;
+        try {
+            // Lazy require to avoid importing legacy local database at module-eval.
+            const { getSessionStore } = require("./session-store.js");
+            store = getSessionStore();
+        }
+        catch (error) {
+            logger.warn("[SessionRegistry] store init failed, falling back to MemorySessionStore:", { error: error.message });
+            const { MemorySessionStore } = require("./session-store.js");
+            store = new MemorySessionStore();
+        }
+        registry = new SessionRegistry(3_600_000, store);
+    }
+    return registry;
+}
+export function resetSessionRegistry() {
+    registry = null;
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/services/synapse/session/session-registry.js.map

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

package/dist/services/synapse/session/session-store-pg.d.ts

@@ -0,0 +1,88 @@
+/**
+ * PgSynapseSessionStore — PostgreSQL parity for the Synapse session store.
+ *
+ * Mirrors PgScheduledJobStore / PgJobStore's discipline: the SessionStore
+ * interface is SYNCHRONOUS (the SessionRegistry calls store.save/load with no
+ * await, matching the PostgreSQL store and legacy local database API). 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 save. 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 session
+ *     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 PgScheduledJobStore and MemoryRepositoryPg — to avoid the
+ * Prisma 7.7.0 + adapter-pg isObjectEnumValue incompatibility. Reuses
+ * getPrismaClient() (no second pool).
+ *
+ * Schema parity: synapse_sessions + synapse_access_history (see Prisma model
+ * SynapseSession / SynapseAccessHistory and PG migration
+ * 20260710120000_add_synapse_sessions_pg). The buffer snapshot + bufferConfig
+ * are reconstructed into a live WorkingMemoryBuffer on load (#17), matching the
+ * PostgreSQL store. ensureReady() exposes the awaited-hydration hook the registry's
+ * resume path uses so a session resume immediately after a process restart
+ * observes PG-persisted sessions (#18).
+ */
+import type { AgentSession } from "../types.js";
+import type { SessionStore } from "./session-store.js";
+export declare class PgSynapseSessionStore implements SessionStore {
+    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-sessionId serialized write chain. recordAccess fires frequently for one
+     * session; without ordering, concurrent upserts on the same row have no
+     * commit-order guarantee — an earlier touch could commit after a later one
+     * and leave stale counts. Chaining each persist onto the previous in-flight
+     * write for that sessionId guarantees commits land in call order. Different
+     * sessionIds remain concurrent (independent rows). Settled entries are
+     * dropped so the map does not grow. Mirrors PgJobStore's inflight pattern.
+     */
+    private inflight;
+    private getClient;
+    /**
+     * Best-effort hydrate the mirror from PG. Resolves (never rejects) — failures
+     * log a warn and leave the mirror empty; the registry can still create
+     * sessions in-memory and persist them once PG is reachable. Also rehydrates
+     * access history per session so the loaded AgentSession is complete.
+     */
+    private ensureHydrated;
+    private rowToSession;
+    save(session: AgentSession): void;
+    load(sessionId: string): AgentSession | null;
+    /**
+     * Await mirror hydration before a read (hydration race fix, #18).
+     *
+     * The SessionStore read contract is synchronous, but this store serves reads
+     * from an in-memory mirror hydrated from PG on first use. The very first
+     * `load()` after a process restart returns null until hydration settles
+     * (typically <100ms). Callers that must observe a persisted session
+     * immediately after restart (session resume) await this before reading.
+     * Sync backends resolve immediately.
+     */
+    ensureReady(): Promise<void>;
+    delete(sessionId: string): void;
+    recordAccess(sessionId: string, memoryId: string, count: number): void;
+    /**
+     * Chain a write onto any in-flight write for the same key so commits land in
+     * call order. Different keys stay concurrent. Mirrors PgJobStore.inflight.
+     */
+    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=session-store-pg.d.ts.map

package/dist/services/synapse/session/session-store-pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store-pg.d.ts","sourceRoot":"","sources":["../../../../src/services/synapse/session/session-store-pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgCvD,qBAAa,qBAAsB,YAAW,YAAY;IACxD,OAAO,CAAC,MAAM,CAAgB;IAC9B,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAwC;IACtD,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;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAyC;IAEzD,OAAO,CAAC,SAAS;IAKjB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IA2DtB,OAAO,CAAC,YAAY;IA+CpB,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IA8EjC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAK5C;;;;;;;;;OASG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAa/B,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqBtE;;;OAGG;IACH,OAAO,CAAC,UAAU;IAelB,mEAAmE;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,0EAA0E;IACpE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}

package/dist/services/synapse/session/session-store-pg.js

@@ -0,0 +1,334 @@
+/**
+ * PgSynapseSessionStore — PostgreSQL parity for the Synapse session store.
+ *
+ * Mirrors PgScheduledJobStore / PgJobStore's discipline: the SessionStore
+ * interface is SYNCHRONOUS (the SessionRegistry calls store.save/load with no
+ * await, matching the PostgreSQL store and legacy local database API). 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 save. 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 session
+ *     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 PgScheduledJobStore and MemoryRepositoryPg — to avoid the
+ * Prisma 7.7.0 + adapter-pg isObjectEnumValue incompatibility. Reuses
+ * getPrismaClient() (no second pool).
+ *
+ * Schema parity: synapse_sessions + synapse_access_history (see Prisma model
+ * SynapseSession / SynapseAccessHistory and PG migration
+ * 20260710120000_add_synapse_sessions_pg). The buffer snapshot + bufferConfig
+ * are reconstructed into a live WorkingMemoryBuffer on load (#17), matching the
+ * PostgreSQL store. ensureReady() exposes the awaited-hydration hook the registry's
+ * resume path uses so a session resume immediately after a process restart
+ * observes PG-persisted sessions (#18).
+ */
+import { logger } from "@massa-ai/shared";
+import { getPrismaClient } from "../../query/prisma-client.js";
+import { getProjectIdentityAliasResolver } from "../../project-identity/alias-resolver.js";
+import { restoreWorkingMemoryBuffer, snapshotWorkingMemoryBuffer, } from "../buffer/working-memory-buffer.js";
+function toNum(v) {
+    if (v == null)
+        return null;
+    return typeof v === "bigint" ? Number(v) : v;
+}
+export class PgSynapseSessionStore {
+    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-sessionId serialized write chain. recordAccess fires frequently for one
+     * session; without ordering, concurrent upserts on the same row have no
+     * commit-order guarantee — an earlier touch could commit after a later one
+     * and leave stale counts. Chaining each persist onto the previous in-flight
+     * write for that sessionId guarantees commits land in call order. Different
+     * sessionIds remain concurrent (independent rows). Settled entries are
+     * dropped so the map does not grow. Mirrors PgJobStore's inflight pattern.
+     */
+    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 registry can still create
+     * sessions in-memory and persist them once PG is reachable. Also rehydrates
+     * access history per session so the loaded AgentSession is complete.
+     */
+    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 < PgSynapseSessionStore.HYDRATE_RETRY_MS) {
+            return Promise.resolve();
+        }
+        this.hydrating = (async () => {
+            try {
+                const prisma = this.getClient();
+                const rows = await prisma.$queryRaw `
+          SELECT * FROM synapse_sessions
+        `;
+                const accessRows = await prisma.$queryRaw `
+          SELECT * FROM synapse_access_history
+        `;
+                const accessBySession = new Map();
+                for (const a of accessRows) {
+                    let m = accessBySession.get(a.session_id);
+                    if (!m) {
+                        m = new Map();
+                        accessBySession.set(a.session_id, m);
+                    }
+                    m.set(a.memory_id, Number(a.access_count));
+                }
+                const next = new Map();
+                const dbIds = new Set();
+                for (const row of rows) {
+                    dbIds.add(row.session_id);
+                    next.set(row.session_id, this.rowToSession(row, accessBySession.get(row.session_id)));
+                }
+                // 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("PgSynapseSessionStore hydrated", {
+                    rows: this.mirror.size,
+                });
+            }
+            catch (e) {
+                this.hydrateFailedAt = Date.now();
+                logger.warn("PgSynapseSessionStore hydrate failed (best-effort)", {
+                    error: e.message,
+                });
+            }
+            finally {
+                this.hydrating = null;
+            }
+        })();
+        return this.hydrating;
+    }
+    rowToSession(row, accessMap) {
+        const taskTokens = row.task_tokens
+            ? new Set(JSON.parse(row.task_tokens))
+            : undefined;
+        let taskEmbedding;
+        if (row.task_embedding) {
+            // pg returns BYTEA as a Buffer. Reconstruct the Float32Array → number[].
+            const buf = Buffer.isBuffer(row.task_embedding)
+                ? row.task_embedding
+                : Buffer.from(row.task_embedding);
+            taskEmbedding = Array.from(new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4));
+        }
+        const accessHistory = accessMap ?? new Map();
+        // Buffer (#17): reconstruct the live WorkingMemoryBuffer from the persisted
+        // bufferConfig + best-effort snapshot so a session resumed after a process
+        // restart keeps its primed working-set. Mirrors the PostgreSQL store's restore.
+        const bufferConfig = row.buffer_config
+            ? JSON.parse(row.buffer_config)
+            : undefined;
+        const snapshot = row.buffer_snapshot
+            ? JSON.parse(row.buffer_snapshot)
+            : undefined;
+        const buffer = bufferConfig
+            ? restoreWorkingMemoryBuffer(snapshot ?? { entries: [], config: bufferConfig })
+            : undefined;
+        const session = {
+            sessionId: row.session_id,
+            agentId: row.agent_id,
+            workspaceId: row.workspace_id ?? undefined,
+            taskContext: row.task_context ?? undefined,
+            taskTokens,
+            taskEmbedding,
+            ttlMs: Number(row.ttl_ms),
+            createdAt: Number(row.created_at),
+            expiresAt: Number(row.expires_at),
+            accessHistory,
+            accessHistoryLimit: Number(row.access_history_limit),
+            buffer,
+        };
+        return session;
+    }
+    save(session) {
+        // Mirror update is synchronous so a subsequent sync load() sees the value.
+        this.mirror.set(session.sessionId, session);
+        void this.ensureHydrated();
+        // Fire-and-forget persist (best-effort, matching PgScheduledJobStore).
+        this.chainWrite(session.sessionId, async () => {
+            const prisma = this.getClient();
+            // Resolve canonical workspace id at the persist seam (spec req 3). The
+            // sync mirror keeps the caller's id; the durable row uses the target.
+            const canonicalWorkspaceId = session.workspaceId
+                ? await getProjectIdentityAliasResolver().resolve(session.workspaceId)
+                : session.workspaceId;
+            const now = Date.now();
+            const taskTokens = session.taskTokens
+                ? JSON.stringify(Array.from(session.taskTokens))
+                : null;
+            const taskEmbedding = session.taskEmbedding
+                ? Buffer.from(new Float32Array(session.taskEmbedding).buffer)
+                : null;
+            const bufferConfig = session.buffer
+                ? JSON.stringify(session.buffer.config)
+                : null;
+            const bufferSnapshot = session.buffer
+                ? JSON.stringify(snapshotWorkingMemoryBuffer(session))
+                : null;
+            await prisma.$executeRaw `
+        INSERT INTO synapse_sessions (
+          session_id, agent_id, workspace_id, task_context, task_tokens, task_embedding,
+          ttl_ms, created_at, expires_at, access_history_limit, buffer_config, buffer_snapshot,
+          updated_at
+        ) VALUES (
+          ${session.sessionId},
+          ${session.agentId},
+          ${canonicalWorkspaceId ?? null},
+          ${session.taskContext ?? null},
+          ${taskTokens},
+          ${taskEmbedding},
+          ${session.ttlMs}::bigint,
+          ${session.createdAt}::bigint,
+          ${session.expiresAt}::bigint,
+          ${session.accessHistoryLimit},
+          ${bufferConfig},
+          ${bufferSnapshot},
+          ${now}::bigint
+        )
+        ON CONFLICT (session_id) DO UPDATE SET
+          agent_id = EXCLUDED.agent_id,
+          workspace_id = EXCLUDED.workspace_id,
+          task_context = EXCLUDED.task_context,
+          task_tokens = EXCLUDED.task_tokens,
+          task_embedding = EXCLUDED.task_embedding,
+          ttl_ms = EXCLUDED.ttl_ms,
+          expires_at = EXCLUDED.expires_at,
+          access_history_limit = EXCLUDED.access_history_limit,
+          buffer_config = EXCLUDED.buffer_config,
+          buffer_snapshot = EXCLUDED.buffer_snapshot,
+          updated_at = EXCLUDED.updated_at
+      `;
+            // Persist access history (replace strategy: clear + reinsert, matching
+            // the PostgreSQL store). Runs in the same chained write so it stays ordered
+            // relative to the session upsert.
+            await prisma.$executeRaw `
+        DELETE FROM synapse_access_history WHERE session_id = ${session.sessionId}
+      `;
+            for (const [memoryId, count] of session.accessHistory) {
+                await prisma.$executeRaw `
+          INSERT INTO synapse_access_history (session_id, memory_id, access_count, last_accessed_at)
+          VALUES (${session.sessionId}, ${memoryId}, ${count}, ${now}::bigint)
+          ON CONFLICT (session_id, memory_id) DO UPDATE SET
+            access_count = EXCLUDED.access_count,
+            last_accessed_at = EXCLUDED.last_accessed_at
+        `;
+            }
+        });
+    }
+    load(sessionId) {
+        void this.ensureHydrated();
+        return this.mirror.get(sessionId) ?? null;
+    }
+    /**
+     * Await mirror hydration before a read (hydration race fix, #18).
+     *
+     * The SessionStore read contract is synchronous, but this store serves reads
+     * from an in-memory mirror hydrated from PG on first use. The very first
+     * `load()` after a process restart returns null until hydration settles
+     * (typically <100ms). Callers that must observe a persisted session
+     * immediately after restart (session resume) await this before reading.
+     * Sync backends resolve immediately.
+     */
+    ensureReady() {
+        return this.ensureHydrated();
+    }
+    delete(sessionId) {
+        this.mirror.delete(sessionId);
+        this.chainWrite(sessionId, async () => {
+            const prisma = this.getClient();
+            await prisma.$executeRaw `
+        DELETE FROM synapse_sessions WHERE session_id = ${sessionId}
+      `;
+            await prisma.$executeRaw `
+        DELETE FROM synapse_access_history WHERE session_id = ${sessionId}
+      `;
+        });
+    }
+    recordAccess(sessionId, memoryId, count) {
+        void this.ensureHydrated();
+        // Mirror the access touch synchronously so a sync load() sees the bump.
+        const session = this.mirror.get(sessionId);
+        if (session) {
+            session.accessHistory.set(memoryId, count);
+        }
+        // Fire-and-forget persist (best-effort).
+        this.chainWrite(`${sessionId}#access`, async () => {
+            const prisma = this.getClient();
+            const now = Date.now();
+            await prisma.$executeRaw `
+        INSERT INTO synapse_access_history (session_id, memory_id, access_count, last_accessed_at)
+        VALUES (${sessionId}, ${memoryId}, ${count}, ${now}::bigint)
+        ON CONFLICT (session_id, memory_id) DO UPDATE SET
+          access_count = EXCLUDED.access_count,
+          last_accessed_at = EXCLUDED.last_accessed_at
+      `;
+        });
+    }
+    /**
+     * Chain a write onto any in-flight write for the same key so commits land in
+     * call order. Different keys stay concurrent. Mirrors PgJobStore.inflight.
+     */
+    chainWrite(key, fn) {
+        const prev = this.inflight.get(key) ?? Promise.resolve();
+        const next = prev.then(fn).catch((e) => {
+            logger.warn("PgSynapseSessionStore 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=session-store-pg.js.map