@dudousxd/nestjs-agent-store-drizzle 0.9.0 → 0.10.1

package/dist/index.cjs

@@ -8,11 +8,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc3) => {
+var __copyProps = (to, from, except, desc4) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc3 = __getOwnPropDesc(from, key)) || desc3.enumerable });
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc4 = __getOwnPropDesc(from, key)) || desc4.enumerable });
   }
   return to;
 };
@@ -24,7 +24,11 @@ __export(index_exports, {
   DrizzleAgentStore: () => DrizzleAgentStore,
   DrizzleAgentStoreModule: () => DrizzleAgentStoreModule,
   DrizzleGovernanceQueries: () => DrizzleGovernanceQueries,
+  DrizzleMemoryProvider: () => DrizzleMemoryProvider,
   DrizzlePricingStore: () => DrizzlePricingStore,
+  DrizzleRagIngestionLog: () => DrizzleRagIngestionLog,
+  RAG_INGESTION_LOG_PAGE_ORDER: () => RAG_INGESTION_LOG_PAGE_ORDER,
+  agentMemory: () => agentMemory,
   agentMessage: () => agentMessage,
   agentModelPricing: () => agentModelPricing,
   agentRun: () => agentRun,
@@ -32,7 +36,8 @@ __export(index_exports, {
   agentThread: () => agentThread,
   agentTokenUsage: () => agentTokenUsage,
   agentToolCall: () => agentToolCall,
-  ensureAgentSchema: () => ensureAgentSchema
+  ensureAgentSchema: () => ensureAgentSchema,
+  ragIngestionLog: () => ragIngestionLog
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -189,13 +194,67 @@ var agentRun = (0, import_sqlite_core.sqliteTable)("agent_run", {
 }, (table) => [
   (0, import_sqlite_core.index)("agent_run_started_idx").on(table.startedAt)
 ]);
+var agentMemory = (0, import_sqlite_core.sqliteTable)("agent_memory", {
+  id: (0, import_sqlite_core.text)("id").primaryKey(),
+  /** The opaque scope token. Unique with `key`: one fact per key per scope. */
+  scope: (0, import_sqlite_core.text)("scope").notNull(),
+  /** What the fact is ABOUT. Two scopes sharing a key are one question answered twice. */
+  key: (0, import_sqlite_core.text)("key").notNull(),
+  /** The fact itself, one line, as the model reads it. */
+  text: (0, import_sqlite_core.text)("text").notNull(),
+  originAuthor: (0, import_sqlite_core.text)("origin_author").$type().notNull(),
+  /** A pointer that is allowed to dangle — see the table note. */
+  originThreadId: (0, import_sqlite_core.text)("origin_thread_id"),
+  originRunId: (0, import_sqlite_core.text)("origin_run_id"),
+  originActorRef: (0, import_sqlite_core.text)("origin_actor_ref"),
+  /** Always-on: carried in every prompt. Set by a host's console, never by a write. */
+  pinned: (0, import_sqlite_core.integer)("pinned", {
+    mode: "boolean"
+  }).notNull().default(false),
+  createdAt: (0, import_sqlite_core.integer)("created_at", {
+    mode: "timestamp_ms"
+  }).notNull(),
+  updatedAt: (0, import_sqlite_core.integer)("updated_at", {
+    mode: "timestamp_ms"
+  }).notNull()
+}, (table) => [
+  (0, import_sqlite_core.uniqueIndex)("agent_memory_scope_key_uq").on(table.scope, table.key)
+]);
+var ragIngestionLog = (0, import_sqlite_core.sqliteTable)("rag_ingestion_log", {
+  /** The vector-store document id (chunk ids are `${documentId}#<n>`). */
+  documentId: (0, import_sqlite_core.text)("document_id").primaryKey(),
+  status: (0, import_sqlite_core.text)("status").$type().notNull(),
+  collection: (0, import_sqlite_core.text)("collection"),
+  ownerType: (0, import_sqlite_core.text)("owner_type"),
+  ownerId: (0, import_sqlite_core.text)("owner_id"),
+  /** Citation-facing origin — the media record's path. */
+  source: (0, import_sqlite_core.text)("source"),
+  mimeType: (0, import_sqlite_core.text)("mime_type"),
+  size: (0, import_sqlite_core.integer)("size"),
+  /** Chunk count on `ingested`; null otherwise. */
+  chunks: (0, import_sqlite_core.integer)("chunks"),
+  /** Skip reason on `skipped` (`unsupported-type` | `too-large` | `empty-text`); null otherwise. */
+  reason: (0, import_sqlite_core.text)("reason"),
+  /** Error message on `failed`; null otherwise. */
+  error: (0, import_sqlite_core.text)("error"),
+  createdAt: (0, import_sqlite_core.integer)("created_at", {
+    mode: "timestamp_ms"
+  }).notNull(),
+  updatedAt: (0, import_sqlite_core.integer)("updated_at", {
+    mode: "timestamp_ms"
+  }).notNull()
+}, (table) => [
+  (0, import_sqlite_core.index)("rag_ingestion_log_collection_idx").on(table.collection, table.updatedAt)
+]);
 var agentSchema = {
   agentThread,
   agentMessage,
   agentToolCall,
   agentTokenUsage,
   agentModelPricing,
-  agentRun
+  agentRun,
+  agentMemory,
+  ragIngestionLog
 };
 
 // src/ensure-schema.ts
@@ -290,7 +349,41 @@ var statements = [
     parent_run_id TEXT
   )`,
   `CREATE INDEX IF NOT EXISTS agent_run_started_idx
-    ON agent_run (started_at)`
+    ON agent_run (started_at)`,
+  // `key` and `text` are quoted: both are keywords in at least one engine this DDL is read by, and
+  // they are the SPI's own field names, which is worth more here than dodging the quoting.
+  `CREATE TABLE IF NOT EXISTS agent_memory (
+    id TEXT PRIMARY KEY NOT NULL,
+    scope TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "text" TEXT NOT NULL,
+    origin_author TEXT NOT NULL,
+    origin_thread_id TEXT,
+    origin_run_id TEXT,
+    origin_actor_ref TEXT,
+    pinned INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS agent_memory_scope_key_uq
+    ON agent_memory (scope, "key")`,
+  `CREATE TABLE IF NOT EXISTS rag_ingestion_log (
+    document_id TEXT PRIMARY KEY NOT NULL,
+    status TEXT NOT NULL,
+    collection TEXT,
+    owner_type TEXT,
+    owner_id TEXT,
+    source TEXT,
+    mime_type TEXT,
+    size INTEGER,
+    chunks INTEGER,
+    reason TEXT,
+    error TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+  `CREATE INDEX IF NOT EXISTS rag_ingestion_log_collection_idx
+    ON rag_ingestion_log (collection, updated_at)`
 ];
 var additiveColumns = [
   {
@@ -1434,8 +1527,150 @@ var DrizzleGovernanceQueries = class {
   }
 };
 
-// src/drizzle-pricing-store.ts
+// src/drizzle-memory-provider.ts
+var import_nestjs_agent_core2 = require("@dudousxd/nestjs-agent-core");
 var import_drizzle_orm4 = require("drizzle-orm");
+function toRecord(row) {
+  return {
+    id: row.id,
+    key: row.key,
+    text: row.text,
+    scope: row.scope,
+    origin: {
+      author: row.originAuthor,
+      ...row.originThreadId !== null ? {
+        threadId: row.originThreadId
+      } : {},
+      ...row.originRunId !== null ? {
+        runId: row.originRunId
+      } : {},
+      ...row.originActorRef !== null ? {
+        actorRef: row.originActorRef
+      } : {}
+    },
+    updatedAt: row.updatedAt.toISOString(),
+    pinned: row.pinned
+  };
+}
+__name(toRecord, "toRecord");
+var DrizzleMemoryProvider = class {
+  static {
+    __name(this, "DrizzleMemoryProvider");
+  }
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+  * Every memory visible at `scopes` — asked on EVERY turn, so it is one indexed `scope in (…)`
+  * against the leading column of the (`scope`, `key`) unique index.
+  *
+  * The scope filter is in the QUERY. The library drops out-of-scope records it is handed, but that
+  * is a backstop: a memory held for another actor or another tenant is never selected here, so it
+  * is unreachable rather than outranked.
+  */
+  async list({ scopes }) {
+    if (scopes.length === 0) {
+      return [];
+    }
+    const rows = await this.db.select().from(agentMemory).where((0, import_drizzle_orm4.inArray)(agentMemory.scope, [
+      ...scopes
+    ]));
+    return rows.map(toRecord);
+  }
+  /**
+  * Delete one, and only from the actor's OWN scope.
+  *
+  * `memoryForgetVerdict` already holds the library's endpoint to that rule; the `where` repeats it
+  * because `forget` takes an id and nothing else, so a caller reaching this provider by any other
+  * path would otherwise delete a tenant's or the deployment's memory by knowing one id.
+  *
+  * `false` where nothing matched — which covers "no such id" and "not yours" identically, so the
+  * answer cannot be used to find out which memories exist about other people.
+  */
+  async forget({ id, ctx }) {
+    const deleted = await this.db.delete(agentMemory).where((0, import_drizzle_orm4.and)((0, import_drizzle_orm4.eq)(agentMemory.id, id), (0, import_drizzle_orm4.eq)(agentMemory.scope, (0, import_nestjs_agent_core2.actorScope)(ctx.actor)))).returning({
+      id: agentMemory.id
+    });
+    return deleted.length > 0;
+  }
+  /**
+  * Upsert on (`scope`, `key`) — one statement, against the unique index, rather than a read
+  * followed by a write: two turns concluding the same key at once would otherwise race to a
+  * duplicate-key insert and one of them would fail the `remember` tool.
+  *
+  * The conflict `set` names exactly what a rewrite may change, so `pinned`, `createdAt` and `id`
+  * are left alone by construction rather than by an exclusion anyone could forget to extend.
+  * Dropping `pinned` would silently unpin a row the next time the agent restated the fact;
+  * rewriting `createdAt` would lose when the belief was first formed; reassigning `id` would
+  * invalidate the delete handle a person was already shown.
+  */
+  async write({ key, text: text2, scope, origin, ctx }) {
+    assertAuthorMayWriteScope({
+      scope,
+      origin,
+      ctx
+    });
+    const now = /* @__PURE__ */ new Date();
+    const columns = {
+      originAuthor: origin.author,
+      originThreadId: origin.threadId ?? null,
+      originRunId: origin.runId ?? null,
+      originActorRef: origin.actorRef ?? null
+    };
+    const [row] = await this.db.insert(agentMemory).values({
+      id: crypto.randomUUID(),
+      scope,
+      key,
+      text: text2,
+      ...columns,
+      pinned: false,
+      createdAt: now,
+      updatedAt: now
+    }).onConflictDoUpdate({
+      target: [
+        agentMemory.scope,
+        agentMemory.key
+      ],
+      set: {
+        text: text2,
+        ...columns,
+        updatedAt: now
+      }
+    }).returning();
+    if (row === void 0) {
+      throw new Error(`DrizzleMemoryProvider: the upsert of "${key}" at "${scope}" returned no row; the driver does not support RETURNING on conflict.`);
+    }
+    return toRecord(row);
+  }
+  /**
+  * Make one memory always-on, or stop it being one. The operator act the SPI has no method for, on
+  * purpose: a pin grants a fact a permanent place in every future prompt, so nothing an agent can
+  * reach may set it. Authorize it in your own console — this takes no `ScopeContext` because it is
+  * not an actor's act on their own memory.
+  *
+  * `false` where there is no such id.
+  */
+  async pin({ id, pinned }) {
+    const updated = await this.db.update(agentMemory).set({
+      pinned,
+      updatedAt: /* @__PURE__ */ new Date()
+    }).where((0, import_drizzle_orm4.eq)(agentMemory.id, id)).returning({
+      id: agentMemory.id
+    });
+    return updated.length > 0;
+  }
+};
+function assertAuthorMayWriteScope({ scope, origin, ctx }) {
+  const own = (0, import_nestjs_agent_core2.actorScope)(ctx.actor);
+  if (origin.author !== "human" && scope !== own) {
+    throw new Error(`DrizzleMemoryProvider: refusing to write an agent-authored memory at "${scope}"; an agent may write only at "${own}"`);
+  }
+}
+__name(assertAuthorMayWriteScope, "assertAuthorMayWriteScope");
+
+// src/drizzle-pricing-store.ts
+var import_drizzle_orm5 = require("drizzle-orm");
 var DrizzlePricingStore = class {
   static {
     __name(this, "DrizzlePricingStore");
@@ -1447,7 +1682,7 @@ var DrizzlePricingStore = class {
   async upsertModelPrice(input) {
     await this.db.update(agentModelPricing).set({
       isCurrent: false
-    }).where((0, import_drizzle_orm4.and)((0, import_drizzle_orm4.eq)(agentModelPricing.modelId, input.modelId), (0, import_drizzle_orm4.eq)(agentModelPricing.isCurrent, true)));
+    }).where((0, import_drizzle_orm5.and)((0, import_drizzle_orm5.eq)(agentModelPricing.modelId, input.modelId), (0, import_drizzle_orm5.eq)(agentModelPricing.isCurrent, true)));
     await this.db.insert(agentModelPricing).values({
       id: crypto.randomUUID(),
       modelId: input.modelId,
@@ -1460,7 +1695,7 @@ var DrizzlePricingStore = class {
     });
   }
   async listCurrentPrices() {
-    const rows = await this.db.select().from(agentModelPricing).where((0, import_drizzle_orm4.eq)(agentModelPricing.isCurrent, true));
+    const rows = await this.db.select().from(agentModelPricing).where((0, import_drizzle_orm5.eq)(agentModelPricing.isCurrent, true));
     return rows.map((row) => ({
       modelId: row.modelId,
       inputPricePer1m: row.inputPricePer1m,
@@ -1476,33 +1711,367 @@ var DrizzlePricingStore = class {
   }
 };
 
-// src/drizzle-agent-store.module.ts
-var import_nestjs_agent_core2 = require("@dudousxd/nestjs-agent-core");
+// src/drizzle-rag-ingestion-log.ts
+var import_node_diagnostics_channel = require("diagnostics_channel");
 var import_common = require("@nestjs/common");
-function _ts_decorate(decorators, target, key, desc3) {
-  var c = arguments.length, r = c < 3 ? target : desc3 === null ? desc3 = Object.getOwnPropertyDescriptor(target, key) : desc3, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc3);
+var import_drizzle_orm6 = require("drizzle-orm");
+function _ts_decorate(decorators, target, key, desc4) {
+  var c = arguments.length, r = c < 3 ? target : desc4 === null ? desc4 = Object.getOwnPropertyDescriptor(target, key) : desc4, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc4);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var CHANNELS = [
+  {
+    name: "aviary:rag:media.ingested",
+    status: "ingested"
+  },
+  {
+    name: "aviary:rag:media.skipped",
+    status: "skipped"
+  },
+  {
+    name: "aviary:rag:media.failed",
+    status: "failed"
+  },
+  {
+    name: "aviary:rag:media.removed",
+    status: "removed"
+  }
+];
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+__name(str, "str");
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+__name(num, "num");
+var RAG_INGESTION_LOG_PAGE_ORDER = [
+  (0, import_drizzle_orm6.desc)(ragIngestionLog.updatedAt),
+  (0, import_drizzle_orm6.asc)(ragIngestionLog.documentId)
+];
+var DEFAULT_PAGE_SIZE = 200;
+var DEFAULT_BATCH_SIZE = 200;
+function batches(batchSize) {
+  const requested = Math.trunc(batchSize ?? DEFAULT_BATCH_SIZE);
+  return Number.isFinite(requested) && requested >= 1 ? requested : DEFAULT_BATCH_SIZE;
+}
+__name(batches, "batches");
+var CURSOR_COLUMNS = {
+  documentId: ragIngestionLog.documentId,
+  updatedAt: ragIngestionLog.updatedAt
+};
+var DrizzleRagIngestionLog = class _DrizzleRagIngestionLog {
+  static {
+    __name(this, "DrizzleRagIngestionLog");
+  }
+  db;
+  logger = new import_common.Logger(_DrizzleRagIngestionLog.name);
+  teardowns = [];
+  inFlight = /* @__PURE__ */ new Set();
+  constructor(db) {
+    this.db = db;
+  }
+  onModuleInit() {
+    for (const channel of CHANNELS) {
+      const listener = /* @__PURE__ */ __name((message) => {
+        const payload = message?.payload;
+        if (payload !== void 0) {
+          this.track(this.record(channel.status, payload));
+        }
+      }, "listener");
+      (0, import_node_diagnostics_channel.subscribe)(channel.name, listener);
+      this.teardowns.push(() => (0, import_node_diagnostics_channel.unsubscribe)(channel.name, listener));
+    }
+  }
+  async onModuleDestroy() {
+    for (const teardown of this.teardowns) {
+      teardown();
+    }
+    this.teardowns = [];
+    await this.settle();
+  }
+  /** Await every in-flight write — for graceful shutdown and deterministic tests. */
+  async settle() {
+    await Promise.allSettled([
+      ...this.inFlight
+    ]);
+  }
+  /** The latest recorded outcome per document, newest first. */
+  async list(query = {}) {
+    const rows = this.db.select().from(ragIngestionLog).where(this.where(query)).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(query.limit ?? DEFAULT_PAGE_SIZE);
+    return query.offset === void 0 ? rows : rows.offset(query.offset);
+  }
+  /**
+  * The same page plus the unpaginated total, so a caller can tell "these are all of them" from
+  * "these are the first N". A list that silently truncates reads as complete when it isn't.
+  *
+  * Offset paging is only sound over a table nobody is deleting from underneath you: a row removed
+  * behind the cursor shifts everything after it back by one, so the next page starts one row late
+  * and that row is never seen. Use {@link iterate} for any sweep that deletes.
+  */
+  async listPage(query = {}) {
+    const [totalRow] = await this.db.select({
+      value: (0, import_drizzle_orm6.count)()
+    }).from(ragIngestionLog).where(this.where(query));
+    return {
+      rows: await this.list(query),
+      total: totalRow?.value ?? 0
+    };
+  }
+  /**
+  * Every matching row, newest first, streamed in batches — the sweep-safe way to walk this table.
+  *
+  * Paging is *keyset*, not offset: each batch asks for the rows that sort strictly after the last
+  * row yielded, using `(updatedAt, documentId)` — one point in
+  * {@link RAG_INGESTION_LOG_PAGE_ORDER}, which is total because it ends in the primary key. A
+  * cursor made of column values does not move when rows leave the table, which is what makes this
+  * delete-safe *by construction* rather than by the caller carefully advancing an offset by only
+  * the rows it kept.
+  *
+  * **The guarantee, stated once:** a row is yielded exactly when — at the moment the batch that
+  * would contain it is fetched — the row exists, matches `where`, and sorts strictly after the
+  * last row already yielded. Everything below is a consequence of that one sentence.
+  *
+  * What you can rely on:
+  * - **Deleting rows while iterating is safe.** Delete any row you like — the one just yielded, the
+  *   whole batch, rows you have not reached yet — and every row that is still there when the sweep
+  *   reaches its position is visited exactly once. Nothing is skipped and nothing is repeated,
+  *   because deleting a row moves no *other* row's `(updatedAt, documentId)`. (Rows you delete
+  *   *ahead* of the cursor are simply never visited, which is the point of deleting them.)
+  * - **Ties are safe.** A bulk upload stamps a whole batch with the same `updatedAt`; the
+  *   `documentId` tiebreaker keeps consecutive batches disjoint even when every row ties.
+  * - **Each row is yielded at most once**, for as long as `updatedAt` only ever moves forward —
+  *   which is what `record()` does, since it always stamps `now`.
+  *
+  * What this is **not**: a snapshot, or a repeatable read. The sweep observes the table as it is
+  * when each batch is fetched, so:
+  * - A row **inserted** mid-sweep by `record()` is stamped `now`. The order is newest-first, so it
+  *   sorts ahead of a cursor the sweep has already moved past, and is not visited. A sweep
+  *   therefore never sees documents ingested after it started — the behaviour an orphan sweep
+  *   wants, since a document that arrived while you were sweeping is not an orphan. (A *direct*
+  *   insert with a backdated `updatedAt` lands ahead of the cursor and **is** visited; nothing in
+  *   this class writes one.)
+  * - A row **re-ingested** mid-sweep has its `updatedAt` bumped to `now`, moving it ahead of the
+  *   cursor for the same reason. If the sweep had already passed it, it is not visited twice; if it
+  *   had not, it is **missed for this pass**. That is the honest limit: against a concurrent
+  *   writer `iterate` guarantees "at most once", not "at least once". Sweeps that must not miss a
+  *   concurrently-rewritten row should be idempotent and run again.
+  * - Only a row whose `updatedAt` moves *backwards* — which needs a direct write — can be yielded
+  *   twice.
+  * - `collection` / `status` are re-evaluated per batch, so a row that stops matching mid-sweep
+  *   stops being visited.
+  *
+  * There is no `limit`/`offset` here on purpose: `where` says *which* rows, `options` says how the
+  * sweep is run. A sweep that stops early stops by `break`ing out of the `for await`.
+  */
+  iterate(where = {}, options = {}) {
+    return this.sweep(where, batches(options.batchSize), options.after, (filter, limit) => this.db.select().from(ragIngestionLog).where(filter).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(limit));
+  }
+  /**
+  * Just the document ids of the matching rows, in {@link RAG_INGESTION_LOG_PAGE_ORDER}.
+  *
+  * Returns **all** of them — no 200-row cap, unlike `list` — by sweeping on {@link iterate}'s
+  * keyset internally, so it is correct against concurrent deletes for the same reason `iterate`
+  * is. What the cap protects against is hydrating an unbounded number of wide rows (`error` is a
+  * TEXT column); this selects two columns — the id, plus the `updatedAt` the cursor needs — and
+  * keeps only the ids, so the peak footprint is one batch of two-column rows plus a list of
+  * strings whose size *is* the answer the caller asked for.
+  *
+  * For callers that need the id set of a collection and nothing else: an orphan sweep unioning the
+  * log against the vector store's own document list.
+  */
+  async listDocumentIds(where = {}, options = {}) {
+    const ids = [];
+    const rows = this.sweep(where, batches(options.batchSize), void 0, (filter, limit) => this.db.select(CURSOR_COLUMNS).from(ragIngestionLog).where(filter).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(limit));
+    for await (const row of rows) {
+      ids.push(row.documentId);
+    }
+    return ids;
+  }
+  /** The latest recorded outcome for one document, or null if it was never attempted. */
+  async get(documentId) {
+    const [row] = await this.db.select().from(ragIngestionLog).where((0, import_drizzle_orm6.eq)(ragIngestionLog.documentId, documentId));
+    return row ?? null;
+  }
+  /** Forget one document's record. Returns whether a row was actually removed. */
+  async remove(documentId) {
+    const removed = await this.db.delete(ragIngestionLog).where((0, import_drizzle_orm6.eq)(ragIngestionLog.documentId, documentId)).returning({
+      documentId: ragIngestionLog.documentId
+    });
+    return removed.length > 0;
+  }
+  /** Forget every record for a collection — for when the collection itself is deleted. */
+  async removeByCollection(collection) {
+    const removed = await this.db.delete(ragIngestionLog).where((0, import_drizzle_orm6.eq)(ragIngestionLog.collection, collection)).returning({
+      documentId: ragIngestionLog.documentId
+    });
+    return removed.length;
+  }
+  /**
+  * The keyset sweep both {@link iterate} and {@link listDocumentIds} are made of. `page` decides
+  * how wide a row is — whole rows for `iterate`, two columns for `listDocumentIds` — and the
+  * `R extends RagIngestionLogCursor` bound says the only thing the sweep needs back: a row it can
+  * read the next cursor off.
+  *
+  * The cursor advances **per yielded row**, not per batch, so a consumer that `break`s mid-batch
+  * leaves it on the last row it actually saw. It is two column values read off that row, so a row
+  * leaving the table cannot move it — the whole reason this is delete-safe by construction.
+  */
+  async *sweep(where, batchSize, after, page) {
+    let cursor = after;
+    for (; ; ) {
+      const rows = await page(this.keyset(where, cursor), batchSize);
+      if (rows.length === 0) {
+        return;
+      }
+      for (const row of rows) {
+        yield row;
+        cursor = {
+          updatedAt: row.updatedAt,
+          documentId: row.documentId
+        };
+      }
+    }
+  }
+  where(query) {
+    return (0, import_drizzle_orm6.and)(query.collection !== void 0 ? (0, import_drizzle_orm6.eq)(ragIngestionLog.collection, query.collection) : void 0, query.status !== void 0 ? (0, import_drizzle_orm6.eq)(ragIngestionLog.status, query.status) : void 0);
+  }
+  /**
+  * The coordinates filter AND'd with "strictly after `cursor` in
+  * {@link RAG_INGESTION_LOG_PAGE_ORDER}".
+  *
+  * The order is `updatedAt desc, documentId asc`, so "after" means an older timestamp, or the same
+  * timestamp and a larger id. Both halves are needed: the `<` alone would re-yield every row tied
+  * with the cursor, and dropping the tie branch would skip them instead.
+  */
+  keyset(where, cursor) {
+    const base = this.where(where);
+    if (cursor === void 0) {
+      return base;
+    }
+    return (0, import_drizzle_orm6.and)(base, (0, import_drizzle_orm6.or)((0, import_drizzle_orm6.lt)(ragIngestionLog.updatedAt, cursor.updatedAt), (0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(ragIngestionLog.updatedAt, cursor.updatedAt), (0, import_drizzle_orm6.gt)(ragIngestionLog.documentId, cursor.documentId))));
+  }
+  /**
+  * Upsert one outcome. Keyed by document id so the row always reflects the *current* state — a
+  * retry that succeeds overwrites the failure it replaces, rather than leaving a stale error next
+  * to a working document.
+  */
+  async record(status, payload) {
+    const documentId = str(payload.mediaId);
+    if (documentId === null) {
+      return;
+    }
+    try {
+      const now = /* @__PURE__ */ new Date();
+      const collection = str(payload.collection);
+      const ownerType = str(payload.ownerType);
+      const ownerId = str(payload.ownerId);
+      const source = str(payload.source);
+      const mimeType = str(payload.mimeType);
+      const size = num(payload.size);
+      const outcome = {
+        status,
+        // The three outcome-specific columns are exclusive: null out the ones this status doesn't
+        // own on every write, so a successful retry clears the previous attempt's error rather than
+        // leaving it next to a working document. Always present → always in the conflict `set`.
+        chunks: status === "ingested" ? num(payload.chunks) : null,
+        reason: status === "skipped" ? str(payload.reason) : null,
+        error: status === "failed" ? str(payload.error) : null,
+        updatedAt: now,
+        ...collection !== null ? {
+          collection
+        } : {},
+        ...ownerType !== null ? {
+          ownerType
+        } : {},
+        ...ownerId !== null ? {
+          ownerId
+        } : {},
+        ...source !== null ? {
+          source
+        } : {},
+        ...mimeType !== null ? {
+          mimeType
+        } : {},
+        ...size !== null ? {
+          size
+        } : {}
+      };
+      await this.db.insert(ragIngestionLog).values({
+        documentId,
+        createdAt: now,
+        ...outcome
+      }).onConflictDoUpdate({
+        target: ragIngestionLog.documentId,
+        set: outcome
+      });
+    } catch (error) {
+      this.logger.warn(`Could not record RAG ingestion outcome for ${documentId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  track(promise) {
+    const tracked = promise.finally(() => {
+      this.inFlight.delete(tracked);
+    });
+    this.inFlight.add(tracked);
+  }
+};
+DrizzleRagIngestionLog = _ts_decorate([
+  (0, import_common.Injectable)(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof AgentDrizzleDb === "undefined" ? Object : AgentDrizzleDb
+  ])
+], DrizzleRagIngestionLog);
+
+// src/drizzle-agent-store.module.ts
+var import_nestjs_agent_core3 = require("@dudousxd/nestjs-agent-core");
+var import_common2 = require("@nestjs/common");
+function _ts_decorate2(decorators, target, key, desc4) {
+  var c = arguments.length, r = c < 3 ? target : desc4 === null ? desc4 = Object.getOwnPropertyDescriptor(target, key) : desc4, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc4);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
 var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
   static {
     __name(this, "DrizzleAgentStoreModule");
   }
   static forRoot(options) {
+    const ragProviders = options.ragIngestionLog === false ? [] : [
+      {
+        provide: DrizzleRagIngestionLog,
+        useFactory: /* @__PURE__ */ __name(() => new DrizzleRagIngestionLog(options.db), "useFactory")
+      }
+    ];
     return {
       module: _DrizzleAgentStoreModule,
       global: true,
       providers: [
+        ...ragProviders,
         {
           provide: DrizzleAgentStore,
           useFactory: /* @__PURE__ */ __name(() => new DrizzleAgentStore(options.db), "useFactory")
         },
         {
-          provide: import_nestjs_agent_core2.AGENT_STORE,
+          provide: import_nestjs_agent_core3.AGENT_STORE,
           useExisting: DrizzleAgentStore
         },
+        // Exported, never bound to AGENT_MEMORY: that token's PRESENCE is what turns memory on, so
+        // binding it here would switch the feature on for every host that installs the store. A
+        // host opts in by naming this provider in `AgentModule.forRoot({ memory: { provider } })`.
+        {
+          provide: DrizzleMemoryProvider,
+          useFactory: /* @__PURE__ */ __name(() => new DrizzleMemoryProvider(options.db), "useFactory")
+        },
         {
           provide: DrizzlePricingStore,
           useFactory: /* @__PURE__ */ __name(() => new DrizzlePricingStore(options.db), "useFactory")
@@ -1510,44 +2079,52 @@ var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
         // AGENT_PRICING_STORE: the host's own store when supplied, else the default Drizzle one.
         // DrizzleGovernanceQueries prices usage against whatever is bound here.
         options.pricingStore ? {
-          provide: import_nestjs_agent_core2.AGENT_PRICING_STORE,
+          provide: import_nestjs_agent_core3.AGENT_PRICING_STORE,
           useClass: options.pricingStore
         } : {
-          provide: import_nestjs_agent_core2.AGENT_PRICING_STORE,
+          provide: import_nestjs_agent_core3.AGENT_PRICING_STORE,
           useExisting: DrizzlePricingStore
         },
         {
           provide: DrizzleGovernanceQueries,
           useFactory: /* @__PURE__ */ __name((pricingStore) => new DrizzleGovernanceQueries(options.db, pricingStore), "useFactory"),
           inject: [
-            import_nestjs_agent_core2.AGENT_PRICING_STORE
+            import_nestjs_agent_core3.AGENT_PRICING_STORE
           ]
         },
         {
-          provide: import_nestjs_agent_core2.AGENT_GOVERNANCE_QUERIES,
+          provide: import_nestjs_agent_core3.AGENT_GOVERNANCE_QUERIES,
           useExisting: DrizzleGovernanceQueries
         }
       ],
       exports: [
+        ...options.ragIngestionLog === false ? [] : [
+          DrizzleRagIngestionLog
+        ],
         DrizzleAgentStore,
-        import_nestjs_agent_core2.AGENT_STORE,
+        import_nestjs_agent_core3.AGENT_STORE,
+        DrizzleMemoryProvider,
         DrizzleGovernanceQueries,
-        import_nestjs_agent_core2.AGENT_GOVERNANCE_QUERIES,
+        import_nestjs_agent_core3.AGENT_GOVERNANCE_QUERIES,
         DrizzlePricingStore,
-        import_nestjs_agent_core2.AGENT_PRICING_STORE
+        import_nestjs_agent_core3.AGENT_PRICING_STORE
       ]
     };
   }
 };
-DrizzleAgentStoreModule = _ts_decorate([
-  (0, import_common.Module)({})
+DrizzleAgentStoreModule = _ts_decorate2([
+  (0, import_common2.Module)({})
 ], DrizzleAgentStoreModule);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DrizzleAgentStore,
   DrizzleAgentStoreModule,
   DrizzleGovernanceQueries,
+  DrizzleMemoryProvider,
   DrizzlePricingStore,
+  DrizzleRagIngestionLog,
+  RAG_INGESTION_LOG_PAGE_ORDER,
+  agentMemory,
   agentMessage,
   agentModelPricing,
   agentRun,
@@ -1555,6 +2132,7 @@ DrizzleAgentStoreModule = _ts_decorate([
   agentThread,
   agentTokenUsage,
   agentToolCall,
-  ensureAgentSchema
+  ensureAgentSchema,
+  ragIngestionLog
 });
 //# sourceMappingURL=index.cjs.map