@equationalapplications/prisma-outbox

Sync @equationalapplications/core-llm-wiki SQLite outbox events to your Prisma-backed database using the transactional outbox pattern — at-least-once delivery with ordering guarantees.

📖 Docs · GitHub · ScopeLab · WikiDemo · Changelog · Issues

Polls the SQLite outbox table written by @equationalapplications/core-llm-wiki and syncs events to your Prisma-backed system inside a Prisma transaction, with configurable batch size, poll interval, error handling, and a concurrency guard.

For the GraphRAG retrieval surface (traverseGraph, useWikiTraversal, formatGraphContext), see GraphRAG guide.

Installation

npm install @equationalapplications/prisma-outbox
# peer deps
npm install @equationalapplications/core-llm-wiki @prisma/client

Quick start

import { PrismaOutboxWorker } from '@equationalapplications/prisma-outbox';
import { WikiMemory } from '@equationalapplications/core-llm-wiki';
import { PrismaClient } from '@prisma/client';

const wiki = new WikiMemory(db, {
  llmProvider,
  config: { enableOutbox: true },
});
await wiki.setup();

const prisma = new PrismaClient();

const worker = new PrismaOutboxWorker({
  wikiMemory: wiki,
  prisma,
  mapEvent: async (event, tx) => {
    // mapEvent must be idempotent: at-least-once delivery means the same event
    // can be retried if acknowledgement fails after the Prisma transaction commits.
    if (event.operation === 'INSERT' && event.table_name.includes('entries')) {
      await tx.wikiEntry.upsert({
        where: { id: event.record_id },
        create: { id: event.record_id, ...(event.payload as Record<string, unknown>) },
        update: {},
      });
    }
  },
  pollIntervalMs: 5000,
  batchSize: 100,
  onError: (err, event) => {
    console.error('Outbox event failed', event.id, err);
    return false; // halt to preserve ordering; return true to skip poison-pill
  },
});

worker.start();

// On shutdown:
worker.stop();

API

PrismaOutboxWorker

PrismaOutboxConfig

How it works

1. Every WikiMemory mutation (when enableOutbox: true) atomically writes an event to the SQLite outbox table in the same transaction as the domain write.
2. PrismaOutboxWorker polls getUnprocessedOutboxEvents() and calls mapEvent inside a Prisma transaction for each event.
3. Successfully processed event IDs are passed to markOutboxEventsProcessed(), which deletes them from SQLite.
4. If a full batch is consumed without error, an immediate follow-up cycle runs (backlog optimization) to drain queues faster than the poll interval.

Limitations

• Single-instance only. The worker does not use row-level locking or leases. Running two PrismaOutboxWorker instances against the same SQLite file will cause duplicate Prisma writes. Run exactly one worker per SQLite database. mapEvent must still be idempotent to tolerate at-least-once delivery (acknowledgement can fail after a successful Prisma commit).

Monorepo Ecosystem

Made with ❤️ by Equational Applications LLC. https://equationalapplications.com/