@oobe-protocol-labs/synapse-client-sdk 1.2.0 → 1.2.2

package/dist/cjs/ai/persistence/helpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module ai/persistence/helpers
+ * @description Serialization utilities, key builders, and PostgreSQL schema
+ * for the Synapse AI persistence layer.
+ *
+ * @since 1.2.2
+ */
+/**
+ * Serialize a value to a JSON string, converting `BigInt` to strings.
+ *
+ * @param value - Any value (may contain `BigInt`, `Map`, nested objects).
+ * @returns JSON string safe for storage.
+ * @since 1.2.2
+ */
+export declare function serialize(value: unknown): string;
+/**
+ * Deserialize a JSON string back to a typed value.
+ *
+ * @typeParam T - Expected return type.
+ * @param json - JSON string from the store.
+ * @returns Parsed value.
+ * @since 1.2.2
+ */
+export declare function deserialize<T = unknown>(json: string): T;
+/**
+ * Build a namespaced Redis key from segments.
+ *
+ * @example
+ * ```ts
+ * buildKey('synapse', 'agent', 'did:agent:1');
+ * // → 'synapse:agent:did:agent:1'
+ * ```
+ *
+ * @param parts - Key segments joined by `:`.
+ * @returns Colon-delimited key string.
+ * @since 1.2.2
+ */
+export declare function buildKey(...parts: string[]): string;
+/**
+ * Strip a prefix from a Redis key and return the remaining segments.
+ *
+ * @param prefix - The prefix to strip (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:id1'`).
+ * @returns Remaining segments after the prefix (e.g. `['agent', 'id1']`).
+ * @since 1.2.2
+ */
+export declare function parseKey(prefix: string, key: string): string[];
+/**
+ * Extract the agent ID from a namespaced Redis key.
+ *
+ * @param prefix - Key prefix (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:my-agent'`).
+ * @returns The agent ID segment, or the full key if pattern doesn't match.
+ * @since 1.2.2
+ */
+export declare function extractAgentId(prefix: string, key: string): string;
+/** Current schema version. Bump when adding migrations. */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Generate the full PostgreSQL DDL for a given table prefix.
+ *
+ * Creates tables:
+ * - `{prefix}_agents`   — agent snapshots (JSONB)
+ * - `{prefix}_sessions` — session records (JSONB)
+ * - `{prefix}_receipts` — payment receipts (JSONB)
+ * - `{prefix}_metrics`  — time-series metric points
+ * - `{prefix}_kv`       — generic key-value store
+ * - `{prefix}_schema_version` — migration tracking
+ *
+ * @param prefix - Table name prefix (default: `'synapse'`).
+ * @returns SQL DDL string ready for `client.query()`.
+ * @since 1.2.2
+ */
+export declare function buildSchema(prefix?: string): string;
+/**
+ * SQL to clean up expired rows from the KV table.
+ *
+ * @param prefix - Table name prefix.
+ * @returns DELETE statement string.
+ * @since 1.2.2
+ */
+export declare function buildKvCleanupSql(prefix?: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/cjs/ai/persistence/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../src/ai/persistence/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAExD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAG9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlE;AAMD,2DAA2D;AAC3D,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAE,MAAkB,GAAG,MAAM,CA2E9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,MAAkB,GAAG,MAAM,CAEpE"}

package/dist/cjs/ai/persistence/helpers.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * @module ai/persistence/helpers
+ * @description Serialization utilities, key builders, and PostgreSQL schema
+ * for the Synapse AI persistence layer.
+ *
+ * @since 1.2.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+exports.serialize = serialize;
+exports.deserialize = deserialize;
+exports.buildKey = buildKey;
+exports.parseKey = parseKey;
+exports.extractAgentId = extractAgentId;
+exports.buildSchema = buildSchema;
+exports.buildKvCleanupSql = buildKvCleanupSql;
+const helpers_1 = require("../../utils/helpers");
+/* ═══════════════════════════════════════════════════════════════
+ *  Serialization
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Serialize a value to a JSON string, converting `BigInt` to strings.
+ *
+ * @param value - Any value (may contain `BigInt`, `Map`, nested objects).
+ * @returns JSON string safe for storage.
+ * @since 1.2.2
+ */
+function serialize(value) {
+    return JSON.stringify((0, helpers_1.toJsonSafe)(value));
+}
+/**
+ * Deserialize a JSON string back to a typed value.
+ *
+ * @typeParam T - Expected return type.
+ * @param json - JSON string from the store.
+ * @returns Parsed value.
+ * @since 1.2.2
+ */
+function deserialize(json) {
+    return JSON.parse(json);
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Redis key builders
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * Build a namespaced Redis key from segments.
+ *
+ * @example
+ * ```ts
+ * buildKey('synapse', 'agent', 'did:agent:1');
+ * // → 'synapse:agent:did:agent:1'
+ * ```
+ *
+ * @param parts - Key segments joined by `:`.
+ * @returns Colon-delimited key string.
+ * @since 1.2.2
+ */
+function buildKey(...parts) {
+    return parts.join(':');
+}
+/**
+ * Strip a prefix from a Redis key and return the remaining segments.
+ *
+ * @param prefix - The prefix to strip (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:id1'`).
+ * @returns Remaining segments after the prefix (e.g. `['agent', 'id1']`).
+ * @since 1.2.2
+ */
+function parseKey(prefix, key) {
+    const stripped = key.startsWith(prefix + ':') ? key.slice(prefix.length + 1) : key;
+    return stripped.split(':');
+}
+/**
+ * Extract the agent ID from a namespaced Redis key.
+ *
+ * @param prefix - Key prefix (e.g. `'synapse'`).
+ * @param key    - Full key (e.g. `'synapse:agent:my-agent'`).
+ * @returns The agent ID segment, or the full key if pattern doesn't match.
+ * @since 1.2.2
+ */
+function extractAgentId(prefix, key) {
+    const parts = parseKey(prefix, key);
+    // Keys are: agent:{id}, session:{agentId}:{sessionId}, etc.
+    return parts.length >= 2 ? parts[1] : key;
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  PostgreSQL schema
+ * ═══════════════════════════════════════════════════════════════ */
+/** Current schema version. Bump when adding migrations. */
+exports.SCHEMA_VERSION = 1;
+/**
+ * Generate the full PostgreSQL DDL for a given table prefix.
+ *
+ * Creates tables:
+ * - `{prefix}_agents`   — agent snapshots (JSONB)
+ * - `{prefix}_sessions` — session records (JSONB)
+ * - `{prefix}_receipts` — payment receipts (JSONB)
+ * - `{prefix}_metrics`  — time-series metric points
+ * - `{prefix}_kv`       — generic key-value store
+ * - `{prefix}_schema_version` — migration tracking
+ *
+ * @param prefix - Table name prefix (default: `'synapse'`).
+ * @returns SQL DDL string ready for `client.query()`.
+ * @since 1.2.2
+ */
+function buildSchema(prefix = 'synapse') {
+    const p = prefix;
+    return `
+-- ═══════════════════════════════════════════════════════════════
+--  Synapse AI Persistence — Schema v${exports.SCHEMA_VERSION}
+--  Prefix: ${p}
+-- ═══════════════════════════════════════════════════════════════
+
+-- Agent snapshots
+CREATE TABLE IF NOT EXISTS ${p}_agents (
+  agent_id   TEXT PRIMARY KEY,
+  snapshot   JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Session records
+CREATE TABLE IF NOT EXISTS ${p}_sessions (
+  id         TEXT NOT NULL,
+  agent_id   TEXT NOT NULL,
+  state      JSONB NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'active',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (agent_id, id)
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_sessions_agent
+  ON ${p}_sessions (agent_id);
+CREATE INDEX IF NOT EXISTS idx_${p}_sessions_status
+  ON ${p}_sessions (status);
+
+-- Payment receipts
+CREATE TABLE IF NOT EXISTS ${p}_receipts (
+  id             TEXT PRIMARY KEY,
+  agent_id       TEXT NOT NULL,
+  session_id     TEXT,
+  receipt        JSONB NOT NULL,
+  amount_charged TEXT NOT NULL DEFAULT '0',
+  settled_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_receipts_agent
+  ON ${p}_receipts (agent_id);
+CREATE INDEX IF NOT EXISTS idx_${p}_receipts_settled
+  ON ${p}_receipts (settled_at DESC);
+
+-- Metric time-series
+CREATE TABLE IF NOT EXISTS ${p}_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  agent_id    TEXT NOT NULL,
+  metric_key  TEXT NOT NULL,
+  value       DOUBLE PRECISION NOT NULL,
+  labels      JSONB DEFAULT '{}',
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE INDEX IF NOT EXISTS idx_${p}_metrics_agent_key
+  ON ${p}_metrics (agent_id, metric_key);
+CREATE INDEX IF NOT EXISTS idx_${p}_metrics_time
+  ON ${p}_metrics (recorded_at DESC);
+
+-- Generic key-value store
+CREATE TABLE IF NOT EXISTS ${p}_kv (
+  key        TEXT PRIMARY KEY,
+  value      JSONB NOT NULL,
+  expires_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS ${p}_schema_version (
+  version    INTEGER PRIMARY KEY,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+INSERT INTO ${p}_schema_version (version) VALUES (${exports.SCHEMA_VERSION})
+  ON CONFLICT (version) DO NOTHING;
+`.trim();
+}
+/**
+ * SQL to clean up expired rows from the KV table.
+ *
+ * @param prefix - Table name prefix.
+ * @returns DELETE statement string.
+ * @since 1.2.2
+ */
+function buildKvCleanupSql(prefix = 'synapse') {
+    return `DELETE FROM ${prefix}_kv WHERE expires_at IS NOT NULL AND expires_at < NOW()`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cjs/ai/persistence/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../src/ai/persistence/helpers.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAeH,8BAEC;AAUD,kCAEC;AAmBD,4BAEC;AAUD,4BAGC;AAUD,wCAIC;AAwBD,kCA2EC;AASD,8CAEC;AAzLD,iDAAiD;AAEjD;;qEAEqE;AAErE;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,KAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAA,oBAAU,EAAC,KAAK,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAc,IAAY;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;qEAEqE;AAErE;;;;;;;;;;;;GAYG;AACH,SAAgB,QAAQ,CAAC,GAAG,KAAe;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,QAAQ,CAAC,MAAc,EAAE,GAAW;IAClD,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnF,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,MAAc,EAAE,GAAW;IACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED;;qEAEqE;AAErE,2DAA2D;AAC9C,QAAA,cAAc,GAAG,CAAC,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,SAAgB,WAAW,CAAC,SAAiB,SAAS;IACpD,MAAM,CAAC,GAAG,MAAM,CAAC;IACjB,OAAO;;uCAE8B,sBAAc;cACvC,CAAC;;;;6BAIc,CAAC;;;;;;;;6BAQD,CAAC;;;;;;;;;iCASG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;iCAQG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;iCAQG,CAAC;OAC3B,CAAC;iCACyB,CAAC;OAC3B,CAAC;;;6BAGqB,CAAC;;;;;;;;6BAQD,CAAC;;;;cAIhB,CAAC,qCAAqC,sBAAc;;CAEjE,CAAC,IAAI,EAAE,CAAC;AACT,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,SAAiB,SAAS;IAC1D,OAAO,eAAe,MAAM,yDAAyD,CAAC;AACxF,CAAC"}

package/dist/cjs/ai/persistence/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module ai/persistence
+ * @description Synapse AI Persistence Layer — Redis, PostgreSQL, and in-memory
+ * adapters for long-term storage of agent snapshots, sessions, receipts,
+ * and metrics.
+ *
+ * ## Architecture
+ *
+ * All adapters implement the universal {@link PersistenceStore} interface
+ * **and** the `PersistenceAdapter` interface from {@link AgentRegistry},
+ * so they work everywhere:
+ *
+ * ```ts
+ * // As a standalone store
+ * const store = new RedisPersistence({ client: redis });
+ * await store.saveAgent(snapshot);
+ *
+ * // As AgentRegistry backend
+ * const registry = new AgentRegistry({ persistence: store });
+ * ```
+ *
+ * ## Adapters
+ *
+ * | Adapter | Backing store | Best for |
+ * |---|---|---|
+ * | {@link MemoryStore} | In-process `Map` | Testing, dev, CLI tools |
+ * | {@link RedisPersistence} | Redis / Valkey | Sessions, caching, pub/sub |
+ * | {@link PostgresPersistence} | PostgreSQL | Analytics, receipts, audit |
+ *
+ * ## Dependency injection
+ *
+ * Redis and PostgreSQL adapters accept a pre-configured client instance
+ * via their constructor config. No runtime dependencies are bundled —
+ * install `ioredis` or `pg` as needed.
+ *
+ * @example Redis quick start
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisPersistence({ client: redis, defaultTtl: 3600 });
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * await store.saveSession(sessionRecord);
+ * await store.recordMetric('agent-1', 'calls', 42);
+ * ```
+ *
+ * @example PostgreSQL quick start
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = new PostgresPersistence({ client: pool });
+ * await store.connect(); // auto-creates tables
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const receipts = await store.listReceipts('agent-1', { limit: 50 });
+ * const stats = await store.getTableStats();
+ * ```
+ *
+ * @example Dual-store pattern (Redis cache + PostgreSQL archive)
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { Pool } from 'pg';
+ * import { RedisPersistence, PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const cache   = new RedisPersistence({ client: new Redis(), defaultTtl: 300 });
+ * const archive = new PostgresPersistence({ client: new Pool() });
+ * await Promise.all([cache.connect(), archive.connect()]);
+ *
+ * // Write to both, read from cache first
+ * async function saveAgent(snapshot) {
+ *   await Promise.all([cache.saveAgent(snapshot), archive.saveAgent(snapshot)]);
+ * }
+ *
+ * async function loadAgent(id) {
+ *   return (await cache.loadAgent(id)) ?? archive.loadAgent(id);
+ * }
+ * ```
+ *
+ * @since 1.2.2
+ */
+export { PersistenceError, type PersistenceStore, type RedisLike, type PgLike, type SessionRecord, type ReceiptRecord, type MetricPoint, type SetOptions, type ListOptions, type MetricQueryOpts, type StoreConfig, type RedisStoreConfig, type PostgresStoreConfig, type MemoryStoreConfig, } from './types';
+export { serialize, deserialize, buildKey, parseKey, extractAgentId, buildSchema, buildKvCleanupSql, SCHEMA_VERSION, } from './helpers';
+export { MemoryStore } from './memory';
+export { RedisPersistence } from './redis';
+export { PostgresPersistence } from './postgresql';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/cjs/ai/persistence/index.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * @module ai/persistence
+ * @description Synapse AI Persistence Layer — Redis, PostgreSQL, and in-memory
+ * adapters for long-term storage of agent snapshots, sessions, receipts,
+ * and metrics.
+ *
+ * ## Architecture
+ *
+ * All adapters implement the universal {@link PersistenceStore} interface
+ * **and** the `PersistenceAdapter` interface from {@link AgentRegistry},
+ * so they work everywhere:
+ *
+ * ```ts
+ * // As a standalone store
+ * const store = new RedisPersistence({ client: redis });
+ * await store.saveAgent(snapshot);
+ *
+ * // As AgentRegistry backend
+ * const registry = new AgentRegistry({ persistence: store });
+ * ```
+ *
+ * ## Adapters
+ *
+ * | Adapter | Backing store | Best for |
+ * |---|---|---|
+ * | {@link MemoryStore} | In-process `Map` | Testing, dev, CLI tools |
+ * | {@link RedisPersistence} | Redis / Valkey | Sessions, caching, pub/sub |
+ * | {@link PostgresPersistence} | PostgreSQL | Analytics, receipts, audit |
+ *
+ * ## Dependency injection
+ *
+ * Redis and PostgreSQL adapters accept a pre-configured client instance
+ * via their constructor config. No runtime dependencies are bundled —
+ * install `ioredis` or `pg` as needed.
+ *
+ * @example Redis quick start
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisPersistence({ client: redis, defaultTtl: 3600 });
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * await store.saveSession(sessionRecord);
+ * await store.recordMetric('agent-1', 'calls', 42);
+ * ```
+ *
+ * @example PostgreSQL quick start
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = new PostgresPersistence({ client: pool });
+ * await store.connect(); // auto-creates tables
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const receipts = await store.listReceipts('agent-1', { limit: 50 });
+ * const stats = await store.getTableStats();
+ * ```
+ *
+ * @example Dual-store pattern (Redis cache + PostgreSQL archive)
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { Pool } from 'pg';
+ * import { RedisPersistence, PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const cache   = new RedisPersistence({ client: new Redis(), defaultTtl: 300 });
+ * const archive = new PostgresPersistence({ client: new Pool() });
+ * await Promise.all([cache.connect(), archive.connect()]);
+ *
+ * // Write to both, read from cache first
+ * async function saveAgent(snapshot) {
+ *   await Promise.all([cache.saveAgent(snapshot), archive.saveAgent(snapshot)]);
+ * }
+ *
+ * async function loadAgent(id) {
+ *   return (await cache.loadAgent(id)) ?? archive.loadAgent(id);
+ * }
+ * ```
+ *
+ * @since 1.2.2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresPersistence = exports.RedisPersistence = exports.MemoryStore = exports.SCHEMA_VERSION = exports.buildKvCleanupSql = exports.buildSchema = exports.extractAgentId = exports.parseKey = exports.buildKey = exports.deserialize = exports.serialize = exports.PersistenceError = void 0;
+/* ── Types ───────────────────────────────────────────────────── */
+var types_1 = require("./types");
+Object.defineProperty(exports, "PersistenceError", { enumerable: true, get: function () { return types_1.PersistenceError; } });
+/* ── Helpers ─────────────────────────────────────────────────── */
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "serialize", { enumerable: true, get: function () { return helpers_1.serialize; } });
+Object.defineProperty(exports, "deserialize", { enumerable: true, get: function () { return helpers_1.deserialize; } });
+Object.defineProperty(exports, "buildKey", { enumerable: true, get: function () { return helpers_1.buildKey; } });
+Object.defineProperty(exports, "parseKey", { enumerable: true, get: function () { return helpers_1.parseKey; } });
+Object.defineProperty(exports, "extractAgentId", { enumerable: true, get: function () { return helpers_1.extractAgentId; } });
+Object.defineProperty(exports, "buildSchema", { enumerable: true, get: function () { return helpers_1.buildSchema; } });
+Object.defineProperty(exports, "buildKvCleanupSql", { enumerable: true, get: function () { return helpers_1.buildKvCleanupSql; } });
+Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return helpers_1.SCHEMA_VERSION; } });
+/* ── Adapters ────────────────────────────────────────────────── */
+var memory_1 = require("./memory");
+Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return memory_1.MemoryStore; } });
+var redis_1 = require("./redis");
+Object.defineProperty(exports, "RedisPersistence", { enumerable: true, get: function () { return redis_1.RedisPersistence; } });
+var postgresql_1 = require("./postgresql");
+Object.defineProperty(exports, "PostgresPersistence", { enumerable: true, get: function () { return postgresql_1.PostgresPersistence; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/ai/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ai/persistence/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;;;AAEH,oEAAoE;AACpE,iCAeiB;AAdf,yGAAA,gBAAgB,OAAA;AAgBlB,oEAAoE;AACpE,qCASmB;AARjB,oGAAA,SAAS,OAAA;AACT,sGAAA,WAAW,OAAA;AACX,mGAAA,QAAQ,OAAA;AACR,mGAAA,QAAQ,OAAA;AACR,yGAAA,cAAc,OAAA;AACd,sGAAA,WAAW,OAAA;AACX,4GAAA,iBAAiB,OAAA;AACjB,yGAAA,cAAc,OAAA;AAGhB,oEAAoE;AACpE,mCAAuC;AAA9B,qGAAA,WAAW,OAAA;AACpB,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AACzB,2CAAmD;AAA1C,iHAAA,mBAAmB,OAAA"}

package/dist/cjs/ai/persistence/memory.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module ai/persistence/memory
+ * @description In-memory persistence store for Synapse AI gateway data.
+ *
+ * Ideal for testing, local development, and single-process deployments
+ * where external database infrastructure is unnecessary.
+ *
+ * Features:
+ * - TTL support on generic key-value entries
+ * - Optional max-entries eviction (FIFO)
+ * - Full {@link PersistenceStore} API
+ * - Drop-in `PersistenceAdapter` for {@link AgentRegistry}
+ *
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const store = new MemoryStore();
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const snap = await store.loadAgent('agent-1');
+ * ```
+ */
+import type { PersistenceStore, MemoryStoreConfig, SetOptions, ListOptions, MetricQueryOpts, SessionRecord, ReceiptRecord, MetricPoint } from './types';
+import type { GatewaySnapshot } from '../gateway/types';
+/**
+ * @description In-memory implementation of {@link PersistenceStore}.
+ *
+ * Data is stored in `Map` instances and does **not** survive process restarts.
+ * TTL is checked lazily on read (no background timers).
+ *
+ * @since 1.2.2
+ */
+export declare class MemoryStore implements PersistenceStore {
+    readonly name = "memory";
+    private readonly maxEntries;
+    private readonly kv;
+    private readonly agents;
+    private readonly sessions;
+    private readonly receipts;
+    private readonly metrics;
+    constructor(config?: MemoryStoreConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, opts?: SetOptions): Promise<void>;
+    del(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    saveAgent(snapshot: GatewaySnapshot): Promise<void>;
+    loadAgent(agentId: string): Promise<GatewaySnapshot | null>;
+    deleteAgent(agentId: string): Promise<boolean>;
+    listAgents(): Promise<string[]>;
+    saveSession(record: SessionRecord): Promise<void>;
+    loadSession(agentId: string, sessionId: string): Promise<SessionRecord | null>;
+    deleteSessions(agentId: string): Promise<number>;
+    listSessions(agentId: string, opts?: ListOptions): Promise<SessionRecord[]>;
+    saveReceipt(record: ReceiptRecord): Promise<void>;
+    listReceipts(agentId: string, opts?: ListOptions): Promise<ReceiptRecord[]>;
+    recordMetric(agentId: string, key: string, value: number, labels?: Record<string, string>): Promise<void>;
+    queryMetrics(agentId: string, key: string, opts?: MetricQueryOpts): Promise<MetricPoint[]>;
+    save(agentId: string, snapshot: GatewaySnapshot): Promise<void>;
+    load(agentId: string): Promise<GatewaySnapshot | null>;
+    delete(agentId: string): Promise<void>;
+    keys(): Promise<string[]>;
+    private enforceEviction;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/cjs/ai/persistence/memory.d.ts.map

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