mastra-pg-pubsub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Hoffmeister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# mastra-pg-pubsub
+
+[![CI](https://github.com/alanhoff/mastra-pg-pubsub/actions/workflows/ci.yml/badge.svg)](https://github.com/alanhoff/mastra-pg-pubsub/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/mastra-pg-pubsub.svg)](https://www.npmjs.com/package/mastra-pg-pubsub)
+[![license](https://img.shields.io/npm/l/mastra-pg-pubsub.svg)](./LICENSE)
+
+PostgreSQL-backed [`PubSub`](https://mastra.ai/reference/pubsub/base) for Mastra. It gives Mastra apps at-least-once delivery, consumer groups, replay by offset, optional dead-lettering, and low-latency `LISTEN/NOTIFY` wakeups using a database you already operate.
+
+## Why
+
+Use this when you want Mastra agent/workflow events to survive process restarts and coordinate across multiple Node processes without adding Redis, NATS, or a cloud queue.
+
+- **At-least-once delivery** with ack/nack and visibility timeouts.
+- **Consumer groups** for competing workers (`subscribe(..., { group })`).
+- **Fan-out** for groupless subscribers.
+- **Replay** via `getHistory`, `subscribeWithReplay`, and `subscribeFromOffset`.
+- **Crash recovery** through durable delivery rows and visibility timeout redelivery.
+- **Low latency** through Postgres `LISTEN/NOTIFY`, with polling as the correctness backstop.
+- **Small runtime surface**: one runtime dependency (`pg`), ESM, strict TypeScript, Node-native tests.
+
+## Install
+
+```sh
+npm install mastra-pg-pubsub @mastra/core
+```
+
+`@mastra/core` is a peer dependency. `pg` is installed as this package's runtime dependency. If your app already owns a `pg.Pool`, pass it in instead of a connection string.
+
+## Quickstart
+
+```ts
+import { Agent } from '@mastra/core/agent';
+import { Mastra } from '@mastra/core/mastra';
+import { PostgresPubSub } from 'mastra-pg-pubsub';
+
+const pubsub = new PostgresPubSub({
+  connectionString: process.env.DATABASE_URL,
+  schema: 'mastra_pubsub',
+});
+
+await pubsub.migrate(); // optional; methods migrate lazily too
+
+export const mastra = new Mastra({
+  pubsub,
+  agents: {
+    assistant: new Agent({
+      id: 'assistant',
+      name: 'Assistant',
+      instructions: 'You are helpful.',
+      model: 'openai/gpt-4o-mini',
+    }),
+  },
+});
+```
+
+You can also use it directly through the Mastra PubSub contract:
+
+```ts
+await pubsub.subscribe('agent.stream.run-123', (event, ack, nack) => {
+  try {
+    console.log(event.type, event.index, event.data);
+    ack?.();
+  } catch {
+    nack?.();
+  }
+});
+
+await pubsub.publish('agent.stream.run-123', {
+  type: 'chunk',
+  data: { text: 'hello' },
+  runId: 'run-123',
+});
+```
+
+## Replay examples
+
+```ts
+const history = await pubsub.getHistory('agent.stream.run-123', 10);
+
+await pubsub.subscribeWithReplay('agent.stream.run-123', (event, ack) => {
+  ack?.();
+});
+
+await pubsub.subscribeFromOffset('agent.stream.run-123', 42, (event, ack) => {
+  ack?.();
+});
+```
+
+Replay registers the live subscription first, then replays history, deduping the boundary by event `index` so no event is missed or delivered twice at the transition.
+
+## Configuration
+
+Provide exactly one of `connectionString` or `pool`.
+
+| Option | Default | Description |
+| --- | ---: | --- |
+| `connectionString` | — | PostgreSQL connection string. The adapter owns and closes its pool. |
+| `pool` | — | Bring-your-own `pg.Pool`; never closed by `PostgresPubSub.close()`. |
+| `schema` | `mastra_pubsub` | Schema for all tables. Must match `^[a-z_][a-z0-9_]*$`. |
+| `pollIntervalMs` | `1000` | Backstop polling interval and redelivery detection bound. |
+| `ackDeadlineMs` | `30000` | Visibility timeout before unacked deliveries can be reclaimed. |
+| `nackDelayMs` | `0` | Delay before a nacked delivery becomes visible again. |
+| `maxDeliveryAttempts` | `5` | Attempts before drop/dead-letter. `Infinity` disables the cap; `0` is treated as `Infinity`. |
+| `batchSize` | `32` | Deliveries claimed per consume-loop tick. |
+| `maxEventsPerTopic` | `10000` | Retention cap per topic. `0` keeps everything. |
+| `cleanupIntervalMs` | `60000` | Maintenance interval. `0` disables maintenance. |
+| `staleSubscriptionMs` | `300000` | Age before stale private subscriptions are pruned. |
+| `listen` | `true` | Enable `LISTEN/NOTIFY` wakeups. `false` uses polling only. |
+| `deadLetter` | `false` | Copy exhausted events to `dead_events`. |
+| `logger` | silent | Optional `debug`, `warn`, and `error` functions. |
+
+## Delivery guarantees
+
+| Property | Guarantee |
+| --- | --- |
+| Delivery | At least once; `ack()` settles, missing ack redelivers after `ackDeadlineMs`. |
+| Ordering | Per-topic `index` order for normal delivery; retries can interleave with newer events. |
+| Groups | Each event is delivered to one member per group. |
+| Fan-out | Each groupless subscriber receives every event published after it subscribes. |
+| Replay | Historical events are ordered by per-topic `index` and available until retention trims them. |
+| Idempotency | Event `id` is stable across redeliveries for consumer-side dedupe. |
+| Lifecycle | `flush()` drains in-flight local work; `close()` is idempotent and cleans private subscriptions. |
+
+This is intentionally **not exactly-once** delivery. Consumers that perform side effects should dedupe by `event.id` or a domain idempotency key.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  P[publish] -->|tx: bump topic counter, insert event + deliveries, NOTIFY| DB[(PostgreSQL)]
+  DB -->|NOTIFY wakeup / poll| L[consume loop per subscription]
+  L -->|claim batch: FOR UPDATE SKIP LOCKED + visibility timeout| DB
+  L -->|event, ack, nack| CB[EventCallback]
+  CB -->|ack: DELETE delivery| DB
+  CB -->|nack: visible_at = now()+nackDelay| DB
+```
+
+The schema is created lazily under a Postgres advisory lock, or explicitly with `await pubsub.migrate()`.
+
+## Local development
+
+```sh
+npm install
+npm run db:up
+npm test
+npm run test:coverage
+npm run typecheck
+npm run lint
+npm run build
+```
+
+`npm test` is key-free and uses the pinned Postgres service from `docker-compose.yml` on port `5544`.
+
+### Real e2e tests
+
+The e2e suite includes one real Mastra durable-agent stream backed by OpenAI and Postgres memory, plus no-OpenAI delivery semantics tests. The real agent test intentionally validates the durable-agent stream API and topic shape for the locked `@mastra/core` version; refresh it when upgrading Mastra.
+
+```sh
+OPENAI_API_KEY=... # or put it in .env
+npm run db:up
+npm run test:e2e
+```
+
+The script loads `.env` when present with Node's `--env-file-if-exists=.env`, so an exported `OPENAI_API_KEY` also works. Keep `.env` out of git.
+
+## Package contents
+
+`npm pack --dry-run` should include only the built `dist/` files plus package metadata, README, and license. Source, tests, local research notes, and `.env` are not published.

package/dist/consume-loop.d.ts

@@ -0,0 +1,46 @@
+import type { EventCallback } from '@mastra/core/events';
+import type { Pool } from 'pg';
+import type { ResolvedConfig } from './types.ts';
+/**
+ * Round-robin set of local callbacks bound to one (topic, subscription) pair.
+ * Group subscriptions round-robin a claimed event across local members;
+ * private (fan-out) subscriptions deliver every event to their single member.
+ */
+export interface CallbackRegistry {
+    /** Ordered callbacks; group loops round-robin, private loops use index 0. */
+    readonly callbacks: EventCallback[];
+    /** Rotating cursor for round-robin group dispatch. */
+    cursor: number;
+}
+/**
+ * One consume loop per (topic, subscription id). Claims batches with
+ * `FOR UPDATE SKIP LOCKED`, extends visibility, delivers sequentially, and
+ * settles deliveries via ack/nack or visibility timeout. Woken by
+ * `LISTEN/NOTIFY` and by a polling backstop that also reclaims expired
+ * deliveries.
+ */
+export declare class ConsumeLoop {
+    #private;
+    /**
+     * @param pool - Connection pool.
+     * @param schema - Validated schema name.
+     * @param config - Resolved configuration.
+     * @param topic - Subscribed topic.
+     * @param subscriptionId - Subscription row id (group name or private id).
+     * @param isGroup - Whether this is a competing-consumer group.
+     * @param registry - Shared local callback registry for this subscription.
+     */
+    constructor(pool: Pool, schema: string, config: ResolvedConfig, topic: string, subscriptionId: string, isGroup: boolean, registry: CallbackRegistry);
+    /** Start the background loop. Safe to call once. */
+    start(): void;
+    /** Request an immediate poll (used by NOTIFY wakeups). */
+    wake(): void;
+    /**
+     * Resolve once the loop is idle with no claimable work and no in-flight
+     * deliveries — the basis for `flush()`.
+     */
+    drain(): Promise<void>;
+    /** Stop the loop and wait for it to settle. Idempotent. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=consume-loop.d.ts.map

package/dist/consume-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume-loop.d.ts","sourceRoot":"","sources":["../src/consume-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAajD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC;IACpC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;;IAiBtB;;;;;;;;OAQG;gBAED,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB;IAgB5B,oDAAoD;IACpD,KAAK,IAAI,IAAI;IAOb,0DAA0D;IAC1D,IAAI,IAAI,IAAI;IASZ;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkN5B,2DAA2D;IACrD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ5B"}

package/dist/consume-loop.js

@@ -0,0 +1,262 @@
+import { quoteIdentifier } from "./sql.js";
+/**
+ * One consume loop per (topic, subscription id). Claims batches with
+ * `FOR UPDATE SKIP LOCKED`, extends visibility, delivers sequentially, and
+ * settles deliveries via ack/nack or visibility timeout. Woken by
+ * `LISTEN/NOTIFY` and by a polling backstop that also reclaims expired
+ * deliveries.
+ */
+export class ConsumeLoop {
+    #pool;
+    #schema;
+    #config;
+    #topic;
+    #subscriptionId;
+    #isGroup;
+    #registry;
+    #stopped = false;
+    #wakeRequested = false;
+    #wake;
+    #idle;
+    #resolveIdle;
+    #inFlight = 0;
+    #loopPromise;
+    /**
+     * @param pool - Connection pool.
+     * @param schema - Validated schema name.
+     * @param config - Resolved configuration.
+     * @param topic - Subscribed topic.
+     * @param subscriptionId - Subscription row id (group name or private id).
+     * @param isGroup - Whether this is a competing-consumer group.
+     * @param registry - Shared local callback registry for this subscription.
+     */
+    constructor(pool, schema, config, topic, subscriptionId, isGroup, registry) {
+        this.#pool = pool;
+        this.#schema = schema;
+        this.#config = config;
+        this.#topic = topic;
+        this.#subscriptionId = subscriptionId;
+        this.#isGroup = isGroup;
+        this.#registry = registry;
+        this.#idle = Promise.resolve();
+    }
+    #q(table) {
+        return `${quoteIdentifier(this.#schema)}.${quoteIdentifier(table)}`;
+    }
+    /** Start the background loop. Safe to call once. */
+    start() {
+        if (this.#loopPromise) {
+            return;
+        }
+        this.#loopPromise = this.#run();
+    }
+    /** Request an immediate poll (used by NOTIFY wakeups). */
+    wake() {
+        this.#wakeRequested = true;
+        if (this.#wake) {
+            const fn = this.#wake;
+            this.#wake = undefined;
+            fn();
+        }
+    }
+    /**
+     * Resolve once the loop is idle with no claimable work and no in-flight
+     * deliveries — the basis for `flush()`.
+     */
+    async drain() {
+        this.wake();
+        await this.#idle;
+    }
+    async #run() {
+        while (!this.#stopped) {
+            this.#wakeRequested = false;
+            let delivered = 0;
+            try {
+                delivered = await this.#tick();
+            }
+            catch (error) {
+                if (!this.#stopped) {
+                    this.#config.logger.error?.('consume loop tick failed', error);
+                }
+            }
+            if (this.#stopped) {
+                break;
+            }
+            if (delivered > 0 || this.#wakeRequested) {
+                continue;
+            }
+            this.#markIdle();
+            await this.#sleep();
+        }
+        this.#markIdle();
+    }
+    #markIdle() {
+        if (this.#inFlight === 0 && this.#resolveIdle) {
+            const resolve = this.#resolveIdle;
+            this.#resolveIdle = undefined;
+            resolve();
+        }
+    }
+    #armIdle() {
+        if (!this.#resolveIdle) {
+            this.#idle = new Promise((resolve) => {
+                this.#resolveIdle = resolve;
+            });
+        }
+    }
+    async #sleep() {
+        this.#armIdle();
+        if (this.#wakeRequested || this.#stopped) {
+            return;
+        }
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#wake = undefined;
+                resolve();
+            }, this.#config.pollIntervalMs);
+            this.#wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+    }
+    async #tick() {
+        if (this.#registry.callbacks.length === 0) {
+            return 0;
+        }
+        const rows = await this.#claim();
+        if (rows.length === 0) {
+            return 0;
+        }
+        this.#armIdle();
+        for (const row of rows) {
+            if (this.#stopped) {
+                break;
+            }
+            await this.#deliver(row);
+        }
+        return rows.length;
+    }
+    async #claim() {
+        const visibility = this.#config.ackDeadlineMs;
+        const sql = `
+      WITH claimed AS (
+        SELECT d.event_seq
+        FROM ${this.#q('deliveries')} d
+        WHERE d.subscription_id = $1 AND d.visible_at <= now()
+        ORDER BY d.event_seq
+        FOR UPDATE SKIP LOCKED
+        LIMIT $2
+      )
+      UPDATE ${this.#q('deliveries')} d
+      SET delivery_attempt = d.delivery_attempt + 1,
+          visible_at = now() + ($3::double precision * interval '1 millisecond')
+      FROM claimed, ${this.#q('events')} e
+      WHERE d.subscription_id = $1
+        AND d.event_seq = claimed.event_seq
+        AND e.seq = d.event_seq
+      RETURNING d.event_seq AS seq, e.id AS event_id, e.index, e.type,
+                e.run_id, e.data, e.created_at, d.delivery_attempt`;
+        const result = await this.#pool.query(sql, [
+            this.#subscriptionId,
+            this.#config.batchSize,
+            visibility,
+        ]);
+        return [...result.rows].sort((a, b) => Number(BigInt(a.seq) - BigInt(b.seq)));
+    }
+    async #deliver(row) {
+        if (row.delivery_attempt > this.#config.maxDeliveryAttempts) {
+            await this.#dropExhausted(row);
+            return;
+        }
+        const callback = this.#nextCallback();
+        if (!callback) {
+            return;
+        }
+        const event = {
+            id: row.event_id,
+            type: row.type,
+            data: row.data,
+            runId: row.run_id,
+            createdAt: row.created_at,
+            index: Number(row.index),
+            deliveryAttempt: row.delivery_attempt,
+        };
+        this.#inFlight++;
+        let settled = false;
+        const ack = async () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            await this.#ack(row.seq);
+        };
+        const nack = async () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            await this.#nack(row.seq);
+        };
+        try {
+            await callback(event, ack, nack);
+        }
+        catch (error) {
+            this.#config.logger.error?.('subscriber callback threw', error);
+        }
+        finally {
+            this.#inFlight--;
+            this.#markIdle();
+        }
+    }
+    #nextCallback() {
+        const callbacks = this.#registry.callbacks;
+        if (callbacks.length === 0) {
+            return undefined;
+        }
+        if (!this.#isGroup) {
+            return callbacks[0];
+        }
+        const index = this.#registry.cursor % callbacks.length;
+        this.#registry.cursor = (this.#registry.cursor + 1) % callbacks.length;
+        return callbacks[index];
+    }
+    async #ack(seq) {
+        await this.#pool.query(`DELETE FROM ${this.#q('deliveries')} WHERE subscription_id = $1 AND event_seq = $2`, [this.#subscriptionId, seq]);
+    }
+    async #nack(seq) {
+        await this.#pool.query(`UPDATE ${this.#q('deliveries')}
+       SET visible_at = now() + ($3::double precision * interval '1 millisecond')
+       WHERE subscription_id = $1 AND event_seq = $2`, [this.#subscriptionId, seq, this.#config.nackDelayMs]);
+        this.wake();
+    }
+    async #dropExhausted(row) {
+        this.#config.logger.warn?.(`dropping event ${row.event_id} on subscription ${this.#subscriptionId} after ${row.delivery_attempt - 1} attempts`);
+        if (this.#config.deadLetter) {
+            await this.#pool.query(`INSERT INTO ${this.#q('dead_events')}
+           (event_id, subscription_id, topic, index, type, run_id, data, created_at, delivery_attempt)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [
+                row.event_id,
+                this.#subscriptionId,
+                this.#topic,
+                row.index,
+                row.type,
+                row.run_id,
+                row.data === null || row.data === undefined ? null : JSON.stringify(row.data),
+                row.created_at,
+                row.delivery_attempt - 1,
+            ]);
+        }
+        await this.#ack(row.seq);
+    }
+    /** Stop the loop and wait for it to settle. Idempotent. */
+    async stop() {
+        this.#stopped = true;
+        this.wake();
+        if (this.#loopPromise) {
+            // #run() swallows tick errors internally, so this never rejects.
+            await this.#loopPromise;
+        }
+    }
+}
+//# sourceMappingURL=consume-loop.js.map

package/dist/consume-loop.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PostgresPubSub } from './postgres-pubsub.ts';
+export type { LogFn, PostgresPubSubConfig, PubSubLogger, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,KAAK,EACL,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { PostgresPubSub } from "./postgres-pubsub.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/listener.d.ts

@@ -0,0 +1,31 @@
+import type { Pool } from 'pg';
+import type { PubSubLogger } from './types.ts';
+/**
+ * Owns a single dedicated `LISTEN` connection and dispatches `NOTIFY` payloads
+ * (topic names) to registered per-topic wakeup handlers. Reconnects on
+ * connection loss so wakeups survive transient database blips; polling remains
+ * the correctness backstop in the meantime.
+ */
+export declare class NotifyListener {
+    #private;
+    /**
+     * @param pool - Pool used to acquire the dedicated listen connection.
+     * @param schema - Validated schema name; determines the channel.
+     * @param logger - Logger for connection diagnostics.
+     */
+    constructor(pool: Pool, schema: string, logger: PubSubLogger);
+    /**
+     * Register a wakeup handler for a topic, ensuring the listen connection is
+     * established. Returns an unregister function.
+     *
+     * @param topic - The topic to wake on.
+     * @param handler - Invoked when a `NOTIFY` for the topic arrives.
+     * @returns A function that removes this handler.
+     */
+    register(topic: string, handler: () => void): Promise<() => void>;
+    /**
+     * Release the listen connection and stop dispatching. Idempotent.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=listener.d.ts.map

package/dist/listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,cAAc;;IASzB;;;;OAIG;gBACS,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IAM5D;;;;;;;OAOG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAwEvE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B"}