@nestarc/inbox 0.0.0-stage → 0.2.0

package/examples/src/tenancy/main.ts

@@ -0,0 +1,210 @@
+import "reflect-metadata";
+import assert from "node:assert/strict";
+import { randomBytes, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Module } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { Pool } from "pg";
+import {
+  TenancyContext,
+  TenancyModule,
+  TenancyService,
+} from "@nestarc/tenancy";
+import {
+  InboxModule,
+  InboxService,
+  createInboxTenancyContext,
+  type InboxHandler,
+  type InboxScope,
+} from "@nestarc/inbox";
+import { PrismaClient, type Prisma } from "../generated/prisma/client";
+import { exampleDatabaseUrl } from "../common";
+
+type Payload = { targetTenant: string };
+const consumer = "example.tenancy.v1";
+const eventType = "example.tenant-work";
+
+async function main() {
+  // This credential is only the isolated fixture's schema administrator. Business
+  // handlers use the separate role below, which cannot bypass RLS or own tables.
+  const admin = new Pool({ connectionString: exampleDatabaseUrl(), max: 2 });
+  const role = `inbox_example_${randomBytes(8).toString("hex")}`;
+  const password = randomBytes(24).toString("hex");
+  let roleCreated = false;
+  let prisma: PrismaClient | undefined;
+  let app:
+    | Awaited<ReturnType<typeof NestFactory.createApplicationContext>>
+    | undefined;
+  try {
+    await admin.query(
+      await readFile(resolve(__dirname, "../../sql/tenancy.sql"), "utf8"),
+    );
+    // Identifiers and credentials here consist exclusively of generated hex.
+    await admin.query(`CREATE ROLE ${role} LOGIN PASSWORD '${password}'
+      NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOBYPASSRLS`);
+    roleCreated = true;
+    await admin.query(`
+      GRANT USAGE ON SCHEMA public TO ${role};
+      GRANT SELECT ON public.nestarc_inbox_schema TO ${role};
+      GRANT SELECT, INSERT, UPDATE ON public.nestarc_inbox TO ${role};
+      GRANT SELECT, INSERT, UPDATE ON public.example_tenancy_records TO ${role};
+      GRANT SELECT, INSERT ON public.example_tenancy_shared TO ${role};
+    `);
+    const appUrl = new URL(exampleDatabaseUrl());
+    appUrl.username = role;
+    appUrl.password = password;
+    const client = new PrismaClient({
+      adapter: new PrismaPg({ connectionString: appUrl.toString(), max: 1 }),
+    });
+    prisma = client;
+    const tenancyModule = TenancyModule.forRoot({
+      tenantExtractor: "x-tenant-id",
+    });
+
+    @Module({
+      imports: [
+        tenancyModule,
+        InboxModule.forRootAsync({
+          imports: [tenancyModule],
+          inject: [TenancyService],
+          useFactory: (tenancy: TenancyService) => {
+            // TenancyModule exports the configured service, but not the context
+            // provider. Public TenancyContext instances share the package's ALS.
+            const context = new TenancyContext();
+            const handler: InboxHandler<Payload, Prisma.TransactionClient> = {
+              consumer,
+              eventType,
+              schemaVersion: 1,
+              async handle(payload, ctx) {
+                if (ctx.scope.kind === "global") {
+                  assert.equal(tenancy.getCurrentTenant(), null);
+                  assert.deepEqual(
+                    await ctx.tx.$queryRawUnsafe(
+                      "SELECT * FROM public.example_tenancy_records",
+                    ),
+                    [],
+                  );
+                  await ctx.tx.$executeRawUnsafe(
+                    "INSERT INTO public.example_tenancy_shared VALUES ($1::uuid, $2::uuid)",
+                    randomUUID(),
+                    ctx.inboxId,
+                  );
+                  return;
+                }
+                assert.equal(tenancy.getCurrentTenantOrThrow(), ctx.scope.id);
+                const rows = await ctx.tx.$queryRawUnsafe<
+                  Array<{ tenant_id: string }>
+                >("SELECT tenant_id FROM public.example_tenancy_records");
+                const tenantId = ctx.scope.id;
+                assert.ok(rows.every((row) => row.tenant_id === tenantId));
+                // Deliberately use the payload value so the forged fixture below
+                // demonstrates the database's WITH CHECK policy rejecting it.
+                await ctx.tx.$executeRawUnsafe(
+                  "INSERT INTO public.example_tenancy_records VALUES ($1::uuid, $2, $3::uuid, 'handled')",
+                  randomUUID(),
+                  payload.targetTenant,
+                  ctx.inboxId,
+                );
+              },
+            };
+            return {
+              prisma: client,
+              handlers: [handler],
+              handlerContext: createInboxTenancyContext({
+                context,
+                tenancy,
+                global: "shared",
+              }),
+              worker: { enabled: false, concurrency: 1, maxAttempts: 1 },
+            };
+          },
+        }),
+      ],
+    })
+    class AppModule {}
+    app = await NestFactory.createApplicationContext(AppModule, {
+      logger: ["error", "warn"],
+      abortOnError: false,
+    });
+    const inbox = app.get(InboxService);
+    const tenancy = app.get(TenancyService);
+    const runId = randomUUID();
+    const tenantA = `${runId}-a`;
+    const tenantB = `${runId}-b`;
+    const accept = (scope: InboxScope, targetTenant: string) =>
+      inbox.accept({
+        scope,
+        source: "trusted-fixture-route",
+        consumer,
+        messageId: randomUUID(),
+        eventType,
+        schemaVersion: 1,
+        payload: { targetTenant },
+      });
+    // Scope comes from trusted routing. A producer payload cannot choose its scope.
+    const accepted = await Promise.all([
+      accept({ kind: "tenant", id: tenantA }, tenantA),
+      accept({ kind: "tenant", id: tenantB }, tenantB),
+      accept({ kind: "tenant", id: tenantA }, tenantB),
+      accept({ kind: "global" }, ""),
+    ]);
+    for (let i = 0; i < accepted.length; i++) await inbox.runOnce();
+    const results = await Promise.all(
+      accepted.map(async (receipt) => {
+        const result = await admin.query<{ status: string }>(
+          "SELECT status FROM public.nestarc_inbox WHERE id=$1",
+          [receipt.id],
+        );
+        return result.rows[0].status;
+      }),
+    );
+    assert.deepEqual(results, ["COMPLETED", "COMPLETED", "DEAD", "COMPLETED"]);
+    const rejected = await admin.query(
+      "SELECT * FROM public.example_tenancy_records WHERE inbox_id=$1",
+      [accepted[2].id],
+    );
+    assert.equal(rejected.rowCount, 0);
+    assert.equal(tenancy.getCurrentTenant(), null);
+    const [setting] = await client.$queryRawUnsafe<
+      Array<{ tenant: string | null }>
+    >(
+      "SELECT NULLIF(current_setting('app.current_tenant', true), '') AS tenant",
+    );
+    assert.equal(setting.tenant, null);
+    const [permissions] = await client.$queryRawUnsafe<
+      Array<{ rolsuper: boolean; rolbypassrls: boolean }>
+    >("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname=current_user");
+    assert.equal(permissions.rolsuper, false);
+    assert.equal(permissions.rolbypassrls, false);
+    console.log(
+      JSON.stringify({
+        tenantsCompleted: 2,
+        crossTenantWrite: "rejected",
+        globalShared: "completed",
+        contextAfterProcessing: null,
+      }),
+    );
+  } finally {
+    try {
+      await app?.close();
+    } finally {
+      try {
+        await prisma?.$disconnect();
+      } finally {
+        try {
+          if (roleCreated)
+            await admin.query(`DROP OWNED BY ${role}; DROP ROLE ${role}`);
+        } finally {
+          await admin.end();
+        }
+      }
+    }
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/src/webhook-ingress/main.ts

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer, type IncomingMessage } from "node:http";
+import {
+  InboxConflictError,
+  InboxService,
+  InboxValidationError,
+} from "@nestarc/inbox";
+import { startInbox, tenantId, waitUntil } from "../common";
+
+const maxBytes = 16 * 1024;
+
+async function body(request: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > maxBytes)
+      throw new InboxValidationError("Webhook body is too large.");
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function main() {
+  const secret = process.env.INBOX_EXAMPLE_WEBHOOK_SECRET;
+  if (!secret || Buffer.byteLength(secret) < 32) {
+    throw new Error(
+      "Set INBOX_EXAMPLE_WEBHOOK_SECRET to a random secret of at least 32 bytes.",
+    );
+  }
+  const fixture = await startInbox("example.webhook.v1", "order.created");
+  const inbox = fixture.app.get(InboxService);
+  const server = createServer((request, response) => {
+    void (async () => {
+      if (
+        request.method !== "POST" ||
+        request.url !== "/webhooks/example-account"
+      ) {
+        response.writeHead(404).end();
+        return;
+      }
+      const bytes = await body(request);
+      const timestamp = request.headers["x-example-timestamp"];
+      const signature = request.headers["x-example-signature"];
+      if (
+        typeof timestamp !== "string" ||
+        !/^\d{10}$/.test(timestamp) ||
+        Math.abs(Date.now() / 1000 - Number(timestamp)) > 300 ||
+        typeof signature !== "string" ||
+        !/^[a-f0-9]{64}$/.test(signature)
+      ) {
+        response.writeHead(401).end();
+        return;
+      }
+      const expected = createHmac("sha256", secret)
+        .update(timestamp)
+        .update(".")
+        .update(bytes)
+        .digest();
+      if (!timingSafeEqual(expected, Buffer.from(signature, "hex"))) {
+        response.writeHead(401).end();
+        return;
+      }
+      // Signature verification precedes JSON interpretation and tenant assignment.
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+      } catch {
+        response.writeHead(400).end();
+        return;
+      }
+      if (
+        !parsed ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed) ||
+        typeof (parsed as { id?: unknown }).id !== "string" ||
+        typeof (parsed as { orderId?: unknown }).orderId !== "string"
+      ) {
+        response.writeHead(400).end();
+        return;
+      }
+      const event = parsed as { id: string; orderId: string };
+      const result = await inbox.accept({
+        scope: { kind: "tenant", id: tenantId }, // server-side account → tenant mapping
+        source: "example-webhook-account",
+        consumer: "example.webhook.v1",
+        messageId: event.id,
+        eventType: "order.created",
+        schemaVersion: 1,
+        payload: { orderId: event.orderId },
+      });
+      response.writeHead(result.kind === "accepted" ? 202 : 200, {
+        "content-type": "application/json",
+      });
+      response.end(JSON.stringify({ kind: result.kind }));
+    })().catch((error: unknown) => {
+      const status =
+        error instanceof InboxConflictError
+          ? 409
+          : error instanceof InboxValidationError
+            ? 400
+            : 503;
+      if (!response.headersSent) response.writeHead(status);
+      response.end();
+    });
+  });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+    const address = server.address();
+    assert.ok(address && typeof address !== "string");
+    const url = `http://127.0.0.1:${address.port}/webhooks/example-account`;
+    const orderId = randomUUID();
+    const content = JSON.stringify({ id: randomUUID(), orderId });
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const signature = createHmac("sha256", secret)
+      .update(`${timestamp}.${content}`)
+      .digest("hex");
+    const headers = {
+      "content-type": "application/json",
+      "x-example-timestamp": timestamp,
+      "x-example-signature": signature,
+    };
+    const rejected = await fetch(url, {
+      method: "POST",
+      body: content,
+      headers: { ...headers, "x-example-signature": "0".repeat(64) },
+    });
+    assert.equal(rejected.status, 401);
+    await rejected.arrayBuffer();
+    const first = await fetch(url, { method: "POST", body: content, headers });
+    assert.equal(first.status, 202);
+    assert.deepEqual(await first.json(), { kind: "accepted" });
+    const duplicate = await fetch(url, {
+      method: "POST",
+      body: content,
+      headers,
+    });
+    assert.equal(duplicate.status, 200);
+    assert.deepEqual(await duplicate.json(), { kind: "duplicate" });
+    await waitUntil(
+      async () =>
+        (await fixture.prisma.exampleProjection.count({
+          where: { tenantId, orderId },
+        })) === 1,
+      "signed webhook projection",
+    );
+    console.log(
+      JSON.stringify({
+        invalidSignature: 401,
+        accepted: 202,
+        duplicate: 200,
+        projections: 1,
+      }),
+    );
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await fixture.close();
+  }
+}
+
+void main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@nestarc/inbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Transactional inbox for NestJS, Prisma and PostgreSQL with durable deduplication, fenced processing and retries.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nestarc/inbox.git"
+  },
+  "homepage": "https://github.com/nestarc/inbox#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "require": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./sql/create-inbox-table.sql": "./src/sql/create-inbox-table.sql",
+    "./sql/migrate-v1-to-v2.sql": "./src/sql/migrate-v1-to-v2.sql"
+  },
+  "files": [
+    "dist",
+    "src/sql",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs",
+    "examples",
+    "!examples/node_modules",
+    "!examples/dist",
+    "!examples/src/generated",
+    "!examples/package-lock.json"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "pretypecheck": "prisma generate --config test/prisma/prisma.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run test/unit",
+    "test:release": "node --test test/release/*.test.mjs",
+    "test:integration": "node scripts/with-test-db.mjs npm run test:integration:run",
+    "test:integration:run": "vitest run test/integration test/failure",
+    "test:operations": "node scripts/with-test-db.mjs node node_modules/vitest/vitest.mjs run test/operations",
+    "test:operations:database": "node scripts/test-db-operations.mjs",
+    "test:broker-recovery": "node scripts/with-test-db.mjs node scripts/test-broker-recovery.mjs",
+    "test:package": "node scripts/with-test-db.mjs node scripts/test-package.mjs",
+    "test:examples": "node scripts/with-test-db.mjs node scripts/test-examples.mjs",
+    "prebenchmark": "npm run build",
+    "benchmark": "node scripts/with-test-db.mjs node scripts/benchmark.mjs",
+    "benchmark:sustained": "node scripts/with-benchmark-db.mjs",
+    "format": "prettier --write src test scripts .github/workflows README.md CHANGELOG.md docs/usage.md docs/releasing.md docs/testing.md package.json tsconfig*.json vitest.config.mts",
+    "format:check": "prettier --check src test scripts .github/workflows README.md CHANGELOG.md docs/usage.md docs/releasing.md docs/testing.md package.json tsconfig*.json vitest.config.mts",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.2.8",
+    "@nestjs/core": "^11.2.8",
+    "@prisma/client": "^7.10.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "@nestarc/tenancy": "^0.16.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.2.8",
+    "@nestjs/core": "11.2.8",
+    "@nestjs/testing": "11.2.8",
+    "@prisma/adapter-pg": "7.10.1",
+    "@prisma/client": "7.10.1",
+    "@types/node": "24.19.2",
+    "@types/pg": "8.23.1",
+    "pg": "8.23.1",
+    "prettier": "3.8.3",
+    "prisma": "7.10.1",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "tsx": "4.23.15",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5",
+    "@nestarc/tenancy": "0.16.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "peerDependenciesMeta": {
+    "@nestarc/tenancy": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "src/internal/reliability-core"
+  ]
+}

package/src/sql/create-inbox-table.sql

@@ -0,0 +1,100 @@
+-- @nestarc/inbox schema version 2. Run explicitly with your application's migrations.
+-- Existing version 1 installations must apply migrate-v1-to-v2.sql instead.
+-- Runtime never creates or upgrades tables. Do not let Prisma db push remove these tables.
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS public.nestarc_inbox_schema (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS public.nestarc_inbox (
+  id uuid PRIMARY KEY,
+  scope_kind text NOT NULL CHECK (scope_kind IN ('tenant', 'global')),
+  scope_id text NOT NULL,
+  source text NOT NULL CHECK (octet_length(source) BETWEEN 1 AND 128),
+  consumer text NOT NULL CHECK (octet_length(consumer) BETWEEN 1 AND 128),
+  message_id text NOT NULL CHECK (octet_length(message_id) BETWEEN 1 AND 256),
+  event_type text NOT NULL CHECK (octet_length(event_type) BETWEEN 1 AND 128),
+  schema_version integer NOT NULL CHECK (schema_version > 0),
+  payload jsonb,
+  payload_purged boolean NOT NULL DEFAULT false,
+  fingerprint text NOT NULL CHECK (fingerprint ~ '^[0-9a-f]{64}$'),
+  fingerprint_version integer NOT NULL CHECK (fingerprint_version = 1),
+  status text NOT NULL DEFAULT 'PENDING'
+    CHECK (status IN ('PENDING', 'PROCESSING', 'RETRYABLE', 'COMPLETED', 'DEAD')),
+  claim_token bigint NOT NULL DEFAULT 0 CHECK (claim_token >= 0),
+  row_version bigint NOT NULL DEFAULT 1 CHECK (row_version > 0),
+  attempt_count integer NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  cycle_attempt_count integer NOT NULL DEFAULT 0 CHECK (cycle_attempt_count >= 0),
+  requeue_count integer NOT NULL DEFAULT 0 CHECK (requeue_count >= 0),
+  received_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  completed_at timestamptz,
+  next_attempt_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  lease_expires_at timestamptz,
+  worker_id text,
+  last_error_code text,
+  last_error_message text,
+  last_requeue_reason text,
+  last_requeue_actor text,
+  last_requeue_at timestamptz,
+  correlation_id text,
+  causation_id text,
+  headers jsonb NOT NULL DEFAULT '{}'::jsonb,
+  replay_of uuid,
+  replay_request_id uuid,
+  replay_source_version bigint,
+  replay_actor text,
+  replay_reason text,
+  replayed_at timestamptz,
+  CONSTRAINT nestarc_inbox_identity_key
+    UNIQUE (scope_kind, scope_id, source, consumer, message_id),
+  CONSTRAINT nestarc_inbox_replay_request_key
+    UNIQUE (scope_kind, scope_id, replay_request_id),
+  CONSTRAINT nestarc_inbox_replay_original_fk
+    FOREIGN KEY (replay_of) REFERENCES public.nestarc_inbox(id),
+  CONSTRAINT nestarc_inbox_replay_check CHECK (
+    (replay_of IS NULL AND replay_request_id IS NULL AND replay_source_version IS NULL
+      AND replay_actor IS NULL AND replay_reason IS NULL AND replayed_at IS NULL) OR
+    (replay_of IS NOT NULL AND replay_of <> id AND replay_request_id IS NOT NULL
+      AND replay_source_version IS NOT NULL AND replay_source_version > 0
+      AND replay_actor IS NOT NULL AND octet_length(replay_actor) BETWEEN 1 AND 256
+      AND replay_reason IS NOT NULL AND octet_length(replay_reason) BETWEEN 1 AND 1024
+      AND replayed_at IS NOT NULL)
+  ),
+  CONSTRAINT nestarc_inbox_scope_check CHECK (
+    (scope_kind = 'global' AND scope_id = '') OR
+    (scope_kind = 'tenant' AND octet_length(scope_id) BETWEEN 1 AND 128)
+  ),
+  CONSTRAINT nestarc_inbox_payload_check CHECK (
+    (payload_purged AND payload IS NULL AND status = 'COMPLETED') OR
+    (NOT payload_purged AND payload IS NOT NULL)
+  ),
+  CONSTRAINT nestarc_inbox_lease_check CHECK (
+    (status = 'PROCESSING' AND lease_expires_at IS NOT NULL AND worker_id IS NOT NULL) OR
+    (status <> 'PROCESSING' AND lease_expires_at IS NULL AND worker_id IS NULL)
+  ),
+  CONSTRAINT nestarc_inbox_completion_check CHECK (
+    (status = 'COMPLETED' AND completed_at IS NOT NULL) OR
+    (status <> 'COMPLETED' AND completed_at IS NULL)
+  )
+);
+
+CREATE INDEX IF NOT EXISTS nestarc_inbox_due_idx
+  ON public.nestarc_inbox (consumer, next_attempt_at, id)
+  WHERE status IN ('PENDING', 'RETRYABLE');
+CREATE INDEX IF NOT EXISTS nestarc_inbox_expired_idx
+  ON public.nestarc_inbox (consumer, lease_expires_at, id)
+  WHERE status = 'PROCESSING';
+CREATE INDEX IF NOT EXISTS nestarc_inbox_scope_list_idx
+  ON public.nestarc_inbox (scope_kind, scope_id, id);
+CREATE INDEX IF NOT EXISTS nestarc_inbox_completed_payload_idx
+  ON public.nestarc_inbox (completed_at, id)
+  WHERE status = 'COMPLETED' AND NOT payload_purged;
+CREATE INDEX IF NOT EXISTS nestarc_inbox_replay_original_idx
+  ON public.nestarc_inbox (replay_of) WHERE replay_of IS NOT NULL;
+
+INSERT INTO public.nestarc_inbox_schema (singleton, version)
+VALUES (true, 2) ON CONFLICT (singleton) DO NOTHING;
+
+COMMIT;

package/src/sql/migrate-v1-to-v2.sql

@@ -0,0 +1,53 @@
+-- Add completed-message replay lineage to an existing @nestarc/inbox v1 installation.
+-- Run explicitly during deployment before starting the v2 application. Transactional
+-- DDL preserves all receipts, fingerprints, processing state, and business writes.
+BEGIN;
+
+LOCK TABLE public.nestarc_inbox IN ACCESS EXCLUSIVE MODE;
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM public.nestarc_inbox_schema WHERE singleton = true AND version IN (1, 2)
+  ) THEN
+    RAISE EXCEPTION 'Expected inbox schema version 1 or 2';
+  END IF;
+END $$;
+
+ALTER TABLE public.nestarc_inbox
+  ADD COLUMN IF NOT EXISTS replay_of uuid,
+  ADD COLUMN IF NOT EXISTS replay_request_id uuid,
+  ADD COLUMN IF NOT EXISTS replay_source_version bigint,
+  ADD COLUMN IF NOT EXISTS replay_actor text,
+  ADD COLUMN IF NOT EXISTS replay_reason text,
+  ADD COLUMN IF NOT EXISTS replayed_at timestamptz;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_request_key') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_request_key
+      UNIQUE (scope_kind, scope_id, replay_request_id);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_original_fk') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_original_fk
+      FOREIGN KEY (replay_of) REFERENCES public.nestarc_inbox(id);
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint
+    WHERE conrelid='public.nestarc_inbox'::regclass AND conname='nestarc_inbox_replay_check') THEN
+    ALTER TABLE public.nestarc_inbox ADD CONSTRAINT nestarc_inbox_replay_check CHECK (
+      (replay_of IS NULL AND replay_request_id IS NULL AND replay_source_version IS NULL
+        AND replay_actor IS NULL AND replay_reason IS NULL AND replayed_at IS NULL) OR
+      (replay_of IS NOT NULL AND replay_of <> id AND replay_request_id IS NOT NULL
+        AND replay_source_version IS NOT NULL AND replay_source_version > 0
+        AND replay_actor IS NOT NULL AND octet_length(replay_actor) BETWEEN 1 AND 256
+        AND replay_reason IS NOT NULL AND octet_length(replay_reason) BETWEEN 1 AND 1024
+        AND replayed_at IS NOT NULL)
+    );
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS nestarc_inbox_replay_original_idx
+  ON public.nestarc_inbox (replay_of) WHERE replay_of IS NOT NULL;
+UPDATE public.nestarc_inbox_schema SET version=2 WHERE singleton=true;
+COMMIT;